分步提交

Overview

将已授权的改动组织成粒度适中、依赖明确的提交序列。先分技术边界，再按业务模块与变更目的细分；每笔表达一个完整意图。

一次分步提交请求是一个批次。提交内容可以按模块拆开，整批标题中的简短主题必须固定，不能随模块变化。

何时使用

• 用户要求提交当前改动、按模块或前后端分批提交，或提交并推送。
• 用户仅要求拆分建议时，输出计划而不提交。

不要使用

仅推送已有提交、改写历史或明确要求单笔提交时，不使用本技能。

适用边界

• 提交请求应完成分析和逐笔提交；仅请求拆分建议时只输出计划。展示计划后，不仅为分组再次要求确认。
• 默认只做本地提交；用户已要求推送时，在提交链检查完成后推送。不附带分支创建、合并、PR、发布或历史改写。
• 用户指定的范围、分组和顺序优先；若实际只有一个完整单元，允许只产生一笔，不凑提交数量。
• 与其他提交技能同时使用时，本技能负责分组、顺序和固定批次主题的系列标题；复用适用的检查与交付要求，不沿用其默认单笔提交行为。

拆分标准

技术边界是起点，业务意图与依赖决定最终分组：

前后端默认分开，同一端的无关模块也分开；文件后缀不能替代职责判断。每笔应能用一句具体说明概括，具有完整行为或结构意义，在前置提交存在时可以构建和验证，并有明确的回滚边界。

• 过大则拆： 混合多个无关目标、业务模块，或可独立交付的重构与功能。
• 过小则并： 按文件拆出无独立意义的样式、导入、类型或测试。独立的一行修复仍可成一笔。
• 不以文件数、行数或固定提交数量作硬门槛；大量机械生成文件也可能属于一个单元。

保留必要的原子组合：

• 实现、对应行为测试和必要说明；依赖声明与锁文件；实现运行所必需的最小配置。
• 同次数据库结构变更的基准、增量迁移、纯 schema 映射与迁移测试；独立后端用例另行提交。
• 必须同步的生成输入与输出。生成代码按实际服务或消费端归属，不制造过期合同。
• 同文件的独立改动可按 hunk 拆；共享类型、重命名或跨文件依赖无法分离时，合并最小必要范围并说明原因。

标题格式

标题格式：type(scope): [序号]批次主题：具体说明，例如 feat(database): [1]订单支付：增加支付状态字段及迁移。

• 标准前缀： 优先遵循项目要求；无要求时使用 Conventional Commits。type 按改动选择，scope 表达技术边界或模块，二者可以逐笔变化；不得以批次主题与序号替代标准前缀，也不为统一系列而把所有改动强行标成同一种 type。
• 固定主题： 规划时从完整交付目标选择简短的业务名，记为本批次唯一的 batch_topic。整批所有标题逐字复用它，跨前后端、数据库、配置或多个业务模块也不变。各笔模块名与功能差异写在 scope 或具体说明中，不能重新充当批次主题。
• 序号： 使用 [1]、[2]、[3]，放在标准前缀之后、固定主题之前，按整批实际提交顺序从 1 连续编号；不能因模块变化重置。失败重试不占号；续接同一批次时，从已成功标题恢复原主题与下一个序号。只有用户明确要求另建独立批次时，才另定主题并重新编号，不改写已有历史。
• 标点与空格： 标准前缀后使用半角 : 和一个空格，固定主题后紧接中文 ：。项目明确要求不同的标题格式时，遵循项目要求。

例如，同一批次包含首页发送与思考状态两个模块，先确定 batch_topic = 对话体验：

fix(commercial): [1]对话体验：支持首页一次发送并防止重复提交
feat(commercial): [2]对话体验：接入思考球体并收敛流式反馈

[1]首页对话：…、[2]思考状态：… 在同一批次中不合格：编号连续，但主题已变化。默认格式下应检查 [序号]固定主题： 这一部分；项目要求其他格式时，检查其中对应的部分，不能仅检查序号或 Conventional Commits 格式。

使用说明

1. 确定范围

读取仓库及受影响目录的 AGENTS.md、交付规则与必要的子模块规则。检查当前分支和操作状态，读取 git status --short、暂存与未暂存的完整 diff，以及 git ls-files --others --exclude-standard 列出的待纳入文件。

• 用户指定范围是上限；未指定且已有暂存内容时，默认只处理原暂存内容。没有暂存内容时依据当前任务确定范围，不顺带纳入无关修改。
• 记录初始 HEAD 与暂存边界。重组 index 前，在仓库外保存原暂存差异的二进制补丁或等效快照，特别保留部分暂存文件的精确内容。
• merge、rebase、cherry-pick 未完成或存在冲突时，转入对应流程，不擅自改变操作状态。真实凭证与本地私有配置不纳入提交。

2. 分组与排序

按拆分标准建立提交单元，依据真实依赖排序：前一笔不能引用尚未提交的类型、字段、包或配置。循环依赖通常说明分组过细，合并最小闭环，不擅自重构业务以拆开。

执行前明确本批次唯一的 batch_topic，用它一次性生成所有拟提交标题，再展示顺序、完整标题、文件或 hunk 和前置依赖的简短表格，补充关键验证方式；无需生成仓库内计划文档。检查每行主题完全相同、序号连续后再开始提交。首笔成功后冻结主题；后续调整分组时，只调整 scope、具体说明和尚未提交部分的顺序。

子模块分别规划提交内容，同一交付批次仍共用固定主题与序号；先完成子模块提交，再按项目规则处理主仓库指针与推送顺序。

3. 验证提交链

按项目要求执行适用检查，包括其要求的 OCR、React Doctor、测试及审查轮数例外，不自行增加固定轮数或强制额外工具。

• 审查可覆盖整条预定提交链，再逐笔复用有效结论；内容变化或 hunk 拆分改变中间语义时，定向复核受影响范围。
• 工作区整体验证不等于每个提交快照通过。存在后续未提交内容掩盖缺失依赖的风险时，使用隔离工作树或等效快照验证中间状态；失败则调整分组或依赖。
• 不为纯拆分新增测试，不操作真实数据库验证迁移。如实记录未覆盖的检查；必需检查失败或未解决问题达到项目阻断标准时，先处理再提交受影响单元及其依赖。

4. 逐笔提交

对每个单元重复：

1. 用明确路径、hunk 或精确补丁隔离暂存内容，只调整 index，不覆盖工作区。部分暂存文件不整文件 git add，不以 git add -A 等方式扫入后续单元。
2. 检查完整的 git diff --cached 与 git diff --cached --check，确认本笔范围、依赖和有效审查覆盖；空暂存区不创建提交。
3. 从已确定的 batch_topic 和下一个序号拼接标题，不根据当前模块重新生成主题。提交前核对标题中的主题与固定值逐字相同、序号接续、分隔符符合适用格式；仓库的单条 commitlint 通过不能代替这项批次检查。非简单改动的正文说明目的、主要变化及实际验证，包含项目要求的诊断记录；多行消息用临时文件及 git commit -F 等安全方式传入。
4. 正常提交，不跳过 Hook。成功后读取 git log -1 --format=%s 核对实际标题与计划一致，再推进序号，并核对实际补丁与 hash；Hook 或并行修改改变内容时，复核受影响部分再继续。失败时检查 index 和工作区变化，修复后重新核对，不盲目重试。

最后按实际提交顺序复核整批标题，确认主题始终等于 batch_topic、序号连续，再核对累计差异与授权范围及剩余改动。标题一致性失败时，不能将批次标记为完成或继续推送。暂停时保留未提交内容及原暂存归属，报告无法恢复的边界差异；不自动 amend、reset 或 squash。仅在已授权时常规推送，拒绝后先检查原因，不自动强推。

交付结果

按顺序列出提交 hash、主题和模块，汇总实际检查结果，注明剩余改动及推送状态。部分完成时说明未完成单元和原因。