前言¶

在 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 仓库