Claude Code 源码架构全景拆解：13 层组件如何组成一个完整的 Agent 操作系统
Claude Code 源码架构全景拆解：13 层组件如何组成一个完整的 Agent 操作系统
很多人以为 Claude Code 就是一个终端里的聊天工具。
你输入一句话，它返回一段代码，完事了。
大错特错。
Claude Code 是目前工程化程度最高的 AI Agent 产品，没有之一。它的源码架构不是"一个循环加几个工具调用"那么简单，而是一套完整的、分层的、可组合的 Agent 操作系统。
今天这篇文章，我把整个架构从底层到顶层，一层一层拆开给你看。
全景图：13 层组件
先看全貌。Claude Code 的架构可以拆成 13 层组件，每一层解决一个特定的工程问题：
┌─────────────────────────────────────────────────────┐
│ Computer Use │ 桌面级操作
├─────────────────────────────────────────────────────┤
│ Hooks │ Remote/Schedule │ MCP/Plugins │ 治理与扩展
├─────────────────────────────────────────────────────┤
│ Agent Team │ Subagent │ Task System │ 多Agent协作
├─────────────────────────────────────────────────────┤
│ Skills/Commands │ Memory │ Prompt/Context │ 能力与记忆
├─────────────────────────────────────────────────────┤
│ Permission Governance │ Tool System │ 动作与治理
├─────────────────────────────────────────────────────┤
│ Agent Loop │ 核心循环
└─────────────────────────────────────────────────────┘下面逐层拆解。
第一层：Agent Loop —— 让模型从"回答"进入"持续行动"
这是整个系统的地基。
普通的 LLM 调用是一次性的：你问一个问题，模型给你一个回答，结束。
Agent Loop 把这个变成持续的：
while task_not_done:
1. 感知（Perceive）：读取当前环境状态、上下文、上一步的结果
2. 思考（Think）：模型决定下一步做什么
3. 行动（Act）：调用工具执行操作
4. 观察（Observe）：收集行动的结果
5. 判断（Evaluate）：任务完成了吗？需要调整方向吗？
6. 循环这个循环看似简单，但工程实现上有大量细节：
- 最大步数控制：防止无限循环烧 token
- 中断机制：用户可以随时按 Ctrl+C 打断
- 流式输出：每一步的思考过程实时显示给用户
- 错误恢复：某一步失败了，不是直接报错退出，而是让模型决定怎么处理
Agent Loop 的本质，是让模型从"被动回答问题"变成"主动持续行动"。 这是 Agent 和 Chatbot 的根本区别。
第二层：Tool System —— 把意图变成动作
模型自己只会生成文本，它不能读文件、不能跑命令、不能改代码。
Tool System 就是那个"手"——把模型的意图（tool_use 请求）变成真实的动作。
Claude Code 的工具系统不是简单的函数注册表，它做了几件关键的事情：
统一接口：所有工具都遵循同一个接口规范：
# 伪代码
tool = {
"name": "str_replace_based_edit_tool",
"description": "对文件进行精确的字符串替换",
"input_schema": {
"type": "object",
"properties": {
"file_path": {"type": "string"},
"old_string": {"type": "string"},
"new_string": {"type": "string"}
}
}
}模型看到的是统一的工具描述，不需要知道每个工具的内部实现。
工具分类：
| 类别 | 工具 | 说明 |
|---|---|---|
| 文件操作 | read_file, write_file, edit_file | 读写改文件 |
| 代码执行 | bash | 执行任意 shell 命令 |
| 搜索 | search_files, grep | 内容搜索和文件查找 |
| 任务管理 | task_create, task_update | 任务追踪 |
| 通信 | ask_user | 向用户提问 |
结果回传：每个工具执行完，结果会以结构化的方式回传给模型，让模型知道操作是否成功，失败了是什么原因。
Tool System 的核心设计原则是：模型的每一个意图，都必须通过工具系统变成可审计的动作。不允许模型直接操作环境，必须经过工具层的抽象和管控。
第三层：Permission Governance —— 让动作可控、可审计、可中断
这是 Claude Code 最被低估的一层。
Agent Loop 让模型能持续行动，Tool System 让模型能执行动作。但是，谁来保证这些动作是安全的？
Permission Governance 就是那道闸门。它有三层防护：
第一层：声明式权限规则
# 权限规则示例
permissions:
allow:
- "read_file" # 读文件：默认允许
- "search_files" # 搜索：默认允许
- "bash(git status)" # git status：默认允许
ask:
- "bash(*)" # 其他 bash 命令：需要用户确认
- "write_file(*)" # 写文件：需要用户确认
deny:
- "bash(rm -rf *)" # 危险命令：直接拒绝第二层：实时审批 当 Agent 想执行一个需要确认的操作时，它不会直接执行，而是暂停并询问用户：
Claude wants to run: npm install express
Allow? [y/n/e(edit)]用户可以批准、拒绝、或者修改命令后再批准。
第三层：审计日志 每一次工具调用——无论是否被批准——都会被记录。谁在什么时候想做什么操作，结果是什么，全部可追溯。
这三层加在一起，构成了一个完整的"动作进入真实环境前的治理体系"：
- 可控：危险操作直接拒绝
- 可审计：所有操作有日志
- 可中断：用户可以随时打断
第四层：Prompt / Context —— 决定模型每一轮看到什么
这是最影响效果，也是最容易被忽略的一层。
每一轮循环中，模型看到的上下文不是简单的"把所有历史消息拼起来"。而是一个经过精心构造的 prompt，包含：
系统提示词（System Prompt）：定义 Agent 的身份、能力边界、行为规范。这部分在整个会话中基本不变。
工具定义（Tool Definitions）：告诉模型有哪些工具可用，每个工具的参数格式是什么。这部分在会话中可能动态变化（比如加载了新的 Skill 后会增加工具）。
对话历史（Conversation History）：之前的对话记录。这里的关键是上下文窗口管理——当对话太长时，哪些消息保留、哪些被摘要、哪些被丢弃。
当前环境状态：当前工作目录、git 状态、打开的文件等。这些信息让模型知道"我现在在什么环境里"。
记忆注入：从长期记忆中检索到的相关信息。比如之前解决过类似问题的经验。
Skill 指令：如果加载了某个 Skill，它的指令会被注入到 prompt 中，影响模型的行为方式。
Prompt / Context 层的核心挑战是权重管理：当上下文超过模型的窗口限制时，保留什么、丢弃什么的决策直接影响 Agent 的表现。Claude Code 用了一套优先级策略：系统提示词 > 工具定义 > 最近对话 > 早期对话摘要 > 记忆。
第五层：Memory —— 让临时对话沉淀成长期经验
没有记忆的 Agent，每次对话都从零开始。你在上周解决的问题，这周它完全不记得。
Claude Code 的记忆系统解决了这个问题：
短期记忆：当前会话中的对话历史。随着对话推进，早期的消息会被摘要压缩。
长期记忆：跨会话的持久化存储。包括：
- 用户偏好（你喜欢的代码风格、命名规范）
- 项目知识（架构决策、技术栈选择、已知问题）
- 经验教训（什么方案有效、什么方案失败了）
记忆检索：不是把所有记忆都塞进 prompt，而是根据当前任务的相关性，检索最相关的几条注入。
记忆更新：Agent 在工作过程中发现的新知识，会自动写入长期记忆。比如它发现"这个项目用 pytest 而不是 unittest"，下次就会自动知道。
记忆系统的本质是：让 Agent 的经验随着使用不断积累，而不是每次都从空白开始。
第六层：Skills / Commands —— 把能力做成可加载的产品单元
这一层是 Claude Code 从"工具"进化成"平台"的关键。
Skill 是什么：一个 Skill 就是一个文件夹，包含：
my-skill/
├── SKILL.md # 技能定义（触发条件、行为指令、工具列表）
├── references/ # 参考文档
├── templates/ # 模板文件
└── scripts/ # 可执行脚本加载机制：Skill 不是全局加载的，而是根据当前任务的相关性动态加载。Claude Code 会扫描所有可用的 Skill，根据任务描述匹配最相关的 Skill，把它的指令注入到 prompt 中。
命令系统：除了自动触发的 Skill，还有用户主动触发的命令（slash commands）。比如 /test 触发测试流程，/deploy 触发部署流程。
分发机制：Skill 可以打包分享，其他用户安装后直接使用。这意味着能力可以在社区中流通。
Skills / Commands 的核心价值：把"会做某件事"的能力，从"写在提示词里"变成"可加载、可复用、可分发的独立单元"。这是 Agent 能力产品化的关键一步。
第七层：Task System —— 把一次行动升级成可追踪的任务
没有 Task System 的 Agent，每次对话都是一个独立的、一次性的操作。
Task System 让 Agent 能够：
- 创建任务：把一个大的目标拆成多个子任务
- 追踪状态：每个任务有 pending / in_progress / completed / cancelled 状态
- 设置优先级：多任务并行时，知道先做什么
- 跨会话恢复：上次没做完的任务，下次继续
这一层把 Agent 从"一问一答"升级成了"项目管理"。你不再需要记住"我让 Agent 做了什么、做到哪了"，Task System 帮你记。
第八层：Subagent —— 把复杂任务拆给独立 Agent 执行
当一个任务太复杂，或者需要不同的上下文/工具集时，Claude Code 可以启动一个 Subagent。
Subagent 的特点：
- 独立上下文：Subagent 有自己的对话历史，不会污染父 Agent 的上下文
- 独立工具集：可以给 Subagent 限定不同的工具权限
- 独立终端：Subagent 有自己的工作目录和终端会话
- 结果回传：Subagent 执行完后，只把最终结果回传给父 Agent，中间过程不进入父 Agent 的上下文
这解决了一个核心问题：上下文污染。如果没有 Subagent，一个复杂的调试任务可能会在对话历史中堆积大量日志和中间结果，把父 Agent 的上下文窗口撑爆，导致它忘记最初的任务目标。
Subagent 的本质是：用进程隔离的方式，实现上下文隔离。
第九层：Agent Team —— 把多个 Agent 组织成协作团队
Subagent 是"父-子"模式，一个 Agent 派遣另一个 Agent。
Agent Team 是"同事"模式，多个 Agent 平等地协作。
团队组成：
- 每个 Agent 有自己的角色（Reviewer、Implementer、Tester、Architect）
- 每个 Agent 有自己的工具集和权限
- 它们共享一个任务列表
- 它们通过消息传递通信
协作模式：
Architect Agent → 设计方案 → 交给 Implementer Agent
Implementer Agent → 写代码 → 交给 Tester Agent
Tester Agent → 跑测试 → 反馈给 Implementer Agent
Implementer Agent → 修复 → 交给 Reviewer Agent
Reviewer Agent → 审查 → 批准或打回Agent Team 的核心挑战是协调成本：多个 Agent 之间如何避免冲突、如何共享状态、如何处理分歧。Claude Code 用共享任务列表 + 消息队列来解决这个问题。
第十层：MCP / Plugins —— 把外部世界接入 Agent
MCP（Model Context Protocol）是让 Agent 连接外部世界的标准协议。
MCP 接入了什么：
- 工具：数据库查询、API 调用、浏览器操作
- 资源：文件系统、知识库、文档
- 提示词：预定义的 prompt 模板
- 事件：外部系统的状态变化通知
插件系统：除了 MCP，Claude Code 还支持更轻量的插件机制，允许社区开发和分发扩展能力。
MCP / Plugins 的核心价值是：Agent 的能力边界不再由代码决定，而是由你接入了什么决定。你想让 Agent 操作 Kubernetes？接一个 MCP server。你想让 Agent 查 Jira？接一个 MCP server。能力是即插即用的。
第十一层：Remote / Schedule —— 把 Agent 放进不同执行现场
本地终端只是 Agent 的一个执行现场。Claude Code 还支持：
远程执行：Agent 在远程服务器上运行，而不是本地机器上。适合需要访问远程资源或需要更强计算能力的场景。
定时调度：用 cron 表达式定义 Agent 的执行时间。比如"每天早上 8 点检查所有 PR 的 CI 状态，如果有失败的就通知我"。
事件触发：当外部事件发生时（比如 GitHub push、Slack 消息），自动启动 Agent 执行相应任务。
这一层把 Agent 从"你坐在电脑前才能用"变成"7×24 小时自动运行"。
第十二层：Hooks —— 在关键生命周期节点插入治理和自动化
Hooks 是 Agent 生命周期中的钩子，允许你在关键节点插入自定义逻辑。
关键 Hook 点：
| Hook 点 | 触发时机 | 典型用途 |
|---|---|---|
pre_tool_use |
工具执行前 | 拦截危险操作、添加审批流程 |
post_tool_use |
工具执行后 | 记录审计日志、触发通知 |
pre_response |
模型回复前 | 内容过滤、合规检查 |
post_response |
模型回复后 | 自动格式化、翻译 |
on_task_start |
任务开始时 | 初始化环境、加载配置 |
on_task_complete |
任务完成时 | 清理临时文件、发送通知 |
Hooks 的核心价值是不侵入核心循环的前提下，实现治理和自动化。你不需要改 Agent 的源码，只需要注册一个 Hook，就能在关键节点插入你的逻辑。
第十三层：Computer Use —— 从代码环境扩展到完整桌面
前面 12 层的 Agent，操作范围还是限于代码环境：文件系统、终端命令、API 调用。
Computer Use 把这个范围扩展到了完整的桌面：
- 截屏和视觉理解：Agent 可以截取屏幕，用视觉模型理解屏幕上显示的内容
- 鼠标操作：点击、拖拽、滚动
- 键盘操作：输入文字、快捷键
- 文件系统全访问：不只是项目目录，而是整个文件系统的读写
- 所有 Linux 命令：文件查找（find/grep）、进程管理（ps/kill）、网络诊断（curl/ping/dig/nslookup/netstat/traceroute）等
这意味着 Agent 可以操作任何有图形界面的软件：浏览器、IDE、设计工具、数据库客户端、终端模拟器。
Computer Use 的核心意义是：Agent 的行动范围不再受限于"能调用什么 API"，而是"人能在电脑上做什么"。
这 13 层如何组合成一个完整的系统
最后，我们看看这 13 层是怎么协同工作的。
一个典型的工作流程：
- Remote/Schedule 触发：GitHub push 事件触发了一个定时任务
- Task System 创建任务："审查这个 PR"
- Agent Loop 启动：Agent 开始感知环境
- Prompt/Context 构造上下文：注入 PR 信息、代码变更、项目规范
- Skills/Commands 加载：匹配到 "code-review" Skill
- Memory 检索：找到这个项目之前的审查记录和已知问题
- Tool System 执行：Agent 调用 read_file 读取变更的代码
- Permission Governance 检查：read_file 是只读操作，允许执行
- Hooks 记录：pre_tool_use 和 post_tool_use 记录审计日志
- Subagent 派遣：对于复杂的审查，派遣一个子 Agent 深入分析
- MCP/Plugins 接入：通过 MCP 调用静态分析工具
- Agent Team 协作：Reviewer Agent 和 Tester Agent 协同工作
- Computer Use 扩展：如果需要在浏览器里测试功能，Agent 可以操作浏览器
- 结果回传，任务完成
每一步都经过了多层组件的协作，但是对用户来说，这一切都是透明的。
写在最后
Claude Code 的源码架构，给我们展示了"一个真正可用的 AI Agent"需要多少工程：
- Agent Loop 解决了"持续行动"的问题
- Tool System 解决了"意图变动作"的问题
- Permission Governance 解决了"动作安全"的问题
- Prompt/Context 解决了"模型看到什么"的问题
- Memory 解决了"经验积累"的问题
- Skills/Commands 解决了"能力复用"的问题
- Task System 解决了"任务追踪"的问题
- Subagent 解决了"上下文隔离"的问题
- Agent Team 解决了"多 Agent 协作"的问题
- MCP/Plugins 解决了"外部集成"的问题
- Remote/Schedule 解决了"自动运行"的问题
- Hooks 解决了"生命周期治理"的问题
- Computer Use 解决了"操作范围扩展"的问题
13 层组件，13 个工程问题，13 套解决方案。
这就是一个完整的 Agent 操作系统。
如果你正在做 AI Agent 相关的产品，这 13 层就是你需要考虑的架构清单。不一定每一层都要做，但是你必须知道每一层在解决什么问题，以及你不做这一层会有什么后果。
希望这篇文章能帮你建立一个完整的 Agent 架构认知。
作者: itech001 来源: 公众号：AI人工智能时代 网站: https://www.theaiera.cn/ 每日分享最前沿的AI新闻资讯和技术研究。
本文首发于 AI人工智能时代，转载请注明出处。
