前言¶

用 DeepSeek Harness（DSH）跑长任务的开发者大概率见过这种状态：Agent 还在运行，工具调用一个接一个，但面板上的 todo 列表停留在几分钟前——已完成的事项仍显示未完成，新出现的阻塞没有记录，下一步是什么也无从判断。任务越长，这个面板越不可信。

这类问题过去通常只能在提示词里叮嘱模型「及时更新」，缺少机制层面的约束。dsh-todo-freshness-guard 换了个思路：在 Harness 层计数、提醒，必要时直接阻断普通工具调用，直到模型重新提交完整的 todo 列表。下面介绍这个插件。

这是什么¶

dsh-todo-freshness-guard 是一个 out-of-tree 的 DeepSeek Harness Guard 插件，由 lamost423 维护，当前版本 0.1.1，包状态为 community preview（社区预览）。它解决的问题只有一个：当 todo_write 列表已经过期，先提醒模型对齐完整列表，提醒无效则阻断普通工具调用。

两点边界要提前说清：它只修复 stale 的 todo_write 状态，不替换、也不修补文件系统的 Write 工具；兼容目标是 DeepSeek Harness 0.1.0-rc.6，Node.js 版本要求为 ^22.19.0 || >=24.0.0。

工作机制¶

插件的全部行为围绕一次成功的 todo_write 展开。当一次 todo_write 成功提交且列表中包含未完成事项后，插件按 Session 统计非记账类工具调用的次数，然后分两档处理：

1. 计数达到 reminderAfterCalls 时，注入一次模型可见的提醒，要求模型对齐完整的 todo 列表；
2. 计数超过 blockAfterCalls 后，拒绝普通工具调用，直到一次新的完整 todo_write 替换列表。

始终可达的路径¶

阻断不是一刀切，以下几条规则保证了模型总有恢复手段：

• todo_write 始终可达；
• 外层 run_code 传输路径保持可达，Code Mode 仍可调用 todo_write；
• 原生调用与 Code Mode SDK 子分发共享同一个计数器，换路径调用不会绕开或重置计数；
• 待办列表全部完成或为空时，强制执行自动停止。

安装与启用¶

先安装与插件兼容的 DSH CLI，再把 release 归档添加到需要启用守卫的 profile（示例用 web），最后启动：

npm install --global @deepseek-ai/dsh@0.1.0-rc.6
dsh plugin --profile web add https://github.com/lamost423/dsh-todo-freshness-guard/releases/download/v0.1.1/dsh-todo-freshness-guard-0.1.1.tgz
dsh web

如果想从源码 checkout 安装，用下面这套流程：

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 层如下：

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

即默认第 5 次调用时提醒、第 8 次之后阻断。两个值都有约束：blockAfterCalls 必须是大于 reminderAfterCalls 的整数，且两者都必须为正整数。

另外要注意加载顺序：应用在此 bundle 之后的 profile 和命令行 patch 层可能替换这行配置。调整阈值后，建议实际跑一轮确认生效的是你想要的值。

移除与验证¶

不需要时用一条命令移除：

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

如果改动过源码，仓库提供两个验证命令：pnpm check 依次执行类型检查、测试和构建，pnpm pack --pack-destination /tmp 把包打到指定目录。

pnpm check
pnpm pack --pack-destination /tmp

测试覆盖面包括原生与 Code Mode 两种策略、并发重置、Loader 组合、打包 Bundle 契约，以及通过官方 DSH 0.1.0-rc.6 实际启动 Web。

适用场景与注意¶

适合的场景很明确：在 DSH 0.1.0-rc.6 上跑长任务、依赖 todo 列表观察进度的使用者。如果任务普遍很短、模型总能及时更新列表，这个插件的存在感会很低。

使用前有几点务必留意：

1. 插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证。许可证为 MIT，衍生部分保留 DeepSeek Harness 许可证，详见仓库中的 NOTICE 文件；
2. 包状态为 community preview，兼容目标锁定 DeepSeek Harness 0.1.0-rc.6，DSH 升级后需重新确认兼容性；
3. 它只处理 stale 的 todo_write 状态，文件系统 Write 工具的问题不在其范围内；
4. 配置可能被后续加载的 patch 层替换，改动阈值后要确认实际生效值。

结尾¶

一句话回顾：dsh-todo-freshness-guard 把「模型自觉更新 todo」变成 Harness 层面的机制约束——先提醒、再阻断，同时保住 todo_write 和 run_code 两条路径，让长任务的进度面板重新可信。

• GitHub 仓库：https://github.com/lamost423/dsh-todo-freshness-guard
• 社区目录页：https://www.skillhub.cn/plugins/lamost423/dsh-todo-freshness-guard

需要说明的是，这个社区目录是独立站点，与 DeepSeek、幻方没有官方从属关系；DSH 的理念是「一切皆插件」，这类社区守卫插件正是这个生态的日常组成部分。