# DSH Todo Freshness Guard｜DSH 待办新鲜度守卫

[English](README.md) | 简体中文

**解决的问题：**Agent 在长任务中可能持续调用工具，却不更新未完成的 `todo_write` 列表，导致用户看到的计划与真实执行状态脱节。

**最痛的问题：**Agent 明明还在运行，用户看到的却是过期状态——已完成事项仍显示未完成，新阻塞没有记录，下一步也无法判断。任务越长，进度越不可信。

**如何解决：**这是一个仓库外的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Guard。它先提醒模型重新同步完整 Todo 列表；列表继续过期时，再阻止普通工具调用。`todo_write` 与外层 `run_code` 恢复通道始终可用。

**Problem it solves:** During long agent turns, the model may keep calling tools without updating its unfinished `todo_write` list. The visible plan then stops matching the work actually being done.

**Most painful failure:** The agent is still active, but the user is looking at stale status—completed work still appears pending, new blockers are missing, and the next step is unclear. This removes progress visibility exactly when a long task needs it most.

![DSH 待办新鲜度守卫让长任务进度始终可见](assets/progress-stays-visible.png)

## 行为

一次成功的 `todo_write` 包含未完成事项后，Guard 会按 Session 统计非记账类工具调用：

- 达到 `reminderAfterCalls` 时，向模型注入一次提醒，要求重新同步完整 Todo 列表。
- 超过 `blockAfterCalls` 后，拒绝普通工具，直到新的完整 `todo_write` 替换旧列表。
- 原生调用与 Code Mode SDK 子调用共用计数器。
- `todo_write` 始终可用。
- 外层 `run_code` 始终可用，保证 Code Mode 能调用 `todo_write`。
- Todo 列表为空或全部完成时，约束自动关闭。

本插件修复的是 `todo_write` 状态长期不更新的问题，不会替换或修改文件系统 Write 工具。

## 兼容范围

- DeepSeek Harness：`0.1.0-rc.6` 至 `0.1.7-rc.2`（会话格式 0–4）
- Node.js：`^22.19.0 || >=24.0.0`
- 当前状态：社区预览版

## 安装

先安装兼容版本的 DSH CLI，再把 Release 压缩包添加到需要启用 Guard 的 Profile：

```sh
npm install --global @deepseek-ai/dsh@0.1.7-rc.2
dsh plugin --profile web add https://github.com/lamost423/dsh-todo-freshness-guard/releases/download/v0.1.2/dsh-todo-freshness-guard-0.1.2.tgz
dsh web
```

也可以从工作副本安装：

```sh
git clone https://github.com/lamost423/dsh-todo-freshness-guard.git
cd dsh-todo-freshness-guard
corepack enable
pnpm install --frozen-lockfile
pnpm build
dsh plugin --profile web add .
dsh web
```

插件默认贡献以下 Patch：

```yaml
- insert:
    - id: todo-freshness-guard
      name: dsh-todo-freshness-guard
      config:
        reminderAfterCalls: 5
        blockAfterCalls: 8
```

后加载的 Profile 或命令行 Patch 可以覆盖这一行配置。两个参数都必须是正整数，且 `blockAfterCalls` 必须大于 `reminderAfterCalls`。

移除插件：

```sh
dsh plugin --profile web remove dsh-todo-freshness-guard
```

## 从 v0.1.1 升级

在 DSH 0.1.7 上，v0.1.1 的提醒一触发，这一轮就会以 `format v4 message requires a producer-owned source kind` 失败，而且该会话之后每一轮都会同样失败。用上面的安装命令添加 v0.1.2 的压缩包（会替换掉 v0.1.1），然后重启 `dsh web`：正在运行的宿主在重启前一直使用旧代码。受影响的会话可以重新打开，出错那一轮会标记为中断；那一轮没来得及保存的部分，以及出错之后到重启之前在该会话里发出的内容，都无法找回。

## 验证

```sh
pnpm check
pnpm pack --pack-destination /tmp
```

测试覆盖原生模式、Code Mode、并发重置、按各版本宿主的会话日志读取方式补读待办、Loader 组合、会话格式 4 下的提醒来源、发布压缩包 Bundle 契约，以及通过官方 DSH `0.1.0-rc.6` 完成真实 Web 启动。

## 许可证

MIT。衍生部分继续遵守 DeepSeek Harness 许可证，详见 [`NOTICE`](NOTICE)。