Pull Request 工作流·免费版
红线
- 不替用户伪造验证结果：没跑过的测试不许写"已测试"，标"待验证"。
- 不执行破坏性 Git 操作：禁止
push --force到共享分支、reset --hard、
删除他人分支等。危险操作只提示命令，由用户自己执行。 - 不隐藏风险：已知问题、未覆盖场景必须写进 PR 描述。
- 不引用任何付费端点/专有服务：只用标准 Git 命令。
何时使用
- 准备提 PR，不知道描述怎么写。
- 改动很大，不确定该不该拆。
- PR 被打了回来，不知道怎么改/怎么回应。
- 想规范团队的提交与 PR 习惯。
反触发（不要用）：
- 只是本地小改动、不需要评审 → 直接提交即可。
- 需要实际执行 push / 创建远程 PR → 涉及外部操作，本技能只生成内容，
由用户确认后自己执行（除非用户明确授权）。
职责边界
- 做：生成标题与描述、建议拆分方案、提供自查清单、协助回应评审。
- 不做：未经确认执行远程操作、伪造测试结果、替用户决定合并。
主流程
第 1 步：看清改动全貌（质检闸 A）
先收集事实，不急着写：
git status # 有哪些改动
git diff --stat # 改动规模
git log --oneline main..HEAD # 本分支提交历史
git diff main...HEAD --stat # 与主干的完整差异
判断三个数：改了几个文件、增删多少行、涉及几个模块。
> 质检闸 A：必须能一句话说清"这个 PR 目的是什么"。
> 说不清 → 大概率该拆，或需求本身没想清楚（可先走头脑风暴）。
第 2 步：判断是否需要拆分（质检闸 B）
| 情况 | 建议 |
|---|---|
| > 400 行有效改动 | 强烈建议拆 |
| 涉及 > 3 个不相关模块 | 建议拆 |
| 混合「重构 + 新功能 + 修 bug」 | 必须拆（重构单独一个 PR） |
| 含大量格式化/自动生成文件 | 单独拆出，或说明为何必须包含 |
| 改动 < 100 行且目标单一 | 不用拆 |
拆分维度（按优先级选）：
- 按关注点：重构 / 新功能 / 修 bug / 文档 分开
- 按层次：数据层 → 逻辑层 → 接口层 → UI 层
- 按可独立发布：能单独上线且不破坏现有功能的先提
> 质检闸 B：若判定需拆，先给出「拆分方案」（每个 PR 一句话 + 依赖顺序），
> 用户确认后再逐个生成描述。
第 3 步：写标题
约定式提交格式（推荐）：
<type>(<scope>): <简要描述>
| type | 用途 |
|---|---|
| feat | 新功能 |
| fix | 修 bug |
| refactor | 重构（不改行为） |
| perf | 性能优化 |
| docs | 文档 |
| test | 测试 |
| chore | 构建/依赖/杂项 |
好标题标准：50 字符内、动词开头、去掉废话。
❌ fix bug
❌ update some files and fix the issue with login
✅ fix(auth): 修复 token 过期后未跳转登录页
✅ feat(export): 支持导出 CSV 格式
第 4 步：写描述（结构化模板）
## 改了什么
- <要点 1>（一句话，说结果不说过程）
- <要点 2>
## 为什么改
<关联 issue #123 / 业务背景 / 之前的痛点>
## 怎么验证
- [ ] 单元测试：`pytest tests/test_xxx.py`
- [ ] 手工步骤：1) 打开 X 2) 点击 Y 3) 预期看到 Z
- [ ] 回归检查：<可能受影响的其他功能>
## 风险与影响
- 影响范围：<哪些模块/接口>
- 破坏性变更：<有/无，有的话写清迁移方式>
- 已知问题：<没解决的，别藏着>
## 备注
<需要 reviewer 特别关注的地方，如"这块我不确定命名是否合适">
写作原则：
- reviewer 时间很贵 → 前三行必须让人看懂在干嘛
- 说结果（"导出速度从 8s 降到 1.2s"）而非过程（"我改了循环"）
- 有截图/前后对比就贴（UI 改动尤其重要）
第 5 步：提交前自查（质检闸 C）
□ 代码能跑起来，没有调试残留（console.log / print / TODO）
□ 新增逻辑有对应测试
□ 既有测试全部通过
□ 没有误提交：密钥、.env、大文件、node_modules、编译产物
□ 提交历史干净（必要时 rebase 整理，但不 force push 共享分支）
□ 分支基于最新的 main（避免合并冲突）
□ 描述里的「怎么验证」步骤自己真的跑过一遍
> 质检闸 C：自查未全绿 → 明确列出未完成项，不生成最终描述。
第 6 步：应对评审意见
| 意见类型 | 回应方式 |
|---|---|
| 事实性错误 | 直接改 + 说明"已修正，原因是…" |
| 风格/偏好 | 若团队有规范就遵守；无规范可讨论，别无意义坚持 |
| 你不理解的要求 | 追问具体场景，别闷头猜着改 |
| 你认为不对的意见 | 摆事实/数据/基准说明，给出取舍，交由 reviewer 定 |
| 要求拆 PR | 按第 2 步的拆分维度拆，别硬顶 |
回应模板：
已处理：改成 <具体做法>，见 commit <hash>。
（若不同意）我的考虑是 <理由>，因为 <数据/场景>。
如果你仍倾向 <原方案>，我可以改，请确认。
常见坑
- 巨型 PR：一次改 2000 行，reviewer 只能走马观花 → 拆。
- 描述等于空：只写"fix bug" → reviewer 得从头读代码，合并慢。
- 混了格式化：自动格式化让 diff 全是噪音 → 单独一个 PR。
- 没说怎么验证：reviewer 不知道从哪下手 → 必写。
- force push 共享分支：会覆盖他人提交 → 禁止。
失败降级
- 改动极简（如改一行配置）→ 标题 + 一句话描述即可，不用完整模板。
- 无法获取 git 信息（非 git 仓库/无权限）→ 请用户贴 diff，基于用户提供内容生成。
- 用户只要标题 → 只生成约定式标题。
依赖
- 标准
git命令行（读取信息用，Bash执行只读命令）。 - 不执行任何写远程的操作（push / force push / 删除分支）除非用户明确要求。
致谢
- 原创免费技能，基于公开通用的约定式提交规范与代码评审最佳实践，
由本技能作者重新组织与本地化撰写。 - 灵感参考 GitHub 社区 "create-pr" 类技能理念，内容全部原创重写。
- 采用 MIT 许可，不依赖任何专有实现或付费服务。
