SuperAPI AI 工具集

explain-pr

编程与开发

查看项目

更新于 10-15 17:31

技能介绍

用途:explain-pr 负责从已校验的验证包渲染 PR 正文,并可选地发布。它不审查代码、不重新解读证据、不提高声明上限、不授权合并,也不决定集成。必需章节、可见性规则与措辞上限来自规范验证记录及其校验器。

输入:需要 PR 标识或准备好的 branch/base/head 上下文、规范化工单摘要、冻结的 CandidateRef 与观测到的 provider PR head SHA、已校验的验证包、简洁的代码映射或 diff 事实。缺失或过期的验证包会被拒绝;模拟、跳过或受限的证据不得被写成更强的叙述。当由 ticket-autopilot 调用时,还需 runner 完整的 render-required 请求,并原样保留其 render_request_hash 与 expected_head_sha,不得重算或替换。

渲染:按契约生成标题,包括变更内容与原因、前后行为、代码映射、测试与分类证据、未通过/失败的门禁与残余限制、审查者清单,以及恰好一个前后对比 Mermaid 图。使用验证包中的字面 ID 与处置,便于机器与审查者追溯每条陈述。不得添加禁用措辞或推断 provider 能力。

校验:使用以下命令校验渲染后的正文:

python3 -B "$VERIFICATION_AUDIT_ROOT/scripts/verification_contract.py"
validate-pr <bundle.json> <body.md> --pr-head-sha <observed-sha>

其中 VERIFICATION_AUDIT_ROOT 是从技能目录解析出的绝对 verification-audit 技能根目录,绝不来自仓库 cwd。校验失败时只修复渲染;语义验证包问题退回 verification-audit;head 变更需要重新获取上游证据。

发布:当用户或调度器要求发布时,仅通过所选 provider 适配器更新 PR 正文,读回并重新校验观测到的正文/head。返回正文、校验结果、provider 观测及任何发布错误。绝不合并。

交接:向 runner 返回 render_request_hash、expected_head_sha、rendered_body、同一份已校验 verification_bundle 及绝对 verification_audit_root。由 runner(而非本技能)持久化内容寻址产物、执行 provider 变更/读回,并决定 pr-open 是否可达。