1. Claude Code 项目概述Claude Code 是一个基于 TypeScript 开发的 AI Agent 运行时系统它不仅仅是一个简单的 CLI 聊天封装而是一个完整的 Agent 运行时环境。这个系统能够自主感知环境如读取文件系统、Git 状态做出决策选择工具、规划步骤执行操作编辑文件、运行命令并观察结果进行迭代修正。作为一个以 LLM 为决策核心、工具调用为执行手段、上下文管理为生命线的系统Claude Code 代表了当前 AI Agent 技术的先进水平。其架构设计和工程实践为开发者构建自己的 AI Agent 系统提供了宝贵的参考。2. 架构全景解析2.1 七层架构设计Claude Code 采用七层架构设计每层有明确的职责边界和接口契约┌─────────────────────────────────────────────────┐ │ 用户交互层 Interactive REPL / Single / Pipe │ ├─────────────────────────────────────────────────┤ │ 对话引擎层 QueryEngine (submitMessage / loop) │ ├─────────────────────────────────────────────────┤ │ 状态管理层 Bootstrap State AppState │ ├─────────────────────────────────────────────────┤ │ 工具执行层 43 Built-in MCP Skills Hooks │ ├─────────────────────────────────────────────────┤ │ 上下文管理层 Prompt Pipeline Memory Compact │ ├─────────────────────────────────────────────────┤ │ Agent 运行时层 Task Multi-Agent Coordinator│ ├─────────────────────────────────────────────────┤ │ 安全与权限层横切Permission Sandbox │ └─────────────────────────────────────────────────┘安全与权限层标注为横切因为权限校验发生在工具调用前、命令执行时、文件写入时等多个切面贯穿几乎所有层级。2.2 ReAct 循环核心系统的运行核心是 ReAct 循环用户输入触发 LLM 推理(Reasoning)LLM 生成工具调用(Acting)系统执行工具并将结果反馈(Observing)LLM 根据反馈决定是否继续循环这个循环持续到任务完成或触发终止条件Token/费用预算耗尽、用户中断、最大轮次限制。2.3 配置驱动设计配置驱动是架构的核心理念。QueryEngineConfig 定义了工具集、命令集、MCP 连接、Agent 配置、权限模式等所有行为参数。不同场景构造不同的 Config 实例实现一套代码多种形态。interface QueryEngineConfig { tools: Tool[]; // 可用工具集 commands: Command[]; // 斜杠命令集 mcpConnections: MCPConnection[]; // MCP 服务端连接 permissions: PermissionConfig; // 权限策略 maxTokens: number; // Token 预算上限 maxCostUSD: number; // 费用预算上限美元 agentType: general | explore | plan; // Agent 类型 systemPromptStages: PromptStage[]; // 系统提示词装配阶段 contextCompaction: CompactConfig; // 上下文压缩策略 hooks: HookConfig[]; // 生命周期钩子 // ... 更多字段 }3. 核心子系统深度解析3.1 QueryEngine对话引擎的心脏QueryEngine 处于七层架构的枢纽位置采用四阶段流水线设计┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 预处理 │ → │ 消息构建 │ → │ 查询循环 │ → │ 后处理 │ │ │ │ │ │ │ │ │ │ 消息规范化│ │ 组装System│ │ LLM 调用 │ │ 会话持久化│ │ Slash 解析│ │ Prompt │ │ 工具执行 │ │ Token 统计│ │ 上下文注入│ │ 历史输入 │ │ 结果反馈 │ │ 状态更新 │ └──────────┘ └──────────┘ │ 循环判断 │ └──────────┘ └──────────┘查询循环是核心采用 async generator 模式实现流式处理和背压控制。StreamingToolExecutor 机制允许在 SSE 流未结束时提前执行工具显著降低端到端延迟。3.2 状态管理双层架构与数据流Claude Code 采用双层状态模型Bootstrap State进程级单例存储低频配置数据AppStateReact 状态树存储高频交互数据数据流设计确保状态变更的高效传播和精准订阅QueryEngine AppState React (Ink) │ │ │ │ setState(prev ...) │ │ │─────────────────────────────→│ │ │ │ 通知 selector 订阅者 │ │ │─────────────────────────→│ │ │ │ selector 比较 │ │ │ 新旧值是否变化 │ │ │ │ │ │ │ [变化] → 重渲染 │ │ │ [未变] → 跳过 │ │ │ │ onChangeAppState 回调 │ │ │─────→ 副作用监听器 │ │ │ 日志、持久化等 │3.3 工具系统三层架构与权限模型工具系统采用统一接口 三层架构原子工具层FileRead, FileEdit, Bash 等每个工具做一件事AI 编排层LLM 自主组合多工具完成复杂任务高阶工具层AgentTool, SkillTool创建新的执行上下文权限体系采用五层漏斗设计任一层拒绝则调用被拦截Session Mode工具白名单/黑名单工具级权限操作级权限路径/命令级权限FileEditTool 采用内容匹配而非行号定位提高编辑确定性old_string 输入 ↓ 全文精确搜索 ↓ ┌────┴────┐ │ 匹配数 │ └────┬────┘ ↙ ↓ ↘ 0 1 1 ↓ ↓ ↓ 报错 执行 报错 替换4. 高级特性与工程实践4.1 Context Engineering200K Token 管理面对上下文窗口限制Claude Code 采用三维模型 六阶段提示流水线 分级压缩策略六阶段系统提示流水线┌─────────────────────────────────────────────────────────────┐ │ Stage 1: 核心指令 ┐ │ │ 角色、行为规范、安全约束 │ 稳定段 → Prompt Cache 缓存 │ │ Stage 2: 工具定义 ┘ │ │ name description schema │ ├─────────────────────────────────────────────────────────────┤ │ Stage 3: 用户上下文CLAUDE.md、引用文件 │ │ Stage 4: 系统状态git status[截断2000字符]、日期、平台 │ 动态段 │ Stage 5: 自定义提示API 传入的额外指令 │ 每轮可变 │ Stage 6: 追加提示memory 召回、运行时注入 │ └─────────────────────────────────────────────────────────────┘四种压缩策略按紧急程度递进Auto-CompactLLM 摘要保留最近 10 条Reactive CompactAPI 返回 token 超限错误时触发Snip Compact插入 [HISTORY_SNIP] 标记Context Collapse折叠非关键上下文段4.2 多 Agent 协作三种隔离级别Claude Code 支持三种协作模式按隔离级别递进子 Agent上下文独立文件系统共享后台 Agent上下文独立文件系统共享执行异步Worktree 隔离利用 Git worktree 创建独立工作目录Coordinator 模式实现任务分解与结果综合用户复杂任务 ↓ Coordinator分析 → 分解 → 分配 → 综合 │ ├──→ Agent A模块 1 修改───→ 结果 A ─┐ │ │ ├──→ Agent B模块 2 修改───→ 结果 B ──┼→ Coordinator 综合 │ │ └──→ Agent C测试验证─────→ 结果 C ─┘ ↓ 最终输出给用户4.3 安全设计纵深防御体系六层独立安全机制构成纵深防御提示注入防御指令优先级路径安全realpathSync 敏感文件黑名单命令注入防御tree-sitter AST 解析权限继承子级只能收紧运行时沙箱macOS Sandbox / Linux seccomp密钥与日志安全OS Keychain PII 过滤命令注入防御采用 AST 级分析比正则匹配更可靠正则匹配脆弱 /^rm\s-rf/ → c\at 绕过 ✓ $(echo rm) 绕过 ✓ tree-sitter AST准确 command_node ├── name: rm → 识别真实命令名 ├── flags: [-r, -f] → 解析标志含义 └── args: [/] → 检查危险参数5. 性能工程与优化策略5.1 全链路优化Claude Code 在四个维度实施性能优化启动阶段Bun 替代 Node.js冷启动从 ~100ms 降至 ~10msAPI 调用Prompt Caching命中率 90%成本降为 1/10本地计算Ripgrep 替代原生文件遍历速度提升 10-100 倍终端渲染React Compiler 自动 memoization5.2 八大设计原则从源码中提炼的八大设计原则透明优于便捷安全默认便捷可选单一职责 AI 编排显式优于隐式为失败设计可观测性渐进复杂度代码即文档这些原则贯穿各子系统形成架构一致性┌─────────────┐ │ 透明 便捷 │ └──────┬──────┘ │ 指导 ┌──────┴───────┐ ↓ ↓ ┌────────┐ ┌──────────┐ │安全默认│ │可观测性 │ └───┬────┘ └────┬─────┘ │ │ └──────┬──────┘ ↓ ┌──────────┐ │为失败设计│ └──────┬───┘ │ ┌──────┴──────┐ ↓ ↓ ┌────────┐ ┌──────────┐ │单一职责│ │渐进复杂度│ │AI编排 │ │ │ └────────┘ └──────────┘6. 工程实践启示Claude Code 的架构设计为构建 AI Agent 系统提供了多个关键启示基础设施重于模型调用LLM 是核心但非全部上下文管理、工具系统等基础设施决定系统能力上限。配置驱动架构通过运行时组装不同配置同一套代码可支持多样化 Agent 形态。安全必须内建从工具调用到多 Agent 协作安全考量应贯穿每个设计决策。上下文工程是关键在有限 Token 窗口内高效管理信息流入流出直接决定 Agent 推理质量。扩展性分层设计Markdown(Skill)→协议(MCP)→代码(Hook)的三层机制覆盖不同技术背景的扩展者。在实际工程中开发者应根据自身场景特点合理借鉴这些设计理念而非简单复制实现。特别是在性能与安全、透明与便捷等需要权衡的领域找到适合自己项目的最优平衡点。
TypeScript AI Agent运行时系统Claude Code架构解析
1. Claude Code 项目概述Claude Code 是一个基于 TypeScript 开发的 AI Agent 运行时系统它不仅仅是一个简单的 CLI 聊天封装而是一个完整的 Agent 运行时环境。这个系统能够自主感知环境如读取文件系统、Git 状态做出决策选择工具、规划步骤执行操作编辑文件、运行命令并观察结果进行迭代修正。作为一个以 LLM 为决策核心、工具调用为执行手段、上下文管理为生命线的系统Claude Code 代表了当前 AI Agent 技术的先进水平。其架构设计和工程实践为开发者构建自己的 AI Agent 系统提供了宝贵的参考。2. 架构全景解析2.1 七层架构设计Claude Code 采用七层架构设计每层有明确的职责边界和接口契约┌─────────────────────────────────────────────────┐ │ 用户交互层 Interactive REPL / Single / Pipe │ ├─────────────────────────────────────────────────┤ │ 对话引擎层 QueryEngine (submitMessage / loop) │ ├─────────────────────────────────────────────────┤ │ 状态管理层 Bootstrap State AppState │ ├─────────────────────────────────────────────────┤ │ 工具执行层 43 Built-in MCP Skills Hooks │ ├─────────────────────────────────────────────────┤ │ 上下文管理层 Prompt Pipeline Memory Compact │ ├─────────────────────────────────────────────────┤ │ Agent 运行时层 Task Multi-Agent Coordinator│ ├─────────────────────────────────────────────────┤ │ 安全与权限层横切Permission Sandbox │ └─────────────────────────────────────────────────┘安全与权限层标注为横切因为权限校验发生在工具调用前、命令执行时、文件写入时等多个切面贯穿几乎所有层级。2.2 ReAct 循环核心系统的运行核心是 ReAct 循环用户输入触发 LLM 推理(Reasoning)LLM 生成工具调用(Acting)系统执行工具并将结果反馈(Observing)LLM 根据反馈决定是否继续循环这个循环持续到任务完成或触发终止条件Token/费用预算耗尽、用户中断、最大轮次限制。2.3 配置驱动设计配置驱动是架构的核心理念。QueryEngineConfig 定义了工具集、命令集、MCP 连接、Agent 配置、权限模式等所有行为参数。不同场景构造不同的 Config 实例实现一套代码多种形态。interface QueryEngineConfig { tools: Tool[]; // 可用工具集 commands: Command[]; // 斜杠命令集 mcpConnections: MCPConnection[]; // MCP 服务端连接 permissions: PermissionConfig; // 权限策略 maxTokens: number; // Token 预算上限 maxCostUSD: number; // 费用预算上限美元 agentType: general | explore | plan; // Agent 类型 systemPromptStages: PromptStage[]; // 系统提示词装配阶段 contextCompaction: CompactConfig; // 上下文压缩策略 hooks: HookConfig[]; // 生命周期钩子 // ... 更多字段 }3. 核心子系统深度解析3.1 QueryEngine对话引擎的心脏QueryEngine 处于七层架构的枢纽位置采用四阶段流水线设计┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 预处理 │ → │ 消息构建 │ → │ 查询循环 │ → │ 后处理 │ │ │ │ │ │ │ │ │ │ 消息规范化│ │ 组装System│ │ LLM 调用 │ │ 会话持久化│ │ Slash 解析│ │ Prompt │ │ 工具执行 │ │ Token 统计│ │ 上下文注入│ │ 历史输入 │ │ 结果反馈 │ │ 状态更新 │ └──────────┘ └──────────┘ │ 循环判断 │ └──────────┘ └──────────┘查询循环是核心采用 async generator 模式实现流式处理和背压控制。StreamingToolExecutor 机制允许在 SSE 流未结束时提前执行工具显著降低端到端延迟。3.2 状态管理双层架构与数据流Claude Code 采用双层状态模型Bootstrap State进程级单例存储低频配置数据AppStateReact 状态树存储高频交互数据数据流设计确保状态变更的高效传播和精准订阅QueryEngine AppState React (Ink) │ │ │ │ setState(prev ...) │ │ │─────────────────────────────→│ │ │ │ 通知 selector 订阅者 │ │ │─────────────────────────→│ │ │ │ selector 比较 │ │ │ 新旧值是否变化 │ │ │ │ │ │ │ [变化] → 重渲染 │ │ │ [未变] → 跳过 │ │ │ │ onChangeAppState 回调 │ │ │─────→ 副作用监听器 │ │ │ 日志、持久化等 │3.3 工具系统三层架构与权限模型工具系统采用统一接口 三层架构原子工具层FileRead, FileEdit, Bash 等每个工具做一件事AI 编排层LLM 自主组合多工具完成复杂任务高阶工具层AgentTool, SkillTool创建新的执行上下文权限体系采用五层漏斗设计任一层拒绝则调用被拦截Session Mode工具白名单/黑名单工具级权限操作级权限路径/命令级权限FileEditTool 采用内容匹配而非行号定位提高编辑确定性old_string 输入 ↓ 全文精确搜索 ↓ ┌────┴────┐ │ 匹配数 │ └────┬────┘ ↙ ↓ ↘ 0 1 1 ↓ ↓ ↓ 报错 执行 报错 替换4. 高级特性与工程实践4.1 Context Engineering200K Token 管理面对上下文窗口限制Claude Code 采用三维模型 六阶段提示流水线 分级压缩策略六阶段系统提示流水线┌─────────────────────────────────────────────────────────────┐ │ Stage 1: 核心指令 ┐ │ │ 角色、行为规范、安全约束 │ 稳定段 → Prompt Cache 缓存 │ │ Stage 2: 工具定义 ┘ │ │ name description schema │ ├─────────────────────────────────────────────────────────────┤ │ Stage 3: 用户上下文CLAUDE.md、引用文件 │ │ Stage 4: 系统状态git status[截断2000字符]、日期、平台 │ 动态段 │ Stage 5: 自定义提示API 传入的额外指令 │ 每轮可变 │ Stage 6: 追加提示memory 召回、运行时注入 │ └─────────────────────────────────────────────────────────────┘四种压缩策略按紧急程度递进Auto-CompactLLM 摘要保留最近 10 条Reactive CompactAPI 返回 token 超限错误时触发Snip Compact插入 [HISTORY_SNIP] 标记Context Collapse折叠非关键上下文段4.2 多 Agent 协作三种隔离级别Claude Code 支持三种协作模式按隔离级别递进子 Agent上下文独立文件系统共享后台 Agent上下文独立文件系统共享执行异步Worktree 隔离利用 Git worktree 创建独立工作目录Coordinator 模式实现任务分解与结果综合用户复杂任务 ↓ Coordinator分析 → 分解 → 分配 → 综合 │ ├──→ Agent A模块 1 修改───→ 结果 A ─┐ │ │ ├──→ Agent B模块 2 修改───→ 结果 B ──┼→ Coordinator 综合 │ │ └──→ Agent C测试验证─────→ 结果 C ─┘ ↓ 最终输出给用户4.3 安全设计纵深防御体系六层独立安全机制构成纵深防御提示注入防御指令优先级路径安全realpathSync 敏感文件黑名单命令注入防御tree-sitter AST 解析权限继承子级只能收紧运行时沙箱macOS Sandbox / Linux seccomp密钥与日志安全OS Keychain PII 过滤命令注入防御采用 AST 级分析比正则匹配更可靠正则匹配脆弱 /^rm\s-rf/ → c\at 绕过 ✓ $(echo rm) 绕过 ✓ tree-sitter AST准确 command_node ├── name: rm → 识别真实命令名 ├── flags: [-r, -f] → 解析标志含义 └── args: [/] → 检查危险参数5. 性能工程与优化策略5.1 全链路优化Claude Code 在四个维度实施性能优化启动阶段Bun 替代 Node.js冷启动从 ~100ms 降至 ~10msAPI 调用Prompt Caching命中率 90%成本降为 1/10本地计算Ripgrep 替代原生文件遍历速度提升 10-100 倍终端渲染React Compiler 自动 memoization5.2 八大设计原则从源码中提炼的八大设计原则透明优于便捷安全默认便捷可选单一职责 AI 编排显式优于隐式为失败设计可观测性渐进复杂度代码即文档这些原则贯穿各子系统形成架构一致性┌─────────────┐ │ 透明 便捷 │ └──────┬──────┘ │ 指导 ┌──────┴───────┐ ↓ ↓ ┌────────┐ ┌──────────┐ │安全默认│ │可观测性 │ └───┬────┘ └────┬─────┘ │ │ └──────┬──────┘ ↓ ┌──────────┐ │为失败设计│ └──────┬───┘ │ ┌──────┴──────┐ ↓ ↓ ┌────────┐ ┌──────────┐ │单一职责│ │渐进复杂度│ │AI编排 │ │ │ └────────┘ └──────────┘6. 工程实践启示Claude Code 的架构设计为构建 AI Agent 系统提供了多个关键启示基础设施重于模型调用LLM 是核心但非全部上下文管理、工具系统等基础设施决定系统能力上限。配置驱动架构通过运行时组装不同配置同一套代码可支持多样化 Agent 形态。安全必须内建从工具调用到多 Agent 协作安全考量应贯穿每个设计决策。上下文工程是关键在有限 Token 窗口内高效管理信息流入流出直接决定 Agent 推理质量。扩展性分层设计Markdown(Skill)→协议(MCP)→代码(Hook)的三层机制覆盖不同技术背景的扩展者。在实际工程中开发者应根据自身场景特点合理借鉴这些设计理念而非简单复制实现。特别是在性能与安全、透明与便捷等需要权衡的领域找到适合自己项目的最优平衡点。
