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

.coderabbit.yaml

@@ -3,6 +3,19 @@ reviews:
   profile: "chill"
   request_changes_workflow: false
   high_level_summary: true
+  high_level_summary_in_walkthrough: true
+  high_level_summary_instructions: |
+    生成 PR 改动总结时遵循 Keep a Changelog 分类(业界 changelog 标准):
+    1. 用中文。
+    2. 按改动类型分组(只用实际涉及的,没有的跳过):
+       - 新增(Added):新功能
+       - 变更(Changed):现有功能改动
+       - 弃用(Deprecated):即将移除
+       - 移除(Removed):移除的功能
+       - 修复(Fixed):bug 修复
+       - 安全(Security):安全修复
+    3. 每条用动宾结构,一句话说清「改了什么」(what),不写「为什么」(why 由作者在 PR description 写)。
+    4. 只总结实质改动,跳过纯格式 / 琐碎,保持简洁。
   auto_review:
     enabled: true
   tools:

AGENTS.md

@@ -100,6 +100,15 @@ 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 / PR 规范**(依据 [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)):
+  - **单个迭代 commit**(开发过程,会被 squash 压掉):写清这步干嘛即可,不强制格式;建议带 type 前缀(`fix:` / `docs:` / `chore:` / `wip:`)方便扫,但不要求 scope / 长度 / body。判据:不看 diff 也能知道这步干了啥(✅ `fix: Y 坐标分母` ❌ `update`)。
+  - **PR title**:`type(scope): subject`(≤50、祈使句、无句号;type ∈ `feat / fix / docs / refactor / test / chore / perf / build / ci / style`,scope = 模块;PR 号不进 subject,squash 自动追加 `(#NNNN)`)—— = squash/merge commit 标题。
+  - **PR description**(开 PR 时作者写,= commit body):写:
+    - **为什么改**(why):解决什么问题 / 目标 + 非显然的决策(为什么这么做);1-3 句,不写实现细节(how 看代码)。
+    - **改动要点**(what):多个改动**分行**(bullet,每条动宾简短,说清改了什么);可按 新增 / 变更 / 修复 / 移除 分组;只实质改动,不展开 how。
+    - **关联**:`Closes #N`(本仓 issue)/ 测试仓 PR 用 `OneDragon-Anything/zzz-od-test#N`(跨仓全名,禁裸 `#N`)。
+  - **merge 时**:commit message = PR title + description(取整段 desc)。作者按上面写好就直接 merge;不符合规范时(贡献者没按规范写、缺 why 等),合并者 merge 时编辑 commit message(网页 squash 框)按规范编写 —— why + 改动要点 + 关联。
+  - **rebase / 直推**(无 merge commit,不进 squash/merge):靠 commit 本身规范。
 - Review 关注逻辑错误、运行时崩溃、死循环、资源泄漏；不要为风格问题大改现有代码。
 - 提交 PR 后，review comment 需要逐条回复或修正。
 

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

@@ -57,17 +57,23 @@ resolve 前确保 CodeRabbit 对这条「说完话了」,不抢它的判断、
 每次 push 触发 review 重审 + CI 重跑,**可能新提 comment**。重复 1-3,直到「review 完成 + 无 unresolved + checks 绿」稳定。若连续 2 轮仍冒新 comment 或无法收敛 → 停下来问人,别死循环。
 
 ### 5. 合并前
-`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 的;之前遗留的分支要手动清。
+- **review PR title + description**(= commit message):作者按 AGENTS.md「commit / PR 规范」写好;收尾时 review,不符合就改规范:
+  - **title**:`type(scope): subject`(≤50、祈使句);不符合 → `gh pr edit <PR> --title "type(scope): subject"`。
+  - **description**:why + 改动要点 + 关联(= commit body);CodeRabbit summary 不该在 desc(放 comment);不符合 → `gh pr edit <PR> --body "..."` 改规范,或合并者 merge 时编辑 commit message(网页框)。
+  - 关联仓 PR(本项目 zzz-od-test)同样 review。
+- **mergeable** 要 `MERGEABLE`、非 `DIRTY`;dirty → rebase 到目标分支。
+- review + mergeable 都满足即可 merge;**可提示 merge,但不主动**(用户明确要求时才执行);merge 决策见 superpowers:finishing-a-development-branch。
 
 ### 6. 关联 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 --repo OneDragon-Anything/zzz-od-test --head <分支>` 查 open PR 为空**不等于**"无配套"。收尾主仓前用 git 验证测试仓同分支有无未合改动:`git -C zzz-od-test fetch origin && git -C zzz-od-test log origin/main..origin/<同名分支>`(有输出 = 测试仓有未合改动,必须先开 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 后,按顺序合(测试仓 → 主仓)。
 
+## 合并后清理(提示,不主动)
+PR 合并后(主仓 + 关联仓都合),可**提示**用户删除该 PR 的本地 + remote 分支(`git branch -d <branch>` + `git push origin --delete <branch>`)。只提示,**不主动执行**——分支可能还在用(回看 / cherry-pick)、或用户想保留,由用户确认时机。`gh pr merge --delete-branch` 会同时删 remote + 本地,但只删当前 PR 的;之前遗留的分支要手动清。
+
 ## 边界(不做什么)
 - 单条 review 怎么 verify/回复/push back → superpowers:receiving-code-review
 - 实现完成后要不要 merge/开 PR/discard → superpowers:finishing-a-development-branch

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

@@ -28,7 +28,15 @@
 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 --repo OneDragon-Anything/zzz-od-test --head <分支>` 查 open PR 为空 ≠ 无配套 —— 测试仓改动可能挂在同分支但没开 PR(有改动但没开 PR)。收尾主仓前必须 `git -C zzz-od-test fetch origin && git -C zzz-od-test log origin/main..origin/<同名分支>` 验证无未合改动。**为什么不用 open PR 判**:PR #2608 收尾时查测试仓同分支 open PR 为空就判"无配套"、直接合了主仓,事后才发现测试仓分支有 11 个未合 commit(有改动、没开 PR)→ 补救才开测试仓 #35。根因:open PR 是「是否已开 PR」的判据,不是「是否有配套改动」的判据;后者要看 git 分支。该方法进 SKILL.md §6;配套的预防约束(开发阶段就同开关联 PR)进 AGENTS.md「提交流程与协作边界」+ development_workflow.md §4(泛化到非游戏流程改动)。
+
+12. **作者开 PR 写 desc 作 commit body,合并者 review(issue #2615)**:仓库 squash + merge commit 取整段 PR description 作 commit message(`*_title=PR_TITLE`、`*_message=PR_BODY`)。**方法论:作者开 PR 时写好 desc(why + 改动要点 + 关联)作 commit body;合并者 merge 前 review,好就 merge,不好微调**。写 desc 的规范在 AGENTS.md(作者,读者广),本 skill(收尾)只 review 不写。
+    - **实测(本 PR verify-squash-body 验证)**:squash `PR_BODY` **取整段 PR desc**(含 `##` 标题、CodeRabbit summary),不截断到第一个 `##`。之前「## 截断」假设错。
+    - **CodeRabbit summary 配置**:`.coderabbit.yaml` 设 `high_level_summary_in_walkthrough: true` 让 summary 放 comment(不进 PR desc/commit body);`high_level_summary_instructions` 用 Keep a Changelog 分类(Added/Changed/Deprecated/Removed/Fixed/Security)只写 what。why 由作者写(CR 读 diff 给不了 why)。
+    - **本项目设置**:squash + merge commit 都 `*_title=PR_TITLE`、`*_message=PR_BODY`;查询 `gh api repos/<owner>/<repo> --jq '{squash_merge_commit_title, merge_commit_title, squash_merge_commit_message, merge_commit_message}'`(admin 可在 GitHub Settings 看,普通 contributor 看不到)。
+    - **规范分层(决策 7)**:单个迭代 commit 宽松 / 需要 commit message 的 merge 严格 Conventional Commits(作者开 PR 写 desc),两层规范在 AGENTS.md;本 skill 收尾只 review。
+    - **为什么不把写 desc 方法论写进本 skill**:写 desc 读者是所有开 PR 的 AI(不止收尾),规范进 AGENTS.md(单一源);本 skill 只放收尾 review 动作。
+    - **不主动 merge**(用户明确要求时才执行):以 review / 提示为主(与 AGENTS.md「提交流程」一致)。
 
 ## 落点