验证关卡 NetraDevLPDN/dsh-proof

dsh-proof

DeepSeek Harness 的验证关卡。
每次编辑后运行 typecheck、lint 和测试 —— 不通过就让智能体继续干活。

功能 • 快速开始 • 用法 • 配置 • 安全 • 文档 • 贡献

=22.19">
=0.2.1-rc.2">

功能

编码智能体最昂贵的失败模式不是语法错误 —— 而是过早收工。智能体改了三个文件，写下「完成」，你手动一查才发现 typecheck 没过，还有两个测试挂了。

dsh-proof 盯准智能体想停下的那一刻：把项目的检查变成回合退出条件。

- Node 项目上零配置，只要包管理器可用。
- 有界纠错循环 —— maxReruns 限制重试次数，不会死循环。
- verify 工具 —— 智能体可以在声称完成之前自己跑一遍同样的检查。
- 提示词段落 —— 智能体知道哪些检查处于启用状态，也知道它们会拦住回合。
- 仅限宿主 —— 没有浏览器 bundle，不依赖 UI。

快速开始

前置条件

- DSH >=0.2.1-rc.2 <0.3.0（在 engines.dsh 中声明）。
- Node.js >=22.19。
- 项目使用的包管理器（npm、pnpm、yarn 或 bun）已加入 PATH。
- 有 package.json，其中至少包含 typecheck、lint、test、check 之一，或者显式配置 checks。

桌面应用

1. 打开左侧边栏（如果已折叠，按 Ctrl+B）。
2. 打开 Plugins 面板（“New session”下方的风车图标）。
3. 点击 Add plugin。
4. 粘贴 release 资源 URL；npm 包发布后，也可以直接填 dsh-proof。
5. 勾选信任复选框，安装；如果提示重启，就重启 DSH。

https://github.com/NetraDevLPDN/dsh-proof/releases/download/v0.1.2/dsh-proof-0.1.2.tgz

desktop 配置档由 Electron 应用管理；命令行会刻意拒绝 dsh plugin --profile desktop。

命令行配置档（web、headless）

dsh plugin --profile web add dsh-proof

或者，从本仓库安装：

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

装完重启配置档：manifest 和导出变更不会热重载。

用法

自动触发

write、edit、apply_patch 或类似调用之后，校验门会在回合结束时激活：

1. 在会话的工作目录里运行各项检查；
2. 全部通过，回合正常结束；
3. 有检查失败，输出经 agent.steer(...) 送回智能体，阻止回合关闭，并开启纠正步骤；
4. maxReruns 限制重试次数（默认 2）。

成功时静默。失败时会在对话里生成一条 [Proof gate] 消息。

verify 工具

verify() # run every check
verify(only="test") # run only the named check

返回 { passed, skipped, cwd, checks[] }，外加一段紧凑的文本渲染：总体状态、检查名、退出码，失败时还有输出。

你会看到什么

- 运行成功时 —— 对话记录里什么都没有；回合直接结束。
- 失败时 —— 一条合成的 [Proof gate] 用户消息，内含失败命令的输出，随后是智能体的下一步。
- 按需调用时 —— verify 工具的结果，带 PASS 或 FAIL。

配置

默认配置在 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

bundle 已经插入了 proof 行。用 - id: proof 覆盖它；再用同一个 id 执行一次 insert，启动时会出现重复项。

| 键 | 默认值 | 用途 |
| enabled | true | 总开关。 |
| autoDetect | true | 在 package.json 里检测 typecheck、lint、test（或 check）。 |
| checks | [] | { name, command, timeoutMs } 列表；优先于自动检测。 |
| cwd | '' | 检查所用的目录；相对于会话目录。 |
| maxReruns | 2 | 每轮最多纠正重试次数（0：只校验，不重试）。 |
| outputChars | 6000 | 返回给模型的最大输出长度。 |
| watchShell | false | 把会改动文件的 shell 命令也视为编辑。 |
| mutatingShellPattern | （内置正则） | 用于判定哪些 shell 命令算编辑的正则。 |
| includeSubagents | false | 对子代理会话也启用校验。 |
| stopOnFirstFailure | true | 第一项检查失败后立即停止。 |

自动检测

包管理器根据锁文件选择（pnpm-lock.yaml、yarn.lock、bun.lockb，都没有则用 npm），但前提是它确实在 PATH 上可用。否则插件回退到 npm。以下脚本会变成命令：

- typecheck → npm run typecheck（或检测到的包管理器）；
- lint → …
- test → …
- check（仅当上面三项都不存在时）。

工作原理

1. 插件监听会话事件。调用 write、edit、str_replace_editor、apply_patch 等工具时，把工作区标记为已编辑。
2. 在 agent/turn-stopping 时，如果文件有改动，就在会话的工作目录里运行检查。
3. 检查失败时，输出会送回智能体，智能体必须先修好才能结束。
4. 只有检查通过，或 maxReruns 用尽（会记录一条警告），这一轮才会在未校验的情况下结束。

安全

这些检查是以你的用户权限、在 DSH 沙箱之外执行的 shell 命令——就像你自己跑 npm test 一样。只配置你信任的命令。

插件本身不改文件。但它运行的命令可能会改（格式化工具、快照更新）。这些输出对模型可见：检查里别打印密钥。

故障排查

- 'pnpm' is not recognized —— 锁文件对应的包管理器不在 PATH 上。插件现在会回退到 npm；否则请安装 pnpm，或用显式 checks 配合 npm。
- Verification skipped —— 没有 package.json，也没配置检查。加一个 test 脚本，或显式配置 checks。
- 编辑后校验没触发 —— 这次编辑可能是通过 pwsh/bash 做的。开启 watchShell: true，或改用编辑工具。
- 检查太慢 —— 调整 timeoutMs，或减少检查项。

已知限制

- 只有已知的编辑工具会触发校验；shell 命令跟踪是可选的启发式。
- 不会自动回滚：插件重试纠正，但不还原文件。
- 检查按顺序执行；测试套件超时就必须调大 timeoutMs。
- 跟踪按会话进行；默认忽略子代理。

开发

pnpm install
pnpm build # tsc → lib/
pnpm test # build + tests (node:test)
pnpm pack # installable archive

结构：

src/index.ts Cordis entry: verify tool, prompt section, hooks
src/gate.ts the gate state machine (testable without DSH)
src/runner.ts bounded command execution
src/types.ts 配置 + 「proof」消息源 src/__tests__/ 单元测试 cordis.patch.yml 打包配置层

参与贡献

欢迎提交 issue 和 pull request。

1. Fork 仓库，新建一个主题分支。
2. 运行 pnpm install 和 pnpm test。
3. 提交信息遵循 Conventional Commits 格式。
4. 发起 pull request，说明行为变更，并列出覆盖这些变更的测试。

CI 在 Ubuntu 和 Windows 上运行。发布步骤见 PUBLISHING.md。

文档

- 更新日志
- 发布指南
- 安全策略
- DSH 插件打包指南

发布

GitHub release 已自动化：推送 v* 标签会触发 release.yml，该工作流运行测试、校验标签与 package.json 是否一致、打包插件，并用 .tgz 产物创建 release。npm 发布仍需手动执行。

许可

MIT。