前言¶
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 。
