SuperAPI AI 工具集

git

编程与开发

查看项目

更新于 10-31 13:16

技能介绍

用途

这是一个供 AI(尤其是 Claude)在执行期间阅读的 Git 操作参考,目标是实现令牌高效的 Git 操作,涵盖提交/PR 流程,以及用于隔离工作流变更的 git worktree。

主要能力

提交工作流(安全扫描 + 自动拆分)

令牌高效 Git:最多 2-4 次工具调用。

  1. 暂存 + 安全扫描:暂存文件,检查 diff 统计,扫描密钥(api_key|token|password|secret|credential)。若发现密钥:停止,展示匹配项,阻止提交。
  2. 拆分决策:若类型混合(feat+fix)、文件数 >10 且不相关、多个范围(前端+后端)则拆分;若类型/范围相同、文件数 ≤3 且行数 ≤50、逻辑相关则单次提交。
  3. 提交信息:格式为 type(scope): description(少于 72 字符,现在时,祈使句)。类型包括 feat、fix、docs、chore、refactor、test、perf。
  4. 确认 → 提交 → 推送:绝不自动提交或自动推送。展示 git diff --stat 与拟定的提交信息,等待用户明确确认后再执行 git commit;提交后单独询问是否 git push,仅在用户要求时推送。无例外。

PR 工作流

执行 git fetch origin main,查看自 main 以来的提交日志与 diff 统计,然后使用 gh pr create --title "type(scope): description" --body "## Summary\n- bullets\n\n## Test Plan\n- steps" 创建 PR。

输出示例

staged: 3 files (+45/-12 lines) | security: passed | commit: a3f8d92 feat(auth): add token refresh

Worktree 隔离

启动工作流时自动创建 git worktree,所有变更位于隔离分支,失败时丢弃,对主分支零损害。

使用方式

何时使用

  • 自动:/run 且 AF_WORKTREE=true 时
  • 手动:用户说“use a worktree”时
  • 跳过:快速修复、配置变更、单文件编辑

生命周期

worktree_lifecycle[5]{event,action}:

  • run:start → "git worktree add .worktrees/[id] -b af/[id]"
  • Phase 1 approved → 所有编辑在 worktree 目录中进行
  • Phase 5 complete → 提供选项:merge / create PR / keep branch / discard
  • run:cancel → "git worktree remove .worktrees/[id]"
  • run failed → 丢弃 worktree,主分支不受影响

配置

export AF_WORKTREE=true export AF_WORKTREE_DIR=".worktrees" # default

将 .worktrees/ 添加到 .gitignore。

适用场景

适用于需要 AI 辅助执行 Git 提交、创建 PR 以及通过 worktree 隔离工作流变更的场景,尤其适合希望控制令牌消耗、避免密钥泄露、并保持主分支安全的开发流程。

限制与安全规则

safety[4]{rule,reason}:

  • 绝不在有未提交变更时强制删除(用户可能丢失工作)
  • 始终提供 merge/PR/keep/discard 选项(由用户决定)
  • 仅在明确取消/失败时自动丢弃(不要假设)
  • 丢弃前进行检查点提交(最后的恢复机会)

该技能与 phase-checkpoint.cjs 配合使用——检查点是 worktree 分支上的提交,在明确合并前主分支始终不受影响。

人类可读说明参见 docs/architecture/HIERARCHICAL_PLANNING.md 或 docs/getting-started/(视主题而定)。