前言¶

在 DeepSeek Harness（DSH）裏跑長任務時，網絡抖動、上游超時、5xx、進程重啓都會打斷當前輪次。會話日誌裏往往還留着完整對話，但 Agent 重啓後仍需要一份緊湊、結構化的「進行到哪了」：目標、當前步驟、已完成的工具調用、結果不確定的調用、待辦，以及最後可見的輸出。單靠翻歷史消息重建上下文，既慢也容易漏狀態。

下面介紹社區插件 dsh-task-checkpoint-guard（維護者 jlnkx5200-beep，分類：工作流）。它在本地持久化結構化檢查點，對可恢復的傳輸類失敗做分類，並在策略允許時用有界探測或延遲後重新武裝 Goal，而不是無差別自動重試。

這是什麼¶

dsh-task-checkpoint-guard 的定位是：Durable task checkpoints and safe, bounded recovery for DeepSeek Harness agents——爲 DSH Agent 提供可 durable 的任務檢查點，以及在明確邊界內的安全恢復。

當前版本 v0.1.0，在 DSH 0.2.1-rc.3、Windows 11、Node.js 24.21.0 環境下開發與測試；package.json 中 engines.dsh 聲明接受範圍爲 >=0.2.1-rc.3 <0.3.0，其他 DSH 版本未宣稱已測。許可證爲 MIT。插件不保存隱藏 chain-of-thought，也不上傳任務記錄。

核心功能¶

檢查點寫入¶

每個活躍 DSH 會話持久化結構化檢查點，形式爲 JSON + Markdown + 會話指針。
記錄原始人類指令、Goal 目標/修訂號、待辦、輪次/步驟位置、工具生命週期，以及有長度上限的可見結果。
不寫入模型推理正文，僅保留 reasoning 塊/字符計數。
寫入前對憑證形態字符串和疑似密鑰的 JSON 字段做脫敏。
採用同目錄臨時文件、fsync、重命名原子寫入；保留 <file>.previous 作爲上一份有效副本。

默認目錄爲 $DSH_HOME/task-checkpoints；未設置 DSH_HOME 時在 Windows 上爲 %USERPROFILE%\.dsh\task-checkpoints。

失敗分類與 fail-closed 恢復¶

將失敗分爲 NETWORK、TIMEOUT、SERVICE、AUTH_OR_REQUEST、ABORTED、UNKNOWN 等類型，並採用 fail-closed 策略，例如：

用戶取消、鑑權/請求錯誤、max-token 停止、部分流式輸出後，不自動恢復；
工具調用尚無 durable 結果時，不自動恢復；
對已結束或結果未知的工具調用，不盲目重試。

三種 recoveryMode¶

off：僅寫檢查點（默認）；
probe：重新武裝 Goal 前做有界 HTTP(S) 就緒探測；
deferred：顯式配置的延遲，不發起出站探測。

恢復時會用 compare-and-set 校驗 Goal 修訂號，重新武裝已 disarm 的活躍 Goal，並注入一條結構化上下文消息。可選在恢復後第一輪拒絕指紋完全相同的重複工具調用，之後 guard 自動清除。

明確不做的事（使用前要清楚）¶

不重建隱藏 chain-of-thought；恢復依賴可見消息、durable 執行事實與結構化狀態。
不上傳、不同步檢查點；除用戶配置的就緒探測外，無其他出站請求。
不保證工具冪等；重複 guard 只覆蓋恢復首輪的完全重複指紋。
不自行開啓模型輪次；自動續跑需要 DSH 的 goals 與 goal-round-driver。無 driver 時 Goal 可被 re-arm 且上下文入隊，但未必有新 turn。
可選通過公開 ctx.sessionQuery 補齊插件掛載前或檢查點滯後於 live log 時缺失的會話事件（需宿主提供該能力）。

宿主依賴¶

Node.js： ^22.19.0 或 >=24.0.0（與 DSH 0.2.1-rc.3 聲明範圍一致）。
必需服務： agents、sessions。
可選： goals + goal-round-driver（自動 Goal 續跑）、credentials（探測鑑權）、sessionQuery（事件回放）。
運行時 無 npm 依賴。

安裝與啓用¶

先在倉庫根目錄打包發佈 tarball：

npm pack

安裝到實際使用的 DSH profile：

dsh plugin --profile <profile> add ./dsh-task-checkpoint-guard-0.1.0.tgz

若使用源碼目錄，可直接：

dsh plugin --profile <profile> add ./dsh-task-checkpoint-guard

確認 profile 合成結果中包含該 bundle：

dsh --profile <profile> --dump-config

按 profile 正常啓動（標準 Web profile 也可用 dsh web）：

dsh --profile <profile>

卸載（不刪除已寫入的檢查點文件，需自行刪目錄）：

dsh plugin --profile <profile> remove dsh-task-checkpoint-guard

典型用法¶

驗證檢查點是否落盤¶

任務跑過後查看本地文件。PowerShell 示例：

Get-ChildItem "$HOME\.dsh\task-checkpoints" -Recurse
Get-Content "$HOME\.dsh\task-checkpoints\tasks\<task-id>.md"

POSIX shell：

find "${DSH_HOME:-$HOME/.dsh}/task-checkpoints" -maxdepth 3 -type f

通過 cordis.patch 覆蓋配置¶

Bundle 默認 recoveryMode: off、啓用本地檢查點、重複工具 guard 限於恢復首輪。要在 profile 的 cordis.patch.yml 中整行重寫該 bundle 的 config（後 patch 會替換整行配置）。示例片段（佔位 URL 與憑證名需換成你的環境）：

- id: task-checkpoint-guard
  name: dsh-task-checkpoint-guard
  config:
    checkpointRoot: ~/.dsh/task-checkpoints
    recoveryMode: probe
    probeUrl: https://api.example.test/v1/models
    probeMethod: GET
    probeAuth: bearer
    credentialRef: EXAMPLE_API_KEY
    probeExpectedStatuses: [200]
    probeTimeoutMs: 5000
    maxProbeAttempts: 5
    initialProbeDelayMs: 1000
    maxProbeDelayMs: 30000
    jitterRatio: 0.2
    maxAutoResumes: 3
    providerFilter: null
    duplicateToolPolicy: deny-on-recovery
    maxToolHistory: 80
    maxToolResultChars: 2000
    maxToolArgumentChars: 1000
    maxRecoveryContextChars: 16000
    persistDebounceMs: 100
    reconstructFromSessionQuery: true

credentialRef 指向 DSH credentials 服務中的密鑰名，值不會寫入檢查點。完整參數語義見倉庫 docs/configuration.md。

適用場景與注意¶

適合誰： 需要在 DSH 上跑較長 Goal/多步工具鏈、且希望在進程或鏈路中斷後保留結構化進度、並在可控條件下嘗試續跑的工作流場景。默認 recoveryMode: off 時，可先只當「本地任務賬本 + 人工決策是否繼續」使用；需要自動 re-arm 時再打開 probe 或 deferred，並確保 profile 具備 goal-round-driver。

安全與權限： 插件以當前 dsh 進程權限運行，讀寫本地檢查點目錄；啓用 probe 時會向配置的 HTTP(S) 端點發起探測。安裝前應閱讀源碼與 MIT 許可證，確認 cordis.patch.yml 與 docs/ 中的行爲符合你的合規要求。DSH 生態強調「一切皆插件」；社區目錄站點與 DeepSeek / 幻方無官方從屬關係，本文介紹的是第三方倉庫 jlnkx5200-beep/dsh-task-checkpoint-guard，而非官方應用商店條目。

兼容： 未承諾適配每一個 DSH 發行版；以 engines.dsh 與 README 中的測試說明爲準。

結尾¶

經過上面的步驟，你可以在本機爲 DSH 會話留下 JSON/Markdown 檢查點，在傳輸類失敗分類清晰的前提下，用 fail-closed 與有界探測避免盲目重試。目錄頁與源碼：

社區目錄：https://www.skillhub.cn/plugins/jlnkx5200-beep/dsh-task-checkpoint-guard
GitHub：https://github.com/jlnkx5200-beep/dsh-task-checkpoint-guard

dsh-task-checkpoint-guard：DSH 長任務的本地檢查點與有界恢復

前言¶

這是什麼¶

核心功能¶

檢查點寫入¶

失敗分類與 fail-closed 恢復¶

三種 recoveryMode¶

明確不做的事（使用前要清楚）¶

宿主依賴¶

安裝與啓用¶

典型用法¶

驗證檢查點是否落盤¶

通過 cordis.patch 覆蓋配置¶

適用場景與注意¶

結尾¶

精选优惠券

dsh-task-checkpoint-guard：DSH 長任務的本地檢查點與有界恢復

前言¶

這是什麼¶

核心功能¶

檢查點寫入¶

失敗分類與 fail-closed 恢復¶

三種 recoveryMode¶

明確不做的事（使用前要清楚）¶

宿主依賴¶

安裝與啓用¶

典型用法¶

驗證檢查點是否落盤¶

通過 cordis.patch 覆蓋配置¶

適用場景與注意¶

結尾¶

精选优惠券

相關文章