zuix-commit

name	zuix-commit
description	分析独立 ZUI 扩展项目的提交范围、生成英文 commit message，或执行明确授权的 Git 提交；按实际 Git 所有权和项目规范操作。

ZUI 扩展项目提交

解析所有权与规则

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

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

从适用的提交规范和最近稳定历史推导 type、scope、语言及格式，显式规范优先。历史不足或相互冲突时，报告影响本次提交的不确定性，不硬编码另一项目的前缀。

操作边界

先判断用户意图：

• 只读模式：用户只要求分析、规划或生成 commit message 时，只读取并返回建议，不运行 git add、git 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。

工作流

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、暂存层级或其他提交范围优先。既有暂存快照与该范围不一致时，保留快照，说明差异；处理方式尚未获授权时，先取得许可，不把范围外暂存内容一并提交，也不自行改写暂存区。
   • 用户未指定不同范围且暂存区已有变更时，将现有暂存快照视为用户主动点名的提交范围；忽略未暂存和未跟踪内容，除非用户明确要求纳入。
   • 对暂存快照的范围、逻辑归属或敏感性有疑问时，不改变暂存区，先询问。
   • 暂存区为空时，只选择用户点名或当前任务直接产生的文件，不默认暂存整个工作区。
   • 用户明确要求“全部当前改动”时，仍排除无关生成物和 .env*、凭据、token、私钥、私有配置等敏感内容。
   • 候选范围确定后才读取对应 cached/unstaged diff 或候选未跟踪文件；使用 --no-ext-diff，pathspec 始终放在 -- 后。评审可读取判断所需的基线源码、调用方和测试，不混入候选外的未提交变更内容。

3. 规划原子提交：先按逻辑目的分组，再应用已推导的 type/scope。

   • 无明显问题的既有暂存快照优先保持为一个提交；用户的主动暂存意图高于通常拆分惯例。
   • 未暂存范围中，不同目标库通常分别提交；共享基础与消费者只有在一个不可分割的功能中才合并。
   • 同一功能涉及新增、修改和删除文件时可以保持一个提交。
   • 需要拆分既有暂存快照时，先说明方案并取得用户许可，不破坏部分暂存内容。

4. 审查每组变更：检查调试残留、明显逻辑错误、遗漏的异常/空值分支、复制错误、公共 API 注释、无关文件、生成物和敏感信息。按文件与行号报告问题；仅有提交授权不包含修复；提交模式下，本任务已有仍适用的修复授权且相应实施确认要求已满足时，在评审后完成范围内修复、重新评审和验证，再继续提交。没有修复授权或需要接受未解决问题时，仍由用户决定；修复后重新收集上下文。

5. 执行验证：始终对候选或暂存变更运行相应 git diff --check。按候选风险从 extensionRoot 实际脚本和规则选择必要检查，复用同一快照的有效结果；快照变化后重新评审并补充受影响验证。宿主联合检查遵循共享工作流的上下文、隔离与批准规则，结果与扩展侧分开。仅有提交授权不包含修复；只读模式不运行会刷新产物或缓存的命令，除非用户明确要求。验证失败时先按第 4 步核对已有修复授权，完成范围内修复并复验；仍有失败时，只有用户明确接受相应风险才继续提交，不绕过 hooks。

6. 输出或提交：

   • 只读模式返回建议分组、scope 推导证据和完整 commit message，然后停止。
   • 提交模式且暂存区为空时，按组使用 git -C <gitRoot> add -- <明确路径...>；不使用 git add . 或 git add -A。
   • 每次提交前重新检查 cached name-status、完整 cached diff 和 cached diff --check，确认只包含当前组且与已评审、已验证快照一致；存在差异时重新评审并补充受影响验证。
   • 用不会触发 shell 插值的参数或标准输入传递 message。hook 修改文件或提交失败后重新检查状态，不使用 --no-verify。

7. 确认结果：运行 git -C <gitRoot> status --short --branch，报告每个 commit 的短 hash、标题、scope 依据、验证结果和仍保留的未提交改动。