Skip to content

dsh-todo-progress-guard

Verified

dsh-todo-progress-guard · v1.0.2 · MIT

DSH host plugin that keeps todo_write progress in sync: it nudges the agent mid-turn and completes stranded tasks when a turn finishes normally.

Install

dsh plugin add dsh-todo-progress-guard

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

dsh-todo-progress-guard

English | 中文

CI

给 DeepSeek Harness(DSH)的任务清单补上「自动推进」:在多步工具调用过程中提醒模型更新 todo_write,并在正常结束一轮对话时把遗留任务收尾为已完成。


它解决什么问题

DSH 自带的 todo_write 是整表替换的规划工具,任务清单只是一份会话投影:

// @deepseek-ai/dsh-tool-todo
apply: (state, event) => {
  if (event.type === "todo/write") return event.data.todos;
  if (event.type === "turn/start") return null;
  return state;
}

也就是说,只有模型再次调用 todo_write,面板才会变化。于是长链路任务里常见两种症状:

  1. 中途不更新:模型开局写一次清单,随后连续跑几十个 bash / read / edit, 注意力被工具结果占满,再也不回头更新进度,面板一直停在第一项 in_progress。
  2. 结束时停在第一个:模型做完全部工作后直接输出最终答复(这一步不再产生工具调用), 自然也没有机会补最后一次 todo_write,于是对话已经结束,任务面板还挂着 1 进行中 · N 待处理。

本插件用一个 Host 侧 Cordis 插件同时补上这两个缺口,不改动 DSH 核心包,也不写新的事件类型。

两种机制

1. 过程提醒(tools/post-execute)

当当前轮次已经有一份未完成的任务清单,而模型连续若干步/若干次工具调用都没调用 todo_write 时,插件会在该步骤最后一个工具结果之后注入一条 user/message 形式的上下文提醒(source.kind = "todo-progress-reminder", form: "notice",在聊天流里渲染成一条可折叠的注入提示)。

提醒正文会把当前清单逐条原文列出,因为 todo_write 要求整表重发——这样模型无需翻找 几十步之前的历史就能直接复制更新:

Task progress reminder (1/3 completed; 2 step(s) / 4 tool call(s) since the last todo_write):
1. [completed] Recon the repository
2. [in_progress] Implement the fix
3. [pending] Run the test suite
If any task above is now completed or in progress, call `todo_write` with the COMPLETE
updated list in your next step. It can run in parallel alongside your next tool call at no
extra step cost, or mark every finished task `completed` before your final reply.

2. 轮次结束收尾(agent/turn-stopping)

一轮对话正常结束的那一刻(turn/end 写入之前、轮次仍处于合法开放状态),如果清单里 还残留 in_progress / pending,插件会追加一条最终的 todo/write 快照,把它们统一收尾为 completed。这样面板状态永远不会比它描述的工作活得更久。

安装

推荐走 Web 界面:打开 插件 → 安装,粘贴下面任意一个 spec。 它会同时完成「装依赖」和「启用该 bundle」,patch 立即生效,不用重启:

github:LaochenFEIZHAI/dsh-todo-progress-guard   # 直接从 GitHub(本仓库)
/absolute/path/to/dsh-todo-progress-guard        # 本机目录,开发时改动即时生效
dsh-todo-progress-guard                          # 发布到 npm 之后

命令行只负责装包(dsh plugin 是 pnpm 的透传,不做 bundle 选择):

dsh plugin --profile web add github:LaochenFEIZHAI/dsh-todo-progress-guard

装完后还要在「插件」页把 dsh-todo-progress-guard 启用一次(等价于把它加进 ~/.dsh/profiles/<name>/package.json 的 dsh.profile.bundles),bundle 的 cordis.patch.yml 才会被应用。

配置

默认值即可直接使用;需要调整时,在 profile 的 cordis.patch.yml 里按 id 覆盖这一行的 config(patch 层会整份替换 config,所以要把三个键都写上):

- id: todo-progress-guard
  config:
    stepThreshold: 2
    callThreshold: 5
    autoCompleteOnTurnEnd: true
字段 默认值 含义
stepThreshold 2 距离上次 todo_write 经过多少个模型步骤后提醒
callThreshold 5 距离上次 todo_write 累计多少次其他工具调用后提醒(需至少跨过 1 步)
autoCompleteOnTurnEnd true 轮次正常结束时是否把遗留任务收尾为 completed

两个阈值是「或」关系:先到先提醒。同一步骤内最多提醒一次;每轮次开始时计数清零。 非法值(非正整数、非布尔)会被忽略并回退到默认值,插件不会因此加载失败。

安全边界

收尾只在一轮确实做完事时发生。以下任一情况插件都不写任何东西:

  • 当前轮次已被用户中断(signal.aborted),或最后一次助手消息被打断;
  • 还有排队中的下一步(agent.inbox.nextStep 非空)——那说明轮次没结束;
  • 本步骤调用过 ask_user_question 或 exit_plan_mode(正在等人类回答,不能替用户判定完成);
  • 清单已全部 completed(无事可做);
  • 清单是刚建好、还没执行过任何其他工具的「纯计划」(这是意图,不是成果)。

插件只追加 todo/write 事件,不改写历史;写入始终发生在合法的开放轮次内,因此与 @deepseek-ai/dsh-tool-todo 自带的持久日志不变式兼容。

兼容性

  • 需要 Host 暴露 sessions 与 sessionProjections 服务;缺失时插件不激活(inject 语义), 不会影响其他插件。
  • 已在 DSH 0.2.0-rc.2 上验证;依赖的扩展点(tools/post-execute 的 additionalContexts、 agent/turn-stopping、todos 投影)均属于该版本的公开契约。
  • 零运行时依赖:插件不 import 任何 DSH 包,因此 link: 本地目录安装和 registry 安装行为 完全一致(若导出 Schemastery Config,link: 安装会因真实路径解析不到 DSH 包而加载失败, 所以配置改为插件内部校验)。

开发

npm test        # node --test,13 个用例覆盖提醒/收尾/边界

测试用一套最小的 Host 替身(会话事件日志 + todos 投影 + 工具 waterfall)驱动真实插件代码, 不使用任何 DSH 内部模块。

许可

MIT