Vibe Agent

主题

第 24 节 · Coding Agent 的工作模式 ​

一句话回答 ​

写代码的过程归纳成 5 步：浏览 → 定位 → 理解 → 修改 → 验证。Coding Agent 的工具集就是按这 5 步分配的。

五阶段工作流 ​

Coding Agent 的五阶段工作流

阶段你（人类）会做什么对应的工具类
① 浏览在 IDE 里展开项目目录树list_dir
② 定位Cmd+P 找文件、Cmd+F 搜文本glob、grep
③ 理解打开关键文件读read
④ 修改写新文件 / 改某一段write、edit
⑤ 验证跑测试 / 跑脚本bash

写代码就是这 5 步循环。Cursor / Claude Code / Codex 这些 2026 年的主流 Coding Agent，核心循环都是这 5 步——只是工具更精致，上面再叠了一层「子任务委派」「并行执行」。

my-agent 简化版 vs 工业版

Day5 我们要做的 my-agent/coding_tools/ 只实现 5 个工具：list_dir / read / write / edit / bash。没有 grep 也没有 glob——重点是让你看清五阶段循环，定位阶段在小项目里 list_dir + read 已经够用。等 Day6 整合时可以对照 examples/full-agent/tools/impl/ 里的工业版（9 个工具，含 grep / glob / webfetch / todo）。

工具不是按"文件操作"分类的 ​

很多人第一反应是按"动词"分：open / close / read / write。这是错的。

正确的分类逻辑是按"Agent 工作流的阶段"分。比如：

  • 为什么不要 open_file？因为 LLM 不需要"打开"——read 读一次就完事
  • 为什么不要 delete_file？因为这是高危操作，也不在 5 个阶段里
  • 为什么不要 move_file？因为模型可以用 bash 调 mv 完成

少而精的工具集，比一堆"看似全面"的工具更好用。

Anthropic 官方建议：5-15 个工具是甜点区

2025 年 Anthropic 工程团队的 Writing effective tools for AI agents 给出的经验：单个工具集（或 MCP server）暴露 超过 20 个工具，模型选错率会出现明显拐点。GitHub Copilot、Speakeasy 等团队的内部数据也指向同一个结论。5-15 个、职责互不重叠——这是工业 Coding Agent 工具集的甜点区。

阶段映射 ​

每阶段对应一类工具

按 5 阶段分组：

浏览阶段：list_dir
定位阶段：glob / grep
理解阶段：read
修改阶段：write / edit
验证阶段：bash
————————
扩展阶段：todo / webfetch（选做，Day7 才用）

今天必做的 5 个：list_dir / read / write / edit / bash。 覆盖了 5 个阶段最低限度的能力。

2026 年工业 Coding Agent 又叠了哪些层

5 个核心工具是底盘，工业产品在上面叠了两类能力：

任务层（怎么把大事拆开）

  • todo / 任务规划：把大任务拆成可勾选清单，Agent 按计划推进，避免「想到哪改到哪」
  • apply_patch / 结构化 diff（OpenAI Codex 主推）：模型一次返回多个文件的 unified diff，宿主程序统一应用，token 比 edit 紧凑
  • subagent / Agent Teams（Claude Code Opus 4.6，2026.02）：主 Agent 把研究、编辑、跑测试拆给多个子 Agent 并行做，每个子 Agent 有独立 context

生态层（怎么接外部世界）

  • webfetch / web_search：拿外部文档、issue、API 资料
  • MCP 工具：把数据库、Sentry、Linear、Slack 等服务统一暴露给 Agent
  • Skills（2025 末-2026 主流）：把「前端设计」「代码审查」这类领域知识打包成可复用模块，同一份 SKILL.md 跨 Claude Code / Cursor / Codex CLI / Gemini CLI 通用

这些都是在 5 个核心工具基础上的扩展——先把底盘打牢，Day7 / Day8 再叠生态层。

一个真实的"五阶段"实战 ​

任务："把 main.py 里的 greet() 函数加一句开场白，跑一遍验证。"

① list_dir(".")          → 看到 main.py / utils.py
② read("main.py")        → 看到 def greet(): print("hello")
③（无需 grep，已定位）
④ edit("main.py",
     old_content="def greet():\n    print('hello')",
     new_content="def greet():\n    print('=== 开场 ===')\n    print('hello')")
                          → ✅ 替换成功
⑤ bash("python main.py") → 看到 "=== 开场 === \\n hello"

跑一遍 demo_24_five_stages.py，手动走一遍这 5 步，你能直观感受到工具输出之间的依赖关系。

工具的"输入"通常依赖前一个工具的"输出" ​

list_dir("./") 输出 → main.py 这个名字 → read("main.py") 的输入
read("main.py") 输出 → 看到 greet() 函数体 → edit() 的 old_content
edit() 输出 → 知道改成功了 → 决定 bash() 跑测试
bash() 输出 → 看到测试结果 → 决定要不要再修一轮

工具之间不是独立的，是一条数据流。这就是为什么工具的输出格式要给"下一个工具的输入"留好接口：

  • read 输出带行号：方便下一步 grep 报错或 edit 引用
  • list_dir 区分文件 / 目录：方便下一步决定 read 还是 list_dir
  • bash 输出含 exit code：方便模型判断"测试通过了没"

工具的输出是"给 LLM 看的 UI"。Anthropic 工程团队把这件事称为 Agent-Computer Interface（ACI）——人有 HCI，Agent 有 ACI，值得投入同等多的设计精力。

一个常见误区："让 LLM 写整个文件" ​

新手常见做法：

python
# ❌ 让 LLM 一次写整个 main.py
write("main.py", "...500 行内容...")

这是反模式，原因：

  1. LLM 写长文件 token 消耗高
  2. LLM 写长文件容易"突然丢一段"
  3. 改一行也要重写整个文件

正确做法：用 edit 做精确的"局部修改"，write 只用来新建文件或整体覆盖（且默认拒绝覆盖）。

2026 三家主流 Coding Agent 的工具集长啥样 ​

把三家产品的核心工具列出来，会发现轮廓惊人地一致：

产品读定位改跑额外
Claude CodeReadGlob / GrepEdit / Write / MultiEditBashTask（subagent）/ TodoWrite / WebFetch
Cursor Composerread_filecodebase_search / grep_search / file_searchedit_file / delete_filerun_terminal_cmdweb_search
OpenAI Codexshell cat / head / tailshell grep / findapply_patch（V4A diff）shell（依赖 shell）

几个观察：

  • 每家都有「读 / 定位 / 改 / 跑」四类——这就是五阶段的真实落地
  • Codex 走极简路线：把读和定位都退回成 shell 命令，只把编辑做成 apply_patch 这一个特殊工具——把编辑做精，其余复用通用 shell
  • Claude Code / Cursor 走结构化路线：每一类都包成专门工具，输出更适合喂回模型

我们 Day5 的 my-agent 走的是 Claude Code 风格的简化版。

动手试试 ​

bash
cd labs/05-coding-agent-tools
python demo_24_five_stages.py

源码：demo_24_five_stages.py

会自动建一个临时工作区，按 5 阶段顺序调用 5 个工具，把每一步的输出打印出来给你看。

小结 ​

概念一句话理解
五阶段工作流浏览 → 定位 → 理解 → 修改 → 验证
工具分类原则按 Agent 工作流阶段分，不是按文件操作分
工具间关系一条数据流，前一个的输出 = 后一个的输入
工具输出给 LLM 看的 UI，要带行号 / 区分类型 / 含状态码
必做 5 个list_dir / read / write / edit / bash
工业版扩展todo / apply_patch / subagent / webfetch / Skills

下一节：每个工具背后藏着大量的"防 LLM 翻车"设计。第 25 节会拆 4 个最关键的设计选择。

Released under the MIT License.

Copyright © 2026-present cnb | ❤️ VitePress