提交信息与 PR 描述
Overview
三个月后排查线上问题时，唯一能救你的就是当时那句提交说明。「fix bug」「update」「修改一些东西」这类信息等于没有信息——既搜不到，也看不出影响面。
本技能产出两类内容：提交信息（简短、可脚本解析、说明改了什么）和 PR 描述（完整、说明为什么改、影响面、怎么验证、怎么回滚）。二者的分工是：提交信息面向搜索与自动化，PR 描述面向 reviewers 与未来的排查者。
When to use
- 用户给了一段 diff / 一批变更，要写 commit message 或 PR 描述。
- 需要把多个零散提交整理成规范的提交序列（拆分或合并建议）。
- 需要生成 changelog 用的条目。
提交信息规范（Conventional Commits）
<type>(<scope>): <subject>
<空行>
<body>
<空行>
<footer>
| type | 用于 |
|---|---|
| feat | 新功能 |
| fix | 修复缺陷 |
| refactor | 重构，不改变外部行为 |
| perf | 性能优化 |
| test | 测试相关 |
| docs | 文档 |
| build / ci | 构建与流水线 |
| chore | 其他杂项 |
| revert | 回滚 |
subject 规则：
- 祈使句、现在时（「add」不是「added」）；中文团队可用中文，但同一仓库必须统一。
- 结尾不加句号；总长 ≤ 72 字符（中文按 ≤ 30 字掌握）。
- 只说「改了什么」，细节留给 body。
body 规则：说为什么改（触发原因、背景），而不是复述 diff；每行 ≤ 100 字符；多个要点用 - 列举。
footer：关联工单（Closes #123）、破坏性变更（BREAKING CHANGE: …）、影响面说明。
PR 描述模板
## 背景 / 为什么改
<一段话：问题是什么、影响谁、为什么现在改>
## 改了什么
- <按模块或逻辑分组，每组一句话>
- …
## 影响面
| 维度 | 说明 |
|---|---|
| 接口契约 | <有无变化，是否向后兼容> |
| 数据结构 | <有无迁移，能否回滚> |
| 配置项 | <新增/变更的配置与默认值> |
| 依赖 | <新增或升级的依赖> |
## 验证方式
- [ ] <具体验证步骤与预期结果>
- [ ] <回归点>
## 回滚方案
<如何回滚；数据变更是否可逆>
## 遗留与后续
<本次未处理、但有计划的事项>
提交拆分建议
一次评审里如果一个提交混了多种改动，应建议拆分：
| 混在一起的内容 | 拆成 |
|---|---|
| 功能 + 格式化 | 分开（格式化单独一个 style/chore） |
| 重构 + 行为变更 | 分开（重构应无行为变化，方便比对） |
| 功能 + 测试 | 可同提交（测试属于该功能），也可分 |
| 多个不相关修复 | 按问题逐个拆 |
关键规则
- 先读 diff 再动笔：不看变更就写说明，等于编造。看不懂变更意图时，标注「需作者补充背景」。
- 不夸大影响面：没动数据库就别写「涉及数据迁移」；不确定就写「未涉及（如需确认请作者核对）」。
- subject 与 body 不重复：body 不写「修改了某某文件」这种 diff 里已经看得到的话。
- 回滚方案必须具体：「回滚此提交」不够，要写清数据/配置是否可逆。
- 敏感信息不入库：提交信息里不写密钥、客户名、内部链接。
- 不编造工单号：没有就留空或写「关联工单：待补」。
自检清单
- [ ] type 与 scope 是否准确？
- [ ] subject 是否 ≤72 字符、祈使句、无句号？
- [ ] body 是否解释了「为什么」而非「改了什么」？
- [ ] PR 描述里影响面四个维度是否都过了一遍？
- [ ] 验证方式是否具体到可执行？
- [ ] 回滚方案是否说明了数据可逆性？
- [ ] 是否有编造的工单号、文件名或影响面？
付费调用（Pay Skill）
本技能按次计费，服务端接入支付宝 AI 按量付费（A2M / HTTP 402 协议）。
- 单次价格：¥0.10 / 次
- 资源接口：
POST https://skillpay-aipay.app.workbuddy.host/skills/pr-commit-writer - 请求体：
{"input": "diff 或变更说明"} - 未付款时返回
HTTP 402与Payment-Needed响应头
买家侧依赖（安装一次即可）
npx -y @alipay/agent-payment@latest install
调用流程（scripts/paid-call.mjs）
node scripts/paid-call.mjs probe --input "$(git diff)" --state-dir .state/pr-commit-writer
node scripts/paid-call.mjs pay --state-dir .state/pr-commit-writer
node scripts/paid-call.mjs complete --state-dir .state/pr-commit-writer --out-shake-no <订单号>
node scripts/paid-call.mjs reset --state-dir .state/pr-commit-writer
脚本只做编排：不接触任何密钥，不自行实现签名或付款。支付后复用同一订单取结果；状态不明时先查单，不重复付款。
