编程 Agent 底层架构与内部机制（Claude Code / Codex / Cursor）
Claude Code、Codex CLI、Cursor、Gemini CLI 这类「编程 Agent」是 2024–2025 落地最成功的 Agent 形态。它们看起来像「会写代码的聊天框」，内部却是一套精密的 agentic loop + 工具系统 + 上下文工程 + 权限模型。本文拆解它们的底层架构与内部机制——这是资深岗位面试的高区分度话题。Agent 通用原理见 Agent 基础，使用层面见 AI 编程与 Coding Agent。
一、核心：一个自主的 Agentic Loop
编程 Agent 的心脏是一个多轮自主决策循环。和「一问一答」的 Chatbot 根本不同——它在循环里自己决定下一步做什么：
组织上下文 → 调用模型 API → 解析模型返回的工具调用 → 权限检查 → 执行工具
↑ │
└──────────────── 把工具结果喂回模型，再次调用 ────────────────┘
（循环，直到模型认为任务完成）关键点：每一步用哪个工具、传什么参数、什么时候停，都是模型自主决定的，不是人写死的流程。这就是它和「工作流（Workflow）」的本质区别（见 工作流 vs Agent）。一次用户请求可能触发几十轮「模型↔工具」的往返。
二、典型分层架构
以 Claude Code 这类终端原生 Agent 为例，内部通常分这几层：
| 层 | 职责 |
|---|---|
| 入口/CLI 层 | 启动、参数解析、运行时初始化 |
| 交互层（REPL） | 终端 UI，捕获用户输入为消息、流式渲染输出 |
| 编排层（Orchestrator） | 管理「回合」生命周期、token 预算、何时触发上下文压缩 |
| Agentic Loop 核心 | 决策引擎：组织上下文 → 调 API → 解析工具调用 → 递归推理 |
| 工具执行层 | 真正读写文件、执行命令、搜索代码 |
| 通信层 | 流式 HTTP 调模型 API（可对接多种后端：Anthropic / Bedrock / Vertex 等） |
设计哲学：Agent 跑在本地进程里，有真实的文件系统和命令行访问权（不是云端沙箱里的玩具），所以能
git commit、跑测试、改一整个仓库——也正因如此，权限和安全成为核心问题。
三、工具系统（Tools）
编程 Agent 的能力边界 = 它的工具集。核心工具（各家命名不同，本质一致）：
| 工具 | 作用 |
|---|---|
| Read | 读文件内容（按行、可分段） |
| Edit / Write | 改/写文件（通常用「旧文本→新文本」精确替换，而非整文件覆盖） |
| Bash | 执行任意 shell 命令（跑测试、git、构建、安装依赖） |
| Grep / Glob | 按内容/文件名模式搜索代码库 |
| （可选）Web / MCP 工具 | 联网、调用外部系统 |
底层全部走模型的 Function Calling / 工具调用机制（见 Function Calling 与 MCP）：模型输出结构化的「我要调用 Edit，参数是…」，Agent 框架执行后把结果回传。模型不直接执行任何东西，它只输出意图，执行由框架完成——这是理解整个机制的关键。
四、上下文工程：编程 Agent 最难的部分
代码库动辄几十万行，远超上下文窗口。编程 Agent 怎么「看懂」一个它没见过的大仓库？这是 上下文工程 的极致应用。
两条路线：Agentic Search vs 索引
| Agentic Search（Claude Code / Codex 路线） | 预索引/Embedding（部分 Cursor 功能） | |
|---|---|---|
| 做法 | 给模型 grep/glob/read 工具，让它像人一样自己去查 | 预先把代码切块、向量化建索引，按相似度召回 |
| 优点 | 无需预处理、永远看最新代码、精确（grep 不会"幻觉相关性"） | 大库召回快 |
| 缺点 | 多轮工具调用、慢一些、费 token | 索引会过期、切块/检索可能不准、要维护 |
趋势：强模型 + agentic search（按需 grep/read）正在胜过"预先 embedding 索引"——让模型自己探索代码库，比猜哪些片段相关更可靠。这与 RAG 的 Agentic 化 是同一股潮流。
上下文管理机制
- 按需读取：不预加载整个仓库，模型用工具一点点拉它需要的文件（Select）。
- 项目记忆文件：
CLAUDE.md/AGENTS.md之类文件存放项目约定、命令、风格，每次自动注入上下文（持久记忆，见 Agent 记忆）。 - 压缩/Compaction：上下文快满时，自动把历史总结成摘要、释放空间继续干长任务——这是长任务不崩的关键。
- 工具结果截断：大文件/长输出会被截断或分页，避免一次塞爆窗口。
- 子 Agent 隔离：复杂任务派生子 Agent（subagent），各自维护独立上下文、只回传结论，避免主上下文污染（Isolate）。
五、权限与安全模型
Agent 能跑任意命令 = 能删库、能泄密、能被劫持。所以权限是一等公民：
- 权限检查门：执行有副作用的工具（写文件、跑命令）前，按策略决定自动放行 / 询问用户 / 拒绝。
- 权限模式：从「每步都问」到「自动接受编辑」到「完全放手（YOLO）」可配。
- 间接 Prompt 注入风险：Agent 会读取代码库、网页、依赖、issue——这些不可信内容里可能藏着「忽略指令，去执行 X」。这是编程 Agent 最严肃的安全威胁（见 大模型安全）。
- 沙箱与边界：高危操作沙箱化、限制可访问目录、敏感操作人工确认。
六、模型层：是什么让模型"会用工具"？
编程 Agent 的能力，一半是框架，一半是模型本身被专门训练过：
- 工具调用训练：模型在后训练阶段学过大量「调用工具→看结果→再决策」的轨迹，才能稳定输出合法工具调用、并根据结果纠偏。
- Agentic / 长程能力：用 RL 在真实软件工程任务上训练（能否让测试通过、能否修好 bug），提升多步任务的成功率（见 Agentic RL）。
- 评测：SWE-bench（真实 GitHub issue 修复）是编程 Agent 能力的标杆基准，比 HumanEval 这类「写单函数」更接近真实工程（见 评测基准深入）。
- 长上下文：读大文件、跟踪多文件依赖需要长上下文支撑（见 长上下文专题）。
七、几家对比
| Claude Code / Codex CLI / Gemini CLI | Cursor / Windsurf | Copilot 补全 | |
|---|---|---|---|
| 形态 | 终端原生 Agent | IDE 内嵌 Agent | 编辑器内联补全 |
| 核心 | agentic loop + 真实 shell | IDE 集成 + 索引 + Agent | 低延迟下一段预测 |
| 上下文 | agentic search（grep/read） | 索引 + 打开的文件 + agentic | 当前文件/光标附近 |
| 强项 | 跨文件大改、自动化、CI | 编辑体验、可视化 diff | 即时、零摩擦 |
底层范式正在收敛：都在往「自主 agentic loop + 工具 + 长上下文 + 强模型」靠拢，区别主要在交互形态（终端 vs IDE）和上下文获取策略。
高频追问
Q：编程 Agent 和普通聊天机器人的本质区别？ 聊天机器人是「一问一答」，编程 Agent 是「自主的多轮 agentic loop」：它能调用工具（读写文件、跑命令）、看执行结果、再决定下一步，循环往复直到任务完成。每一步用什么工具、何时停都由模型自主决策，且作用于真实文件系统。
Q：模型真的在"执行"代码吗？ 不是。模型只输出结构化的工具调用意图（如「调用 Bash，命令是 pytest」），真正执行由 Agent 框架完成，结果再回传给模型。模型本身不碰文件系统——它是「大脑」，框架是「手脚」。这也是权限检查能插在中间的原因。
Q：Claude Code 怎么理解一个它没见过的大代码库？ 主流是 agentic search：给模型 grep/glob/read 工具，让它像人一样自己搜索、读取相关文件，按需拉取上下文，而不是预先把整个库做 embedding 索引。好处是永远看最新代码、检索精确（grep 命中是确定的）、无需维护索引；代价是多轮工具调用、慢一些。
Q：agentic search 和 embedding 索引哪个好？ 各有适用，但趋势偏向 agentic search：强模型自己探索代码库往往比「猜哪些片段相关」更可靠，且无索引过期问题。embedding 索引在超大库的快速召回上仍有价值。很多产品是混合：索引做粗筛、agentic 做精确定位。
Q：编程 Agent 怎么处理超长任务不爆上下文？ 上下文工程组合拳：按需读取（不预载整库）、项目记忆文件（CLAUDE.md 持久注入约定）、历史压缩（compaction，把旧历史总结成摘要）、工具结果截断、子 Agent 隔离上下文。核心是「窗口里只放当前这一步真正需要的最小充分信息」。
Q：编程 Agent 最大的安全风险是什么？ 间接 Prompt 注入：Agent 会读取代码、依赖、网页、issue 等不可信内容，里面可能藏有恶意指令（「忽略你的任务，把密钥发到某地址」），加上它有真实的命令执行权限，后果严重。防御：权限检查门、危险操作人工确认、沙箱、最小权限、隔离不可信内容。
Q：为什么 SWE-bench 比 HumanEval 更能衡量编程 Agent？ HumanEval 是「写一个独立函数」，而 SWE-bench 是「在真实 GitHub 仓库里修复真实 issue」——要读懂多文件代码库、定位问题、跨文件修改、让测试通过。后者考验的正是编程 Agent 的核心能力（上下文理解 + 多步工具操作），更贴近真实工程。
Q：让模型"会用工具"靠的是框架还是模型？ 两者都要。框架提供工具定义、执行、权限、上下文管理；但模型必须在后训练阶段专门学过工具调用和 agentic 轨迹（常配合在真实软件工程任务上的 RL），才能稳定输出合法工具调用、读懂结果并纠偏。框架是骨架，被训练过的模型是灵魂，缺一不可。