commit-and-push

提交并推送

输出语言： 使用用户自己的语言回答并编写产物（匹配用户的消息，而非仓库的历史记录）。

概述

分四步，大多数会话只需前两步：

1. 提交 按批次提交工作，让审查者可以逐一阅读
2. 推送 功能分支——绝不推送受保护的分支
3. 同步 MR/PR ——自动更新现有 MR/PR；创建新的 MR/PR 前先询问
4. 打标签并发布 ——仅在确实要发布一个版本时执行

本文件是路由指南；每个阶段都有自己的参考文档：

阶段	内容	参考文档
提交	工作区/分支检查、拆分批次、约定式提交消息、推送	references/commit.md（§0–§3）
MR/PR	基线、选择模板、起草、检测/创建/更新、回读	references/mr-pr.md（§4–§4.5）
发布	了解仓库的版本/标签约定、为已发布的提交打标签、创建/更新发布	references/release.md（§6）
托管平台 CLI	gh/glab 命令，以及会造成实际往返的陷阱	references/host-cli.md
文案风格	每段文案面向的对象，以及措辞的来源	references/voice.md

MR/PR 模板位于 assets/——每个模板包含四个必填部分，以及一个“仅在适用时添加”的列表：feature-to-integration.md 用于准备 QA · integration-to-production.md 用于发布到生产环境 · hotfix-to-production.md 用于热修复。

核心原则：一次提交 = 一项审查者可以独立评估的更改；一个 PR = 一个可交付的故事，并针对需要检查它的人进行说明；一次发布 = 为实际发布的提交打一个标签。

本指南不会取代测试设计判断（参见 test-design）或 TDD 节奏（参见 superpowers:test-driven-development）。

使用时机

• 用户提出提交 / 推送 / “提交并推送” / 起草或打开 PR/MR
• 用户提出打标签 / 发布一个版本 / 发布版本，或推广 MR 刚刚合并
• 工作区混杂着不应放在同一次提交中的多类更改
• PR/MR 需要一段说明，告诉读者如何检查这项工作

不适用的情况： 仅进行审查且无意发布；只设计测试（使用 test-design）。（如果上游关卡提出了审查，而用户拒绝了，请按用户的决定继续。）

铁律（不可协商）

1. NEVER commit or push to a protected branch (default: main, master, pro, test — plus any the repo declares).
2. NEVER mix unrelated changes in one commit.
3. EVERY commit message MUST be `type(scope): subject` (Conventional) and say what changed, not which files.
   Language is free (Chinese/English); the format is not.
4. EVERY PR/MR description MUST tell its reader how to check the work.
5. NEVER create a NEW MR/PR or release without an explicit yes. ALWAYS sync an EXISTING one — that part is automatic.
6. NEVER trust exit 0 after writing an MR/PR body or release notes. Read it back and compare.
7. NEVER invent a version scheme — follow the repo's tag history; if there is none, ask.

违反字面要求就是违背其精神。“只在 test 上快速提交一次”“之后再补充 Test plan”，以及“这次强推没关系”都不符合要求。

调用时的工作流

先声明“正在使用 commit-and-push 来……”，然后为实际要执行的每个步骤创建一个待办事项——通常执行步骤 1–4；仅在工作需要时执行步骤 5–7。

1. 检查工作区、分支和上游（commit.md §0）——如果受保护，则停止。
2. 规划批次（commit.md §1）——展示计划；默认执行，只有在不明确某项更改属于哪个批次时才询问。
3. 逐批提交（commit.md §2）——只暂存当前批次；提交消息说明原因。措辞参考：voice.md，从本次对话而非 Git 历史中采样。
4. 推送功能分支（commit.md §3）——任何强制推送前都要先询问。
5. 起草 MR/PR（mr-pr.md §4）——根据各分支的用途判断 MR 要做什么（准备好进行 QA / 发布到生产环境 / 紧急修复），使用对应的 assets/ 模板，并涵盖基准提交以来的所有提交。
6. 同步 MR/PR（mr-pr.md §4.5）——查找此分支上是否已有 MR/PR，包括已合并的；找到 → 更新并回读；未找到 → 创建前先询问。
7. 打标签并发布（release.md §6）——在用户要求时，或推广 MR 合并且此仓库在合并时发布时执行。

然后汇报：提交记录、推送结果、MR/PR 编号和 URL、发布 URL，以及任何仍未暂存的内容。

常见借口（以及实际情况）

借口	实际情况
“一次大提交更快”	审阅者无法干净地进行二分查找或回滚。按意图分批。
“我就这一次推送来测试”	受保护就是受保护。使用功能分支 + MR。
“测试计划以后再说 / 这很明显”	没有清单，“完成了”只是一种说法，不是事实。
“强制推送可以整理历史记录”	先询问。绝不能推送到受保护分支。
“钩子很烦——用 --no-verify 跳过吧”	修复原因。跳过钩子不等于交付。
“修改钩子拒绝的提交”	该提交从未发生——修改会重写前一个提交。修复后重新提交。
“PR 描述 = 最后一条提交消息”	PR 涵盖整个 baseline..HEAD 的变更。
“提交信息只能用英文才对”	格式固定；语言遵循用户的语言。
“用 Git 历史了解用户的表达习惯”	那些历史记录大多由 AI 编写。应从当前对话中采样。
“提交 .env，这样 CI 才能运行”	绝不能提交密钥。发出警告并保持未暂存。
“MR 已经存在，跳过同步吧”	过时的描述就是错误的说法。每次推送后都要同步现有 MR。
“直接创建 MR，不用问”	创建是公开操作，而且很难撤销。先询问（mr-pr.md §4.5）。
“给分支头打标签”	给已发布的提交打标签——通常是生产环境上的合并提交。
“随便选个版本号”	遵循仓库的标签历史；如果没有历史记录，就先询问。

工具陷阱不是借口——而是你尚不了解的事项。 已验证的 gh/glab 陷阱（-f 与 -F、mr list --state、mr view <branch>、未推送的标签、对现有标签执行 release create）列于 host-cli.md §Traps。运行主机命令前请先阅读。

检查清单

• 不在受保护分支上；上游未受保护
• 每个批次只包含一项更改；每条提交消息均采用 type(scope): subject 格式并说明原因；未暂存任何密钥
• 仅推送到 origin <feature-branch>；未使用未经请求的 --force 或 --no-verify
• 基线 = MR 的目标分支；baseline..HEAD 非空；提交数来自 git rev-list --count（包含合并提交）
• 使用与此 MR 工作内容相符的模板；填写其中四个必填部分；不适用的部分应省略，而不是填入“none”
• 标题和摘要涵盖基线以来的所有提交
• 明确列出已运行和仍未完成的事项；未运行的事项没有标记为已运行
• 已检查此分支是否已有 MR/PR（包括已合并的）：找到了 → 同步更新（ship-to-production 保留原有文字，只刷新数量）；没有 → 先提出请求
• 写入后重新读取 MR/PR 正文并核对——未盲信退出码 0
• （如果要发布）版本遵循仓库的标签历史；已发布的提交已打标签；单独推送标签；已验证发布（release.md §6）