SuperAPI AI 工具集

commit

编程与开发

查看项目

更新于 10-16 06:09

技能介绍

用途

commit 是一个用于创建 git 提交的 Agent 技能。它把改动文件提交为一次 git commit,提交信息尽量精简,可选带 JIRA 单号前缀。触发方式包括:/commit、commit this、commit my changes。

主要能力

收集上下文

该技能会运行其捆绑脚本,建议在单次 Bash 调用中执行(技能被调用时会显示其基准目录):

bash <skill-base-dir>/scripts/gather-context.sh

该脚本会输出:分支名、从分支名提取的 JIRA 单号候选、git status、最近 5 次提交(用于匹配仓库的提交风格),以及已暂存/未暂存的 diff(超过 400 行会被截断,可通过设置 MAX_DIFF_LINES 调高)。

脚本把 JIRA 单号视为候选而非事实:如果明显不是工单引用则应拒绝(例如 feature/uc-1-gtfs-import 会得到 UC-1,这是用例编号而非工单)。若单号为 none 或被拒绝,会在当前对话最近约 10 条用户消息中扫描 [A-Z]+-\d+ 形式的提及,并使用最近的一个。若仍无结果,则不带前缀继续。

决定暂存内容

查看 git status。如果 $ARGUMENTS 列出了具体路径,只暂存这些路径;否则根据对话上下文暂存明确属于当前任务的文件。不暂存无关改动(notebook 重跑、.gitignore 修改、设置文件等),除非用户明确要求包含,并应把这些无关改动指出来。禁止使用 git add -A 或 git add .,必须按显式路径暂存。

起草提交信息

硬性规则:

  • 首行总长度不超过 100 字符,含 JIRA 前缀。
  • 格式:若找到单号则为 BRO-XX <简短的祈使句摘要>,否则仅为 <简短的祈使句摘要>。
  • 使用祈使语气(“Add”“Fix”“Refactor”),结尾不加句号。
  • 除非改动从 diff 看确实不明显,或带有未来读者需要的约束(变通方案、刻意省略、后续事项),否则不写正文。不确定时省略正文。
  • 若确实需要正文:主题行后空一行,然后写一段紧凑文字或 2–3 条简短要点。不要标题、不要 co-author 尾注、不要营销文案。

提交前确认

通过 AskUserQuestion 询问用户是提交还是取消。该对话框必须自包含——不能依赖工具调用之前打印的文本可见:

  • 在 Commit 选项的 preview 字段中放入完整的起草提交信息。
  • 在问题文本中列出将要暂存的文件,以及刻意不纳入的文件(附一行理由)。
  • 不设单独的“edit”选项。若用户选择 Commit 并附带说明,则按说明微调信息后直接提交,不再询问。若用户通过“Other”作答,则视为重写指示:修改后再次确认。
  • 用户未批准前不要提交。

执行提交

获得批准后:

  • git add <显式路径>
  • git commit -m "$(cat <<'EOF' ... EOF)" —— 始终通过 heredoc 传递信息,以便多行正文正确格式化。
  • 运行 git status 并报告新的 HEAD 短 SHA 与摘要。
  • 若提交因钩子被拒,进入“处理提交钩子失败”流程。

处理提交钩子失败

当 git commit 因 pre-commit 或 commit-msg 钩子失败时,不要放弃,也不要绕过。先分析:

  1. 阅读完整钩子输出,确定实际原因(格式化器、linter、类型检查、测试、密钥扫描、信息策略等)。
  2. 再次运行 git status 与 git diff —— 许多钩子(prettier、black、ruff、eslint --fix、import 排序工具)会就地修复文件并仅以失败提示需要重新暂存。

然后把失败分类:

琐碎——无需询问直接修复

指不可能改变行为或含义的机械性改动:

  • 空白:行尾空白、缺少文件末尾换行、行尾符规范化、制表符与空格
  • 格式化器施加的代码格式(prettier、black、gofmt、rustfmt 等)
  • 自动修复工具完成的 import 排序 / 删除未使用 import
  • 钩子已就地修改、只需重新暂存的文件

对于这些,应用修复(或仅重新暂存钩子修改过的文件——仅限属于本次提交的文件),以同一信息重试 git commit,并简要报告钩子改动了什么。

实质性——先询问

指任何需要判断或真实代码改动的情况:

  • 需要手动改代码的 lint 或类型错误
  • 失败的测试
  • 密钥/凭据检测发现
  • commit-msg 策略拒绝(用户已批准该确切信息——通过 AskUserQuestion 确认调整后的信息,新信息放在确认选项的 preview 中)

对于这些,用 1–3 行总结失败,说明拟采取的修复,并通过 AskUserQuestion 询问是修复、不包含这些改动提交(例如在合理情况下取消暂存问题文件),还是取消。仅在批准后应用修复,然后重试提交。

硬性规则:

  • 绝不传 --no-verify。
  • 绝不 amend —— 以全新 git commit 重试(失败的尝试未产生任何提交)。
  • 若经过 2 次修复尝试后钩子仍失败,停止,展示剩余错误输出,交由用户决定。

参数

$ARGUMENTS 可包含要暂存的显式文件路径,或提交信息的额外上下文。若为空,则从对话中推断。

使用方式

以 /commit、commit this、commit my changes 等形式触发。技能不接受子代理(subagent)。

适用场景与限制

适用于在对话式开发过程中把当前任务的改动提交为一次 git commit,并希望提交信息精简、可选带 JIRA 前缀的场景。限制包括:不使用 git add -A/git add .,需按显式路径暂存;不允许 --no-verify;不允许 amend;遇到需要判断的钩子失败必须先征得用户同意。