docs(harness): commit 规范分两层,squash 用 PR description

AGENTS.md

@@ -100,6 +100,9 @@ uv run --env-file .env ruff check --fix src/你修改的文件.py
   - **同开关联 PR**:开主仓 PR 时同开测试仓 PR,PR 描述互相挂链接(**跨仓链接用 `OneDragon-Anything/<repo>#<N>` 或完整 URL,禁裸 `#N`** —— 裸 `#N` 会被 GitHub 识别成本仓而非目标仓);别让测试仓分支挂着改动却没开 PR(主仓合了才补测试仓 = 漏)。
   - **合并顺序:测试仓先 → 主仓后**(主仓 main 的 test-check clone 测试仓 main,测试仓先合才稳)。
 - 如果用户明确要求切换分支，先 `stash` 当前改动，再切换。
+- **commit message 分两层**(规范依据 [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)):
+  - **单个迭代 commit**:写清这一步干嘛即可,不强制格式;建议带 type 前缀(`fix:` / `docs:` / `chore:` / `wip:`)方便扫,但不要求 scope / 长度 / body。判据:不看 diff 也能知道这步干了啥(✅ `fix: Y 坐标分母` ❌ `update`)。
+  - **需要额外提供 commit message 的 merge**(squash、merge commit 等):**merge 时 review + 编辑 commit message** 按 Conventional Commits(不直接用 PR description 整段)。分工:PR description 给 reviewer(why、关联、CodeRabbit summary 都行);commit message 给 git 历史(精简、规范)。merge 时(网页 squash 框,或 AI 用 `gh pr merge --squash --subject --body`)把默认值(来自 desc)编辑成:`type(scope): subject` + body(开头一段 why,每行 ≤72,不列改动清单;删 review 专用的 CodeRabbit summary / `##` 标题;关联用 footer `Closes #N`)。type ∈ `feat / fix / docs / refactor / test / chore / perf / build / ci / style`,scope = 模块,subject 祈使句 ≤50、无句号,PR/issue 号不进 subject(GitHub squash 自动追加 `(#NNNN)`)。rebase 无 merge commit、无设置,靠 commit 本身规范;没描述的 PR 由 CodeRabbit summary 默认补 commit body,merge 时可不动。
 - Review 关注逻辑错误、运行时崩溃、死循环、资源泄漏；不要为风格问题大改现有代码。
 - 提交 PR 后，review comment 需要逐条回复或修正。
 

skills/zzz-od-dev-pr-finishing/SKILL.md

@@ -12,7 +12,7 @@ description: 当用户要把已开的 PR 推到「完善可合并」、处理 PR
 1. **CI checks**:required 全 pass;**条件触发类 check 的 `skipping` 不算失败**(如打包/签名/发布类 check,PR 上不触发属正常)—— 只看 required 是否绿。
 2. **自动化 review 完成且无新建议**:CodeRabbit 这轮 review 跑完。⚠️ **增量 review 无新建议时,它不建 check run、也不留 review 记录** —— 完成态靠它回复的 issue comment(对 `@coderabbitai review` / 自动 review 的 ack,body `<details>` 里 `✅ Action performed` → `Review finished`)确认,结合 0 unresolved。别因 `reviews` 没新记录 / 没 check run 就以为没 review(见流程 1)。
 3. **讨论区无 unresolved thread**:每条都处理过(每条最终都要 resolve,不留 —— 见流程 2)。
-4. **关联 PR(跨仓)也都 done**:跨仓同分支的关联 PR(如测试仓 PR)也按本 skill 收尾全清;**都 done 才合**(见流程 6)。
+4. **关联 PR(跨仓)也都 done**:跨仓同分支的关联 PR(如测试仓 PR)也按本 skill 收尾全清;**都 done 才合**(见流程 7)。
 
 ## 流程
 
@@ -56,14 +56,23 @@ resolve 前确保 CodeRabbit 对这条「说完话了」,不抢它的判断、
 ### 4. push → 迭代
 每次 push 触发 review 重审 + CI 重跑,**可能新提 comment**。重复 1-3,直到「review 完成 + 无 unresolved + checks 绿」稳定。若连续 2 轮仍冒新 comment 或无法收敛 → 停下来问人,别死循环。
 
-### 5. 合并前
+### 5. merge 前/时整理 commit message(供 squash / merge commit)
+仓库 squash / merge commit 默认用 PR description 作 commit message(`PR_BODY` 取整段 desc,含 CodeRabbit 自动 summary);但 commit message 该符合 Conventional Commits,desc 整段未必符合。**分工:desc 给 reviewer,commit message 给 git 历史** —— commit message 在 merge 那一步 review/edit,不直接用 desc 整段,也不必改 desc(规范见 AGENTS.md「commit message 分两层」):
+- **PR title**(= squash/merge commit 标题):merge 前校验成 `type(scope): subject`(≤50、祈使句);已合规则不动。
+- **commit message body**(merge 时):默认来自 desc(含 CodeRabbit summary、`##` 标题等 review 专用内容);merge 时 review,编辑成规范 —— 开头一段 why(每行 ≤72,不列改动清单),删 review 专用的 CodeRabbit summary / `##` 标题,关联用 footer(`Closes #N`)。
+- **怎么操作**:人 merge 用网页 squash 框 review/edit;AI 用 `gh pr merge <PR> --squash --subject "type(scope): subject" --body "..."`(指定精简 body,覆盖默认 desc)。
+- **没描述的 PR**:CodeRabbit summary 默认补 commit body,merge 时可不动。
+- **关联仓 PR(本项目 zzz-od-test)**:同样在 merge 时整理。
+- AI 不执行 merge(merge 由用户决定);这步只把 commit message 规范讲清,merge 时照做。
+
+### 6. 合并前
 `mergeable` 要 `MERGEABLE`、非 `DIRTY`;dirty → rebase 到目标分支。是否 merge / 合并方式不在本 skill 范围(见 superpowers:finishing-a-development-branch)。
 
 **合并后清理(提示,不主动)**:PR 合并后,可**提示**用户删除该 PR 的本地 + remote 分支(`git branch -d <branch>` + `git push origin --delete <branch>`)。只提示,**不主动执行**——分支可能还在用(回看 / cherry-pick)、或用户想保留,由用户确认时机。`gh pr merge --delete-branch` 会同时删 remote + 本地,但只删当前 PR 的;之前遗留的分支要手动清。
 
-### 6. 关联 PR(跨仓)协同
+### 7. 关联 PR(跨仓)协同
 本项目跨仓:主仓 PR 常带配套**测试仓 PR**(同分支名,主仓描述带测试仓 PR 链接)。
-- **关联 PR 不只看 open PR(由真实事故提炼)**:测试仓改动可能挂在同分支但**没开 PR**(改动没经 review)→ `gh pr list --head <分支>` 查 open PR 为空**不等于**"无配套"。收尾主仓前用 git 验证测试仓同分支有无未合改动:`git -C zzz-od-test fetch https && git -C zzz-od-test log https/main..<同名分支>`(有输出 = 测试仓有未合改动,必须先开 PR 合掉再合主仓,否则主仓 main 的 test-check 跑测试仓 main 缺这些测试 = CI 通过但测试缺失;无输出 = 确实无配套)。
+- **关联 PR 不只看 open PR(由真实事故提炼)**:测试仓改动可能挂在同分支但**没开 PR**(改动没经 review)→ `gh pr list --head <分支>` 查 open PR 为空**不等于**"无配套"。收尾主仓前用 git 验证测试仓同分支有无未合改动:`git -C zzz-od-test fetch origin && git -C zzz-od-test log origin/main..<同名分支>`(有输出 = 测试仓有未合改动,必须先开 PR 合掉再合主仓,否则主仓 main 的 test-check 跑测试仓 main 缺这些测试 = CI 通过但测试缺失;无输出 = 确实无配套)。
 - **一起收尾**:关联 PR 都按本 skill 走(CI/review/unresolved 全清),不只当前 PR。
 - **合并顺序:测试仓先 → 主仓后**。主仓合到 main 后,main 的 `test-check` clone 测试仓 **main**;测试仓先合确保测试改动进测试仓 main,主仓 main CI 才稳(主仓先合 → 主仓 main CI clone 测试仓 main 无新改动 → 测试缺失/失败)。
 - **都 done 才合**:关联 PR 全 green + review pass + 无 unresolved 后,按顺序合(测试仓 → 主仓)。

skills/zzz-od-dev-pr-finishing/design.md

@@ -28,7 +28,16 @@
 8. **push 后不自动触发 = 被 auto-pause(非偶发)**:CodeRabbit 有 `reviews.auto_review.auto_pause_after_reviewed_commits` 机制 —— PR 活跃开发 / 频繁 commit 时**自动暂停** review,之后**每次 push 都不自动触发**(不是偶尔)。检测:PR 有 `Reviews paused` comment(grep body 含 `Reviews paused` / `review paused`)。暂停下两命令语义不同:`@coderabbitai review` = **单次**触发(保持暂停,下次 push 仍不自动);`@coderabbitai resume` = **恢复**自动(之后 push 自动触发,ack `Reviews resumed.`)。ack 里那句「此命令仅在自动 review 暂停时适用」就是在提示当前处于暂停态。预防:调 `.coderabbit.yaml` 的 `auto_pause_after_reviewed_commits` 阈值 / 关闭。实战:PR 2419 从 7-01 起被 auto-pause,故每轮 push 都要手动补 —— 曾误判为「偶尔不触发」,实际是**始终暂停**。
 9. **增量 review 无建议时 API 无痕**:增量 review 没新建议时,CodeRabbit 不建 check run、不留 review 记录,只回复一条 issue comment(`✅ Action performed` / `Review finished`)。故「review 完成」的可靠判据是这条 ack comment 的 body,不是 check run / reviews(实战:PR 2419 增量 review 完成但 API reviews 停在上一天、该 commit 无 CodeRabbit check run)。**手动 @ 后 ack 的演变**:ack comment 先回 `Review triggered`(review 进行中),真正完成后 CodeRabbit **编辑同一条** comment 为 `Review finished`(不另发新 comment)。`triggered` 是中间态 —— 判完成必须看到 `finished`,别把 `triggered` 当结果(实战:PR 2419 bf2ebfea 手动 @ 后 06:38Z 回 triggered,review 完成后同条被编辑成 finished)。
 10. **时区**:GitHub API 时间是 UTC(`Z` 后缀),显示给用户前转本地(维护者 UTC+8);避免时间串造成困惑。
-11. **关联 PR 用 git 验证,不只查 open PR**:`gh pr list --head <分支>` 查 open PR 为空 ≠ 无配套 —— 测试仓改动可能挂在同分支但没开 PR(有改动但没开 PR)。收尾主仓前必须 `git -C zzz-od-test fetch https && git -C zzz-od-test log https/main..<同名分支>` 验证无未合改动。**为什么不用 open PR 判**:PR #2608 收尾时查测试仓同分支 open PR 为空就判"无配套"、直接合了主仓,事后才发现测试仓分支有 11 个未合 commit(有改动、没开 PR)→ 补救才开测试仓 #35。根因:open PR 是「是否已开 PR」的判据,不是「是否有配套改动」的判据;后者要看 git 分支。该方法进 SKILL.md §6;配套的预防约束(开发阶段就同开关联 PR)进 AGENTS.md「提交流程与协作边界」+ development_workflow.md §4(泛化到非游戏流程改动)。
+11. **关联 PR 用 git 验证,不只查 open PR**:`gh pr list --head <分支>` 查 open PR 为空 ≠ 无配套 —— 测试仓改动可能挂在同分支但没开 PR(有改动但没开 PR)。收尾主仓前必须 `git -C zzz-od-test fetch origin && git -C zzz-od-test log origin/main..<同名分支>` 验证无未合改动。**为什么不用 open PR 判**:PR #2608 收尾时查测试仓同分支 open PR 为空就判"无配套"、直接合了主仓,事后才发现测试仓分支有 11 个未合 commit(有改动、没开 PR)→ 补救才开测试仓 #35。根因:open PR 是「是否已开 PR」的判据,不是「是否有配套改动」的判据;后者要看 git 分支。该方法进 SKILL.md §7;配套的预防约束(开发阶段就同开关联 PR)进 AGENTS.md「提交流程与协作边界」+ development_workflow.md §4(泛化到非游戏流程改动)。
+
+12. **commit message 在 merge 时单独定(issue #2615)**:仓库 squash + merge commit 默认用 PR description 作 commit message(`PR_BODY` + `PR_TITLE`),但 commit message 该符合 Conventional Commits,desc 整段(含 CodeRabbit summary)未必符合。**方法论:desc 给 reviewer,commit message 给 git 历史,分工** —— commit message 在 merge 那一步 review/edit,不直接用 desc 整段,也不必改 desc。
+    - **实测(本 PR verify-squash-body 验证)**:squash `PR_BODY` **取整段 PR desc**(含 `##` 标题、CodeRabbit 自动 summary),不截断到第一个 `##`。之前「## 截断」假设错。
+    - **CodeRabbit summary 进 desc**:`.coderabbit.yaml` 的 `high_level_summary` 让 CR 把 `## Summary` 作为 release notes 追加进 PR desc(自己的 `<!-- release notes -->` 标记块,不覆盖用户写的)。对没描述的 PR 有用(补 commit body);有描述的 PR merge 时删掉。
+    - **merge 时操作**:人用网页 squash 框 review/edit;AI 用 `gh pr merge --squash --subject --body` 指定。把默认(= desc 整段)编辑成:subject = `type(scope): subject`,body = why(删 CodeRabbit summary / `##`,关联用 footer `Closes #N`)。
+    - **本项目设置**:squash + merge commit 都 `PR_BODY` + `PR_TITLE`;查询 `gh api repos/<owner>/<repo> --jq '{squash_merge_commit_message, merge_commit_message}'`(admin 可在 GitHub Settings 看,普通 contributor 看不到)。
+    - **规范分层(决策 7)**:单个迭代 commit 宽松 / 需要 commit message 的 merge 严格 Conventional Commits(merge 时编辑成规范),两层规范在 AGENTS.md;本 skill 收尾动作只管 merge 时的 commit message。
+    - **为什么不把七规则写进本 skill**:七规则读者是所有写 commit 的 AI,不止收尾 AI;规范进 AGENTS.md(每会话进 context,单一源),本 skill 只放收尾动作 + 指针。
+    - **AI 不 merge**:只把 commit message 规范讲清,merge 由用户(与现有边界一致)。
 
 ## 落点