深度揭秘 Anthropic Claude Code 架构设计，快速读懂 AI Agent 的核心秘密

Anthropic 在发布 Claude Code 的 npm 包时，意外没有排除 source map 文件，导致了庞大的源码泄露。虽然官方迅速修复，但有人将该源码发布到了GitHub上，这份庞大的源码映射文件，让我们有机会窥探到 Claude Code 背后的设计巧思。今天，我们不谈泄露风险，只聊技术架构，帮你快速理清这个高质量 AI Agent 平台的核心要点。

源码地址：https://github.com/instructkr/claude-code

1. 代码结构与运行环境

Claude Code 用 TypeScript 编写，运行于 Node.js。其终端界面由 React + Ink 组成，Ink 让 React 组件能在命令行流畅渲染。源码模块大致分为：

• entrypoints/：启动与初始化逻辑
• query/：Agent 循环引擎，AI 交互核心
• tools/：45+ 工具实现，能力丰富
• commands/：丰富命令集，超过 100 条
• services/：API 调用、分析等业务逻辑
• components/ 和 hooks/：UI 组件和 React 钩子
• state/：状态管理
• utils/swarm/：多 Agent 协作核心
• skills/：扩展功能的 skill 系统
• buddy/：隐藏的电子宠物彩蛋

光是主入口 main.tsx 就有 800KB，体现出项目体量不小。

2. 细粒度的启动流程与信任边界

Claude Code 启动分六阶段，设计巧妙保障安全与速度：

• 并行预取：比如配置信息和系统 keychain 同时加载，避免等待。
• 配置验证：遇错直接报错，保证环境正确。
• 安全环境变量配置：仅加载必要证书和网络配置。
• 信任确认：用户确认风险，开启「信任边界」，后面才允许加载更多权限。
• 完整初始化：OAuth、LSP、Git 仓库检测等。
• 延迟预取：初步渲染完再慢慢加载非关键内容，提升启动速度。

这种分阶段加载+信任边界的设计非常适合需要敏感权限管理的 AI 产品。

3. 核心 Agent 循环：流式工具即时执行

系统核心在于 Agent 循环，实现方式概括为：

• 收集上下文（用户消息、系统状态、历史记录）生成完整 prompt
• 调用 Claude API，开启流式返回
• 模型返回过程中遇到工具调用，立即执行该工具，不等待完整回复
• 根据模型反馈判断是否继续调用工具或结束循环

此外，有安全阀限制循环最大轮次和预算，防止无限调用形成恶性循环。

4. 工具执行策略：并发与串行分明

工具分两类：

• 并发安全工具：文件读取、搜索等无状态操作允许并行执行
• 非并发安全工具：写文件、执行 bash 命令等会修改状态，需串行

每个工具自带并发安全判断，框架统一调度，确保性能与安全兼顾。用户按下 Esc 可精确取消对应正在执行的工具调用。

5. 四层权限管道，精细控制安全风险

权限系统分五模式，重点是 auto 模式，采用四层递进阻断风险：

1. 规则匹配：简单快速字符串规则
2. Bash 命令分类器：识别常见危险操作，如 rm -rf 等
3. 对话上下文分类器：针对复杂语境判定安全
4. Claude Sonnet API 调用：独立模型最终判定，保证严密

由快到慢的多层过滤保证了体验流畅又安全。

6. 上下文与消息管理：智能压缩与渐进披露

上下文窗口容量有限，Claude Code 设计了：

• 多来源系统提示文件（多层级 CLAUDE.md）
• 记忆文件索引与按需加载机制
• 自动压缩早期对话与工具调用，保留关键信息，节约 tokens
• 延迟加载工具和复杂技能，不一开始就放进 prompt
• 大窗口支持最高可扩展至百万级 token

渐进式工具披露，模型只拿必要工具 schema，避免 prompt 爆炸。

7. Skill 扩展体系，灵活且可定制

Skill 本质是带有前置声明的 Markdown 文件，从多层渠道加载，支持多种触发条件和权限配置。技能的参数替换和激活路径设计精巧，支持成百上千技能而不影响性能。

8. MCP（Model Context Protocol）一等公民

Claude Code 对 MCP 的支持非常全面：

• 多种传输协议支持（stdio、SSE、WebSocket、HTTP）
• 三重认证机制，减轻用户认证负担
• 工具列表延迟加载，按需获取 schema
• 多 MCP 服务器动态增量通知和防竞态写入

MCP 从配角变成核心能力，支持灵活联网 Agent。

9. 多 Agent 协作：“Swarm” 系统

多 Agent 以 InProcess 模式为主，利用 Node.js 的 AsyncLocalStorage 实现上下文隔离，避免了进程通信开销。权限请求通过 mailbox 发送给 leader agent 审批。团队和成员 Agent 配置清晰，实时 UI 标记身份。

10. 丰富实用的附加功能

• Loop 定时任务：内置 Skill 支持灵活的 cron 表达式调度，支持本地与远程（云端）触发，默认 14 天过期。
• 快捷键系统：上下文感知，自定义组合键，支持热重载，提升终端交互体验。
• Hook 机制：提供生命周期事件扩展，支持 SDK 回调和 shell 命令，方便插件与用户自定义逻辑注入。
• 状态管理：分全局基础设施状态和 React 渲染相关状态清晰管理。
• 费用追踪：实时监控模型调用和搜索开销，避免无意中费用飙升。

11. 终极彩蛋：电子宠物系统

Claude Code 内置还隐藏着一个有趣的电子宠物系统（计划于 2026 愚人节上线）。18 种宠物，各具 ASCII 画风和动画，带稀有度与属性设定，还能跟用户互动。Anthropic 工程师的小心思，给严肃的 AI 产品增添了童趣。

总结：AI Agent 的架构宝典

从 Claude Code 的设计，我们能提炼到几个对 AI Agent 开发极具启发意义的原则：

• 流式优先：实时执行，降低用户等待感
• 权限即管道：多层、渐进的权限判断，比简单开关更安全
• 工具声明并发安全：框架调度更灵活高效
• 上下文才是核心：智能压缩和渐进加载至关重要
• 多 Agent 不必多进程：合理上下文隔离即可高效协作
• 开放可扩展通过 Hook：比硬编码更灵活，利于生态发展

整体而言，Claude Code 不仅是 Anthropic 构建 AI Agent 的旗舰项目，更是一本活生生的 Agent 架构教科书，值得每个 AI 工程师细细品读。

欢迎关注一步API（https://yibuapi.com） ，我们还会持续分享更多AI咨询、AI工具、实战经验、踩坑记录，助力你高效玩转AI开发、避开行业弯路。

想了解更多细节、获取专属支持，可添加客服微信：xuexiv5876 \ YibuDev，随时咨询交流～