dsh-evidence-gate

Agent 声称完成前强制验收：装上之后，Agent 不能再空口说完成。

| 优先级 | 状态 | 名称核查 | 形态 | | --- | --- | --- | --- | | S（第一个立项） | MVP 已发布（2026-08-16，51 单测全绿 + 隔离环境五场景验证，见 docs/verification-report.md） | dsh-evidence-gate 未被占用（2026-08-15） | 纯 DSH 插件 |

解决什么问题

Coding Agent 最常见的信任缺口：

• 测试没有真正运行，或只修了表面问题；
• 通过修改测试制造绿色结果；
• 构建失败却声称完成；
• 修改了范围之外的文件；
• 引入 Secret 或调试代码；
• 功能完成但没有留下任何验证证据。

dsh-evidence-gate 在 Agent 准备结束回合（agent/turn-stopping）或为 Goal 盖章时自动执行预定义验收规则：通过则生成结构化"验证回执"（EvidenceReceipt）写入会话日志；失败则不结束会话，把失败原因注入 Agent 继续修复（带重试上限，防死循环）。

核心能力

1. 命令验收：npm test、npm run lint、npm run build 等，经 ctx.jobs 后台执行，超时受控；
2. Git Diff 门禁：allowedPaths / forbiddenPaths / 最大改动文件数 / 最大新增行数；
3. Secret 扫描：对 Diff 增量做出站前扫描；
4. 失败注入：失败摘要经 agent.inject() 回注会话，明确要求"不要通过修改测试规避问题"；
5. 验证回执：Markdown（人读）+ JSON（机器读）双格式；JSON 回执作为持久会话事件入日志，供下游插件消费；
6. Web UI 状态：会话时间线上的通过/失败徽章与检查项明细。

差异化定位

生态里已有三个同概念项目（dsh-verify-judge、dsh-verify-gate、governed-workflow-for-dsh，均 0-2★，详见 docs/research.md），说明需求真实、无人做透。本插件的护城河不是"能验收"，而是：

1. 版本化的 EvidenceReceipt Schema——被 dsh-bakeoff（方案对比）、dsh-smart-router（结果驱动路由）、dsh-agent-autopsy（失败复盘）、project-passport（交接凭证）共同消费的标准格式；
2. Verifier 插件式接口——验收器本身可被第三方扩展；
3. 双验收点——回合级（turn-stopping）与目标级（goal 盖章）同时覆盖。

技术方案概要

挂载点均已核查（证据见 ../../docs/dsh-platform-notes.md）：

| 挂载点 | 用途 | | --- | --- | | agent/turn-stopping（serial） | 回合结束前触发验收；官方 Claude Code Stop hook 桥同点挂载，拦截语义可用 | | goal 域盖章点 | 目标级验收（goal 自带回合上限，与重试上限对齐） | | tools/pre|post-execute（waterfall） | 记录验收期间的工具调用证据 | | ctx.jobs | 运行耗时命令，不阻塞 agent loop | | SessionEventMap 声明合并 | evidence/receipt 持久事件（ignorable: true） | | agent.inject() | 失败结果注入下一步 |

完整设计（回执 Schema、Verifier 接口、配置格式、防规避策略、风险）见 docs/design.md；MVP 实现与验证证据见 docs/verification-report.md。

平台注意（developer preview）：当前 DSH（≤0.1.0-rc.6 / master 47f9438）的 Session.append 尚无写入 ignorable 标记的 API，含回执事件的会话在恢复时会被持久化层 fail-closed 拒绝（官方机制笔记明示 “writers do not yet set ignorable; Session.append gains that surface with its first user”）。需要可恢复会话的 部署请设 receipt.sessionEvent: false（回执仅落盘，不写会话事件）；详见验证报告第 7 节 P1。

MVP 范围

1. 命令执行验收（含超时与退出码判定）；
2. Git Diff 范围与规模检查；
3. Secret 扫描（增量）；
4. 验收失败注入并继续修复（maxRetries 默认 3）；
5. Markdown + JSON 回执，JSON 入会话日志；
6. Web UI 通过/失败徽章。

明确不做（MVP 阶段）：HttpEndpointVerifier、TestResultVerifier 细粒度解析、团队策略同步、回执远程上报。

与现有项目的关系

• 复用官方核心：ctx.jobs、token-meter（成本记录）、会话持久化；
• 下游消费者：dsh-bakeoff、dsh-smart-router、dsh-agent-autopsy、project-passport；
• 共享底座：回执类型随本插件孵化，v1 冻结后抽入 packages/evidence-core（见 ../../docs/shared-foundation.md）。

文档导航

• docs/design.md — 技术设计准备（架构、Schema、配置、防规避、风险）
• docs/research.md — 竞品调研档案与命名核查