本文基于Amazon Q Developer CLI和Claude Code两个开源项目，从架构层面拆解AI Coding Agent的核心设计。详细分析了Agent Loop智能体循环、工具系统、四层安全模型、Context Window管理策略、MCP工具扩展协议等关键技术，总结了七大设计原则。这些工具通过LLM大脑+工具手脚的模式，实现了"给AI放权"和"不让AI搞破坏"的平衡，为开发者理解AI Coding工具的工作原理和安全边界提供了宝贵参考。

---

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

大模型入门学习教程 （附PDF文档）

现在国内外关于大模型入门教程做的比较好的并不多，这其实也是一件好事，有难度和有门槛才能避免烂大街，现在大模型入门教程热度最高的包括李宏毅老师、吴恩达老师、Datawhale开源社区等

选择合适的入门学习教程，能少走弯路，抓住核心内容，快速达到前沿的水平，甚至是发表大模型相关的论文都是可以的

这一期主要是给大家推荐李宏毅老师的最新课程：大模型入门学习教程

这个教程的主要内容如下（总共11讲）：

第1讲：总体介绍

这一讲主要介绍现在大模型作为生成式人工智能，其发展的历史过程，以及大模型落地的主要应用方向，了解大模型主要学习什么内容，难度不大，简单看一下就行

第2讲：提示词和AI代理人

首先介绍什么是提示词工程，提示词就是人类和大模型交互的语言，对于大模型的引导需要通过提示词来完成，然后介绍如何引导模型进行思考，比如COT是什么，在模型训练过程中提供额外信息

第3讲：生成策略

同一个问题，多次询问大模型，大模型会给出不同的回答，如何提高回复的准确率以及稳定性，是一个重要的大模型生成策略。了解大模型的生成概率与什么有关，比如top_p, top_k，temperature等

第4讲：深度学习和Transformer

这一部分先介绍一些深度学习基础内容，大模型的模型都是深度学习模型，了解深度学习中基础内容是有必要的，比如损失函数，反向传播，梯度下降等，然后介绍大模型的基础框架transformer，transformer模型结构一定要非常熟悉，很重要

第5讲：大模型评估和道德问题

这一部分先介绍大模型的评估标准，现在有很多benchmark从各个方面来评测大模型的不同能力，评估指标很多，开源的模型往往会选择有利于自己的指标进行展示，然后介绍大模型中存在的道德问题，因为大模型不能随意生成一些不符合道德社会文明的内容

第6讲：AI的可解释性

给大模型一个输入，只能得到一个输出，但是我们并不清楚大模型的思考过程是怎么样的，这个问题，大模型是怎么思考的，提升大模型的可解释性有助于后续研究如何提升大模型的推理性能，像COT就是显式展示大模型的思考过程，然后还可以让语言模型来解释语言模型

第7讲：视觉大模型

常说的大模型，都指的是文本大模型，输入是文本，输出也是文本，而现实世界中，可能我们的输入既有文本，又有图片和视频，输出也可能是多样化的，视觉大模型就是能解决文本和视觉两种模态的大模型

第8讲：GPT-4o

前面都是关于大 模型的理论，这一部分是拆解一个完整的大模型是怎么样的，以GPT-4o为例进行说明，GPT**-4o是首个端到端多模态通用模型**，是迈向AGI的一步，能够实现文本，音频和图片的多模态交互

上面就是大模型的入门教程的所有内容，学完这些可以去看看关于大模型微调，大模型训练，大模型推理加速，RAG和Agent等相关的内容，后面最好整一两个项目来实践一下

上述资料获取：

1. 关注公众号【大模型应用开发LLM】领取即可获取

2. 这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】