use-git-agent

Git Agent CLI

加载此技能后，请根据具体情况选择合适的 git-agent 命令—— 不要默认使用 git-agent commit。请使用下方的触发条件表，将 当前情况对应到合适的命令。

何时使用 git-agent

在以下时机使用 git-agent。每种情况对应一个命令：

情况	命令
即将开始涉及多个文件的工作／修改某项功能——查找还有哪些内容会变动	git-agent graph impact [files...]
修改某个函数／类型——想了解它的调用方（依赖它的对象）	git-agent graph impact --symbol <name> 或 git-agent graph callers <symbol>
修改某个函数——想了解它调用了什么	git-agent graph callees <symbol>
定位某个符号，查看其源代码及一跳范围内的邻接项	git-agent graph node <name> 或 git-agent graph query <search>
决定更改后要运行哪些测试	git-agent graph affected [files...]
测试／回归故障——查找引入问题的 Agent 操作	git-agent graph diagnose [symptom] --file <source>
“Agent（或人工）最近改了什么”／审查会话	git-agent graph timeline（--file／--source／--since）
查看单个文件的完整历史，识别重命名，并标记外部编辑	git-agent graph provenance <file>
图查询无结果或看起来已过时	git-agent graph status → git-agent graph sync（或使用 git-agent graph index 完整重建）
怀疑 Event Log 被篡改	git-agent graph verify
准备好提交已暂存的更改	git-agent commit --intent "..."
新建仓库，或尚未配置范围	git-agent init
配置 Provider／API 密钥／模型	git-agent config show／config set <key> <value>

如果情况未列出，请运行 git-agent --help 或 git-agent graph --help。 所有 graph 查询均为只读且可离线运行（不需要大模型或 API 密钥）；只有 commit 和 init --scope 需要 Provider。

修改功能前查找相关文件

准备修改某项功能时——或正在编辑过程中——请询问 git 图谱还有哪些文件与 你正在处理的文件相关。这些文件最可能也需要更新（测试、调用方、同级模块）， 也很容易被遗漏。提供两种分析模式：

协同变更模式（默认）——历史上经常一起变更的文件

# Given the files of a feature, rank the files that usually change with them:
git-agent graph impact application/commit_service.go cmd/commit.go --json

# Given a directory (a whole module/feature area):
git-agent graph impact infrastructure/hook --json

# No arguments: use your CURRENT uncommitted edits as the seeds —
# "given what I've already changed, what else usually moves with it?"
git-agent graph impact --json

阅读 JSON 并据此确定优先级：每个条目都有 seed_matches（与多少个种子文件 共同变更——数值越高，说明该文件与此功能的关联越核心）、 related_to（关联到哪些种子）、coupling_strength 和 score（排名依据）。 如果某个文件的 seed_matches 等于种子文件数量，则它与整个功能紧密耦合； 完成前请打开该文件。首次运行会自动为 git 历史建立索引； 查询可离线运行，无需大模型或 API 密钥。

结构模式——调用或引用指定符号的符号

知道要修改的函数、结构体或类型时，结构模式会遍历 AST，查找直接调用方和引用 （入边——依赖该符号的对象），无需历史记录。传入 --symbol <name>（模式默认为 structural）：

# Find all symbols structurally linked to CommitService:
git-agent graph impact --symbol CommitService --json

# Combine both signals — co-change AND structural — for the richest view:
git-agent graph impact --symbol CommitService --mode combined --json

其 JSON 结构与协同变更模式不同：包含一个 seed_node 对象（其中有该符号的 kind、qualified_name、file_path、行号、列号、is_exported、 return_type），以及一个由结构上关联的符号组成的 impacted 数组。修改特定 函数或类型，并想了解哪些对象直接依赖它时，请使用此模式。

何时使用哪种模式

问题	模式
“我正在编辑这些文件——通常还有什么会一起变动？”	cochange（默认）
“我正在修改这个函数——哪些对象会调用或引用它？”	--symbol <name>（结构模式）
“全部信息都给我——历史记录和 AST”	--symbol <name> --mode combined

请在涉及多个文件的工作开始时主动运行 impact，并在提交前再次运行， 确保没有遗漏任何与更改耦合的内容。

提交工作流

1. 意图 — 根据对话提炼一句话意图。如果没有相关线索，运行 git diff --stat 了解变更内容，然后据此形成意图。

2. 提交 — 运行：

   git-agent commit --intent "..."
   

   首次尝试时不要使用提供商标志。

3. 遇到身份验证错误（401 / 缺少密钥）时 — 使用 --free 重试一次：

   git-agent commit --intent "..." --free
   

4. 如果 --free 也失败 — 引导用户创建 ~/.config/git-agent/config.yml：

   base_url: https://api.openai.com/v1
   api_key: sk-...
   model: gpt-4o
   

   其他受支持的提供商：Cloudflare Workers AI、本地 Ollama。

实用标志

标志	使用场景
--dry-run	用户想在提交前预览消息
--no-stage	用户已暂存特定文件，且不希望自动暂存
--amend	用户想改写最近一次提交消息
--intent "..."	始终设置；让生成的消息聚焦于目标
--co-author "Name <email>"	标注共同作者（可重复）；如果配置中设置了 no_model_co_author，则跳过
--trailer "Key: Value"	添加任意 git trailer（可重复）
--no-attribution	省略默认的 Co-Authored-By: Git Agent trailer
--max-diff-lines N	限制发送给模型的差异行数（0 = 不限）

--amend 和 --no-stage 不能同时使用。

拆分为多个提交

当 AI 规划器检测到逻辑上不同的变更时，git-agent 会自动将已暂存的变更拆分为多个原子提交（最多 5 组）。每组都会分别暂存、提交并通过钩子验证。无需用户操作；这是默认行为。

自动生成作用域

如果项目未配置任何作用域，git-agent 会在规划前根据 git 历史记录自动生成作用域。每个作用域都是一个结构化对象，包含 name 和可选的 description（在生成提交消息时用作 LLM 上下文）。手动触发作用域生成：git-agent init --scope。

要求模型共同作者

在 .git-agent/config.yml（或用户级 / 本地作用域）中设置 require_model_co_author: true，以确保每次提交都带有来自已知 AI 提供商域名的 Co-Authored-By trailer。仅使用默认的 Git Agent 署名 trailer 不满足此要求；只有 anthropic.com、openai.com、google.com 中的域名，以及 model_co_author_domains: 下列出的域名才计入。

启用此标志后，调用方必须显式传入 --co-author "Model Name <email@domain>"。git-agent 会在调用 LLM 前于 CLI 层验证此项；如果缺少该标志，则以代码 1 退出并给出明确提示——不会依赖模型生成 trailer（模型可能弄错大小写或位置）。示例：

git-agent commit --co-author "Claude Opus 4.7 <[email protected]>"

钩子失败

如果提交被阻止（退出代码为 2），请使用更具体的 --intent 重试：

git-agent commit --intent "update module path"

钩子退出代码：0 = 允许，非零 = 阻止。

提交格式

<type>(<scope>): <description>

- <Bullet one>
- <Bullet two>

<Explanation paragraph>

Co-Authored-By: Git Agent <[email protected]>

• 标题：小写，不超过 50 个字符，不带句点
• 项目符号：首字母大写，使用祈使语气，每条不超过 72 个字符；LLM 以 JSON 数组形式生成；trailer 不会进入 LLM 上下文
• 说明：必填，使用句子式大小写；超过 100 个字符的行会换行至约 72 个字符
• 终端输出仅显示说明段落（项目符号会出现在 git 提交正文中，但不会显示在 CLI 输出中）

其他命令

命令	作用
git-agent graph impact [path...]	根据种子文件（文件、目录，或不传参数时的工作树变更）对历史上常一起变更的文件进行排序。查找某项功能变更可能需要修改的其他文件。使用 --json 输出 JSON
git-agent graph impact --symbol <name>	基于 AST 结构分析影响：调用或引用给定符号的符号（入边——依赖它的对象）。--mode combined 会将共同变更和结构分析结果分别放入独立字段
git-agent graph timeline	显示近期的 Agent/人工操作历史（会话、工具、文件）；可使用 --file、--source、--since 筛选
git-agent graph diagnose [symptom] --file <source>	将故障症状追溯到最可能引入问题的 Agent 操作（可疑时间窗口 + 共同变更 + 排序）。--file <source> 用于确定相关文件集（实际上是查找候选项的必需参数）；[symptom] 是可选上下文。添加 --llm 可通过配置的诊断大模型重新排列候选项
git-agent graph provenance <file>	单个文件的重命名感知变更历史：记录每次捕获的变更以及外部变更，并合并重命名前的身份信息
git-agent graph status	显示图索引健康状况和行数（提交、文件、作者、共同变更对、会话、操作）
git-agent graph verify	遍历哈希链式 Event Log 并验证其未被篡改。发现断链时以状态码 4 退出
git-agent graph index	构建/刷新所有派生索引：将 Event Log 重放为各项投影（会话、操作、共同变更），并确保 AST 索引就绪。--reindex 会强制完整重新建立 AST 索引
git-agent graph sync	使各项投影与 Event Log 保持同步（已是最新时不执行操作；否则仅增量重放新事件）
git-agent graph callers <symbol>	调用或引用某个符号的 AST 节点（入边），最多遍历 --depth 层
git-agent graph callees <symbol>	某个符号调用或引用的 AST 节点（出边），最多遍历 --depth 层
git-agent graph node <name>	匹配该名称的符号：每个符号的位置、签名、源码片段，以及一跳调用者/被调用者路径。返回一个数组（每个匹配项对应一个条目）
git-agent graph query <search>	在符号名称、限定名称或签名中进行 FTS5 前缀搜索（例如，process 可匹配 processData）；可使用 --kind 筛选
git-agent graph affected [files...]	查找因给定文件变更而受到传递影响的测试文件（标准输入：git diff --name-only）
git-agent capture	将 Agent 操作记录到图中。设计为 Claude Code PostToolUse 钩子（通过 init --agent-hook 安装）。不会显示在 --help 中
git-agent init	在仓库中初始化 git-agent（生成 scopes、.gitignore，并安装钩子）
git-agent init --agent-hook	安装 Claude Code PostToolUse 钩子，以自动将 Agent 编辑记录到图中
git-agent init --scope	仅重新生成 scopes
git-agent init --user --hook <value>	在用户级配置（~/.config/git-agent/config.yml）中配置钩子，不受任何项目配置影响
git-agent config show	显示解析后的提供方配置
git-agent config set <key> <value>	设置配置值（自动选择作用范围）
git-agent config get <key>	显示配置值及其来源作用范围
git-agent completion <shell>	生成 Shell 补全脚本（bash/zsh/fish/powershell）
git-agent version	显示构建版本

CLI 参考

完整命令参考（所有标志、子命令、配置作用范围、钩子类型）：references/cli.md