semantic-git

语义化 Git

使用约定式提交格式管理 Git 提交，确保提交原子化且消息简洁。

此技能支持 zagi，旨在与 AI IDE（Cursor 等）配合使用。

工具

• 首选：zagi（更适合 Agent 使用的 Git 界面）。
  • 如果满足以下任一条件，则假设已安装 zagi：
    • Shell 中的 git 被设为 zagi 的别名；或
    • 存在 zagi 可执行文件。
  • 如有疑问，请将 git 视为可能兼容 zagi，并避免使用冷门标志。
  • 即使可以使用 zagi，也要生成普通的 git 命令，并让任何 git → zagi 集成来处理这些命令。
• 备用方案：无法使用 zagi 时使用普通 git。

适用场景

• 将更改提交到 git
• 暂存待提交的文件
• 编写提交消息
• 管理原子提交
• 推送更改前

核心原则

• 原子提交：将相关更改一起暂存并提交。测试应与实现代码一同提交。
• 用户确认：提交前以及开始下一次提交前，始终先征求用户确认。
• 约定式格式：除非另有要求，否则使用约定式提交消息格式（feat、fix 等）。
• 消息简洁：保持消息简短明了。除非更改较复杂，否则省略描述。
• 命令透明：始终展示即将执行的确切 git 命令（这些命令可能由 zagi 通过别名或包装器处理），并询问用户希望：
  • 手动执行这些命令，还是
  • 由 Agent 执行。

提交消息格式

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

类型

• feat：新增功能
• fix：修复错误
• docs：仅更改文档
• style：不影响代码含义的更改（空白字符、格式、缺少分号等）
• refactor：既不修复错误也不添加功能的代码更改
• perf：提升性能的代码更改
• test：添加缺失的测试或修正现有测试
• build：影响构建系统或外部依赖项的更改
• ci：更改 CI 配置文件和脚本
• chore：维护任务（更新构建任务、依赖项等；不更改生产代码）
• revert：撤销先前的提交

破坏性更改

在类型或范围后使用 ! 表示破坏性更改：

• feat!: add new API
• fix(api)!: change response format

主题行

• 使用祈使语气：“add feature”，而不是 “added feature” 或 “adds feature”
• 首字母小写（以专有名词开头时除外）
• 末尾不加句号
• 尽可能控制在 72 个字符以内

正文和页脚

• 除非更改较复杂或需要解释，否则省略正文
• 必要时，简洁说明并引用问题、PR 或文档
• 破坏性更改使用页脚：BREAKING CHANGE: <description>

工作流

1. 实现原子变更：同时编写代码和测试。
   • 仅修改测试时，使用 test:。
2. 运行 CI 检查：暂存前确认类型检查、测试和 lint 均通过。
   • 如果有单个 CI 命令，优先使用它（例如，pnpm ci、npm run ci、just ci）。
   • 如果没有 CI 命令，则分别运行各项检查（类型检查、测试、lint）。
   • 如果任何检查失败，立即停止并报告，不要继续。
3. 暂存原子变更：将相关文件（实现和测试）归为一组。
4. 建议提交消息：根据变更生成一条约定式提交消息。
5. 生成命令：

   • 使用 git 构造明确的 shell 命令（它可能是 zagi 之类的别名或封装），例如：

     git add path/to/file1 path/to/file2
     GIT_AUTHOR_DATE="YYYY-MM-DD HH:MM:SS" \
     GIT_COMMITTER_DATE="YYYY-MM-DD HH:MM:SS" \
     git commit -m "feat: add feature"
     

   • 始终按顺序向用户打印这些命令。

6. 询问执行偏好：
   • 询问用户希望：
     • 自行复制并运行这些命令，还是
     • 由 Agent 运行这些命令。
   • 只有在用户明确批准后才能执行命令。
7. 提交：
   • 执行时，必须严格运行已打印的命令。
   • 遵循用户关于回填时间戳或附加标志的任何指示。
8. 下一次提交：
   • 暂存下一组变更前，先向用户确认上一次提交已完成且用户已了解相关内容。

自动化模式

如果用户要求“继续直到 X”或“自动执行直到 X”：

• 自动进行原子提交，但仍须打印命令。
• 对于每次提交：
  • 显示暂存和提交命令。
  • 可根据用户的自动化请求选择自动执行这些命令。
• 达到 X 时，恢复询问确认。
• X 可以是：指定文件、功能完成、测试通过等。

停止并询问流程

以下情况必须先停止并询问用户：

• 添加类型忽略标记（@ts-ignore、# type: ignore 等）。
• 添加抑制项（ESLint disable、pylint disable 等）。
• 使用 any 类型或类似的类型逃逸方式。
• 不确定如何继续实现。
• 需求不明确。
• 计划执行破坏性 git 操作（reset --hard、checkout .、clean -f、push --force）；优先考虑更安全的替代方案，并说明风险。

示例

简单功能或行为变更：

feat: add user authentication

包含作用范围的功能：

feat(api): add user endpoint

错误修复：

fix: resolve memory leak in cache

破坏性变更：

feat!: migrate to new API version

仅修改测试：

test: improve unit tests for auth service

重构（不改变行为）：

refactor: extract validation logic into separate function

复杂变更（包含正文）：

feat(api): add pagination support

Implements cursor-based pagination for large datasets.
See docs/api/pagination.md for details.

参考资料

详细指南请参阅：

• references/conventional-commits.md – 提交格式和示例
• references/ci-verification.md – CI 检查模式和验证
• references/co-authors.md – 处理 Co-Authored-By 尾注和 zagi 的共同作者剥离