前言¶

用 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 的理念是「一切皆插件」，這類社區守衛插件正是這個生態的日常組成部分。