回执与权威状态绑定
用途:让“完成”这个结论可被第三方独立核对
问题
「问题」小节链接如果结论只是文本(“测试通过”),它无法被验证,也无法防止过期结论被反复引用。必须把结论绑定到不可伪造、可复查的外部状态上。
回执(receipt)的最小字段
「回执(receipt)的最小字段」小节链接| 字段 | 作用 |
|---|---|
commit + branch |
结论针对的确切代码状态 |
diff_digest |
变更范围摘要(文件列表、行数、关键符号) |
checks[] |
每项检查的名称、命令、退出码、耗时、输出摘要(哈希) |
metrics |
用例数、断言数、覆盖率、变异杀伤率等数值 |
environment |
执行环境标识(CI provider + run id,或本机指纹) |
verdict |
四值判定结果与不通过原因列表 |
issued_at / expires_at |
结论时效(代码变了旧回执即失效) |
signature |
由门禁而非 Agent 生成,可校验来源 |
三条硬规则
「三条硬规则」小节链接- 权威状态优先:以 Git 提交与 CI 运行为准。工作区未提交的修改、本地临时运行结果不能作为交付依据。
- 不匹配即失效:当前 HEAD 与回执 commit 不一致 → 结论作废,重新执行。这防止“拿旧绿灯交付新改动”。
- 等价指纹复用:如果两次执行的输入指纹完全一致(同一 commit、同一配置、同一环境镜像),可复用结论以免重复跑;指纹必须覆盖所有影响结果的要素,宁可少复用不可错复用。
为什么“由门禁生成”很关键
「为什么“由门禁生成”很关键」小节链接若 Agent 可以自行编写回执文件,它就成了裁判。签名/生成权必须掌握在 Agent 无法写入的组件里:CI 服务端产出、受保护分支上的检查、或独立验证进程。
与 PR/评审流程集成
「与 PR/评审流程集成」小节链接Agent 提交 → 门禁执行 → 回执写入 PR(由系统而非作者)→ 评审人看回执与 diff → 合并要求:verdict == PASS 且 commit 与 HEAD 一致合并保护规则应要求“最新提交上的通过检查”,而不是“曾经通过过”。
可核对性设计
「可核对性设计」小节链接- 回执中的每一项都应能点开看到原始输出(不是摘要),包括失败堆栈。
- 报告文件与产物保留期要覆盖审计需求。
- 提供“复算”入口:任何人可对同一 commit 重跑门禁并比对结果(一致性验证)。
常见误区
「常见误区」小节链接| 误区 | 修正 |
|---|---|
| 回执由 Agent 自己写 | 由门禁生成并签名 |
| 结论不带 commit | 无法判断是否过期 |
| 用工作区状态出结论 | 必须绑定提交 |
| 复用旧绿灯 | commit 不一致即作废 |
| 指纹漏掉配置或环境 | 等价复用会给出错误绿灯,宁可重跑 |
| 只存结论不存原始输出 | 无法审计与复算 |
延伸阅读
「延伸阅读」小节链接- 本站:fail-closed 门禁设计、四值判定模型
- SLSA / in-toto 等供应链证明框架(关于“证明”与“可验证产物”的公开规范)