Cursor、Claude Code、Amazon Q、Windsurf... 2026 年 AI Coding 已经卷成红海。但你有没有想过：这些工具到底是怎么工作的？ 本文基于 Amazon Q Developer CLI （Rust 实现）和 Claude Code（TypeScript + Python）两个已开源项目的源码，从架构层面拆解 AI Coding Agent 的核心设计。
看完你会明白：为什么这些工具能写代码、能改文件、能跑命令------以及它们是如何在「给 AI 放权」和「不让 AI 搞破坏」之间做平衡的。
1 先搞清楚一件事：AI Coding ≠ 聊天机器人
很多人以为 AI Coding 工具就是 ChatGPT 套了个 IDE 的壳。大错特错。
聊天机器人只能「说」，AI Coding Agent 能「做」。区别在哪？Tool Use（工具调用）。
当你让 Claude Code 帮你改一个 bug 时，背后发生的事情是这样的：
👤 你：「帮我修一下 src/app.js 里的 bug」
⬇️
🤖 LLM 思考：我需要先看看这个文件
📤 LLM 输出工具调用：fs_read("src/app.js")
⬇️
⚙️ Agent 执行：读取文件内容 → 返回给 LLM
⬇️
🤖 LLM 思考：找到 bug 了，第 42 行有问题
📤 LLM 输出工具调用：fs_write("src/app.js", ...)
⬇️
⚙️ Agent 执行：修改文件 → 返回结果
⬇️
🤖 LLM：「搞定了，问题出在...」
这个过程叫 Agent Loop（智能体循环），是所有 AI Coding 工具最核心的设计模式。
💡 关键概念：LLM 不直接操作你的电脑。它通过结构化的 JSON 请求告诉 Agent「我想做什么」，Agent 验证权限后代为执行。这样所有操作都可审计、可拦截、可回滚。
2 Agent Loop：一个精巧的状态机
Amazon Q CLI 在 Rust 里实现了一个显式的有限状态机来管理整个 Agent 循环：
▲ Agent Loop：用户输入 → Prompt → LLM → 流式解析 → 工具执行 → 循环
▲ 6 种状态的有限状态机：Idle → ExecutingRequest → ExecutingHooks → WaitingForApproval → ExecutingTools → 循环
这个状态机看起来简单，但有几个精妙之处：
🔄 循环是自动的 ------ LLM 调用工具后，结果会自动注入对话并再次调用 LLM，直到 LLM 决定停下来。你跟它说「帮我重构这个模块」，它可能会连续调用 20 多次工具才停下。
⚡ 工具可以并行执行 ------ LLM 一次可以返回多个 tool_use，Agent 用 Tokio 的 FuturesUnordered 并行执行，然后打包所有结果一起发回。
🛡️ 每次工具调用都过权限检查 ------ Allow 直接执行，Ask 弹出确认，Deny 直接拒绝并告诉 LLM 原因。
3 工具系统：AI 的「手和脚」
AI Coding Agent 的能力上限完全取决于它有哪些工具。来看 Amazon Q CLI 的内置工具集：
▲ LLM 一次返回多个 tool_use → TaskExecutor 并行执行 → 打包结果发回 LLM
工具描述的艺术
这里有一个很多人不知道的细节：工具的 description 不是给人看的文档，而是给 LLM 看的行为指令。它的质量直接决定 Agent 的表现。
比如 ExecuteCmd 的描述里写着：
这段描述的目的是引导 LLM 优先使用 FsRead/FsWrite 等专用工具，而不是什么都用 bash 命令------因为专用工具更安全、更可控。
⚠️ 这是 Prompt Engineering 最被低估的领域：工具描述的措辞差异，可以让 Agent 的行为从「靠谱」变成「灾难」。一个写得好的 description 比调整模型温度有用 10 倍。
__tool_use_purpose：让 AI 「三思后行」
Amazon Q CLI 有一个精妙的设计------每次工具调用都强制 LLM 填写一个 purpose 字段：
这个字段的作用：① 用户能看到 AI 为什么做这个操作；② 迫使 LLM「思考」后再行动，减少无意义的调用；③ 所有操作都有审计记录。
4 安全模型：四层纵深防御
给 AI 能力越大，安全就越重要。Amazon Q CLI 实现了四层安全架构：
▲ Amazon Q CLI 四层纵深防御：Hook → 用户确认 → 路径权限 → 工具白名单
其中路径权限是最有意思的一层：
所有路径都会先做 canonicalize 规范化处理，防止用 ../ 这种路径穿越攻击绕过权限。
Claude Code 这边则用 Hook 实现了声明式安全策略，自动检测 9 种常见安全风险：命令注入、XSS、eval() 滥用、SQL 注入、硬编码凭证等等。
5 Context Window 管理：最核心的稀缺资源
这是 AI Coding 和传统软件最大的架构差异。
▲ 五层 Prompt 架构：System Prompt → Context Entries → Tool Specs → 对话历史 → 用户消息
传统软件的瓶颈是 CPU、内存、IO。AI Coding 的瓶颈是 Context Window ------ LLM 一次能处理的 token 上限。超了就「失忆」，之前的对话全忘了。
Amazon Q CLI 用了四个策略来管理这个稀缺资源：
1 自动压缩（Compact）------ 当上下文溢出时，调用 LLM 对历史对话生成摘要。200K tokens 的历史压缩成 2K tokens 的摘要 + 最近 20 条消息。
2 消息截断 ------ 读取大文件时只保留前 10000 字符，附带 ...truncated 提示。
3 历史裁剪------ 保留最近的消息，删除最早的。但要维护结构完整性（不能破坏 tool_use/tool_result 配对）。
4 资源文件限制------ 自动包含的资源文件不超过 10KB。
💡 Amazon Q CLI 的终端提示符会实时显示 Context Window 使用率：[default] 42% > _ → 正常[default] 85% !> _ → 警告，该 /compact 了
6 MCP 协议：工具扩展的事实标准
两个项目都采用了 MCP（Model Context Protocol） 作为工具扩展协议。MCP 正在成为 AI Coding 领域的事实标准。
简单说，MCP 就是 AI Agent 调用外部工具的「USB 接口」：
▲ MCP 协议：AI Agent 通过 JSON-RPC 与 MCP Server 通信，McpManager 用 Actor 模型管理多个 Server
Amazon Q CLI 用 Actor 模型管理多个 MCP Server ------ 每个 Server 是一个独立的 Actor，通过消息通信，支持独立的连接管理、错误恢复和工具发现。
这意味着你可以用任何语言写一个 MCP Server，定义自己的工具（比如查数据库、调内部 API、操作 K8s 集群），然后任何支持 MCP 的 AI Agent 都能用。
7 插件体系：Claude Code 的五维扩展
Claude Code 定义了 5 种正交的扩展点，每种解决不同的需求：
▲ 五种扩展点 + Hook 事件生命周期
最有意思的是 feature-dev 插件的 7 阶段工作流，展示了 Agent 编排的最佳实践。注意 Phase 2 ------ 并行启动多个子 Agent 去探索不同的代码路径，这就是 Multi-Agent 协作在实际产品中的落地。
8 两个项目的架构对比
| 维度 | Amazon Q CLI | Claude Code |
|---|---|---|
| 语言 | Rust（系统级性能） | TypeScript + Python |
| 架构 | 单体 Agent + Actor 并发 | 核心引擎 + 插件生态 |
| 并发 | Tokio async + Actor | Node.js 事件循环 + 子进程 |
| 扩展 | MCP + Hook 脚本 | 5 维插件体系 |
| 状态 | SQLite 持久化 | 文件系统 + 会话状态 |
| 优势 | 性能、类型安全、编译时保证 | 开发效率、生态丰富、灵活性 |
一个走性能路线，一个走生态路线。但核心范式完全一致：LLM Agent + Tool Use + Streaming + Safety + MCP。
▲ Rust vs TypeScript 两种技术路线的详细对比
▲ 流式处理全链路：LLM API → StreamParseState 增量解析 → 实时渲染/工具执行 → 终端 UI
9 七大设计原则总结
原则 1：LLM 是大脑，工具是手脚 LLM 不直接操作系统，通过结构化的 Tool Use 间接操作。所有操作可审计、可拦截、可回滚。原则 2：流式处理优先 不等完整响应，增量解析 + 实时渲染。用户体验接近实时对话。原则 3：安全是架构级关注点 权限不是事后补丁，而是从工具定义到用户确认的完整链路。原则 4：Context Window 是稀缺资源 所有设计都围绕「如何在有限窗口内塞入最有价值的信息」。原则 5：工具描述即 Prompt 工具的 description 直接决定 Agent 选择和使用工具的方式。原则 6：MCP 标准化工具生态 统一的工具接口协议，支持跨 Agent 复用。原则 7：状态机驱动对话管理不是简单的一问一答，而是带有明确状态转换的有限状态机。
写在最后
AI Coding 看起来像魔法，但拆开看，本质就是：一个循环 + 一堆工具 + 一套权限。
理解了这些底层原理，你会发现：
📌 为什么有时候 Agent 会「失忆」------ Context Window 满了
📌 为什么它有时候不用最好的方法 ------ 工具描述引导不够好
📌 为什么不同工具的「手感」差很多 ------ 状态机和错误处理的精细度不同
📌 为什么 MCP 这么重要 ------ 它是工具生态的 USB 接口
如果你正在做 AI 相关的开发，或者在考虑自己搭 Agent 系统，这两个开源项目是最好的学习材料。代码不会说谎。
📎 参考项目：• Amazon Q Developer CLI：github.com/aws/amazon-q-developer-cli• Claude Code：github.com/anthropics/claude-code
--- END ---
欢迎关注我的个人主页：https://zmead.com/