ARTICLE / ai

AI Coding Agent 架构深度解析：从 ReAct 循环到多 Agent 协作的工程实现

Updated: 2026-07-23
Reading time: 17 min

2026 年，AI 编程工具的格局已经从"选哪个 IDE 插件"演变为"选哪种 Agent 架构"。Claude Code、OpenAI Codex、Cursor、Devin、Windsurf 等产品分属四大架构类别——AI 原生 IDE、Agentic CLI、云端委托 Agent 和平台原生 Copilot——它们的差异不在于底层模型是否足够聪明，而在于Agent 脚手架如何编排模型能力与开发环境的交互。研究表明，在相同底层模型（如 Opus 4.5）下，不同 Agent 脚手架在 SWE-bench 上的表现差距可达 17 分，这说明架构设计本身就是一种"能力乘数"。

然而，大多数开发者对这些工具的理解停留在"它能帮我写代码"的层面，对 Agent 内部的推理循环、上下文压缩、工具调用协议、多 Agent 协作和安全隔离等核心架构缺乏系统认知。本文不重复工具选型对比（参见本板块的 AI 编程工具技术栈），而是深入 Agent 内部，从架构工程师的视角解析 AI Coding Agent 的六大核心子系统。

1. 从 Autocomplete 到 Autonomous Agent：架构演进

理解 AI Coding Agent 的最佳起点是看清它从何而来。编程辅助工具经历了三个明确的架构代际：

代际	代表产品	核心能力	交互模式	架构特征
G1: 补全器	Copilot (2021)	FIM 填充，基于光标上下文生成	被动触发，逐行建议	单轮推理，无状态
G2: 对话助手	Copilot Chat (2023)	多轮对话，代码解释，局部编辑	主动提问，命令式	多轮对话，有会话状态
G3: 自主 Agent	Claude Code / Codex (2025)	自主规划、多文件编辑、测试验证、PR 提交	目标驱动，循环执行	ReAct 循环，工具调用，持久状态

关键跃迁点：从 G2 到 G3 不是"功能更多了"，而是控制流从人类手中转移到了 Agent 手中。在 G2 模式下，人类决定"改哪个文件、怎么改"，AI 只负责生成补全；在 G3 模式下，人类只说"做什么"，Agent 自己决定"怎么做"——读取代码库、制定计划、修改文件、运行测试、修复错误、提交变更，全程无需人工干预。

这种转变的底层驱动力不是 UI 改进，而是 LLM 推理能力跨过了一个关键阈值：模型能够在足够大的上下文窗口中，同时理解代码语义、项目结构和工具输出，从而形成可靠的自主决策循环。

2. 核心推理架构：ReAct 循环

所有现代 AI Coding Agent 共享同一个推理内核——ReAct（Reasoning + Acting）循环。这个循环的朴素实现可以概括为：

┌───────────────────────────────────────────────────┐
│                 Agent Loop (ReAct)                  │
│                                                     │
│  ┌─────────┐   ┌─────────┐   ┌─────────┐          │
│  │  Think   │──▶│   Act   │──▶│ Observe │──┐       │
│  │ 推理/规划 │   │工具调用   │   │解析输出  │  │       │
│  └─────────┘   └─────────┘   └─────────┘  │       │
│       ▲                                    │       │
│       └────────────────────────────────────┘       │
│                                                     │
│  终止条件: 任务完成 / 达到最大轮次 / 需要人工介入       │
└───────────────────────────────────────────────────┘

每一轮循环的四个步骤：

Think（推理）：模型分析当前状态，决定下一步行动。这可能包括理解用户意图、阅读代码文件、分析错误信息、制定修改策略
Act（行动）：调用具体工具执行操作——读取文件、编辑代码、运行命令、搜索代码库
Observe（观察）：解析工具返回的结果——文件内容、命令输出、错误信息
循环判断：决定是继续下一轮迭代还是终止

2.1 Claude Code 的 Agent Loop 实现

Claude Code 的源码泄露揭示了其核心设计哲学：“Less scaffolding, more model”——尽可能信任模型的推理能力，将系统复杂度从编排层转移到模型自身。整个架构的核心是一个朴素的推理-行动循环，没有 DAG 编排器、没有分类器、没有 RAG 系统。

用户输入
    │
    ▼
┌──────────────────────────────┐
│      System Prompt            │
│  (CLAUDE.md + 项目上下文)      │
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│      ReAct Loop               │
│                              │
│  1. 模型生成文本或工具调用      │
│  2. 执行工具，获取结果          │
│  3. 结果追加到 prompt          │
│  4. 重复直到任务完成           │
│                              │
│  40+ 内置工具:                │
│  - Read/Edit/Write (文件)     │
│  - Bash (命令执行)             │
│  - Grep/Glob (代码搜索)       │
│  - MCP 工具 (外部服务)         │
└──────────────────────────────┘

关键工程细节：

流式看门狗：如果在配置的超时窗口内没有收到新的流式事件，请求会被主动取消并重试，防止挂死的连接导致 Agent 循环永久阻塞
权限管线：每次工具调用前，系统检查权限配置——只读、本地修改、受限执行或完全控制——权限决策在模型推理之后、工具执行之前
上下文压缩：当对话历史超过上下文窗口限制时，Agent 会自动压缩早期的工具调用结果，保留关键信息

2.2 与传统 Pipeline 的本质区别

与传统的代码生成 Pipeline（如 CI/CD 中的 lint→format→test 线性流水线）相比，ReAct 循环的核心优势在于非线性自我修正能力：

维度	传统 Pipeline	ReAct Agent Loop
执行路径	固定的线性步骤	动态决策树，可回溯
错误处理	失败即停止，人工介入	自动诊断，自主修复重试
上下文利用	每步独立，无累积	循环累积，越做越"懂"
适用场景	已知的、确定性的任务	开放性的、需要推理的任务

核心洞察：ReAct 循环的本质是将"编程"这个人类活动抽象为"观察-思考-行动"的认知循环。Agent 不是在"生成代码"，而是在"执行软件工程任务"——理解需求、分析代码、制定策略、执行修改、验证结果。

3. 上下文工程：Agent 的记忆系统

Agent 的能力上限由上下文窗口决定——它能在一次推理中"看到"多少信息。然而，一个真实的代码仓库可能包含数百万行代码，远超任何模型的上下文限制。**上下文工程（Context Engineering）**正是解决这一矛盾的核心技术。

3.1 上下文管理的三层架构

┌──────────────────────────────────────────────┐
│              Context Architecture             │
│                                               │
│  Layer 1: System Context (常驻)                │
│  ┌─────────────────────────────────────────┐ │
│  │ CLAUDE.md / AGENTS.md / .cursorrules    │ │
│  │ 项目规范、编码风格、架构约束              │ │
│  │ 占用: ~2-5K tokens                       │ │
│  └─────────────────────────────────────────┘ │
│                                               │
│  Layer 2: Task Context (按需加载)              │
│  ┌─────────────────────────────────────────┐ │
│  │ 相关源文件、依赖定义、测试用例            │ │
│  │ 通过 Grep/Glob/Read 动态获取             │ │
│  │ 占用: ~10-50K tokens                     │ │
│  └─────────────────────────────────────────┘ │
│                                               │
│  Layer 3: Working Memory (循环累积)            │
│  ┌─────────────────────────────────────────┐ │
│  │ 对话历史、工具调用结果、中间推理          │ │
│  │ 随循环推进不断增长                        │ │
│  │ 压缩策略: 摘要/截断/滑动窗口             │ │
│  └─────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

3.2 上下文压缩策略

当对话历史超过上下文窗口时，Agent 必须做出取舍。主流的压缩策略包括：

策略一：滑动窗口截断——保留最近 N 轮对话，丢弃早期历史。简单粗暴但可能丢失关键上下文。

策略二：摘要压缩——用模型对早期对话生成摘要，替换原始内容。信息密度更高但可能丢失细节。

策略三：选择性保留——根据信息类型决定保留策略：

信息类型	保留策略	原因
用户最终目标	始终保留	Agent 需要持续对齐意图
最近 3 轮工具结果	始终保留	当前工作流的直接上下文
早期文件内容	摘要化	细节可重新读取
早期命令输出	丢弃	输出可重新执行
错误信息和修复记录	保留摘要	避免重复犯错

3.3 AGENTS.md 与 CLAUDE.md：指令层级设计

不同的 Agent 产品采用了不同的项目级指令文件设计：

工具	指令文件	层级设计	特点
Claude Code	`CLAUDE.md`	仓库根 / 子目录 / 用户全局	按目录层级自动合并，monorepo 友好
OpenAI Codex	`AGENTS.md`	仓库根 / 子目录	层级化项目指令，引导代码库导航
Cursor	`.cursorrules`	项目根	单文件配置，兼容 VS Code 生态

设计原则：指令文件本质上是给 Agent 的 System Prompt 扩展。好的指令文件应该像给一个新入职的高级工程师写 onboarding 文档——告诉它项目的架构约定、编码规范、常用命令和禁忌事项。

实战建议：不要把指令文件当成文档来写，而是当成可执行的行为规范。“使用 TypeScript 严格模式"比"我们的项目使用 TypeScript"更有效。Claude Code 的官方建议甚至包括使用"IMPORTANT"或"YOU MUST"等强调词来提升指令遵循度。

4. 工具系统：Agent 与开发环境的接口

Agent 的能力不仅取决于推理模型，更取决于它能调用什么工具。工具系统是 Agent 与外部开发环境交互的唯一通道，其设计质量直接决定了 Agent 的实用边界。

4.1 Agent-Computer Interface (ACI)

SWE-agent 的研究首先提出了 ACI（Agent-Computer Interface） 的概念——为 Agent 设计的专用接口，而非为人类设计的接口。这个看似简单的区别带来了深远的影响：

维度	人类接口 (HCI)	Agent 接口 (ACI)
信息呈现	语法高亮、缩进、GUI	纯文本、结构化输出、可解析格式
操作粒度	键盘/鼠标事件	文件级读写、命令执行
错误反馈	弹窗、波浪线	stderr 输出、返回码
导航方式	目录树、标签页	Grep/Glob 搜索、路径定位

核心洞察：Agent 不需要"看起来像人类在编辑器里写代码"的界面，它需要的是高信息密度、低交互开销的结构化接口。这就是为什么 Claude Code 选择终端而非 IDE 作为主界面——终端天然就是 ACI 的最佳载体。

4.2 工具分类体系

一个典型的 AI Coding Agent 的工具集可以分为四个层级：

┌─────────────────────────────────────────────┐
│              工具层级体系                      │
│                                              │
│  L4: 协作工具                                │
│  ┌─────────────────────────────────────┐    │
│  │ Git 操作 / PR 创建 / Issue 更新       │    │
│  └─────────────────────────────────────┘    │
│                                              │
│  L3: 验证工具                                │
│  ┌─────────────────────────────────────┐    │
│  │ 测试运行 / Lint 检查 / 构建验证       │    │
│  └─────────────────────────────────────┘    │
│                                              │
│  L2: 操作工具                                │
│  ┌─────────────────────────────────────┐    │
│  │ 文件读写 / 代码编辑 / 命令执行        │    │
│  └─────────────────────────────────────┘    │
│                                              │
│  L1: 感知工具                                │
│  ┌─────────────────────────────────────┐    │
│  │ 文件搜索 / 代码浏览 / 依赖分析        │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘

4.3 MCP 协议：工具生态的标准化

Model Context Protocol（MCP） 是 Anthropic 提出的工具调用标准协议，它解决了一个关键问题：让 Agent 能够以统一的方式接入任意第三方服务。

MCP 的架构分为三层：

层级	角色	说明
MCP Host	Agent 应用	Claude Code、Cursor 等 Agent 产品
MCP Client	协议客户端	嵌入在 Host 中，管理连接
MCP Server	工具提供方	数据库、API、文件系统等外部服务

# MCP Server 的最小实现示例
from mcp import Server, Tool

server = Server("my-tools")

@server.tool("search_logs")
def search_logs(query: str, time_range: str) -> str:
    """搜索应用日志，返回匹配的条目"""
    results = log_service.search(query, time_range)
    return format_log_entries(results)

@server.tool("run_query")
def run_query(sql: str) -> dict:
    """执行只读 SQL 查询"""
    if is_read_only(sql):
        return db.execute(sql)
    return {"error": "仅允许 SELECT 查询"}

MCP 的价值不仅在于技术标准化，更在于安全治理——通过 MCP Server 可以集中控制 Agent 对外部服务的访问权限、速率限制和审计日志，而无需修改 Agent 本身。

5. 多 Agent 协作架构

当单个 Agent 无法在有限的上下文窗口内完成复杂任务时，多 Agent 协作成为必然选择。2026 年的主流 AI Coding Agent 已经普遍支持多 Agent 并行执行。

5.1 三种协作模式

模式	架构	代表产品	适用场景
串行委派	主 Agent 分解任务 → 子 Agent 逐个执行 → 主 Agent 合并结果	Claude Code sub-agents	复杂任务的分治
并行竞速	多个 Agent 同时在不同分支执行同一任务 → 自动评判最优	Cursor background agents, Codex worktrees	寻找最优解
角色分工	不同 Agent 扮演不同角色（规划/编码/审查）→ 协作完成	Devin, 多 Agent 框架	端到端软件工程

5.2 Git Worktree：并行 Agent 的隔离基座

Git Worktree 是实现多 Agent 并行执行的关键技术。它允许同一个仓库同时拥有多个工作目录，每个 Agent 在独立的 worktree 中操作，互不干扰：

┌──────────────────────────────────────────────┐
│           Git Worktree 并行架构               │
│                                               │
│  ┌──────────────┐  ┌──────────────┐          │
│  │  Agent A      │  │  Agent B      │          │
│  │  worktree/feat│  │  worktree/fix │          │
│  │  分支: feature│  │  分支: bugfix │          │
│  └──────┬───────┘  └──────┬───────┘          │
│         │                  │                   │
│         ▼                  ▼                   │
│  ┌──────────────────────────────────────────┐ │
│  │          共享的 .git 对象库               │ │
│  └──────────────────────────────────────────┘ │
│         │                                      │
│         ▼                                      │
│  ┌──────────────────────────────────────────┐ │
│  │     Auto-Judge: 评估各 Agent 输出质量     │ │
│  │     合并最佳结果到主分支                   │ │
│  └──────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

Claude Code 的 Background Agents（v2.0.60+）正是基于这一模式：用户可以启动多个并行子任务，每个子任务在隔离的 worktree 中执行，完成后自动合并结果。Cursor 同样支持最多 8 个并行 Agent，每个在独立分支上运行。

5.3 Sub-Agent 通信协议

多 Agent 之间的信息传递需要精心设计。以 Claude Code 的 Sub-Agent 为例：

主 Agent
  │
  ├── spawn Sub-Agent A (任务: 重构认证模块)
  │     ├── 输入: 任务描述 + 相关文件路径
  │     ├── 上下文: CLAUDE.md 副本 + 有限历史
  │     └── 输出: 修改后的文件 + 执行报告
  │
  ├── spawn Sub-Agent B (任务: 编写测试)
  │     ├── 输入: 任务描述 + Sub-Agent A 的输出引用
  │     ├── 上下文: CLAUDE.md 副本 + 相关测试框架信息
  │     └── 输出: 新增测试文件 + 覆盖率报告
  │
  └── 合并: 综合 A 和 B 的输出，运行完整测试套件验证

关键约束：Sub-Agent 的上下文窗口通常比主 Agent 小，因此需要精准的信息裁剪——只传递子任务必需的文件片段和约束条件，而非整个代码库的上下文。

6. 执行环境与安全隔离

Agent 能够执行任意命令的能力，既是其最大优势，也是其最大风险。执行环境的隔离设计直接决定了 Agent 在生产环境中的可用性。

6.1 三层安全架构

┌──────────────────────────────────────────────┐
│           安全隔离三层架构                     │
│                                               │
│  Layer 3: 权限控制                             │
│  ┌─────────────────────────────────────────┐ │
│  │ .claude/settings.json                    │ │
│  │ allow: [Read(*), Bash(pnpm test)]       │ │
│  │ deny: [Bash(rm -rf *)]                  │ │
│  └─────────────────────────────────────────┘ │
│                                               │
│  Layer 2: 会话沙箱                             │
│  ┌─────────────────────────────────────────┐ │
│  │ Git Worktree 隔离                        │ │
│  │ 可写文件系统 (临时目录)                   │ │
│  │ 网络访问控制 (按需放开)                   │ │
│  └─────────────────────────────────────────┘ │
│                                               │
│  Layer 1: VM / 容器隔离                        │
│  ┌─────────────────────────────────────────┐ │
│  │ Devin: 独立 VM + 浏览器 + 终端           │ │
│  │ Codex: 云端沙箱环境                       │ │
│  │ 本地 Agent: Docker 容器 (可选)            │ │
│  └─────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

6.2 权限模型对比

工具	权限粒度	默认行为	安全评级
Claude Code	工具级 allow/deny 列表	每次危险操作需确认	⭐⭐⭐⭐ 高
Cursor	文件级 ignore + 操作确认	编辑需确认，命令需确认	⭐⭐⭐ 中
Codex	沙箱隔离 + 权限声明	云端隔离执行	⭐⭐⭐⭐⭐ 最高
Devin	完整 VM 隔离	完全隔离的执行环境	⭐⭐⭐⭐⭐ 最高

6.3 敏感信息防护

Agent 在执行过程中可能接触密钥、凭证等敏感信息。生产级防护策略包括：

环境变量隔离：使用 direnv 或 1Password CLI，确保密钥不进入 Agent 的上下文窗口
.gitignore 防护：Agent 的文件搜索工具会自动跳过被忽略的文件，但仍需显式配置 deny 规则
预提交钩子：在 Agent 提交代码前，通过 gitleaks 等工具扫描是否意外包含敏感信息
MCP Server 权限：通过 MCP 协议集中管控 Agent 对数据库、API 等外部服务的访问

7. 评测体系：如何衡量 Agent 的代码能力

理解 Agent 架构的最后一个关键维度是评测。不同于传统的代码生成评测（如 HumanEval 问"给定函数签名，生成函数体”），Agent 评测需要模拟真实的软件工程场景。

7.1 SWE-bench：Agent 评测的事实标准

SWE-bench 收集了真实 GitHub 仓库的 Issue，要求 Agent 阅读代码库、理解问题、生成修复补丁并通过测试套件。它是目前最接近"Agent 是否能替代初级工程师"的评测基准。

评测基准	任务类型	规模	难度	最佳成绩 (2026 Q2)
SWE-bench Verified	单 Issue 修复	500 题	中等	~79% (Opus 4.5 + scaffold)
SWE-bench Pro	复杂多文件修改	1,865 题	高	~45% (各模型)
SWE-EVO	跨版本演进修复	48 题	极高	~25% (GPT-5.4 + OpenHands)
Terminal-Bench 2.1	终端操作能力	多维度	中高	~83% (GPT-5.6 Sol + Codex)

关键发现：

脚手架效应：同一模型在不同 Agent 脚手架上的表现差距可达 17 分（731 题中），证明架构设计本身是一种"能力乘数"
长周期任务的断崖下降：在 SWE-EVO（跨版本演进）上，最强模型仅达 25%，而其在 SWE-bench Verified 上可达 72.8%，说明当前 Agent 在持续多文件推理上仍有巨大提升空间
数据污染风险：基于宽松许可证（MIT/Apache）的仓库构建的评测集，可能已被模型在预训练中见过，SWE-bench Pro 通过使用 GPL 许可和商业代码来缓解这一问题

7.2 实用评测框架

对于团队选型，建议采用分层评测策略：

评测层级	方法	关注维度
L1: 快速验证	在团队实际仓库上跑 10 个典型任务	基础可用性
L2: 深度对比	选择 3-5 个跨模块的复杂 Issue	多文件推理能力
L3: 生产模拟	在 CI/CD 流水线中运行 Agent 一周	可靠性、成本、安全

8. 总结与展望

AI Coding Agent 的架构演进仍在快速推进。回顾本文的核心观点：

ReAct 循环是统一内核：无论产品形态如何（IDE、CLI、云端），所有 Agent 共享"感知-推理-行动-观察"的核心循环，差异在于循环的编排策略和工具调用深度
上下文工程是性能瓶颈：Agent 的能力上限不取决于模型智商，而取决于它能在有限窗口内"看到"多少有效信息。CLAUDE.md/AGENTS.md 的设计质量直接影响 Agent 表现
ACI 优于 HCI：为 Agent 设计的结构化接口（ACI）比模仿人类的 GUI 更高效，这也是终端原生 Agent（Claude Code、Codex CLI）在复杂任务上表现更好的根本原因
多 Agent 是复杂任务的必经之路：Git Worktree 隔离 + Sub-Agent 并行 + Auto-Judge 质量控制，构成了当前最成熟的多 Agent 协作架构
安全隔离不能事后补救：权限控制、沙箱执行、敏感信息防护必须在架构设计阶段就内建，而非上线后"打补丁"

展望 2026 下半年，三大趋势值得关注：一是 Agent 记忆系统的标准化（跨会话的代码库理解），二是 Agent-to-Agent 协议（A2A/ACP）的成熟，三是评测基准从单 Issue 修复向长期软件演进（SWE-EVO）迁移。架构的复杂度还会继续增长，但核心循环不会改变——变的是循环中每一步的深度和广度。

参考资源

SWE-bench: Can Language Models Resolve Real-World GitHub Issues? — Agent 评测的事实标准，包含 Verified 和 Pro 两个版本
SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering — ACI（Agent-Computer Interface）概念的提出论文
Claude Code Source Analysis — Claude Code 内部架构的源码级分析文档
Anthropic Claude Code Best Practices — 官方的 CLAUDE.md 配置和 Agent 使用最佳实践
Model Context Protocol Specification — MCP 工具调用标准协议的官方文档
SWE-bench Pro: Can AI Agents Solve Long-Horizon Software Engineering Tasks? — 更高难度的 Agent 评测基准，覆盖商业代码库
SWE-EVO: Benchmarking Coding Agents in Long-Horizon Software Evolution Scenarios — 跨版本软件演进评测基准，揭示 Agent 在长期任务上的能力缺口
Best AI Coding Agents in 2026 — 2026 年 AI Coding Agent 产品全景对比