Commit

按模块和功能提交

只创建本地 commit，不 push、不创建 PR、不改写已有历史。先读仓库根 AGENTS.md、.agents/CI-AND-PR.md 与 doc/15-contributing.md §15.9/§15.11。

1. 强制前置门禁

创建任何 commit、调整暂存区或制定最终分组前,必须完整加载并依次执行 .agents/skills/format/SKILL.md 与 .agents/skills/check/SKILL.md:

1. 先记录 git status --short 和完整 diff,根据用户请求确认本次授权 覆盖的文件及其中既有改动是否允许格式化。存在归属不明、其他 Agent 改动或未授权 WIP 时停止询问;/commit 不自动授权格式化这些文件。
2. 再按 /format 检查依赖与平台并执行 tools/format.sh;macOS 使用 该 skill 规定的 Homebrew GNU sed 路径。缺少工具且需要安装依赖时先 征得用户确认;不允许跳过格式化后继续提交。
3. 脏工作树中 tools/format.sh 会在格式化阶段全部成功后,因检测到 tracked diff 打印 Files have changed. 并返回 1;这是预期的差异 状态,不能误判为格式化失败。未完成全部阶段、工具报错或出现其他 非零退出时停止,不得提交。
4. 格式化后对照执行前 diff 重新检查工作树。若触及授权范围外的干净或 已脏文件,报告精确范围并停止,不得提交或回退维护者内容。
5. 再按 /check 检查 cpplint 依赖并执行 tools/check.sh。任何告警 或非零退出都必须停止提交;不得追加过滤、使用 NOLINT 消音或绕过 检查。只有用户另行要求修复时才修改对应源码。
6. 两项门禁都完成后运行 git diff --check,然后才允许进入改动盘点与 分组。最终报告必须列出实际工具版本、命令和结果;不得把缺失、跳过 或失败写成通过。

只要 /format 或 /check 未执行、无法执行或未通过,本 skill 就不得 创建任何 commit。

2. 盘点全部改动

1. 确认位于 VLink 仓库且当前不是 detached HEAD；存在 unresolved conflict 时停止。
2. 同时检查 git status --short、staged/unstaged diff、文件状态和 untracked 文件内容。忽略 ignored 文件，不提交构建产物、缓存、密钥、 token 或与任务无关的个人配置。
3. 结合 .agents/REPO-REFERENCE.md 判断模块职责，并从实际 diff 识别 功能目的；不得只按顶层目录或扩展名机械分组。
4. 已有 staged 内容也必须纳入分析。需要重组 index 时只调整暂存区， 不改写或丢弃工作树内容，并在每一步后核对 staged/unstaged 差异。

3. 制定提交分组

每个 commit 只表达一个可独立说明、独立评审的逻辑变化：

• 不同模块或互不依赖的功能分别提交。
• 同一功能的实现、测试、公开注释、Python/C 导出、示例和文档同步放在 同一 commit，不为追求目录整齐拆散必要同步项。
• 公共基础设施先于依赖它的功能提交；生成文件与其源文件成对提交。
• 行为修复、纯重构、格式整理、CI/构建、Agent 指引分别提交，除非其中 一项是另一项不可分割的组成部分。
• 同一文件含多个独立改动时可按 hunk 分拆暂存；改动相互交叠、无法安全 分拆时保持同组，不修改源码制造拆分。
• 不为减少 commit 数量混合无关内容，也不把一个完整功能切成逐文件碎片。

开始提交前先形成有序分组清单，列出每组目的、type/scope 和文件/hunk。 用户已明确要求自动提交时直接执行；只有改动意图无法从代码判断、发现 疑似敏感信息或无法无损分组时才停止询问。

4. 编写 Commit Message

遵循 type(scope): subject。type、scope、subject 与必要的 body 全部使用英文;代码标识、路径、API 名和错误信息保持原文,与 doc/15-contributing.md §15.11 一致。

• type 从 feat、fix、refactor、perf、docs、test、build、 ci、chore、style、revert 中选择。
• scope 使用仓库现有模块名，如 base、extension、proxy、 module-dds、cli-bag、cmake、agents；不可拆分的跨 scope 改动可省略 scope 或使用 *,但可拆分时不得用 * 掩盖混合提交。
• subject 使用简洁明确的英文祈使句，不加句号且不超过 72 字符；准确 写出行为，不使用 update、adjust、misc fixes、cleanup 等 空泛表述。
• subject 已足够时不写 body。重要行为无法在 subject 中讲清时添加一个 简短英文 body，优先说明原因、用户可见影响、性能/兼容变化或关键约束， 不逐文件复述 diff；每行不超过 72 字符。
• 仅在确有破坏性变更或 issue 时写 BREAKING CHANGE:、Closes:、 Refs: footer，不推测编号。

示例：

ci: standardize GitHub Actions script style
fix(packup): prevent empty config from leaking local scope
docs(agents): add module-aware commit skill

5. 逐组暂存和提交

对每一组依次执行：

1. 暂存前重新读取 git status、目标文件和相关 diff;出现不在分组清单 内的新变化时停止并重新分析,不得覆盖、回退或顺手纳入其他 Agent 的 工作。只暂存该组的明确路径或 hunk，禁止无检查地使用 git add -A、 git add . 或通配整个仓库。
2. 查看完整 git diff --cached 和 --stat，确认没有混入下一组、 ignored/生成垃圾或敏感信息；运行 git diff --cached --check。
3. git commit 前再次确认工作树和 index 未发生并发变化。staged diff 非空且单独成立时再用最终 message 提交。
4. commit hook 失败时不得使用 --no-verify。检查 hook 产生的变化， 修正分组或报告阻塞后再提交。
5. 用 git show --stat --oneline HEAD 核对结果，再处理下一组。不得 amend、rebase、squash 或 reset 已创建的 commit，除非用户明确要求。

本 skill 只额外授权上述强制 /format 与 /check;不要自行执行 cmake、ninja、clang-tidy 或测试二进制,也不要在 commit message 中声称未执行的验证已通过。

6. 完成后报告

输出按顺序排列的 commit hash、subject 和每组核心范围；同时报告剩余 未提交改动及原因,并单列 /format、/check 的实际结果。最后确认未 push、未创建 PR、未改写历史。