Zui Commit

ZUI 提交

操作边界

先判断用户意图，再执行对应模式：

• 只读模式：用户仅要求分析变更、规划提交、评审或生成 commit message 时，只读取仓库状态并返回建议，不运行 git add、git commit 或其他写操作。明确的只读限制优先于技能的默认行为。
• 提交模式：用户直接调用 /zui-commit、$zui-commit 或要求使用本技能，且没有只读限制，即视为明确提交授权；明确要求提交、保存或入库改动也进入此模式。候选范围确定、审查无问题且必要检查通过后，直接暂存并提交，不再询问是否提交、选择哪组或确认提交信息。

仅讨论或修改本技能、在引用内容中出现技能名称，不构成提交请求。由其他技能引用时沿用用户实际授权，不把开发或评审请求自动升级为提交。

始终遵守以下边界：

• 保留用户已有的暂存、未暂存和未跟踪改动，不修改或提交无关内容。
• 不擅自执行 --amend、--no-verify、push、force push、reset 或清理工作区。
• 遇到未解决冲突、正在进行但意图不明的 merge/rebase/cherry-pick，或无法可靠判断提交范围时，停止写操作并请求用户决定。

提交规范

• 首行格式：<type> <scope>: <description>
  • <type>：* = change、+ = addition、- = removal。按提交的主要语义判断，不按文件的 A/M/D 状态机械拆分；新增功能即使同时修改旧文件，仍可使用 +。
  • <scope>：lib/<name>/ 内的变更使用 <name>；仓库根、开发基础设施或不可拆分的跨库变更使用 proj。
  • <description>：使用简洁的英文祈使句，结尾不加句号。
• 标题长度按整行计算（包括 type 和 scope），以约 50 个字符为目标；这是软目标，不为缩短而省略关键信息。
• 提交信息全部使用英文，不使用 emoji。
• 默认提供正文；标题已能完整说明的极小改动（如拼写修正）可以省略。需要解释行为变化、原因或注意事项时保留正文。
• 有正文时，第二行留空，正文从第三行开始；用 Markdown 列表（- ）按逻辑列出主要变更，并说明必要的原因或决策依据。避免逐文件复述 diff，不强制条目数量。
• 变更列表之后按需空一行追加 Note: ...，写清兼容性影响、迁移步骤或使用限制及所需行动；验证缺口具体说明未覆盖的场景。没有实际注意事项时省略，不写空泛提醒。
• 正文以本次提交的实际 diff 和验证结果为依据，不混入其他提交或未提交改动。
• 不添加 Co-authored-by 等 Agent 相关信息。

示例：

+ form-builder: add textarea option

- Add textarea fields so forms can collect multiline text
- Preserve textarea settings when editing existing fields

Note: Rendering saved textarea fields in the consuming application
has not been verified.

与代码评审技能协作

候选范围、写操作授权、验证编排和最终提交结果始终由本技能负责。审查候选组时，完整读取 ZUI 代码评审，只复用其中与评审阶段有关的只读边界、评审方法、严重度和 findings 输出规则。

• 将当前候选提交组声明为显式评审范围，不让代码评审技能重新执行默认范围选择。
• 现有暂存快照只评审 cached 内容；尚未暂存的候选组只评审精确 diff、pathspec 或 hunk；用户明确给出的 revision/range 保留原有语义。
• 不混入其他工作区改动；候选组为空时直接报告无可提交内容，不回退评审未推送提交。
• 确认所有被当前变更新增引用的兄弟技能和 reference 已在基线中受跟踪，或被纳入同一原子候选组；否则引用断链本身就是 finding。
• 评审阶段保持只读。仅有提交授权时，只允许后续按已确认范围暂存和提交，不包含修复代码、刷新生成物或推送。提交模式下，若本任务已有仍适用的修复授权，且相应实施确认要求已满足，则在评审后完成范围内修复、重新评审和验证，再继续提交；不重复询问是否修复。
• 验证由本技能统一编排；同一候选快照已有的有效结果可以复用，快照变化后必须重新评审并补充受影响验证。

步骤

1. 收集上下文：先并行运行 git --no-optional-locks status --short --branch、git diff --cached --name-status、git diff --name-status、git ls-files --others --exclude-standard -z 和 git log --oneline -10，只收集分层状态、路径和历史，不读取全部无关变更内容。

2. 确定候选范围：

   • 用户明确点名的文件、hunk、暂存层级或其他提交范围优先。若非空暂存快照与该范围不一致，不得把范围外暂存内容一并提交，也不得自行改写暂存区；先说明差异并取得用户对暂存区处理方式的许可，除非当前请求已经明确授权相应的整体调整。
   • 用户未指定不同范围且暂存区已有变更时，将现有暂存快照视为用户主动点名的提交范围；忽略未暂存和未跟踪变更，除非用户明确要求纳入。
   • 对现有暂存快照的范围、逻辑归属或敏感性有任何不确定性时，停止写操作并询问用户，不自行改变暂存区或猜测意图。
   • 暂存区为空且未指定范围时，默认选择当前 ZUI Git 仓库内的可提交改动，包括已跟踪文件的增删改和与项目交付相关的未跟踪文件；不要求这些改动必须由当前任务产生。不进入 exts/ 链接指向的扩展仓库或其他 Git 根收集改动。
   • 无论默认范围还是用户要求“全部当前改动”，都排除无关生成物以及 .env*、凭据、token、私钥、私有配置等敏感内容；确有无法可靠判断的内容时，只澄清具体疑点，不把空暂存区或多个目标库本身视为范围不明。
   • 候选范围确定后，才读取该范围的 git diff --cached --no-ext-diff --find-renames、git diff --no-ext-diff --find-renames 和候选未跟踪文件；pathspec 始终放在 -- 后。不要读取候选范围外的未提交变更内容；评审时仍可只读查看判断所需的基线源码、调用方、测试和引用目标。

3. 规划原子提交：先按逻辑目的分组，再决定 type 和 scope。

   • 现有暂存快照如无明显的范围、逻辑或敏感性问题，优先保持为一个提交；用户的主动暂存意图高于通常的按库拆分惯例。
   • 对尚未暂存、由本技能规划的范围，不同库通常分别提交；仓库级改动通常使用 proj。
   • 同一功能涉及新增、修改和删除文件时可以保持为一个提交。
   • 只有逻辑独立，或没有单一主要语义时，才继续拆分。
   • 已有暂存快照需要拆分时，先说明拆分方案并取得用户许可，再改变暂存区；不得破坏部分暂存内容。
   • 对范围明确的未暂存改动，按逻辑目的自行分组；各组检查通过后依次提交，不要求用户再次选择提交哪组。

4. 审查每组变更：

   • 按“与代码评审技能协作”审查当前候选快照。
   • 另外检查提交专属问题：console.log、console.debug、debugger、临时 alert 等调试残留，无关文件或生成物，source-of-truth 不一致，以及 .env*、凭据、token、私钥和私有配置等疑似敏感信息。

   有 confirmed finding 或疑似敏感信息时先按严重度和文件/行号报告。只读模式将 commit message 标记为“修复或明确接受后可用”；只有剩余变化仍构成独立完整提交时，才另外给出不含问题部分的分组建议。提交模式先核对本任务已有的修复授权；已有适用批准时按前述流程修复，没有修复授权或需要接受未解决问题时，暂停受影响的写操作并由用户决定；不确定事项单列为风险，不冒充 finding。修复或候选范围变化后，重新收集上下文、审查并验证。

5. 执行验证：

   • 始终对候选或暂存的 tracked diff 运行相应的 git diff --check；未跟踪文本文件使用 zui-review 的等价 whitespace 检查。
   • 选择覆盖候选风险的最小充分组合，不机械运行全部命令：
     • 仓库内 .agents/skills/*、skills/* 和 skills-exts/* 使用 skill-creator 的 quick_validate.py 并检查引用；另行解析 agents/openai.yaml，核对界面字段、$skill-name 默认提示及资源路径，因为 quick validator 不覆盖该文件。修改 skills/zui 的脚本或检查器时再运行 pnpm test:skills。
     • 普通 TS/TSX/JS、工具和测试改动通常运行 pnpm check；只有范围窄、目标检查能明确覆盖且完整检查成本不相称时，才改用目标 lint、类型检查及相关 unit/DOM 测试，并说明收窄后的覆盖边界。
     • 公共导出、包元数据、依赖锁、构建脚本、Vite/Tailwind 或分发契约改动增加 pnpm test:build，并在代表性构建未覆盖目标库时增加目标库构建。
     • 文档管线或导航改动仅在隔离快照中增加 pnpm docs:build，因为它会刷新 ignored 的 docs/_ 生成内容；无法隔离时报告未运行及残余风险，不在当前工作区直接执行。CSS 或视觉改动增加目标构建和浏览器/人工视觉验证；浏览器行为、焦点、portal 或无障碍改动增加目标 Chromium E2E 或 pnpm test:e2e。仅在兼容性风险明确时运行跨浏览器测试。
     • 完整 zui 构建、覆盖率和发布级检查只用于构建图、测试基础设施、发布契约等相应高风险变更，不作为每次提交的固定成本。
   • 确认命令实际覆盖候选范围：pnpm check 不覆盖 CSS、文档、dev.ts 和真实浏览器行为，test:build 与 E2E 也只覆盖代表性库。未覆盖部分必须使用目标验证或明确列为残余风险，不能用笼统通过代替。
   • 运行会写入或清理 build/、dist/、docs/_、coverage/、test-results/ 等目录的验证前，先确认现有内容是否属于用户工作，并优先使用精确包含已评审候选快照的隔离副本或显式临时输出。只清理本次创建且路径已确认的临时目录；不得删除、覆盖或自动暂存候选范围外产物。无法安全隔离时先请求许可或报告未运行。
   • 只读模式不运行会刷新生成目录、覆盖率或浏览器结果的命令，除非用户明确要求；提交模式可运行候选所需验证。验证失败时区分本次引入、已有基线和环境问题，不绕过 Git hooks；仅在用户明确接受相应风险后继续提交。

6. 输出或提交：

   • 只读模式：有 finding 时先输出 findings，再返回建议的提交分组、完整 commit message、验证结果和残余风险，然后停止。
   • 提交模式下直接完成已通过审查和必要验证的组，不停在建议或等待再次确认。存在问题或检查失败时，仅暂停受影响组及其依赖组；相互独立且检查通过的组继续提交，未解决的问题按步骤 4、5 处理。
   • 提交模式且暂存区为空：按组使用明确路径暂存，避免笼统执行 git add . 或 git add -A。
   • 每次提交前重新检查 git diff --cached --name-status、完整 cached diff 和 git diff --cached --check，确认暂存区只包含当前组且与已评审、已验证范围一致；任何差异都返回步骤 4 重新审查并补充验证。
   • 使用安全的文件或标准输入传递完整 commit message（如 git commit -F -），保留标题与正文之间的空行及实际换行；不要截断正文或将换行写成字面量 \n。若 hook 修改文件或提交失败，重新检查仓库状态，不使用 --no-verify 绕过。
   • 每次提交成功后运行 git log -1 --format=%B，核对实际保存的完整 message，确认标题、空行、正文和按需附加的注意事项与预期一致；发现差异时如实报告，不擅自 amend。

7. 确认结果：运行 git status --short --branch，报告每个 commit 的短 hash、标题、评审结论、已运行的验证、用户明确接受的问题或风险，以及仍保留的未提交改动。