Claude Code 架构深度解析

基于 2026-03-31 泄露源码（~1,900 文件 / 512,000+ 行 TypeScript）的逆向架构分析。

本文档聚焦设计思路与可复用的工程模式，适合作为构建 AI Agent CLI 工具的学习参考。

目录

  1. 总体架构概览
  2. 启动流程与分层引导
  3. Agent 循环引擎（核心）
  4. 工具系统与权限模型
  5. 多 Agent 协调架构
  6. MCP 协议集成与插件系统
  7. 终端 UI 架构（React + Ink）
  8. 状态管理与会话持久化
  9. 安全模型：多层纵深防御
  10. 性能工程
  11. 可观测性体系
  12. Feature Flag 与条件编译
  13. 你能从中学到什么

1. 总体架构概览


┌─────────────────────────────────────────────────────────┐

│ 入口层 (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 解析)

2. 启动流程与分层引导

设计思路：极致的启动速度优化

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 时握手已完成。

3. Agent 循环引擎（核心）

整体架构

这是整个产品的心脏 —— 一个流式、可恢复、支持并发工具执行的 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 耗尽 → 停止

流式工具执行（StreamingToolExecutor）

这是一个精妙的设计：不等模型生成完毕就开始执行工具。


模型输出流：[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）错误时，恢复链：

  1. 先尝试 Context Collapse drain（便宜）
  2. 再尝试 Reactive Compact（全量压缩，剥离图片）
  3. 最后才显示错误

4. 工具系统与权限模型

工具接口设计

每个工具是一个实现了 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 安全模型（最复杂的工具）

BashTool 使用 tree-sitter AST 解析来理解命令结构：


用户命令 → tree-sitter 解析 → AST

│

├─ simple（单命令）→ 语义安全检查

│ ├─ 命令白名单（git status, ls, cat...）

│ ├─ 危险标志检测（--upload-pack, -exec...）

│ └─ 路径约束验证（不越界工作目录）

│

├─ compound（管道/重定向）→ 逐段分析

│ ├─ cd + git 组合 → 沙箱逃逸风险 → deny

│ └─ 输出重定向 → 路径约束验证

│

└─ too-complex（eval/嵌套）→ 保守 ask/deny

5. 多 Agent 协调架构

两层编排模式


┌─────────────────────────────────────────┐

│ Coordinator Agent │

│ （编排器，不直接执行任务） │

│ 工具：AgentTool + SendMessageTool │

│ + TaskStopTool │

└────┬────────┬────────┬──────────────────┘

│ │ │

▼ ▼ ▼

┌────────┐ ┌────────┐ ┌────────┐

│Worker 1│ │Worker 2│ │Worker 3│ ← 每个 Worker 是独立的 Agent 循环

│ Bash │ │ Edit │ │ Read │ ← 工具集可以不同

│ Edit │ │ Write │ │ Glob │ ← 可以要求不同的权限模式

│ Read │ │ Bash │ │ Grep │ ← 可以使用不同的模型

└────────┘ └────────┘ └────────┘

Agent 定义系统

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 上下文隔离

每个子 Agent 获得：

  • 独立的文件状态缓存（从父级克隆，但独立运行）
  • 独立的成本追踪（共享父级的总预算）
  • 独立的 AbortController（可以单独取消）
  • 可选的 Git Worktree 隔离（在独立分支中工作）
  • 继承的 MCP 客户端 + 自己的专属 MCP 服务器

6. 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() 自动转换为技能

7. 终端 UI 架构（React + Ink）

为什么用 React 做 CLI？

Claude Code 用 React + Ink 构建终端界面。这不是炫技，而是因为：

  1. 复杂的异步状态管理：同时有对话消息、工具执行进度、权限对话框、后台任务状态
  2. 声明式 UI 更新：状态变化自动反映到终端渲染（而非手动 ANSI 拼接）
  3. 组件复用：80+ 组件库（消息渲染、权限对话框、设置面板...）

组件层次


<App> // FPS 监控 + 统计 + 状态提供者

<REPL> // 主交互循环

├─ <VirtualMessageList> // 虚拟滚动消息列表

│ ├─ <MessageRow> // 单条消息

│ │ ├─ <ToolUseLoader> // 工具执行中动画

│ │ ├─ <ToolResultView> // 工具结果渲染

│ │ └─ <MarkdownText> // Markdown 渲染

│ └─ <PermissionRequest> // 内联权限确认

│

├─ <StatusLine> // 底部状态栏

│ ├─ 模型名称 + Token 计数

│ ├─ 费用显示

│ └─ Bridge/Team 状态指示器

│

├─ <TextInput> // 用户输入（支持 Vim 模式）

└─ <CompanionSprite> // 小猪/恐龙动画 🐷

Hooks 体系

100+ 自定义 Hooks，按职责分组：

| 类别 | 典型 Hook | 作用 |

| 状态 | useAppState() | 全局状态读取 |

| 权限 | useCanUseTool() | 工具权限决策引擎 |

| 输入 | useVimInput() | VI 模式文本编辑 |

| 远程 | useReplBridge() | VS Code 扩展桥接 |

| MCP | useMergedTools() | 合并所有工具源 |

| 性能 | useVirtualScroll() | 虚拟滚动 |

8. 状态管理与会话持久化

不可变状态树


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。

会话持久化：NDJSON 方案


~/.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 定义。

9. 安全模型：多层纵深防御

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 权限继承 + 输出安全分类

第五层：ML 安全分类器（可选）


if (feature('TRANSCRIPT_CLASSIFIER')) {

// Transformer 模型实时分类命令安全性

const classification = await classifyCommand(command)

}

第六层：路径约束

所有文件操作都受工作目录约束，防止沙箱逃逸：

  • 输出重定向校验
  • cd + git 组合检测
  • 符号链接追踪

10. 性能工程

启动性能

| 优化手段 | 节省时间 | 实现方式 |

| 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 用户）

11. 可观测性体系

三层遥测架构


事件层：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

启动 Profiler


// 分阶段记录启动耗时

profileCheckpoint('cli_entry')

profileCheckpoint('main_tsx_imports_loaded')

profileCheckpoint('init_function_start')

profileCheckpoint('init_function_end')

profileCheckpoint('eagerLoadSettings_end')

// → 最终生成 profileReport() 上报

12. Feature Flag 与条件编译

feature() 函数：编译时开关


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 安全分类器 |

GrowthBook A/B 测试


// 快速路径（缓存，可能过期）

const enabled = getFeatureValue_CACHED_MAY_BE_STALE('gate_name', false)

  

// 慢速路径（阻塞等待初始化，保证最新）

const enabled = await checkGate_CACHED_OR_BLOCKING('security_gate')

GrowthBook 数据缓存到磁盘（~/.claude.json），启动时先用缓存，后台刷新（内部 20 分钟，外部 6 小时）。

13. 你能从中学到什么

架构设计层面

| 学习点 | 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/模型降级 三级自动恢复 | 生产级容错 |

对于构建类似产品的启示

  1. Agent Loop 是核心——要设计得可恢复、可中断、可观测
  2. 工具安全不能靠单一检查——必须是纵深的多层管线
  3. 上下文窗口是有限资源——需要渐进式管理策略
  4. 启动速度是用户体验——每一毫秒都值得优化
  5. Feature Flag 不只是开关——配合编译时 DCE 可以做到零运行时成本
  6. 会话状态要持久化——NDJSON 是简单有效的方案
  7. 多 Agent 系统需要明确的隔离边界——文件状态、成本、中止信号都要独立

本文档基于泄露源码分析，仅供学习和研究目的。

最后修改：2026 年 03 月 31 日
© 允许规范转载
收款不要了，给孩子补充点点赞数吧