前言¶

在 DSH（DeepSeek Harness）裏，一個常見的失敗模式是「過早完成」：智能體編輯了幾個文件，寫完“done”，然後你手動檢查才發現類型檢查失敗、測試沒過。這類錯誤不是語法錯誤，而是邏輯和測試層面的，但智能體已經停止工作，需要人工介入修復。

dsh-proof 的目標是智能體準備結束當前回合的瞬間：它把項目的類型檢查、代碼規範檢查和測試變成一個回合出口條件。只有當這些檢查全部通過，回合才真正結束；否則輸出會被送回智能體，強制其進入修正步驟。

是什麼¶

dsh-proof 是一個爲 DeepSeek Harness 設計的驗證插件，由 NetraDevLPDN 維護。它運行在 Node.js 環境中，依賴 DSH 0.2.1-rc.2 或更高版本（0.3.0 之前）以及 Node.js >= 22.19。

插件本身不做文件修改，而是調用項目已有的檢查命令（typecheck、lint、test 等），在每次編輯後執行。如果檢查失敗，它會通過 agent.steer(...) 通知智能體，阻塞回合結束並觸發修正。默認最多重試 2 次（maxReruns），防止無限循環。

核心能力¶

• 零配置：在擁有 package.json 且包管理器在 PATH 的 Node 項目上，插件可以自動檢測 typecheck、lint、test 或 check 腳本，無需額外配置。
• 有界修正循環：通過 maxReruns 限制重試次數（默認 2），避免因檢查失敗導致無限循環。
• verify 工具：智能體可以在回合內手動調用 verify() 或 verify(only="test") 來執行檢查，返回通過/失敗狀態和輸出。
• 提示區可見：插件會將當前激活的檢查列表寫入提示區，讓智能體知道哪些檢查會阻塞回合。
• 僅主機運行：不依賴瀏覽器或 UI，直接在本地 shell 中執行命令，運行在用戶權限下。

安裝與啓用¶

前置條件¶

• DSH 版本 >=0.2.1-rc.2 <0.3.0（在 engines.dsh 中聲明）。
• Node.js >=22.19。
• 項目中存在 package.json，且至少包含 typecheck、lint、test 或 check 之一，或已顯式配置 checks。
• 包管理器（npm、pnpm、yarn 或 bun）在 PATH 中可用。

Desktop 應用¶

1. 在左側邊欄（如果摺疊，按 Ctrl+B 展開）。
2. 打開「Plugins」面板（在「New session」下方，齒輪圖標）。
3. 點擊「Add plugin」。
4. 輸入 dsh-proof（npm 包名），或從 Releases 頁面下載最新的 .tgz 資源。
5. 勾選信任複選框，安裝，並在需要時重啓 DSH。

注意：desktop profile 由 Electron 應用管理，CLI 的 dsh plugin --profile desktop 命令會被拒絕。

CLI profile（web 或 headless）¶

通過命令行添加插件：

dsh plugin --profile web add dsh-proof

也可以從本地構建包添加：

pnpm install
pnpm test
pnpm pack
dsh plugin --profile web add ./dsh-proof-0.1.3.tgz

添加後需要重啓 profile，因爲 manifest 和導出更改不會熱重載。

典型用法¶

自動運行¶

在智能體執行 write、edit、apply_patch 等操作後，插件會在回合結束時自動觸發檢查流程：

1. 在會話工作目錄中運行所有激活的檢查。
2. 如果全部通過，回合正常結束（輸出中無提示）。
3. 如果檢查失敗，輸出會被髮送回智能體，通過 agent.steer(...) 阻塞回合關閉，並進入修正步驟。
4. 默認最多重試 2 次（maxReruns），超過後停止並記錄警告。

成功時無額外提示，失敗時會在對話中顯示 [Proof gate] 用戶消息，包含失敗命令的輸出，隨後智能體會嘗試修復。

手動調用 verify 工具¶

智能體可以在回合內手動執行檢查：

verify()             # 運行所有檢查
verify(only="test")  # 僅運行名爲 "test" 的檢查

該工具返回對象包含 passed、skipped、cwd、checks[]，並附帶緊湊的文本渲染，展示整體狀態、檢查名稱、退出碼以及失敗時的輸出。

配置¶

默認配置適用於常見的 Node 項目。如需覆蓋，可在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中添加頂層覆蓋：

- id: proof
  config:
    checks:
      - name: typecheck
        command: npm run typecheck
        timeoutMs: 120000
      - name: test
        command: npm test
        timeoutMs: 180000

插件包已自動插入 proof 行，使用 - id: proof 進行覆蓋；如果使用相同 id 再次插入，會在啓動時創建重複項。

配置項說明¶

自動檢測規則¶

插件會根據 lockfile 中的包管理器（pnpm-lock.yaml、yarn.lock、bun.lockb）選擇包管理器，但僅當該包管理器實際在 PATH 中時纔會使用；否則回退到 npm。對應的腳本會被映射爲命令：

• typecheck → npm run typecheck（或檢測到的管理器）
• lint → 對應腳本
• test → 對應腳本
• check → 僅在 typecheck、lint、test 均不存在時使用

工作原理¶

1. 插件監聽會話事件。調用 write、edit、str_replace_editor、apply_patch 等工具會將工作區標記爲已編輯。
2. 在 agent/turn-stopping 階段，如果檢測到文件變更，插件會在會話工作目錄中運行檢查。
3. 檢查失敗時，輸出通過 agent.steer(...) 返回給智能體，迫使智能體在回合結束前修復錯誤。
4. 只有當檢查通過或 maxReruns 用盡時，回合纔會結束（後者會記錄警告）。

安全與注意事項¶

• 檢查是在用戶權限下執行的 shell 命令，運行在 DSH 沙箱之外，類似於你手動運行 npm test。只配置你信任的命令。
• 插件本身不修改文件，但它運行的命令可能會修改文件（例如格式化器、快照更新）。這些命令的輸出對模型可見，避免在檢查中打印敏感信息。

適用場景¶

適合在 DSH 項目中使用，尤其是需要確保智能體輸出的代碼通過類型檢查、Lint 規則和測試的場景。適用於 Node.js 項目，且項目已有相應的檢查腳本。對於非 Node 項目或沒有檢查腳本的倉庫，需要顯式配置 checks 或安裝相關工具。

總結¶

dsh-proof 把項目的靜態檢查和測試變成智能體回合的出口條件，避免「過早完成」導致的隱性錯誤。它支持零配置自動檢測，也支持精細配置，並內置 verify 工具和有界修正循環，適合需要在每次編輯後保證質量的 DSH 場景。

插件目錄頁
GitHub 倉庫