AI Agent / 系统课时

实现 Git 工具

实现 Git 工具

本篇实现一个供智能体调用的 Git 工具,让 Agent 能在修改代码前查看仓库状态、分析差异并读取提交历史。完成后,智能体可以基于真实版本信息判断当前代码变化,为后续修改、审查和回滚提供依据。

学习目标

  • 理解智能体为什么需要 Git 工具以及工具职责边界
  • 实现状态、差异和历史查询能力
  • 掌握执行 Git 命令时的安全控制方式

设计 Git 工具能力

Git 工具不应该直接替代开发者操作所有版本管理流程,而应该提供只读的上下文获取能力。智能体最常需要的是三个信息:当前工作区是否有修改、具体修改内容是什么、最近提交记录如何。

典型工具接口可以拆分为三个动作:

工具能力 作用
status 查看未提交文件
diff 查看代码变化
log 查看提交历史

这些信息能够帮助 Agent 判断修改范围,避免在不了解当前状态时直接生成补丁。

实现 Git 查询工具

下面使用 Python 封装 Git 命令,并限制工具只执行预定义操作。示例中省略权限系统,只展示核心调用逻辑。

python
import subprocess


def run_git(command: list[str]) -> str:
    # 只允许固定 Git 查询命令进入执行层
    allowed = {"status", "diff", "log"}
    if command[0] not in allowed:
        raise ValueError("unsupported git command")

    result = subprocess.run(
        ["git", *command],
        capture_output=True,
        text=True,
        check=True,
    )
    return result.stdout


print(run_git(["status", "--short"]))

预期输出

text
 M src/agent.py
?? tests/test_agent.py

工具返回的内容应该作为 Agent 上下文输入,而不是让模型自行猜测仓库状态。

处理差异和历史信息

查看差异时,需要控制返回长度。大型仓库可能产生大量 diff,如果全部发送给模型,会增加上下文成本。

可以增加限制参数:

python
def get_diff(max_lines: int = 200) -> str:
    output = run_git(["diff"])
    return "\n".join(output.splitlines()[:max_lines])

预期结果

text
diff --git a/src/agent.py b/src/agent.py
+def call_tool(name, args):

历史查询通常只需要最近几次提交:

bash
git log --oneline -5

预期输出

text
8fa21ab add tool router
31bd902 implement agent loop

安全边界与常见问题

Git 工具最大的风险不是查询,而是开放执行能力。如果允许模型调用任意 Git 命令,可能出现删除分支、覆盖文件等不可逆操作。

实现时应注意:

  • 默认只开放查询类命令
  • 限制工作目录范围
  • 对返回内容进行长度控制
  • 记录每次工具调用日志

常见问题是智能体看到 diff 后误判修改范围。解决方式是同时提供 status、diff 和 log,让模型拥有完整上下文。

本课总结

  • Git 工具为智能体提供真实代码状态,而不是让模型猜测变化。
  • status、diff、log 是代码修改场景中最核心的只读能力。
  • 工具设计需要限制权限,避免 Agent 执行危险版本操作。

下一课预告

下一课将实现工具参数校验机制,让智能体生成的调用参数在执行前经过严格检查,减少运行错误。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现 Git 工具

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通