写 PR

完成标准

把 PR 写成 reviewer 可独立判断是否合并的工程结论。格式整齐不算完成；只有正文中的事实能由 diff、源码、命令输出或运行态读回逐项支撑，才算完成。

不得根据 commit 标题拼正文。不得把计划、工具成功回执、构建成功或控制面状态冒充业务验证。缺少关键证据时停止创建/更新 PR，明确缺口并继续执行安全且在范围内的验证；确实无法补齐时把缺口写入正文，不得编造。

强制流程

1. 读取规则与基准案例

先读取仓库 AGENTS.md、PR 模板和分支规则，再查看 references/examples.md 的类型索引，并从中完整读取至少一个匹配当前风险的合成案例。复杂 PR 同时命中两种类型时各读一个；交付链路案例已同时覆盖 CI、部署和跨仓时可只读该案例。不要为了省上下文只读索引摘要。

合成案例是公开安全的写作质量基准，仅用于校准证据密度，不用于复制篇幅、文件名或业务措辞。案例不能证明当前代码、分支、环境或部署状态；当前 PR 的事实必须重新取证。没有完整读取对应案例，不得写 PR。

2. 建立证据包

创建正文前，先在推理或临时草稿中填满以下字段：

证据包不能仅由 git diff --stat、commit message 或既有 PR body组成；必须读取关键 diff/源码及本轮验证输出。

3. 获取 ground truth

至少执行并读取：

• git status --short --branch
• git diff --stat <base>...HEAD
• git diff --name-status <base>...HEAD
• git log --oneline <base>..HEAD
• 关键文件的 diff 与当前行号
• 本轮实际验证输出或验收记录

push 前执行 gh pr view --json state,mergedAt。若分支 PR 已合并，不得继续 push 该分支；新开分支或按用户明确要求处理。

4. 通过类型化门禁

所有 PR 必须满足：

• 正文首屏说明背景/问题、目标和本 PR 的结果。
• 列出关键 file:line，并解释行为变化。
• 验证使用“动作 → 可观察结果 → 证明内容”，包含真实命令或复现场景。
• 明确未验证项、风险和影响边界；没有则说明为何没有。
• 不含凭据、PII、客户隐私、内部连接信息或无关日志。

额外门禁：

• Bug：必须给因果链，并至少提供一项反证/排除依据；只写症状和改动不通过。
• 功能/架构：必须说明现有缺口、关键数据/调用流、设计取舍、兼容性与回滚。
• 前端：必须复跑用户操作链并写修复前后可见结果；lint/build 不能代替交互验证。
• CI/构建：lint 只能证明配置可解析；还需真实构建、产物存在性/内容或 manifest/digest 读回。使用可覆盖 Tag 时，必须用构建当次输出、不可变 digest 或 OCI revision label 把源码 SHA 与产物绑定；只读取“当前 Tag”不能证明它由本 PR 产生，缺少绑定证据时必须明确降级结论。
• 部署：控制面成功不能代替业务验证；至少写目标环境、部署对象、运行态、实际镜像 digest/版本，以及安全 smoke 或明确未执行原因。浮动 Tag 必须同时回读工作负载 imageID，不能用期望 Tag 代替实际运行 digest。
• 跨仓任务：逐仓写职责、PR base/head、依赖顺序、独立验证和最终状态，禁止用一段公共摘要覆盖全部仓库。

任一适用门禁未通过，禁止把 PR 描述成“验证完成”或“已部署”。

5. 撰写正文

按改动选择最小充分结构，不删减证据：

• Bug：问题 → 根因与排除依据 → 改动 → 验证 → 风险/未覆盖项。
• 功能/架构：背景与范围 → 实现 → 关键取舍 → 验证 → 兼容性/回滚/待办。
• CI/部署：目标与现有链路 → 流水线/部署机制 → 跨仓依赖 → 构建与产物证据 → 运行态/业务验证 → 边界与回滚。

多文件映射优先用表格。不要逐 commit 复述，不要粘贴冗长日志，不要使用“优化若干”“本地测试通过”等不可复核表述。

标题用一句中文写清“对象 + 行为 + 结果”，仓库有约定时保留 fix(scope): 等前缀。

关键代码片段

新建或更新的 PR 正文必须包含 ## 关键实现（可用“核心代码”“关键代码”或“实现片段”）章节，并满足：

• 从当前真实 diff/实现中摘取 1–3 个最能解释行为变化的代码或配置片段；不得用伪代码替代。
• 每个片段前标明可定位的 file:line，代码围栏必须带语言标记，如 java、typescript、vue、yaml、sql。
• 单个片段不超过 20 行、合计不超过 60 行，只保留关键条件、数据流、查询或配置；不得整段复制 diff。
• 片段后用一句话解释“这段代码如何改变行为/为何这样取舍”，不能让 Reviewer 自己猜。
• 禁止粘贴凭据、PII、内部地址、生成代码、压缩代码、lockfile 或大段日志；必要值须脱敏。

纯文档或配置 PR 也应摘取最关键的文档/配置片段并使用准确语言标记。历史参考快照可能早于本规则；所有新建或更新的 PR 必须遵守。

Test Case 格式

验证章节中的每个 Test Case 必须使用 GitHub Checkbox，不得改用普通列表或只写一张结果表：

- [x] `mvn test -Dtest=FooTest` → `Tests run: 3, Failures: 0`，故障路径回归通过。
- [ ] UAT 页面保存→刷新→回显：未执行，缺少可用测试账号。
- [ ] 生产 smoke：待部署后执行，本 PR 不声称已上线。

只有本轮已有 ground truth 证明通过的项才能勾选 [x]。失败、未执行、未验证、待部署、跳过或 PENDING 项必须保持 [ ]，并在同一行写清状态和原因。工具返回成功但没有可观察断言的项不得勾选。

历史参考快照用于学习证据密度，可能早于本 Checkbox 格式规则；新建或更新的 PR 必须遵守本节。

正文完成后必须按当前平台运行对应脚本。Windows（PowerShell 7）：

& <skill-dir>\scripts\check-pr-body.ps1 -Body $body -Type <bug|feature|frontend|ci|deploy|cross-repo>

macOS / Linux（Bash）：

<skill-dir>/scripts/check-pr-body.sh --body "$body" --type <bug|feature|frontend|ci|deploy|cross-repo>

两个脚本执行同一组结构门禁，均以退出码 0 表示通过、1 表示正文不通过、2 表示调用参数或运行环境错误。脚本任一 FAIL 都阻止写入 GitHub。脚本只能发现结构性缺证，不能代替人工核对事实；脚本通过后仍须执行本技能的语义门禁。

6. 写入并回查

用允许写入路径中的 UTF-8 body 文件执行 gh pr create --body-file 或 gh pr edit --body-file，避免 PowerShell 多层引号破坏 Markdown。

写入后执行：

gh pr view --json number,title,body,url,state,baseRefName,headRefName

逐项确认 title/body/base/head/state 与预期一致。回查前不得声称 PR 已创建或已更新。

7. 合并或部署后更新事实

如果同一任务继续完成合并、部署或业务验证，PR 正文中不得保留与事实冲突的“待合并/待部署”。在最终回报前更新正文，增加 合并后验证 或 部署结果，写入实际时间点、运行版本/digest、运行态和 smoke；随后再次 gh pr view 回查。

如果不应修改已合并 PR 正文，则按仓库约定追加自包含评论，并在最终回报中明确正文未更新及原因。

最终回报

不得只返回链接。每个 PR 至少回报：

• 仓库、PR 标题、URL、base ← head、状态。
• 一句话核心改动。
• 最关键的本地/运行态验证结果。
• 部署状态、未验证项或剩余边界。

多 PR 按依赖顺序列出，并说明整个链路是否闭环。

发布前失败检查

逐项回答“是”。任何“否”都必须先修正文或补证据：

• Reviewer 不打开外部文档，能否解释为什么改、如何生效？
• 是否至少有关键位置、因果/调用链、设计边界、实跑证据四类信息？
• 每条“通过/完成/部署”是否都有独立 ground truth？
• 是否区分编译、测试、启动、接口、UI、部署和业务 E2E？
• 是否包含来自真实改动、带 file:line 和语言标记的最小关键代码片段，并紧邻解释其作用？
• 验证章节的 Test Case 是否全部使用 Checkbox，且只有已有通过证据的项被勾选？
• 是否写清跨仓依赖、风险、回滚和未验证项？
• 最终回报是否比“PR 链接 + 状态”提供更多可审阅信息？