基于 2026-03-31 泄露源码（~1,900 文件 / 512,000+ 行 TypeScript）的逆向架构分析。 本文档聚焦设计思路与可复用的工程模式，适合作为构建 AI Agent CLI 工具的学习参考。
- 总体架构概览
- 启动流程与分层引导
- Agent 循环引擎（核心）
- 工具系统与权限模型
- 多 Agent 协调架构
- MCP 协议集成与插件系统
- 终端 UI 架构（React + Ink）
- 状态管理与会话持久化
- 安全模型：多层纵深防御
- 性能工程
- 可观测性体系
- Feature Flag 与条件编译
- 你能从中学到什么
┌─────────────────────────────────────────────────────────┐
│ 入口层 (Entrypoints) │
│ CLI (Commander.js) │ SDK │ VS Code Bridge │ Assistant │
└──────────┬──────────┴─────┴───────┬────────┴────────────┘
│ │
┌──────────▼────────────────────────▼─────────────────────┐
│ 编排层 (Orchestration) │
│ QueryEngine ←→ query() 主循环 ←→ StreamingToolExecutor │
│ ├─ System Prompt 组装 (context.ts) │
│ ├─ 上下文窗口管理 (autocompact / context-collapse) │
│ ├─ 成本追踪 (cost-tracker) │
│ └─ 错误恢复 (PTL / max-output / reactive-compact) │
└──────────┬──────────────────────────────────────────────┘
│
┌──────────▼──────────────────────────────────────────────┐
│ 工具层 (Tools) │
│ BashTool │ FileEditTool │ FileReadTool │ WebFetchTool │
│ AgentTool │ GlobTool │ GrepTool │ NotebookEditTool ... │
│ ├─ 权限检查管线 (canUseTool → rules → classifier) │
│ └─ MCP 动态工具 (MCPTool) │
└──────────┬──────────────────────────────────────────────┘
│
┌──────────▼──────────────────────────────────────────────┐
│ 服务层 (Services) │
│ MCP Client │ Analytics │ OAuth │ GrowthBook │ Plugins │
│ LSP │ Compact │ Session Storage │ Team Memory Sync │
└──────────┬──────────────────────────────────────────────┘
│
┌──────────▼──────────────────────────────────────────────┐
│ UI 层 (Terminal UI) │
│ React + Ink │ 虚拟滚动 │ 权限对话框 │ 状态栏 │ Vim 模式 │
└─────────────────────────────────────────────────────────┘
技术栈：Bun 运行时 + TypeScript + React + Ink (终端 UI) + Commander.js (CLI 解析)
Claude Code 的启动流程体现了一个核心理念：越早需要的东西越先加载，不需要的东西绝不加载。
entrypoints/cli.tsx // 入口：零依赖快速路径
│
├─ --version → 直接输出 MACRO.VERSION，0 个 import
├─ --claude-in-chrome-mcp → 单独服务入口
├─ daemon/ps/logs/... → 23+ 个 feature-gated 快速路径
│
▼ (仅交互模式才继续)
main.tsx :: main() // CLI 参数解析 + 环境探测
│
├─ 并行预取：MDM 设置 + Keychain 凭证 + API 预连接
├─ Commander.js preAction hook → init() + 迁移 + 远程设置
│
▼
main.tsx :: run() // 命令路由
│
├─ setup() → 会话恢复 / Worktree 创建 / Hook 初始化
├─ showSetupScreens() → 信任对话框 / OAuth / 引导向导
│
▼
replLauncher.tsx // REPL 挂载
└─ <App><REPL /></App> // React 渲染树启动
模式 1：Side-effect 前置 + 并行预热
// main.tsx 最顶部（在所有 import 之前）
profileCheckpoint('main_tsx_entry'); // 标记入口时间
startMdmRawRead(); // 启动 macOS MDM 子进程（并行）
startKeychainPrefetch(); // 启动 Keychain 读取（并行）
// ... 然后才是 ~135ms 的模块加载不是等到需要时才读取，而是在模块评估阶段就启动 I/O 子进程，等到真正需要时结果已经就绪。
模式 2：Feature-gated 快速路径
// cli.tsx 中 23+ 个条件分支，每个都是独立子命令
if (feature('CHICAGO_MCP') && args.includes('--computer-use-mcp')) {
const { startComputerUseMcpServer } = await import('./services/computerUse/...')
return startComputerUseMcpServer() // 完全独立路径，不加载主 CLI
}大量子命令通过 feature() 在编译时被彻底移除（Dead Code Elimination），外部用户的 bundle 根本不包含内部功能代码。
模式 3：网络预连接
preconnectAnthropicApi() // TCP+TLS 握手，不等响应（fire-and-forget）在 init 阶段就建立到 Anthropic API 的 TLS 连接，等到第一次 query 时握手已完成。
这是整个产品的心脏 —— 一个流式、可恢复、支持并发工具执行的 Agent Loop。
用户输入 → QueryEngine.submitMessage()
│
├─ 1. 处理用户输入（斜杠命令/附件/文本）
├─ 2. 组装 System Prompt
│
▼
query() 主循环 ←────────────────────┐
│ │
├─ 3. 上下文管理 │
│ ├─ History Snip（截断无关消息）│
│ ├─ Microcompact（合并缓存块） │
│ ├─ Context Collapse（分阶段汇总）
│ └─ Autocompact（全量压缩） │
│ │
├─ 4. 流式 API 调用 │
│ └─ for await (callModel(...)) │
│ ├─ 实时 yield 文本块 │
│ └─ 发现 tool_use → 立即启动执行
│ │
├─ 5. 错误恢复 │
│ ├─ PTL → Context Collapse → Reactive Compact
│ ├─ Max Output → 升级 token 限制 → 重试(×3)
│ └─ 模型降级 → Tombstone + 重新流式传输
│ │
├─ 6. 工具执行 │
│ └─ StreamingToolExecutor │
│ ├─ 并发安全的工具并行执行 │
│ └─ 权限检查 → canUseTool() │
│ │
├─ 7. 附件注入 │
│ ├─ Memory 预取 │
│ ├─ Skill 发现 │
│ └─ Queued Commands │
│ │
└─ 8. 循环判断 ──────────────────┘
├─ 有 tool_use → 继续
├─ stop_reason=end_turn → 运行 stop_hooks → 可能继续
├─ maxTurns 超限 → 停止
└─ Token Budget 耗尽 → 停止
这是一个精妙的设计：不等模型生成完毕就开始执行工具。
模型输出流：[text...] [tool_use_1] [text...] [tool_use_2] [tool_use_3]
│ │ │
执行时间线： ├──执行 Tool1──┐ ├──执行 Tool2──┐
│ │ │ │
│ ▼ │ ▼
结果收集： │ Result1 │ Result2
└──执行 Tool3──→ Result3
关键约束：
isConcurrencySafe：标记为并发安全的工具（如 FileRead、Glob）可以并行执行- 非并发工具独占执行（如 BashTool、FileEdit）
siblingAbortController：一个工具出错时可以中止同级工具- 模型流式传输期间已完成的工具结果会立即被消费和 yield
这是长对话不崩溃的关键：
| 层级 | 策略 | 触发条件 | 成本 |
|---|---|---|---|
| L1 | History Snip | 总是执行 | 零（纯裁剪） |
| L2 | Microcompact | 缓存填充时 | 零（合并已有块） |
| L3 | Context Collapse | 上下文增长 | 低（分段摘要） |
| L4 | Autocompact | 接近 token 限制 | 高（全量 LLM 总结） |
当 API 返回 Prompt Too Long（PTL）错误时，恢复链：
- 先尝试 Context Collapse drain（便宜）
- 再尝试 Reactive Compact（全量压缩，剥离图片）
- 最后才显示错误
每个工具是一个实现了 Tool<Input, Output> 接口的对象：
type Tool = {
name: string
call(args, context, canUseTool, parentMessage, onProgress): Promise<ToolResult>
prompt(options): Promise<string> // 告诉模型如何使用这个工具
description(input, options): Promise<string>
inputSchema: ZodSchema // 输入验证
isReadOnly(input): boolean // 只读操作？
isConcurrencySafe(input): boolean // 可以并行？
isDestructive(input): boolean // 破坏性操作？
checkPermissions(input, context): Promise<PermissionResult>
// UI 渲染
renderToolUseMessage(input): ReactNode
renderToolResultMessage(output): ReactNode
userFacingName(input): string // "Running tests" 等活动描述
}设计亮点：
buildTool()工厂函数提供安全默认值，避免每个工具都要实现全部方法isReadOnly/isConcurrencySafe/isDestructive三维分类影响权限和执行策略prompt()方法让工具自己告诉模型使用方式，实现工具自描述
// tools.ts — Feature-gated 工具池
export function getAllBaseTools(): Tools {
return [
BashTool, FileReadTool, FileEditTool, FileWriteTool, // 核心工具
AgentTool, WebFetchTool, WebSearchTool, // 标准工具
...(process.env.USER_TYPE === 'ant' ? [REPLTool] : []), // 内部专用
...(feature('MONITOR_TOOL') ? [MonitorTool] : []), // Feature-gated
...cronTools, // 条件加载的工具组
]
}
// 根据权限上下文过滤
export function getTools(permissionContext): Tools {
// SIMPLE 模式 → 只保留 Bash + Read + Edit
// COORDINATOR 模式 → 加入 AgentTool + TaskStopTool
// 应用 deny 规则 → 移除被禁止的工具
}用户调用工具
│
▼
Layer 1: 全局权限模式
├─ bypassPermissions → 全部 allow（危险模式）
├─ dontAsk → 全部静默 deny
├─ plan → 只允许只读工具
└─ default / acceptEdits → 继续检查
│
▼
Layer 2: 规则匹配（settings.json / policy）
├─ deny rules（如 Bash(rm:*) → deny）
├─ ask rules（如 Bash(*) → always ask）
└─ allow rules（如 FileRead(*) → allow）
│
▼
Layer 3: 工具自身权限检查（checkPermissions）
├─ BashTool: AST 解析 → 语义安全检查
├─ FileEditTool: 路径约束检查
└─ AgentTool: 子 agent 权限继承
│
▼
Layer 4: ML 分类器（可选，feature-gated）
└─ Transformer 模型判断命令安全性
│
▼
Layer 5: 用户确认对话框（ask → 显示 UI）
└─ 用户选择 Allow / Deny / Always Allow
BashTool 使用 tree-sitter AST 解析来理解命令结构：
用户命令 → tree-sitter 解析 → AST
│
├─ simple（单命令）→ 语义安全检查
│ ├─ 命令白名单（git status, ls, cat...）
│ ├─ 危险标志检测（--upload-pack, -exec...）
│ └─ 路径约束验证（不越界工作目录）
│
├─ compound（管道/重定向）→ 逐段分析
│ ├─ cd + git 组合 → 沙箱逃逸风险 → deny
│ └─ 输出重定向 → 路径约束验证
│
└─ too-complex（eval/嵌套）→ 保守 ask/deny
┌─────────────────────────────────────────┐
│ Coordinator Agent │
│ （编排器，不直接执行任务） │
│ 工具：AgentTool + SendMessageTool │
│ + TaskStopTool │
└────┬────────┬────────┬──────────────────┘
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│Worker 1│ │Worker 2│ │Worker 3│ ← 每个 Worker 是独立的 Agent 循环
│ Bash │ │ Edit │ │ Read │ ← 工具集可以不同
│ Edit │ │ Write │ │ Glob │ ← 可以要求不同的权限模式
│ Read │ │ Bash │ │ Grep │ ← 可以使用不同的模型
└────────┘ └────────┘ └────────┘
Agent 可以来自三个来源：
// 内置 Agent（代码中定义）
type BuiltInAgentDefinition = {
source: 'built-in'
agentType: 'worker' | 'explore' | 'plan' | 'verification'
tools: string[] // 工具白名单
maxTurns: 30 // 最大循环次数
model: 'inherit' // 继承父级模型
getSystemPrompt: (params) => string
}
// 自定义 Agent（用户在 .claude/agents/ 中定义）
type CustomAgentDefinition = {
source: 'projectSettings' // 来自项目配置
mcpServers: [...] // 专属 MCP 服务器
skills: ['verify', 'debug'] // 预加载技能
isolation: 'worktree' // Git worktree 隔离
memory: 'project' // 项目级持久化
}每个子 Agent 获得：
- 独立的文件状态缓存（从父级克隆，但独立运行）
- 独立的成本追踪（共享父级的总预算）
- 独立的 AbortController（可以单独取消）
- 可选的 Git Worktree 隔离（在独立分支中工作）
- 继承的 MCP 客户端 + 自己的专属 MCP 服务器
配置来源 连接管理 工具暴露
┌──────────┐ ┌──────────────────┐ ┌──────────────────┐
│ 用户设置 │ │ │ │ MCP Tool │
│ 项目设置 │───▶│ MCP Client │───▶│ name: server__tool│
│ 企业策略 │ │ (stdio/sse/http) │ │ call → callTool()│
│ CLI 参数 │ │ │ │ │
│ 插件注入 │ │ 认证：OAuth/JWT │ │ MCP Resource │
└──────────┘ │ 重连：自动指数退避 │ │ MCP Prompt→Skill │
└──────────────────┘ └──────────────────┘
MCP 集成的亮点：
- 工具名称空间：
{serverName}__{toolName}避免冲突 - 大输出处理：超过阈值的结果自动持久化到磁盘
- 认证链：OAuth + JWT + Cross-App Access 三种方式
- LRU 缓存：工具/资源列表按服务器 memoize，
listChanged通知时失效
技能（Skill）= 预包装的提示词 + 行为配置：
# .claude/skills/my-skill.md
---
name: /my-skill
description: 自动化代码审查
whenToUse: 当用户请求代码审查时
tools: [FileRead, Glob, Grep] # 限制可用工具
permissionMode: plan # 只读规划模式
---
这是技能的系统提示词内容...技能来源：
- 内置技能：
verify、debug、remember、batch等 15+ - 用户技能：
~/.claude/skills/目录 - 项目技能：
.claude/skills/目录 - MCP 技能：MCP 服务器的
listPrompts()自动转换为技能
Claude Code 用 React + Ink 构建终端界面。这不是炫技，而是因为：
- 复杂的异步状态管理：同时有对话消息、工具执行进度、权限对话框、后台任务状态
- 声明式 UI 更新：状态变化自动反映到终端渲染（而非手动 ANSI 拼接）
- 组件复用：80+ 组件库（消息渲染、权限对话框、设置面板...）
<App> // FPS 监控 + 统计 + 状态提供者
<REPL> // 主交互循环
├─ <VirtualMessageList> // 虚拟滚动消息列表
│ ├─ <MessageRow> // 单条消息
│ │ ├─ <ToolUseLoader> // 工具执行中动画
│ │ ├─ <ToolResultView> // 工具结果渲染
│ │ └─ <MarkdownText> // Markdown 渲染
│ └─ <PermissionRequest> // 内联权限确认
│
├─ <StatusLine> // 底部状态栏
│ ├─ 模型名称 + Token 计数
│ ├─ 费用显示
│ └─ Bridge/Team 状态指示器
│
├─ <TextInput> // 用户输入（支持 Vim 模式）
└─ <CompanionSprite> // 小猪/恐龙动画 🐷
100+ 自定义 Hooks，按职责分组：
| 类别 | 典型 Hook | 作用 |
|---|---|---|
| 状态 | useAppState() |
全局状态读取 |
| 权限 | useCanUseTool() |
工具权限决策引擎 |
| 输入 | useVimInput() |
VI 模式文本编辑 |
| 远程 | useReplBridge() |
VS Code 扩展桥接 |
| MCP | useMergedTools() |
合并所有工具源 |
| 性能 | useVirtualScroll() |
虚拟滚动 |
type AppState = DeepImmutable<{
messages: Message[] // 对话历史
mainLoopModel: ModelSetting // 当前模型
toolPermissionContext: ToolPermissionContext // 权限上下文
mcp: { clients, tools, commands } // MCP 状态
tasks: { [taskId]: TaskState } // 后台任务
agentNameRegistry: Map<string, AgentId> // 子 Agent 注册表
// Bridge 状态
replBridgeEnabled: boolean
replBridgeConnected: boolean
replBridgeSessionActive: boolean
// 功能开关
thinkingEnabled: boolean
kairosEnabled: boolean // 助手模式
}>使用 useSyncExternalStore() 模式（类似 Zustand），不依赖 Redux。
~/.claude/sessions/{sessionId}.jsonl
├─ {type: "user_message", content: [...]}
├─ {type: "assistant_message", role: "assistant", ...}
├─ {type: "tool_use", tool_name: "bash_tool", ...}
├─ {type: "tool_result", ...}
├─ {type: "file_history_snapshot", ...} ← 文件备份（支持 --continue 恢复）
├─ {type: "attribution_snapshot", ...} ← Git 提交归属追踪
├─ {type: "context_collapse_commit", ...} ← 压缩后的上下文状态
└─ {type: "session_metadata", customTitle, tag, agent_name, ...}
优点：追加写入、易于流式读取、可部分恢复、人类可读。
--continue → 加载最近会话（跳过后台/daemon 会话）
--resume <id> → 加载指定会话（支持跨目录 JSONL 路径）
--fork-session → 复制消息到新会话 ID
恢复时协同还原：文件历史快照 + 归属快照 + 上下文压缩状态 + Todo 列表 + Agent 定义。
Claude Code 的安全设计是教科书级别的纵深防御（Defense in Depth）：
首次运行 → 信任对话框（必须 Accept）
└─ 记录到 ~/.claude/config.json
| 模式 | 行为 | 适用场景 |
|---|---|---|
default |
危险操作询问用户 | 日常使用 |
acceptEdits |
文件编辑自动允许 | 信任项目 |
plan |
只允许只读工具 | 规划阶段 |
dontAsk |
全部静默拒绝 | CI/CD |
bypassPermissions |
全部允许 | 仅内部 |
// settings.json
{
"permissions": {
"deny": ["Bash(rm:*)", "Bash(eval:*)", "FileWrite(/etc/*)"],
"ask": ["Bash(git push:*)"],
"allow": ["FileRead(*)", "Glob(*)"]
}
}支持用户级、项目级、企业策略级三层规则覆盖。
- BashTool：tree-sitter AST 解析 → 命令安全分类 → 路径约束
- FileEditTool：精确字符串匹配（防止误编辑）+ 路径约束
- AgentTool：子 Agent 权限继承 + 输出安全分类
if (feature('TRANSCRIPT_CLASSIFIER')) {
// Transformer 模型实时分类命令安全性
const classification = await classifyCommand(command)
}所有文件操作都受工作目录约束，防止沙箱逃逸：
- 输出重定向校验
cd + git组合检测- 符号链接追踪
| 优化手段 | 节省时间 | 实现方式 |
|---|---|---|
| Side-effect 前置 | ~65ms | Keychain 读取与模块加载并行 |
| 网络预连接 | ~100ms | preconnectAnthropicApi() TCP+TLS 预热 |
| mdm read 并行 | ~50ms | macOS 设备管理设置异步读取 |
| Feature DCE | ~200ms+ | feature() 编译时消除未使用代码 |
| 快速路径 | 全量 | --version 零 import 直接输出 |
- 虚拟滚动：1000+ 消息对话不卡顿
- 流式工具执行：不等模型完成就开始执行工具
- LRU 缓存：MCP 工具列表、文件状态等热路径缓存
- React Compiler：自动优化组件重渲染
- FPS 追踪：
FpsMetricsProvider实时监控终端渲染帧率
// 不阻塞主流程的后台预取
void prefetchOfficialMcpUrls() // MCP 注册表
void prefetchPassesEligibility() // 订阅状态
void prefetchFastModeStatus() // 快速模式状态
void fetchBootstrapData() // 引导数据
void prefetchAwsCredentials() // AWS 凭证（Bedrock 用户）事件层：logEvent('tengu_session_started', { subscription_type, ... })
│
├─ First-party batch logger → HTTP POST /api/event_logging/batch
├─ GrowthBook exposure tracker → 实验曝光去重
└─ OpenTelemetry → gRPC/OTLP exporters
├─ Metrics（指标）
├─ Logs（日志）
└─ Traces（链路追踪，Perfetto 格式）
// 内部用户：100% 采样
// 外部用户：0.5% 采样（低优先级事件）
const sampleRate = isAntUser ? 1.0 : 0.005// 分阶段记录启动耗时
profileCheckpoint('cli_entry')
profileCheckpoint('main_tsx_imports_loaded')
profileCheckpoint('init_function_start')
profileCheckpoint('init_function_end')
profileCheckpoint('eagerLoadSettings_end')
// → 最终生成 profileReport() 上报import { feature } from 'bun:bundle'
// 这不是运行时 if—— Bun bundler 在构建时直接消除死代码
if (feature('COORDINATOR_MODE')) {
const { CoordinatorMode } = require('./coordinator/coordinatorMode.js')
// 外部 bundle 中这整块代码不存在
}已知的 feature flag（30+）：
| Flag | 功能 |
|---|---|
COORDINATOR_MODE |
多 Agent 协调 |
KAIROS |
助手模式（Assistant） |
PROACTIVE |
主动式 Agent |
CHICAGO_MCP |
Chrome + Computer Use MCP |
BRIDGE_MODE |
VS Code 远程桥接 |
BG_SESSIONS |
后台会话 |
AGENT_TRIGGERS |
Cron 触发器 |
VOICE_MODE |
语音模式 |
DAEMON |
Daemon 长运行模式 |
HISTORY_SNIP |
历史裁剪 |
CONTEXT_COLLAPSE |
上下文折叠 |
TOKEN_BUDGET |
Token 预算控制 |
TRANSCRIPT_CLASSIFIER |
ML 安全分类器 |
// 快速路径（缓存，可能过期）
const enabled = getFeatureValue_CACHED_MAY_BE_STALE('gate_name', false)
// 慢速路径（阻塞等待初始化，保证最新）
const enabled = await checkGate_CACHED_OR_BLOCKING('security_gate')GrowthBook 数据缓存到磁盘（~/.claude.json），启动时先用缓存，后台刷新（内部 20 分钟，外部 6 小时）。
| 学习点 | Claude Code 的做法 | 适用场景 |
|---|---|---|
| Agent Loop 设计 | 流式 API 调用 + 流式工具执行 + 多层错误恢复 + 上下文窗口管理 | 任何 AI Agent 产品 |
| 工具抽象 | 统一接口 + 自描述 prompt + 三维分类（只读/并发/破坏性） | 可扩展的工具系统 |
| 权限纵深防御 | 5-6 层权限检查管线，从全局模式到 AST 级安全分析 | 需要安全保障的 AI 工具 |
| 上下文窗口管理 | 4 层渐进式压缩策略（Snip → Micro → Collapse → Compact） | 长对话 AI 应用 |
| 多 Agent 协调 | Coordinator/Worker 两层模式 + Agent 定义系统 + 上下文隔离 | 多 Agent 系统 |
| MCP 集成 | 标准化协议接入外部工具，命名空间隔离，认证链 | 工具生态扩展 |
| 学习点 | Claude Code 的做法 | 价值 |
|---|---|---|
| 启动性能 | Side-effect 前置 + 并行预热 + 编译时 DCE + 快速路径 | 毫秒级体验差异 |
| React for CLI | Ink 框架 + 声明式状态管理 + 虚拟滚动 | 复杂终端 UI |
| 不可变状态 | DeepImmutable<> + useSyncExternalStore |
可预测的状态管理 |
| 会话持久化 | NDJSON 追加写入 + 增量恢复 | 可靠的会话恢复 |
| Feature Flag | 编译时 DCE + 运行时 GrowthBook + 采样遥测 | 安全的渐进发布 |
| 条件编译 | feature() 内外部代码分离 |
单代码库多产品变体 |
| 遥测设计 | 分层采样 + 基数感知 + 延迟加载（400KB OTel 动态导入） | 低开销可观测性 |
| 错误恢复 | PTL/MaxOutput/模型降级 三级自动恢复 | 生产级容错 |
- Agent Loop 是核心——要设计得可恢复、可中断、可观测
- 工具安全不能靠单一检查——必须是纵深的多层管线
- 上下文窗口是有限资源——需要渐进式管理策略
- 启动速度是用户体验——每一毫秒都值得优化
- Feature Flag 不只是开关——配合编译时 DCE 可以做到零运行时成本
- 会话状态要持久化——NDJSON 是简单有效的方案
- 多 Agent 系统需要明确的隔离边界——文件状态、成本、中止信号都要独立
本文档基于泄露源码分析，仅供学习和研究目的。