Claude Code 架构概览

写代码的皮卡丘
0 阅读6分钟

Claude Code 架构概览

Claude Code 的核心是一个生产级的、具备自治能力的代码代理（Code Agent） 。其本质是一个精心设计的工程化系统，通过为概率性的LLM（大语言模型）构建一套确定性的控制体系，实现了从“思考”到“执行”再到“验证”的完整闭环。

其架构设计遵循关注点分离原则，将复杂的代理行为拆解为职责清晰的层次，确保了系统的可维护性、安全性与可扩展性。

目录参考

src/
├── main.tsx                 # REPL 引导程序，4,683 行
├── QueryEngine.ts           # SDK/headless 查询生命周期引擎
├── query.ts                 # 主代理循环 (785KB，最大文件)
├── Tool.ts                  # 工具接口 + buildTool 工厂
├── Task.ts                  # 任务类型、ID、状态基类
├── tools.ts                 # 工具注册、预设、过滤
├── commands.ts              # 斜杠命令定义
├── context.ts               # 用户输入上下文
├── cost-tracker.ts          # API 成本累积
├── setup.ts                 # 首次运行设置流程
│
├── bridge/                  # Claude Desktop / 远程桥接
│   ├── bridgeMain.ts        #   会话生命周期管理器
│   ├── bridgeApi.ts         #   HTTP 客户端
│   ├── bridgeConfig.ts      #   连接配置
│   ├── bridgeMessaging.ts   #   消息中继
│   ├── sessionRunner.ts     #   进程生成
│   ├── jwtUtils.ts          #   JWT 刷新
│   ├── workSecret.ts        #   认证令牌
│   └── capacityWake.ts      #   基于容量的唤醒
│
├── cli/                     # CLI 基础设施
│   ├── handlers/            #   命令处理器
│   └── transports/          #   I/O 传输 (stdio, structured)
│
├── commands/                # ~80 个斜杠命令
├── components/              # React/Ink 终端 UI
├── entrypoints/             # 应用入口点
├── hooks/                   # React hooks
├── services/                # 业务逻辑层
├── state/                   # 应用状态
├── tasks/                   # 任务实现
├── tools/                   # 40+ 工具实现
├── types/                   # 类型定义
├── utils/                   # 工具函数（最大目录）
└── vendor/                  # 原生模块源码存根

核心引擎：代理循环 (The Agent Loop)

整个系统的“心脏”是一个名为代理循环的状态机。它不是一个简单的 while(true)，而是一个精密的、可中断的、支持流式处理的执行引擎。

                    核心循环
                    ========

    用户 --> messages[] --> Claude API --> 响应
                                          |
                                stop_reason == "tool_use"?
                               /                          \
                             是                           否
                              |                             |
                        执行工具                        返回文本
                        追加 tool_result
                        循环回退 -----------------> messages[]


    这就是最小的代理循环。Claude Code 在此循环上
    包裹了生产级线束：权限、流式传输、并发、
    压缩、子代理、持久化和 MCP。
  1. 用户输入：用户的指令被封装成 messages[]。
  2. API调用：messages[] 被发送至 Claude API 进行推理。
  3. 决策分支：API 返回的响应中，stop_reason 决定了下一步行动。
    • 工具调用 ( tool_use ) ：模型决定需要执行一个操作（如读取文件、运行命令）。系统会执行工具，将结果封装为 tool_result 并追加到 messages[] 中，然后循环回退，带着新信息再次请求API。
    • 文本响应：模型认为任务已完成或需要用户输入，则直接将文本结果返回给用户。

这个最小循环是 Claude Code 自主完成复杂任务的骨架。所有生产级特性——如权限控制、上下文压缩、子代理等——都是在此循环之上构建的增强层。

️ 分层架构：从入口到执行

Claude Code 的源码结构清晰地反映了其分层架构思想，从顶层的用户交互到底层的工具实现，各司其职。

┌─────────────────────────────────────────────────────────────────────┐
│                         入口层                                      │
│  cli.tsx ──> main.tsx ──> REPL.tsx (交互式)                        │
│                     └──> QueryEngine.ts (headless/SDK)              │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       查询引擎                                      │
│  submitMessage(prompt) ──> AsyncGenerator<SDKMessage>               │
│    ├── fetchSystemPromptParts()    ──> 组装系统提示词               │
│    ├── processUserInput()          ──> 处理 /命令                   │
│    ├── query()                     ──> 主代理循环                   │
│    │     ├── StreamingToolExecutor ──> 并行工具执行                  │
│    │     ├── autoCompact()         ──> 上下文压缩                   │
│    │     └── runTools()            ──> 工具编排                     │
│    └── yield SDKMessage            ──> 流式传输给消费者             │
└──────────────────────────────┬──────────────────────────────────────┘

入口层 (Entry Layer)
这是用户与系统交互的起点，负责引导和会话生命周期管理。

  • 交互式模式 (REPL) ：由 main.tsx 引导，启动基于终端的交互式界面，处理用户的实时输入。
  • 无头/SDK模式：由 QueryEngine.ts 驱动，为外部程序或脚本提供查询接口，管理完整的会话生命周期。

编排层 (Orchestration Layer)
这是代理循环的核心实现，负责上下文管理、API通信和流程控制。

  • 查询引擎 ( QueryEngine.ts ) ：作为会话的“协调者”，它接收用户输入，组装包含静态规则和动态上下文的系统提示词，并启动代理循环。它通过 AsyncGenerator 实现流式输出和背压控制，允许调用方按需消费消息。
  • 主循环 ( query.ts ) ：这是整个系统代码量最大、逻辑最复杂的文件，是代理循环的具体实现。它负责：
    • 调用 LLM API。
    • 解析响应并分发工具调用。
    • 触发上下文压缩 (autoCompact)，在上下文窗口接近上限时，智能地总结历史对话，确保关键信息不丢失。
    • 管理工具的执行编排 (runTools)。

能力层 (Capability Layer)
这一层将抽象的工具调用转化为具体的、安全的操作。

  • 工具系统 ( tools/ , Tool.ts ) ：包含40多个工具的实现，如文件读写、终端命令执行、Git操作等。Tool.ts 定义了工具的通用接口和工厂函数。
  • Harness (控制面) ：这是 Claude Code 走向生产环境的关键，扮演着“方向盘+安全带”的角色。它通过一系列钩子 (Hooks) 在循环的关键节点进行强制干预，实现确定性控制：
    • PreToolUse：在工具执行前进行权限检查和安全校验，例如拦截危险的 rm -rf 命令。
    • PostToolUse：在工具执行后进行结果处理，如自动格式化代码或运行测试。
    • UserPromptSubmit：在用户提交指令后，动态注入项目规则或上下文信息。

生态层 (Ecosystem Layer)
这一层处理与外部世界的连接和扩展。

  • MCP (模型上下文协议) ：作为AI时代的“USB-C”，MCP标准化了Agent与外部资源（如数据库、API）的连接方式，实现了能力的即插即用。
  • Skills (技能) ：一种模块化的“知识胶囊”。当遇到特定领域的复杂任务时，系统会按需加载对应的Skill文件夹（包含SKILL.md指南和相关脚本），为LLM提供精确的操作指引，而无需将所有知识常驻内存。
  • 子代理 (Subagents) ：一种“分而治之”的架构。主Agent可以生成一个拥有独立上下文和工具集的子Agent实例（本质上是递归调用 query.ts），将复杂任务分解。这种设计支持无限嵌套，极大地提升了处理复杂问题的能力。

关键架构观察

  1. query.ts是绝对核心：所有的数据流、上下文、工具调用和API交互最终都汇聚于此。它是理解整个系统运作的关键。
  2. utils/是隐藏的巨人：这个目录占据了总代码量的三分之一以上，包含了权限系统、安全检查、会话存储等最核心的业务逻辑。它远非简单的“工具函数”集合，而是整个系统的“暗物质”。
  3. UI复杂度不容小觑：components/ 目录拥有超过8万行代码，表明Claude Code的终端交互体验已经堪比一个图形界面应用，包含了权限弹窗、多Agent面板、Diff预览等丰富的React组件。
  4. 递归是强大的设计模式：子代理通过递归调用主循环实现，这种设计使得Agent能力可以无限组合与嵌套，是系统可扩展性的基石。
  5. 软硬结合的控制哲学：系统通过 CLAUDE.md（软约束，引导意图）和 Harness（硬约束，强制执行）相结合，在LLM的灵活性与工程实践的确定性之间找到了最佳平衡点。

avatar
文章
阅读
粉丝