前言¶
DSH 是面向智能體開發的插件化運行時，同類產品通常只記錄對話，不記錄「需求」和「證據」之間的對應關係。實際用下來會遇到一類麻煩：agent 在總結裏說做完了，但會話日誌裏找不到對應的工具調用、文件或命令；子 agent 改了同一個文件，父會話並不知道。要查就得翻日誌，事後很難追。
dsh-reqtrace 針對的就是這個問題。它是社區開發者 xingyanghaifu 維護的 DSH 插件，歸類在 admin-security，做的事是「requirement-to-evidence audit」：把每條需求映射到會話裏實際出現的工具調用、文件和命令，找出缺失或超出範圍的工作，並順帶審計子 agent 和文件衝突。插件自身不編輯文件、不審批工具、不主動改會話狀態，符合 DSH「一切皆插件」的思路。
下面按安裝、核心功能、用法、注意項介紹。
安裝與啓用¶
插件提供兩種安裝路徑，命令必須按原文使用，不要憑名稱拼接。
從 GitHub 安裝：
dsh plugin --profile desktop add github:xingyanghaifu/dsh-reqtrace
從本地檢出安裝（示例路徑來自 README）：
dsh plugin --profile web add E:\dshwork\dsh-reqtrace
運行環境要求：DSH 版本 >=0.2.1-rc.1 <0.3.0，Node.js ^22.19 或 >=24。裝完打開右側邊欄的「需求對賬 / Requirement Trace」面板即可使用；也可以從權限下拉框旁邊的小文檔圖標進入，或在會話裏執行 /reqtrace。
核心功能¶
插件圍繞「任務清單—驗收項—證據—驗證」這條鏈展開，主要能力有：
1、Live task list。每 2 秒讀取 agent 最新的 todo_write 列表，展示待辦、進行中、已完成的步驟，不調用模型；全部完成後列表摺疊。
2、Checklist。從當前用戶請求中抽出 3 到 8 條驗收項，也可以手動編輯。
3、Evidence mapping。把每條需求映射到會話日誌裏真實出現過的工具調用、文件和命令。
4、Subagent coverage。父級審計包含存活的和已歸檔的子會話、子清單，並在兩個會話改動同一文件或改得不一致時給出警告。
5、Per-requirement verification。針對某條需求輸入命令（例如 npm test），通過 DSH 的 ops_bash 工具執行，結果隨賬本保存並顯示 ✓ / ×；沒有任何東西會自動執行。
6、Close the loop。缺失或未完成項可以發回給 agent，作爲精確的後續指令（Fix with evidence），內容包含原始任務和具體缺口。
7、History first, resume later。點擊歷史任務展開它的清單和證據，不會給當前 agent 發消息、也不切換會話；Continue this task 是顯式獨立動作。
8、Reports。可導出 JSON 或 Markdown，內容包括需求、證據、工具命令、驗證結果和子任務。
9、Audit modes。默認直接模型調用，快速；可選子 agent 複覈（spawn），隔離但更慢更貴。
10、Strict mode。在回合結束時如果明確需求仍缺失，可主動引導 agent。
插件唯一寫入的狀態是本地賬本，以及你顯式觸發的後續 / 驗證動作。
典型用法¶
面板是主要界面，命令是可選補充。典型流程如下：
1、打開右側邊欄的「需求對賬 / Requirement Trace」。
2、如果清單爲空，用 Extract checklist（會消耗 token）。
3、逐條查看每條需求下的證據；懸停命令看目標文件，懸停驗證徽章看輸出。
4、對缺失項點擊 Verify，輸入命令執行，結果保存。
5、要讓 agent 補完缺口，點擊 Ask Agent to finish；要看歷史工作，展開 Task history 下任一條目。
面板之外可用的命令：
/reqtrace audit the current session
/reqtrace history print recent task ledgers
/reqtrace resume list resumable tasks
/reqtrace resume <n> hand a historical checklist to the current agent
/reqtrace clear clear the current session ledger
/reqtrace clear all clear all saved ledgers
配置項¶
在 Settings → 需求對賬 中調整。所有項默認都是關閉或最低閾值，token 消耗由模型調用決定。
| Setting | Default | Meaning |
|---|---|---|
| Auto-audit on turn end | off | Run an audit automatically after a task. Costs tokens. |
| Extract checklist at task start | off | Turn the user message into acceptance items. Costs tokens. |
| Strict mode | off | Steer the agent when a clear requirement is missing. |
| Minimum tool calls | 2 | Shorter tasks do not trigger the reminder. |
| Audit mode | direct | direct or subagent independent review. |
數據與隱私¶
賬本本地保存在 $DSH_HOME/reqtrace/ledgers.json；內存中最多保留 200 個會話，持久化最新的 100 個。插件不上報遙測、不上傳數據；唯一會發起的網絡調用是模型調用，以及你顯式運行的驗證命令（走 DSH 工具管線）。審計和抽取使用配置的 agentDefaultModel；驗證命令與 agent 走同一套 DSH 工具策略 / 審批路徑，且不會被自動啓動。
適用場景與注意事項¶
適合需要在 DSH 會話裏做需求對賬、事後復盤或審計子 agent 的開發者。要注意幾點：
1、插件以當前 DSH 進程權限運行，驗證命令會走同一套工具審批，安裝前應先檢查源碼與許可證。
2、審計基於模型對會話證據的判斷，「聲稱」沒有證據支撐時會被報爲缺失，而不是被信任。
3、驗證按單條需求觸發，不會自動發現正確的命令，也不會把測試結果自動映射到需求。
4、子 agent 審計依賴可用的 spawn provider，不可用時插件會回退到直接調用。
5、這是早期插件（version 0.1.0），賬本 schema 和 UI 可能變化。許可證爲 MIT。
社區目錄頁把插件歸在 admin-security 分類下。DSH 的社區目錄是獨立站點，與 DeepSeek / 幻方沒有官方從屬關係，插件也不是官方應用商店裏的產品。倉庫自帶 33 個測試覆蓋證據收集、prompt 構造、JSON 修復、todo 讀取、子 agent 審計、配置清理、命令註冊、strict 引導、驗證執行和 UI 註冊。
結語¶
dsh-reqtrace 的價值不在替代人工，而在把「agent 做了什麼」和「需求要求什麼」的對照關係固化下來，讓缺口可見、可追、可補。目錄頁見 https://www.skillhub.cn/plugins/xingyanghaifu/dsh-reqtrace ，源碼見 https://github.com/xingyanghaifu/dsh-reqtrace 。
