---
name: zuix-commit
description: "审查并提交独立 ZUI 扩展项目的改动；用户直接调用本技能即进入提交模式，必要检查通过后直接提交。只要求分析、评审或生成提交信息时保持只读。"
---

# ZUI 扩展项目提交

## 解析所有权与规则

按 [共享工作流](../zuix-standards/references/workflow.md) 解析本次所需上下文并读取适用 `AGENTS.md`，复用仍适用的发现。提交首先需要明确 `extensionRoot` 与实际 `gitRoot`；宿主只在相关联合验证需要时解析。

所有 Git 命令使用 `git -C <gitRoot>`，不要把宿主 `exts/` 符号链接所在仓库当成文件所有者。目标库的目录名、package 名、zui 名只用于定位和理解变更，不用于猜测 commit scope。

从适用的提交规范和最近稳定历史推导 type、scope、语言及首行格式，显式规范优先。正文是否需要以及如何组织按下文“提交信息”判断，不仅根据历史提交是否带正文。历史不足或相互冲突时，报告影响本次提交的不确定性，不硬编码另一项目的前缀。

## 操作边界

先判断用户意图：

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

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

始终遵守：

- 保留已有暂存、未暂存和未跟踪改动，不修改或提交无关内容。
- 不擅自执行 `--amend`、`--no-verify`、push、force push、reset、clean 或删除操作。
- 不修改 `zuiRoot` 的源码、注册、依赖或锁文件；宿主联合验证的生成物和缓存写入遵循共享工作流的验证隔离与批准规则；若用户明确把宿主改动也纳入提交，它属于另一个 Git 根，必须单独分析和提交。
- 遇到未解决冲突、意图不明的 merge/rebase/cherry-pick、多 Git 根混杂，或无法可靠判断提交范围时，停止写操作并请求用户决定。

## 提交信息

除非扩展项目规范另有规定，保留 ZUI 常用语义：`*` 表示修改、`+` 表示新增、`-` 表示移除；按提交的主要目的判断，不按文件 A/M/D 状态机械拆分。标题使用简洁英文祈使句，不添加 emoji、句号或 Agent `Co-authored-by`。

- 标题长度按整行计算（包括 type 和 scope），以约 50 个字符为目标；这是软目标，不为缩短而省略关键信息。
- 默认提供正文；标题已能完整说明的极小改动（如拼写修正）可以省略。需要解释行为变化、原因或注意事项时保留正文。
- 有正文时，第二行留空，正文从第三行开始；用 Markdown 列表（`- `）按逻辑列出主要变更，并说明必要的原因或决策依据。避免逐文件复述 diff，不强制条目数量。
- 变更列表之后按需空一行追加注意事项（英文使用 `Note: ...`），写清兼容性影响、迁移步骤或使用限制及所需行动；验证缺口具体说明未覆盖的场景。没有实际注意事项时省略，不写空泛提醒。
- 正文与标题使用同一语言，以本次提交的实际 diff 和验证结果为依据，不混入其他提交或未提交改动。

示例（首行的 type、scope 和语言仍以扩展项目规范为准）：

```text
<type> <scope>: 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.
```

## 与代码评审技能协作

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

- 将当前候选提交组声明为显式评审范围，不让评审技能重新执行默认范围选择。
- 现有暂存快照只评审 cached 内容；尚未暂存的候选组只评审精确 diff、pathspec 或 hunk；用户明确给出的 revision/range 保留原有语义。不用工作区内容替代被评审快照。
- 不混入其他工作区改动；候选组为空时直接报告无可提交内容，不回退评审未推送提交。
- 确认被当前变更新增引用的兄弟技能和 reference 已在基线中受跟踪，或被纳入同一原子候选组；否则引用断链本身就是 finding。
- 评审阶段保持只读，后续修复和提交仍按本技能的操作边界及已有授权处理；验证统一编排，复用同一候选快照的有效结果，快照变化后重新评审并补充受影响检查。

## 工作流

1. **收集上下文**：并行收集状态、路径和必要历史，不读取全部无关变更内容：
   - `git -C <gitRoot> --no-optional-locks status --short --branch`
   - `git -C <gitRoot> diff --cached --name-status`
   - `git -C <gitRoot> diff --name-status`
   - `git -C <gitRoot> ls-files --others --exclude-standard -z`
   - `git -C <gitRoot> log --oneline -20`

   记录 `extensionRoot` 相对 `gitRoot` 的路径，确认候选文件由该 Git 根拥有。
2. **确定候选范围**：
   - 用户明确指定的文件、hunk、暂存层级或其他提交范围优先。既有暂存快照与该范围不一致时，保留快照，说明差异；处理方式尚未获授权时，先取得许可，不把范围外暂存内容一并提交，也不自行改写暂存区。
   - 用户未指定不同范围且暂存区已有变更时，将现有暂存快照视为用户主动点名的提交范围；忽略未暂存和未跟踪内容，除非用户明确要求纳入。
   - 对暂存快照的范围、逻辑归属或敏感性有疑问时，不改变暂存区，先询问。
   - 暂存区为空且未指定范围时，默认选择当前 `extensionRoot` 内的可提交改动，包括已跟踪文件的增删改和与项目交付相关的未跟踪文件；不要求这些改动必须由当前任务产生。父级 Git 根中的其他项目不自动纳入。
   - 无论默认范围还是用户要求“全部当前改动”，都排除无关生成物和 `.env*`、凭据、token、私钥、私有配置等敏感内容；确有无法可靠判断的内容时，只澄清具体疑点，不把空暂存区或多个目标库本身视为范围不明。
   - 候选范围确定后才读取对应 cached/unstaged diff 或候选未跟踪文件；使用 `--no-ext-diff`，pathspec 始终放在 `--` 后。评审可读取判断所需的基线源码、调用方和测试，不混入候选外的未提交变更内容。
3. **规划原子提交**：先按逻辑目的分组，再应用已推导的 type/scope。
   - 无明显问题的既有暂存快照优先保持为一个提交；用户的主动暂存意图高于通常拆分惯例。
   - 未暂存范围中，不同目标库通常分别提交；共享基础与消费者只有在一个不可分割的功能中才合并。
   - 同一功能涉及新增、修改和删除文件时可以保持一个提交。
   - 需要拆分既有暂存快照时，先说明方案并取得用户许可，不破坏部分暂存内容。
   - 对范围明确的未暂存改动，按逻辑目的自行分组；各组检查通过后依次提交，不要求用户再次选择提交哪组。
4. **审查每组变更**：按“与代码评审技能协作”审查当前候选快照，另外检查提交专属的调试残留、无关文件、生成物和敏感信息。有 confirmed finding 时先按严重度和文件/行号报告，不确定事项单列为风险；只读模式将有问题的 commit message 标记为“修复或明确接受后可用”。仅有提交授权不包含修复；提交模式下，本任务已有仍适用的修复授权时，在评审后完成范围内修复、重新评审和验证，再继续提交。没有修复授权或需要接受未解决问题时，仍由用户决定；修复后重新收集上下文。
5. **执行验证**：始终对候选或暂存的 tracked diff 运行相应 `git diff --check`；未跟踪文本文件使用 `zuix-review` 的等价 whitespace 检查。按候选风险从 `extensionRoot` 实际脚本和规则选择必要检查，复用同一快照的有效结果；快照变化后重新评审并补充受影响验证。宿主联合检查遵循共享工作流的上下文、隔离与批准规则，结果与扩展侧分开。仅有提交授权不包含修复；只读模式不运行会刷新产物或缓存的命令，除非用户明确要求。验证失败时先按第 4 步核对已有修复授权，完成范围内修复并复验；仍有失败时，只有用户明确接受相应风险才继续提交，不绕过 hooks。
6. **输出或提交**：
   - 只读模式有 finding 时先输出 findings，再返回建议分组、scope 推导证据、完整 commit message、验证结果和残余风险，然后停止。
   - 提交模式下直接完成已通过审查和必要验证的组，不停在建议或等待再次确认。存在问题或检查失败时，仅暂停受影响组及其依赖组；相互独立且检查通过的组继续提交，未解决的问题按第 4、5 步处理。
   - 提交模式且暂存区为空时，按组使用 `git -C <gitRoot> add -- <明确路径...>`；不使用 `git add .` 或 `git add -A`。
   - 每次提交前重新检查 cached name-status、完整 cached diff 和 cached `diff --check`，确认只包含当前组且与已评审、已验证快照一致；存在差异时重新评审并补充受影响验证。
   - 用不会触发 shell 插值的文件或标准输入传递完整 message（如 `git -C <gitRoot> commit -F -`），保留标题与正文之间的空行及实际换行；不要截断正文或将换行写成字面量 `\n`。hook 修改文件或提交失败后重新检查状态，不使用 `--no-verify`。
   - 每次提交成功后运行 `git -C <gitRoot> log -1 --format=%B`，核对实际保存的完整 message，确认标题、空行、正文和按需附加的注意事项与预期一致；发现差异时如实报告，不擅自 amend。
7. **确认结果**：运行 `git -C <gitRoot> status --short --branch`，报告每个 commit 的短 hash、标题、scope 依据、验证结果和仍保留的未提交改动。