Agent 开发（四）—— 扩展篇：功能扩展

一、从终端命令到自然语言

1.1 传统 CLI 的痛点

在扩展之前，我们只有一条命令：

commit-agent --stage

这个命令只做一件事：生成 commit message 并提交。如果你想做其他操作——切换分支、查看日志、合并代码——你需要记住另一套命令：

git switch main
git log --oneline -5
git merge feature-x
git reset --soft HEAD~1
git stash push -m "wip"

这里有几个问题：

1. 记忆成本高：每个操作有独立的命令、参数、标志，你需要记住它们的具体写法
2. 组合操作麻烦：想"先 stash 当前工作，再切换到 main 分支，合并 feature，再切回来 pop"——需要 4 条命令串起来
3. 错误成本高：git reset --hard 敲错了就是数据丢失
4. 上下文割裂：每条命令独立执行，没有"状态"，没有"之前发生了什么"

1.2 自然语言交互的优势

把 Git Agent 从"单条命令"升级为"对话式助手"后，上述问题全部消失：

举个例子：

CLI 方式：

git stash push -m "temp work"
git checkout main
git pull origin main
git checkout feature
git stash pop

Agent 方式：

> 帮我暂存当前工作，切到 main 拉取最新，再切回来恢复

Agent 自动决定调用的工具序列：stash_push → switch_branch → ...。

1.3 交互模式的演进

v1（实战篇）            v2（扩展篇）
单向流程                对话式 REPL

CLI 参数 → 执行        你：当前在哪个分支？
                        Agent：当前在 main 分支
                       你：切到 feature-x
                        Agent：已切换到 feature-x
                       你：审查代码变更
                        Agent：调 get_working_diff → 给你分析结果

v1 是"问一次答一次"，v2 是"持续对话，Agent 自主决策"。

二、架构演进：从单向流程到 Agent Loop

2.1 架构变化

v1（实战篇）                          v2（扩展篇）

cli.py → agent.py                     cli.py → agent.py → tools.py
         → llm_client.py                       → llm_client.py (对话历史版)
         → git_utils.py                         → git_utils.py (17 个函数)
         → prompts.py                           → tools.py (NEW: 工具定义 + 调度)
                                                 → prompts.py (多工具提示词)

数据流：
用户输入 → LLM → 文本 → CLI 输出       用户输入 → LLM → 工具调用 → 执行 → 结果回 LLM → 最终回复
                                        ↑_____________________________________________↓
                                                      Agent Loop

核心变化：引入 tools.py 作为工具注册中心，将工具定义和调度逻辑从 llm_client.py 和 agent.py 中分离出来。

2.2 Agent Loop：思考→行动→观察

Agent Loop 是这个架构的灵魂。每次用户输入，Agent 进入一个循环：

用户输入
  │
  ▼
┌─────────────────────────────┐
│  LLM 决策                    │
│  (调用工具 or 回复用户)        │
└──────────┬──────────────────┘
           │
      ┌────┴────┐
      │         │
  调工具      回复文本
      │         │
      ▼         ▼
  执行函数    显示给用户
      │         │
      ▼         │
  结果回传──────┘
  (继续循环)

关键实现（agent.py）：

def run_agent_turn(client, user_input):
    client.add_message("user", user_input)
    tools = get_tool_definitions()

    for _ in range(MAX_TURNS):        # MAX_TURNS = 10 防止无限循环
        response = client.send_with_tools(tools)
        msg = response.choices[0].message

        if msg.tool_calls:
            # 执行每个工具调用
            for tool_call in msg.tool_calls:
                result = execute_tool(tool_call.function.name, args)
                client.add_tool_result(tool_call.id, result)
            # → 继续循环，LLM 基于工具结果再次决策
        else:
            # LLM 返回文本，本轮结束
            return msg.content

为什么需要 MAX_TURNS？

没有上限的话，LLM 可能陷入无限循环——比如连续调用 get_working_diff 10 次而不返回文本。MAX_TURNS=10 确保单轮用户输入最多自动执行 10 步操作，超时后提示用户重新说明需求。

2.3 Conversation History：让 Agent 记住上下文

Agent 需要"记忆"才能进行多轮对话。LLMClient 内部维护一个 messages 列表：

class LLMClient:
    def __init__(self, api_key):
        self.client = OpenAI(api_key=api_key, base_url="https://api.deepseek.com")
        self.messages = []  # 整个会话的消息历史

    def add_message(self, role, content):
        """添加用户/助手/系统消息"""
        self.messages.append({"role": role, "content": content})

    def add_tool_result(self, tool_call_id, content):
        """添加工具执行结果（role='tool'）"""
        self.messages.append({
            "role": "tool",
            "tool_call_id": tool_call_id,
            "content": content,
        })

会话历史的结构：

messages = [
    {"role": "system", "content": AGENT_SYSTEM_PROMPT},
    {"role": "user", "content": "当前在哪个分支？"},
    {"role": "assistant", "content": None, "tool_calls": [...]},   # LLM 决定调工具
    {"role": "tool", "tool_call_id": "...", "content": "main"},    # 工具结果
    {"role": "assistant", "content": "当前在 main 分支"},          # 最终回复
    {"role": "user", "content": "帮我创建一个新分支 test"},
    ...  # 持续增长
]

每次调用 API 时，整个 messages 列表都发给 LLM，LLM 因此知道"之前说过什么、做过什么"。

2.4 tools.py：工具注册中心

tools.py 是新增模块，负责两件事：

1. 工具定义：返回 OpenAI Function Calling 格式的工具列表
2. 工具调度：根据工具名找到对应的 handler 执行

# 工具定义（OpenAI Function Calling 格式）
def get_tool_definitions() -> list:
    return [
        {
            "type": "function",
            "function": {
                "name": "current_branch",
                "description": "查看当前所在的分支名",
                "parameters": {"type": "object", "properties": {}, "required": []}
            }
        },
        {
            "type": "function",
            "function": {
                "name": "create_branch",
                "description": "创建并切换到新分支",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string", "description": "新分支的名称"}
                    },
                    "required": ["name"]
                }
            }
        },
        # ... 共 17 个工具
    ]

# 工具调度（映射到实际函数）
def execute_tool(tool_name, arguments, api_key="", model="deepseek-chat"):
    handlers = {
        "current_branch": lambda: f"当前分支：{current_branch()}",
        "create_branch": lambda: create_branch(arguments["name"]),
        "switch_branch": lambda: switch_branch(arguments["name"]),
        # ...
    }
    handler = handlers.get(tool_name)
    if not handler:
        return f"[ERROR] unknown tool: {tool_name}"
    return handler()

这个调度模式的关键在于：handler 返回的是字符串，这个字符串会通过 add_tool_result() 回传给 LLM。LLM 看到结果后，决定下一步做什么——是继续调工具，还是回复用户。

三、新增工具详解

3.1 分支管理

区分 create 和 switch：实战篇中 create_branch 同时做"创建 + 切换"。扩展篇新增 switch_branch 用于仅切换（git switch），更符合 Git 2.23+ 的推荐用法。

3.2 代码审查与提交

提交流程（Agent 自动执行）：

用户：提交代码
Agent：→ 调 get_working_diff → 看到修改了哪些文件
       → 调 generate_commit_message → 得到 commit message
       → 回复你：
          变更内容：
          README.md | +10
          生成的 commit message：
          feat: 添加用户注册接口
          
          是否提交？(y/n)
用户：确认
Agent：→ 调 commit_changes → 提交成功

这个流程体现了 Agent Loop 的核心价值：一次用户输入触发 LLM 多次工具调用，中间不需要用户干预。只有最终的确认步骤才需要用户参与。

3.3 回溯与变更管理

为什么分开 soft 和 hard？

rollback_to_commit 的 soft 模式会检查是否有未提交的变更——因为 soft reset 保留工作区内容，如果已有未提交变更会导致冲突。而 hard 模式（--hard）正是用来丢弃变更的，所以即使有未提交变更也应该能执行。force_reset 则完全不检查，是一个"我说了算"的逃生舱。

这在 LLM 的系统提示词里明确写了：

对于 destructive 操作（force_reset、discard_changes、hard reset、force delete），
必须告知用户后果并获得明确确认后再调用工具。

3.4 Stash 暂存管理

Stash 是一个典型的多工具协作场景。用户说"我临时切一下分支"时，Agent 应自动判断是否需要先 stash：

> 帮我切到 main 看一下东西，再回来
Agent：当前分支有未提交的变更，我先 stash 一下
       → stash_push("temp before switching to main")
       → switch_branch("main")
       → ... 用户看完 ...
你：好了切回来
Agent：→ switch_branch("feature")
       → stash_pop()

3.5 其他工具

四、REPL 对话式交互的实现

4.1 REPL 循环设计

CLI 入口从 argparse 单命令改为主循环：

def main():
    api_key = os.environ.get("DEEPSEEK_API_KEY")
    if not api_key:
        print("[ERROR] 请设置 DEEPSEEK_API_KEY")
        sys.exit(1)

    client = LLMClient(api_key=api_key, model=args.model)
    client.add_message("system", AGENT_SYSTEM_PROMPT)

    print("Git Agent 已启动（输入 /exit 退出，/help 查看帮助）")

    while True:
        user_input = input("\n> ").strip()

        if user_input == "/exit":
            break
        elif user_input == "/help":
            show_help()
            continue
        elif not user_input:
            continue
        elif user_input == "/clear":
            # 清空历史，但保留 system prompt
            client.messages = [client.messages[0]]
            print("对话历史已清空")
            continue

        response = run_agent_turn(client, user_input)
        print(f"\n{response}")

为什么用 / 开头做命令？ 避免与自然语言冲突。/exit、/help、/clear 都是元操作，不走 Agent Loop。其中 /clear 在长时间的对话后特别有用——上下文窗口满了会导致模型忘记早期对话。

4.2 对话历史管理

随着对话进行，messages 列表不断增长。两个问题：

1. Token 消耗增大：每次 API 调用都发送全部历史
2. 上下文窗口溢出：DeepSeek 是 64K 上下文窗口

目前通过 /clear 手动清理。未来可以：

• 自动截断：保留最近 N 轮对话
• Token 计数：超过阈值时自动 summarize 历史

4.3 保留 CLI 模式

扩展篇保留了 --no-repl 参数，可以用单条命令模式：

commit-agent --no-repl "查看当前分支"
commit-agent --no-repl "创建一个分支叫 test"

这在脚本化和集成场景下有用，REPL 和 CLI 只是交互方式不同，后端 Agent 逻辑完全复用。

五、安全设计

5.1 三层安全机制

5.2 危险操作清单

以下操作在 System Prompt 中被标记为"需用户确认"：

• force_reset — 丢弃所有未提交变更
• discard_changes — 丢弃本地修改（不可恢复）
• rollback_to_commit 的 hard 模式 — 回溯到历史版本
• delete_branch 的 force 模式 — 删除未合并的分支

5.3 状态检查

以下操作在函数层面有安全检查：

六、运行示例

6.1 启动

# 设置 API Key（Windows PowerShell）
$env:DEEPSEEK_API_KEY="sk-xxxx"

# 启动 REPL
commit-agent

6.2 会话示例

Git Agent 已启动（输入 /exit 退出，/help 查看帮助）

> 当前在哪个分支？

当前分支：main

> 创建一个分支叫 feature/login

已创建并切换到分支：feature/login

> 查看最近的提交

提交历史：
abc1234 initial commit

> 审查我的代码变更

（Agent 调 get_working_diff）
变更内容：
login.py | +45  新增登录页面
api.py   | +20  新增登录接口

> 生成 commit message

（Agent 调 generate_commit_message）
[Commit Message] type=feat title=feat: 添加用户登录功能
body:
- 新增登录页面（邮箱+密码）
- 新增登录 API 接口
- 使用 JWT 进行身份认证

是否提交？(y/n)

> y

（Agent 调 commit_changes）
提交成功

> /clear

对话历史已清空

> 切到 main 分支

已切换到分支：main

> 合并 feature/login

合并成功

> /help

Git Agent 可用工具列表：
- get_working_diff: 获取代码变更
- current_branch: 查看当前分支
- create_branch: 创建分支
- switch_branch: 切换分支
- merge_branch: 合并分支
- show_commit_log: 查看提交历史
- ...（共 17 个工具）

> /exit

再见！

七、常见问题

7.1 LLM 不调用正确的工具

这是最常见的问题。可能的原因和对策：

7.2 对话历史越来越长

随着对话进行，messages 列表持续增长，导致：

1. API 调用变慢（token 增加）
2. LLM 注意力分散（历史过长）

解决方法：

• /clear 手动清理
• 自动摘要历史（高级功能，需额外 LLM 调用）

7.3 Agent 陷入循环

LLM 连续多次调用工具而不返回回复。MAX_TURNS=10 防止无限循环。

7.4 Windows 编码

运行前设置环境变量避免终端编码问题：

$env:PYTHONIOENCODING='utf-8'

八、与通用 AI 助手的对比

读完本文你可能会想：既然 Claude、DeepSeek、ChatGPT 这些通用 AI 助手也能读懂并执行 git 命令，为什么还要专门写一个 Agent？

两种方案有本质差异，适用不同场景。以下以本文的 Git Agent 与 Claude Code（命令行 AI 助手）为例对比：

8.1 优势对比

8.2 通用 AI 助手的优势

8.3 选择建议

你的 Agent = 遥控器：一键开电视、调音量、换台，快且准
通用 AI 助手 = 管家：能分析「今晚看什么好」，但调频道你得说一声

什么时候用你的 Agent：

• 高频重复操作：每天提交代码、切分支、合并，形成肌肉记忆
• 标准化流程：团队统一的提交流程（必须先 lint → 再测试 → 再提交）
• 有固定规则：commit 必须符合 Conventional Commits、分支命名规范等
• 团队共享：写好一个 Agent，团队所有人都能用，行为一致

什么时候用通用 AI 助手：

• 复杂一次性操作：回滚到某个特定提交前先检查影响范围
• 需要判断的任务：分析多个分支的差异、审查代码质量、定位 bug
• 跨领域操作：不只改 Git，还要改代码、查文档、调配置
• 探索性工作：不确定该做什么，需要 AI 给建议

8.4 也可以组合使用

两者不是二选一的关系。实际工作流中完全可以结合：

日常开发 → 用你的 Git Agent 快速提交、切分支
遇到复杂问题 → 用通用 AI 助手分析影响范围、给建议
有了方案 → 回到 Git Agent 执行具体操作

打个比方：你用遥控器（Agent）换台看节目，但不确定看什么时，叫管家（通用 AI）过来推荐一下。两种工具各司其职。

九、总结

从实战篇到扩展篇，发生了什么变化？

为什么自然语言比终端命令更好？

1. 降低认知负荷：不需要记住命令和参数，直接说话就行
2. 组合操作一步到位：一句话 = 多条 git 命令
3. 容错性强：LLM 理解同义表达，"切到 main"和"切换到 main 分支"都行
4. 有上下文：Agent 记住"之前做了什么"，不需要重复说明
5. 安全：危险操作有确认机制，不会像 git reset --hard 那样不可挽回

项目的完整代码

所有代码在 git-commit-agent/ 目录下：

commit_agent/
├── __init__.py
├── cli.py          # REPL 入口 + 命令解析
├── agent.py        # Agent Loop 核心
├── git_utils.py    # 17 个 Git 操作封装
├── llm_client.py   # DeepSeek API + 对话历史
├── tools.py        # 工具定义 + 调度 (NEW)
└── prompts.py      # 多工具系统提示词
tests/
├── test_commit_agent.py   # 46 个测试
quick_test.py              # 快速测试脚本 (9 个测试)

讨论

完成该项目后，读者可能会有疑问，尽管我在文中写了当前的Agent与通用AI 助手的对比，但实际上，通用AI助手（如Claude Code）可以轻松完成当前Agent的开发，这就让目前的工作显得非常无意义，也让Agent开发显得有些没有价值

但是，真正的agent开发不是做这个层面的工作，写几个tool definition + 一个 system prompt就能跑的agent，只能作为Agent的Hello World；后续的内容还有很多，包括基础设施的搭建，安全与治理，Agent能力的测试与评估，此外还需要集成入现有的系统。

这些东西，不是写一个 system prompt 就能解决的。它们是工程问题，需要一整套架构和持续的维护。因为，还是有必须继续学习的。