前言¶
在 DeepSeek Harness（DSH）裏跑長鏈路任務時，常見失敗模式是：執行智能體宣稱某步已完成，該說法進入對話 transcript，下一輪在未經覈對的前提上繼續推進。下游無法區分「已驗證步驟」與「樂觀自報」，錯誤會層層疊加，最終答案可能看起來很有把握卻早已偏離事實。
社區插件 dsh-verified-progress（維護者 lion231226，目錄分類 admin-security）針對的是這一類問題：爲長時 DSH 工作維護一份 verified-progress ledger——獨立校驗方對每一步聲稱給出結構化裁決，只有滿足准入規則的回合才記爲進度；若校驗過程中工作區被改動，指紋對比會使該裁決作廢，且永遠不能升格爲進度。
這是什麼¶
dsh-verified-progress 是 DSH 生態中的插件包（npm 名 dsh-verified-progress，當前資料中版本 0.3.1，MIT 許可證）。它不把「請校驗方只讀」當作唯一保障，而是在每次校驗 episode 前後對工作區做指紋快照（文件 size、mtime，以及在 hash 上限內的 SHA-256），用 檢測 替代單純依賴工具過濾或提示詞約束。
流程可概括爲：
claim ──▶ independent verification ──▶ verdict
│
complete + clean + aligned ──▶ ledger (progress)
│
anything else ──▶ ledger (evidence only)
准入規則在代碼中強制執行，而非僅寫在 prompt 裏：integrity === "violation" || contract !== "aligned" 時，status 不能爲 complete。未聲明的 integrity 會保守地視爲 suspect，不會默認 clean。
核心功能¶
1. 獨立校驗，替代自報進度¶
校驗方是 無對話上下文繼承 的子智能體，以只讀工具集查看工作區，並在回覆中給出三行控制字段：
Status: complete | incomplete | blocked
Integrity: clean | suspect | violation
Contract audit: aligned | unknown | needs_revision | invalid
僅當裁決 complete、clean、aligned 時，該步纔會進入賬本意義上的「進度」；被拒絕的回合仍留在賬本中作爲 evidence，不會被提升爲進度。
2. 持久化 verified-progress 賬本¶
接受的步驟追加寫入 ledger.jsonl（每行一個 JSON 對象，每次 append 後 fsync）；state.json 提供 last-wins 投影。進程崩潰、上下文壓縮或新會話重新打開同一 run 時，仍可查詢：哪些已驗證、哪些因何被拒、還剩什麼。被拒回合保留爲證據，便於後續輪次看到已失敗過的聲稱。
3. 工作區突變檢測（指紋守衛）¶
校驗前後對聲明範圍內的文件做指紋對比。若校驗 episode 期間工作區發生變化，該輪記爲 blocked / violation，無論校驗報告讀起來多幹淨，都不能升格爲進度——因爲會寫文件的校驗方不是中立見證，可能「先改再報」；指紋對比不依賴對校驗方的信任。
4. 插件暴露的工具¶
| 工具 | 用途 |
|---|---|
verified_progress_verify |
針對工作區校驗一步聲稱，並將裁決寫入賬本 |
verified_progress_ledger |
讀回已驗證進度、被拒聲稱與剩餘項 |
verified_progress_state |
當前 run 狀態：已驗證輪次、待處理聲稱、開放項 |
guard_scope：聲明指紋根目錄¶
verified_progress_verify 必須配合 guard_scope：工作區相對路徑或 glob，非 glob 前綴成爲指紋根。示例：
verified_progress_verify claim="the parser handles CRLF input"
guard_scope="src/parser/**"
這不是可選裝飾。若對整個工作區根做指紋，在 desktop profile 下根目錄可能是 harness 主目錄，sessions/**、storages/** 等會被會話本身持續寫入，會導致每輪都像「工作區被 mutate」而誤殺。因此：
- 路徑須解析在 工作區內；絕對路徑與
..會被拒絕； - 當工作區即爲 harness 主目錄時，必須 提供 scope；僅在根級排除
sessions、storages、logs、telemetry、cache、profiles等 harness 自有目錄（嵌套項目內的sessions/仍可被守衛）； - 輸出會打印
Fingerprinted: <path>，避免裁決範圍含糊。
安裝與啓用¶
按環境選擇 README 中的安裝方式之一。無 registry、無 git 時，tarball 爲通用默認：
dsh plugin --profile web add \
https://github.com/lion231226/dsh-verified-progress/releases/latest/download/dsh-verified-progress.tgz
包發佈後也可從 registry 安裝：
dsh plugin --profile web add dsh-verified-progress
本機已安裝 git 時，可從倉庫地址安裝：
dsh plugin --profile web add github:lion231226/dsh-verified-progress
未安裝 git 時使用 github: 形式可能因 git ls-remote 失敗而報錯，易被誤判爲插件損壞；tarball 走 HTTPS，不依賴 git。
安裝後 需重啓 harness：激活失敗的插件不會自動重試，模塊緩存也會保留舊版本直至進程重啓。包爲純 ESM，無運行時依賴，無需額外 build。
環境要求（來自 package.json）：Node >= 22，DSH >= 0.2.0-rc.2；peer 依賴含 @deepseek-ai/cordis 等 DSH 相關包。
典型用法¶
- 安裝插件並重啓 harness。
- 對某步完成聲稱調用
verified_progress_verify，傳入自然語言claim與guard_scope（指向你真正要守衛的項目路徑，而非整個 harness 狀態樹）。 - 根據返回的三行控制字段與指紋結果判斷該步是否進入進度；需要彙總時用
verified_progress_ledger或verified_progress_state。
賬本文件不在項目目錄，而在 harness 狀態目錄下：
<state>/verified-progress/runs/<runId>/ledger.jsonl
<state>/verified-progress/runs/<runId>/state.json
<runId> 有 session id 時取自 session id，否則取自工作目錄哈希，同一 session 重開會對應同一 run。
適用場景與注意¶
適合：多輪、長 horizon 的 DSH 任務，需要在 crash、compaction 或新會話後仍能回答「什麼被獨立驗證過、什麼被拒、還差什麼」；願意用額外 token 換每步一次校驗 episode 的團隊。
不必上插件：單輪、極短任務——校驗成本可能高於收益。
設計邊界（README 明確說明）：
- 校驗方是 獨立上下文子智能體，不是獨立 OS 進程；仍與執行方同屬 harness 權限域，指紋檢測使違規 可發現，而非從物理上不可能寫盤。
- 突變守衛是 正確性工具，不是安全邊界：不防本地攻擊者，不是沙箱，未納入快照的路徑不在對比範圍內。
- 超過 hash 上限的大文件僅比 size/mtime，快照會標明 evidence gap，不會假裝做了內容哈希。
- 每次驗證消耗 token。
插件以 當前 dsh 進程的權限 運行；安裝前請自行查閱 GitHub 倉庫 源碼與 MIT 許可證，確認符合你的合規與信任要求。DSH 社區插件目錄（如 SkillHub）爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-verified-progress 把 LongHorizon 類循環裏的「獨立校驗 + 賬本」落到 DSH 插件形態：聲稱經獨立校驗方裁決，指紋守衛否決校驗期間改動了工作區的回合，賬本讓進度與證據在會話中斷後仍可追溯。
- 目錄頁：https://www.skillhub.cn/plugins/lion231226/dsh-verified-progress
- GitHub：https://github.com/lion231226/dsh-verified-progress
