万字长文拆解 Claude Code 源码:Anthropic 如何打造最强Agent

世界是个草台班子，claude code官方研发不小心将带有sourcemap的npm包发布到公共仓库，然后就被人反向追踪出了源代码。

我也连夜构建了进行了运行测试，用claude模型分析claude code，我想没人比它更懂它自己家的东西了吧。接下来我们就看下它是如何实现Harness设计，如何做账号封控。

万字长文，请注意关注收藏，方便后续查看。

首先我们还是要知道，Claude Code 是 Anthropic 推出的 AI  Agent编程助手，以终端原生体验著称——它不是一个 IDE 插件，而是一个独立的 CLI 应用，能直接在你的终端里读写文件、执行命令、搜索代码、管理 Git，甚至操控浏览器。

最近，有开发者通过 source map 还原了 Claude Code 的完整源码。这让我们第一次有机会从工程角度，深入了解 Anthropic 是如何设计和实现这样一款复杂的 AI 原生应用的。

本文基于这份还原后的源码树，从架构设计、技术选型、核心子系统等多个维度进行拆解。

一、技术选型：为什么是 Bun + Ink + React？

Claude Code 的技术栈选择颇具启发性：

层级	技术选型	选择理由
运行时	Bun	极快的启动速度、原生 TypeScript 支持、内置包管理
语言	TypeScript (ESM)	类型安全、模块化、生态丰富
终端 UI	Ink + React	组件化终端渲染，复用 React 生态
LLM SDK	@anthropic-ai/sdk	官方 SDK，支持流式输出
协议层	MCP SDK	Model Context Protocol 标准实现
可观测性	OpenTelemetry	全链路追踪和指标收集
配置校验	Zod	运行时类型校验
特性开关	GrowthBook	A/B 测试和渐进式发布

几个值得注意的选择：

选 Bun 而非 Node.js，核心原因是启动性能。CLI 工具的冷启动时间至关重要，Bun 的零编译 TypeScript 执行和更快的模块解析，让 Claude Code 能在毫秒级完成引导。

选 Ink 而非 blessed 或 raw ANSI，是因为 React 的组件化模型天然适合构建复杂的交互式终端界面。Claude Code 的 REPL 需要处理消息列表虚拟化、对话框焦点管理、权限弹窗、进度动画等大量 UI 状态——用命令式 API 管理这些会是一场噩梦。

引入 OpenTelemetry，说明 Anthropic 对 AI 应用的可观测性非常重视。从 API 调用延迟、Token 消耗、工具执行耗时到用户交互模式，全部纳入了监控体系。

二、启动架构：多阶段引导与性能极致优化

Claude Code 的启动流程是一个精心设计的多阶段管线：

bootstrap-entry.ts        ← Bun 入口  ↓ ensureBootstrapMacro()  ← 编译期宏注入entrypoints/cli.tsx       ← 快速路径：--version / --help 零导入返回  ↓main.tsx                  ← 完整初始化  ├─ profileCheckpoint()        ← 各阶段计时  ├─ startMdmRawRead()          ← 异步企业管理配置  ├─ startKeychainPrefetch()    ← 并行预取 OAuth/API 密钥  ├─ init()                     ← 核心初始化  ├─ getTools()                 ← 注册 40+ 工具  └─ launchRepl()               ← 启动交互循环

有几个精妙的设计点：

零导入快速路径：当用户只是执行 claude --version 时，不会触发任何重量级模块的加载。版本号通过编译期宏 MACRO.VERSION 直接内联，做到真正的零开销。

并行预取：Keychain 读取、MDM 配置加载、远程设置拉取等 I/O 密集型操作全部并行启动，不阻塞主线程。

编译期死代码消除：通过 feature('COORDINATOR_MODE')、feature('KAIROS') 等特性门控函数，配合编译器的 DCE（Dead Code Elimination），确保未启用的功能模块不会出现在最终产物中。

三、REPL 核心：2000 行的 React 组件如何驾驭终端交互

Claude Code 的核心交互界面是一个约 2000+ 行的 React 组件——REPL.tsx。它处理了令人惊讶的复杂度：

REPL 组件  ├─ VirtualMessageList     ← 虚拟化消息列表（支持数千条消息）  ├─ PromptInput            ← 用户输入（多行、补全、历史）  ├─ MessageRow             ← 消息渲染（Markdown、代码高亮）  ├─ ToolUseLoader          ← 工具执行状态展示  ├─ PermissionRequest      ← 权限请求对话框  ├─ CostThresholdDialog    ← Token 消耗预警  └─ StatusLine             ← 底部状态栏

消息虚拟化是一个关键优化。与 Web 端的虚拟列表类似，Claude Code 不会把所有历史消息都保持在渲染树中，而是只渲染可视区域内的消息节点——这让它即使在超长对话中也能保持流畅。

焦点管理系统则解决了终端 UI 的一个核心难题：当同时存在输入框、权限弹窗、成本警告对话框时，键盘焦点应该路由到哪里？Claude Code 用 FocusManager 实现了一个焦点栈，确保弹窗总是优先获取输入。

整个 UI 状态流转遵循经典的单向数据流：

用户输入 → processUserInput()    ↓QueryEngine.query()          ← 调用 LLM    ↓工具调用 → Tool.invoke()     ← 执行工具    ↓AppState 更新 → React 重渲染 → 终端输出    ↓回到输入等待

四、工具系统：40+ 工具的统一抽象

Claude Code 的工具系统是其核心竞争力。所有工具都遵循统一的接口定义：

buildTool({name: 'file-read',displayName: 'Read File',description: '...',inputSchema: { /* JSON Schema */ },invoke: async (input, context) => {return { output: '...' }  }})

40+ 个内置工具可以大致分为六大类：

#文件操作

• FileReadTool：读取文件，支持图片、PDF、Jupyter Notebook 等多种格式
• FileEditTool：编辑文件，带差异预览
• FileWriteTool：创建新文件
• GlobTool：文件模式匹配搜索
• GrepTool：全文内容搜索

#代码执行

• BashTool：Shell 命令执行（核心工具，使用频率最高）
• PowerShellTool：Windows 平台支持
• NotebookEditTool：Jupyter Notebook 编辑

#智能体与工作流

• AgentTool：生成子智能体（协调器模式下使用）
• TeamCreateTool / TeamDeleteTool：多智能体团队管理
• SendMessageTool：智能体间通信
• SkillTool：调用已安装的技能包

#Web 能力

• WebFetchTool：HTTP 请求
• WebSearchTool：网络搜索
• WebBrowserTool：完整浏览器自动化控制

#MCP 集成

• MCPTool：调用任意 MCP 工具
• ListMcpResourcesTool / ReadMcpResourceTool：MCP 资源管理

#任务与规划

• TaskCreateTool / TaskGetTool / TaskListTool：任务追踪
• EnterPlanModeTool / ExitPlanModeTool：规划模式切换

#权限控制

工具系统内建了三级权限模型：

模式	行为	适用场景
AUTO	严格受限，仅允许文件读取等安全操作	自动化流水线
MANUAL	每次工具调用需用户确认	常规交互
BYPASS	所有工具直接可用	受信环境

这种设计在安全性和便捷性之间取得了很好的平衡——你可以让 Claude 在沙箱中自由操作，也可以要求它每一步都问你的意见。

五、MCP：Model Context Protocol 的深度集成

Claude Code 是 MCP（Model Context Protocol）的标杆实现之一。它的 MCP 集成不是简单的”调一调 API”，而是一个完整的基础设施：

#多作用域配置系统

配置优先级（从高到低）：enterprise → project → user → dynamic → claudeai（官方默认）

每个作用域可以配置不同的 MCP 服务器，用 Zod Schema 做运行时校验，支持环境变量展开和 OAuth 认证。

#多传输协议

Claude Code 支持四种 MCP 传输方式：

• Stdio：标准输入输出（本地工具）
• SSE：Server-Sent Events（实时推送）
• HTTP：标准 HTTP 请求（REST API）
• WebSocket：双向通信（长连接场景）

#自动恢复

MCP 客户端内建了断线重连和错误恢复机制——这在实际使用中非常重要，因为外部工具服务可能随时中断。

#工具发现

连接 MCP 服务器  → listTools()     → 自动注册为可用工具  → listResources() → 资源预取  → listPrompts()   → Prompt 模板管理

这意味着你只需配置好 MCP 服务器地址，Claude Code 就能自动发现并使用该服务器提供的所有能力，做到了真正的即插即用。

六、多智能体协调：Coordinator 模式

Claude Code 内置了一个多智能体协调系统，这可能是最前沿的设计之一：

Coordinator（协调器 / 主智能体）  ├─ Agent Worker 1  ← 并行处理子任务  ├─ Agent Worker 2  ← 独立上下文和工具集  └─ Agent Worker N  ← 通过 SendMessage 通信

通过环境变量 CLAUDE_CODE_COORDINATOR_MODE=1 开启后，主智能体可以：

• 使用 AgentTool 创建子智能体
• 用 TeamCreateTool 组建任务团队
• 通过 SendMessageTool 在智能体间传递信息
• 每个子智能体有独立的工具权限和执行上下文

这本质上是一个进程内的多智能体框架，让单个 Claude Code 实例能够并行处理复杂的多步骤任务。

七、Bridge：连接云端和本地的桥梁

Bridge 系统是 Claude Code 支持远程开发的核心：

本地终端 CLI    ↓ OAuth + 可信设备令牌BridgeApiClient    ↓ 会话管理Cloud Code Runtime（CCR）容器    ├─ 多会话管理（--spawn / --capacity）    ├─ 轮询 + 退避重试    └─ 优雅关闭（SIGTERM → SIGKILL 宽限期）

它让你可以在本地终端操作，但实际的代码执行环境运行在云端容器中。支持多会话并发、断线恢复和安全的 JWT 令牌认证。

八、Hooks 系统：最优雅的 Harness 工程

如果说工具系统是 Claude Code 与外部世界交互的”手”，那么 Hooks 系统就是控制这双手的”神经系统”。这是整个源码中最值得深入研究的工程设计之一——一个覆盖 AI 智能体完整生命周期的可编程拦截框架。

#什么是 Hooks？

Hooks 让你可以在 Claude Code 执行的任何关键节点插入自定义逻辑——Shell 命令、LLM Prompt、HTTP 请求、甚至子智能体验证。本质上，这是一个面向 AI 智能体的 AOP（面向切面编程）框架。

#21+ 个生命周期事件

Claude Code 定义了覆盖完整生命周期的事件钩子：

┌─────────────────────────────────────────────────────────────┐│                      Session Lifecycle                       ││  SessionStart → Setup → ... → Stop → SessionEnd             │├─────────────────────────────────────────────────────────────┤│                      Tool Execution                          ││  PreToolUse → [Tool Runs] → PostToolUse / PostToolUseFailure │├─────────────────────────────────────────────────────────────┤│                      User Interaction                        ││  UserPromptSubmit → PermissionRequest → PermissionDenied     │├─────────────────────────────────────────────────────────────┤│                      Sub-Agent                               ││  SubagentStart → ... → SubagentStop / TeammateIdle           │├─────────────────────────────────────────────────────────────┤│                      Context & Config                        ││  FileChanged → CwdChanged → ConfigChange → InstructionsLoaded│├─────────────────────────────────────────────────────────────┤│                      Task & Compact                          ││  TaskCreated → TaskCompleted / PreCompact → PostCompact      │├─────────────────────────────────────────────────────────────┤│                      MCP Elicitation                         ││  Elicitation → ElicitationResult                             │└─────────────────────────────────────────────────────────────┘

这意味着你可以：

• 在工具执行前检查命令安全性（PreToolUse）
• 在AI 回复后自动执行代码检查（PostToolUse）
• 在会话启动时初始化环境（SessionStart）
• 在子智能体空闲时分配新任务（TeammateIdle）
• 在文件变化时触发自动反应（FileChanged）

#六种 Hook 类型

// settings.json 配置示例{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"echo $TOOL_INPUT | jq '.command'","if":"Bash(rm *)","timeout":30,"async":true}]}]}}

类型	执行方式	典型场景
command	Shell 命令	安全审计、日志记录、环境检查
prompt	LLM 评估	语义级输入验证、内容审核
agent	子智能体	复杂验证、多步骤检查
http	Webhook POST	外部系统集成、审计日志
callback	编程函数	SDK/插件内部使用
function	会话内函数	动态注册的运行时回调

其中 prompt 类型最具创新性——它允许用一个小型 LLM 来审核大型 LLM 的行为，实现了 AI 对 AI 的监督。

#精妙的匹配与过滤机制

Hook 的触发不是简单的事件名匹配，而是一个多层过滤管线：

事件触发  ↓ ① matcher 模式匹配（工具名/事件源等）  ↓ ② if 条件过滤（权限规则语法，如 "Bash(git *)"）  ↓ ③ 信任检查（工作空间是否受信任）  ↓ ④ 策略过滤（企业托管策略是否允许）  ↓ ⑤ 去重合并（多来源同一 Hook 去重）  ↓执行

if 条件使用权限规则语法，支持通配符匹配：

• Bash(git *) — 仅匹配 git 相关命令
• Write(*.ts) — 仅匹配写入 TypeScript 文件
• Read(src/*) — 仅匹配 src 目录下的读取操作

这种设计让 Hook 配置既精确又灵活，避免了不必要的执行开销。

#并行执行与超时控制

同一事件的多个 Hook 并行执行，每个 Hook 有独立的超时控制：

PreToolUse:Bash 触发  ├─ Hook 1 (command): 安全审查  ← timeout: 30s  ├─ Hook 2 (prompt): 语义检查   ← timeout: 60s  └─ Hook 3 (http): 审计日志     ← timeout: 10s, async: true      ↓ 并行执行，独立超时  结果聚合 → 权限决策

场景	默认超时
工具相关 Hook	10 分钟
SessionEnd Hook	1.5 秒
异步 Hook	15 秒

特别值得注意的是 asyncRewake 模式：Hook 在后台异步执行，不阻塞主流程；但如果检测到问题（exit code 2），会通过通知队列唤醒模型重新处理——这是一种优雅的”延迟否决”机制。

#Hook 输出与流程控制

Hook 的输出通过 Zod Schema 严格校验，能够影响后续的执行流程：

// Hook 输出结构{continue: boolean,          // 是否继续执行（默认 true）decision: 'approve' | 'block', // 允许或阻止stopReason: string,         // 阻止原因additionalContext: string,  // 传递给模型的额外上下文systemMessage: string,      // 显示给用户的警告hookSpecificOutput: {hookEventName: 'PreToolUse',permissionDecision: 'allow' | 'ask' | 'deny',  // 权限决策updatedInput: { ... },     // 修改工具输入（！）updatedMCPToolOutput: ...  // 修改 MCP 工具输出（！）  }}

Shell 命令的退出码语义也经过精心设计：

• 0：成功，stdout 作为上下文
• 2：阻断性错误，停止执行并反馈原因
• 其他：非阻断错误，仅告警

这意味着一个简单的 Shell 脚本就可以实现复杂的控制逻辑：

#!/bin/bash# PreToolUse hook: 阻止删除 node_modules 以外的目录COMMAND=$(echo"$TOOL_INPUT" | jq -r '.command')if [[ "$COMMAND" == rm* ]] && [[ "$COMMAND" != *node_modules* ]]; thenecho"Blocked: 不允许删除非 node_modules 目录" >&2exit 2  # 阻断fiexit 0  # 放行

#多来源合并与企业管控

Hook 可以来自四个不同的来源，按优先级合并：

Enterprise policySettings    ← 最高优先级，企业管控  ↓ mergeProject settings.json        ← 项目级配置  ↓ mergeUser settings                ← 用户偏好  ↓ mergePlugin / Skill hooks         ← 插件/技能注册  ↓ deduplicate最终执行列表

企业管控策略可以：

• allowManagedHooksOnly: true — 仅允许企业管理的 Hook
• disableAllHooks: true — 禁用所有 Hook（核弹级选项）
• 用户级设置无法覆盖企业策略

#Post-Sampling 内部 Hook

除了用户可配置的 Hook 外，还有一类内部 Post-Sampling Hook：

registerPostSamplingHook(async (context: REPLHookContext) => {// 可以访问完整的消息历史、系统提示、用户上下文// 用于 Magic Docs、Magic Panel 等内部功能})

这些 Hook 不暴露在 settings.json 中，通过编程方式注册，在每次 LLM 采样完成后触发。它们可以获取完整的对话上下文（消息历史、系统提示、工具使用上下文），用于实现更高层的智能功能。

#安全设计

Hooks 系统的安全设计值得单独展开：

1. 工作空间信任前置：所有 Hook 在工作空间信任对话框通过前完全不执行
2. SSRF 防护：HTTP 类型 Hook 内置 ssrfGuard，防止服务端请求伪造
3. 策略隔离：非管理设置无法禁用管理 Hook，企业策略始终优先
4. AbortSignal 取消：支持信号级的超时和中断控制
5. 全链路追踪：Analytics + OpenTelemetry 双重遥测，每次 Hook 执行留痕

这套 Harness 工程的精髓在于：它不是后期打补丁加上去的”钩子”，而是从第一天就设计好的系统级拦截框架。21 个生命周期事件、6 种执行方式、多层安全控制——这是我见过的 AI 智能体产品中最完善的可编程控制平面。

九、更多亮点特性

#Vim 模式

Claude Code 内置了完整的 Vim 键绑定状态机，支持：

• INSERT / NORMAL 模式切换
• 移动命令：h/l/j/k、w/b/e（字词移动）、f/F/t/T（查找字符）
• 操作符：d（删除）、c（修改）、y（复制）
• 文本对象：iw（内词）、aw（含周围空格的词）等
• 寄存器和 . 重复

这不是一个简单的 Vim 模拟，而是一个纯函数实现的完整状态机，通过 resolveMotion() 和 executeOperatorMotion() 等函数组合来处理复杂操作。

#语音输入

支持 16kHz 单声道音频采集，2 秒静默检测自动截断。使用原生 NAPI 绑定做音频捕获，SoX 作为后备方案。

#技能系统

类似插件但更轻量的扩展机制：

• 内置技能：随应用启动自动注册
• 磁盘技能：从 ~/.claude/skills/ 目录加载，支持 YAML frontmatter 配置
• 支持 Token 估算、参数替换、文件提取等高级特性

#30+ 斜杠命令

/init    — 初始化项目配置/model   — 切换模型/vim     — 开关 Vim 模式/voice   — 语音输入/cost    — 查看 Token 消耗/export  — 导出对话/plan    — 进入规划模式/pr_comments — 处理 PR 评论/commit-push-pr — 一键提交推送并创建 PR...

#主动式交互（Proactive）

通过特性开关控制的主动交互系统，支持状态机管理（活跃/暂停/阻塞）和观察者模式订阅。

十、状态管理：去繁就简

Claude Code 没有引入 Redux 或其他重型状态管理库，而是采用了极简的 Store 模式：

// 泛型 Store，纯函数更新Store<AppState> {getState(): AppStatesetState(updater: (prev: AppState) =>AppState): voidsubscribe(listener: () =>void): Unsubscribe}

AppState 包含消息列表、设置、权限、任务、智能体等全部状态，通过 React Context Provider 注入组件树。没有 action、reducer、middleware 的层层抽象——对于 CLI 应用来说，这恰好是合适的复杂度。

十一、Query Engine：LLM 调用的编排中枢

QueryEngine 是连接用户输入和 LLM 响应的核心编排器：

1. buildQueryConfig()     → 快照特性开关和运行时配置2. normalizeMessages()    → 消息格式化 + 自动压缩3. Claude API 调用        → 流式输出4. canUseTool() 权限检查  → 弹窗或自动放行5. Tool.invoke() 执行     → 流式工具执行6. 用量追踪 + 摘要生成7. 循环直到任务完成

关键设计包括：

• Prompt 缓存策略：支持基于工具/系统提示/无缓存三种模式
• 自动上下文压缩：当 Token 接近限制时自动压缩历史消息
• API 错误分类与重试：网络错误、速率限制、认证失败各有不同的处理路径
• 流式工具执行：工具的输出可以实时流式传输到终端

十二、隐藏的「下一代」功能：从宠物到做梦

源码中还埋藏着一批尚未正式发布的功能，全部通过 feature() 门控和 GrowthBook 灰度控制。它们揭示了 Anthropic 对 AI 编程助手未来形态的思考——远远超出了”对话式代码补全”的范畴。

#1. Buddy：你的 AI 宠物

没错，Claude Code 里有一个完整的宠物系统。

18 种物种：duck · goose · blob · cat · dragon · octopus · owl · penguinturtle · snail · ghost · axolotl · capybara · cactusrobot · rabbit · mushroom · chonk

每个宠物有 5 项属性：DEBUGGING（调试力）、PATIENCE（耐心）、CHAOS（混乱值）、WISDOM（智慧）、SNARK（毒舌度）。

稀有度体系遵循经典的抽卡概率：

稀有度	概率	属性下限
Common	60%	5
Uncommon	25%	15
Rare	10%	25
Epic	4%	35
Legendary	1%	50

此外还有 1% 的概率出闪光（Shiny）版。

关键设计：你的宠物由用户 ID 哈希确定，使用 Mulberry32 确定性伪随机数生成器——这意味着无法刷稀有度，你的宠物从注册那一刻起就命中注定了。

// 用户 ID → Bun.hash / FNV-1a → Mulberry32 PRNG → 物种+稀有度+属性const seed = hashString(userId + 'friend-2026-401')const rng = mulberry32(seed)

架构上，宠物分为 Bones（骨骼）和 Soul（灵魂）两层：

• Bones（物种、稀有度、属性、闪光）：从用户 ID 哈希实时重新生成，永不持久化——这样即使有人手动修改配置文件，也无法伪造稀有度
• Soul（名字、性格）：由 LLM 生成并持久化存储，可以让 Claude 给你的宠物取名和写性格描述

宠物还有 6 种眼睛样式（·✦×◉@°）和 8 种帽子（只有 Uncommon 及以上才有帽子，Common 永远光头），UI 通过 React 组件 CompanionSprite 以 ASCII 动画渲染在终端中。

#2. Kairos：24 小时在线的主动助手

普通的 Claude Code 是被动的——你问它才答。Kairos 模式则完全不同，它让 Claude 变成一个主动式 AI 助手。

核心是一个订阅式状态机：

activateProactive() → active = true  ↓ subscribeToProactiveChanges()观察者收到通知 → 触发主动行为  ↓pauseProactive() / setContextBlocked()  ↓ 按需暂停或阻塞

Kairos 模式下的 Claude 会：

• 维护每日日志（Daily Log），记录和追踪工作进展
• 通过 Channels 系统主动推送通知（KAIROS_CHANNELS）
• 订阅 GitHub Webhooks（KAIROS_GITHUB_WEBHOOKS），自动响应代码变更
• 使用专属的主动推送工具，给你发文件、发通知

它有一个巧妙的 nextTickAt 调度机制，控制下一次主动行为的时机——不会像闹钟一样疯狂打扰你，而是根据上下文节奏智能安排。

门控链：KAIROS → KAIROS_CHANNELS → KAIROS_BRIEF → KAIROS_GITHUB_WEBHOOKS，四级特性开关逐步放开能力。

#3. Auto-Dream：Claude 也会做梦

这可能是最有诗意的功能名——当你不用 Claude Code 的时候，它会在后台”做梦”。

实际上是一个自动记忆整理系统。当你通过 /memory 让 Claude 存储了信息后，这些记忆会随着时间积累变得碎片化。Auto-Dream 在空闲时自动整理它们。

触发条件是一个三重门控（按计算成本从低到高排列）：

① 时间门：距上次整理 ≥ 24 小时  ↓ 通过② 会话门：期间至少有 5 个新会话  ↓ 通过③ 锁门：PID 文件锁，防止多进程并发  ↓ 通过启动做梦进程

做梦分四个阶段：

1. Orient（定向）：浏览现有记忆目录，阅读索引文件
2. Gather Signal（收集信号）：检查每日日志，用 grep 在历史对话记录中搜索关键词
3. Consolidate（整合）：将新信息合并到现有记忆文件，去重，将相对日期转换为绝对日期
4. Prune/Index（修剪/索引）：更新索引文件（上限 25KB），每行约 150 字符

做梦使用 runForkedAgent 启动一个独立的子智能体，与主会话完全隔离（skipTranscript: true），且 Bash 被限制为只读命令（ls、find、grep、cat、head、tail……不能 rm，做梦不会删你的东西）。

#4. Daemon：变身后台守护进程

Daemon 模式让 Claude Code 脱离终端，作为后台服务持续运行——类似 MySQL 或 Nginx 守护进程。

核心架构是一个工作队列：

Daemon 进程（无头模式，无 TUI）  ├─ 工作队列轮询（每秒状态更新）  ├─ JWT 令牌自动刷新（到期前 5 分钟）  ├─ 心跳上报（每次轮询迭代）  ├─ 多会话管理（每个会话独立 Git Worktree）  └─ 休眠检测（超过 240s 无响应 → 判定系统休眠）

退避策略经过精心设计：

参数	默认值
连接初始延迟	2 秒
连接退避上限	2 分钟
连接放弃超时	10 分钟
关闭宽限期（SIGTERM→SIGKILL）	30 秒

每个会话会创建独立的 Git Worktree，任务完成后自动清理——多个任务可以并行操作不同分支，互不干扰。

#5. UDS Inbox：跨会话通信

以前你开三个 Claude Code 窗口，它们互相不知道对方的存在。UDS Inbox 改变了这一点。

底层使用 Unix Domain Socket 实现本地进程间通信：

Claude Code 会话 A ←── UDS ──→ Claude Code 会话 B       ↑                                ↑       └────── UDS ── Claude Code 会话 C ┘

三种消息寻址方式：

寻址	语法	用途
直连本地	uds:/path/to.sock	点对点通信
远程会话	bridge:session_xxx	跨网络通信
广播	*	通知全部队友

消息协议支持纯文本和结构化消息（用于协调协议），包括关闭请求（shutdown_request）、关闭确认（shutdown_response）、方案审批（plan_approval_response）等类型。跨会话消息用 <cross-session-message> 标签包裹，接收方在下一轮对话时读取——不会中断正在进行的操作。

#6. Teleport：跨机器传送

在公司电脑上用 Claude Code 写到一半，回家想继续？Teleport 可以把整个工作会话从一台电脑传送到另一台。

传输的不只是对话历史，而是完整的会话上下文：

SessionContext {sources: [...]           // Git 仓库、知识库cwd: string// 工作目录outcomes: Outcome[]      // 执行结果  custom_system_prompt     // 自定义系统提示model: string// 使用的模型  seed_bundle_file_id      // Git Bundle（Files API 上传）github_pr: { owner, repo, number }  // 关联的 PR}

网络请求使用指数退避重试（2s → 4s → 8s → 16s，最多 4 次），仅重试暂态错误（网络断开、5xx），4xx 错误立即失败——不浪费时间在不可恢复的错误上。

#7. Ultraplan：30 分钟远程深度规划

输入 /ultraplan + 一段描述，系统会在云端启动一个独立的 Claude Code 实例，用 Opus 4.6 模型，花最多 30 分钟深度分析你的项目：

用户输入 /ultraplan "重构认证模块"  ↓本地: 启动对话框确认 → 构建规划 Prompt  ↓云端: 创建 CCR 会话（权限模式: plan）  ↓轮询循环（每 3 秒，持续 30 分钟）  ├─ running     → 还在分析...  ├─ needs_input → 等待补充信息  └─ plan_ready  → 方案完成！  ↓用户选择:  ├─ "远程执行" → 云端直接实施，提交 PR  └─ "传送回来" → Teleport 到本地继续

ExitPlanModeScanner 是一个精巧的状态机，持续扫描远程会话事件流，追踪方案的提交和审批状态。如果方案被多次否决，系统会记录拒绝次数——方便后续分析规划质量。

配置	值
轮询间隔	3 秒
最大超时	30 分钟
连续失败上限	5 次

---

这七个功能共同勾勒出 Anthropic 对 AI 编程助手的终极愿景：不再是一个你需要时才打开的工具，而是一个有个性（Buddy）、会主动帮忙（Kairos）、自己整理记忆（Auto-Dream）、24 小时待命（Daemon）、多实例协作（UDS Inbox）、跨设备无缝切换（Teleport）、能独立做深度规划（Ultraplan）的数字工作伙伴。

十三、账号风控系统：从设备指纹到封号的完整链路

Claude Code 不只是一个编程工具——它内置了一套企业级风控反滥用系统。从客户端数据采集到服务端综合判定，再到最终的处置措施，形成了一条完整的安全闭环。

#1. 客户端采集：四维数据画像

客户端持续采集四类信号，构建完整的用户行为画像：

（1）Device ID — 永久设备标识

每个 Claude Code 安装会生成一个不可变的 64 字符设备 ID：

// src/utils/config.tsexportfunctiongetOrCreateUserID(): string {const config = getGlobalConfig()if (config.userID) return config.userIDconst userID = randomBytes(32).toString('hex')  // 64 字符saveGlobalConfig(current => ({ ...current, userID }))return userID}

这个 ID 持久化在 ~/.claude/config.json，作为设备的唯一身份贯穿所有上报通道。此外还有两层加固：

标识层	实现	用途
Device ID	crypto.randomBytes(32) → 存 config.json	永久设备标识，各通道共用
Trusted Device Token	服务端签发 → 存系统钥匙串	OAuth 级别设备认证
消息指纹	SHA256(salt + msg[4,7,20] + version)[:3]	检测前端篡改（每轮计算）

消息指纹尤其值得关注——它从每条消息的第 4、7、20 个字符取样，配合硬编码盐值 59cf53e54c78 计算 SHA256 前 3 位，能检测出任何对系统提示的篡改。代码注释警告：“Do not change without careful coordination with 1P and 3P APIs”。

（2）环境指纹 — 80+ 维度设备画像

Claude Code 采集的环境信息远超一般应用，覆盖 80+ 维度：

// src/services/analytics/metadata.tstypeEnvContext = {// 基础环境（5 维）platform: string// 'macos' | 'windows' | 'wsl' | 'linux'arch: string// CPU 架构nodeVersion: string// 运行时版本version: string// Claude Code 版本buildTime: string// 构建时间戳// 终端/IDE 检测（30+ 维）terminal: string | null// Cursor, VSCode, JetBrains 全家桶, Ghostty, Kitty...// 开发环境（20+ 维）packageManagers: string// npm, yarn, pnpmruntimes: string// bun, deno, nodevcs?: string// git, hg, svn, perforce, jujutsu, sapling...// 部署平台（15+ 维）deploymentEnvironment: string// Codespaces, Gitpod, Replit, Vercel, AWS Lambda...// 运行状态（10+ 维）isCi: booleanisGithubAction: booleanisClaudeCodeRemote: booleanisLocalAgentMode: boolean// ...更多标志位}

终端检测堪称”谍战级”——通过 CURSOR_TRACE_ID 识别 Cursor，通过 VSCODE_GIT_ASKPASS_MAIN 路径识别各种 VS Code 分支，JetBrains 全家桶（PyCharm、IntelliJ、WebStorm 等 14 款 IDE）则通过 bundleId 和 TERMINAL_EMULATOR 环境变量识别。所有检测函数用 memoize 缓存，确保不重复执行。

（3）行为事件 — 245+ 事件类型

系统定义了 245+ 种行为事件，覆盖用户操作的每一个角落：

事件类别	数量	示例
API 交互	14	api_error, api_success, api_retry, 529_error
工具使用	12	tool_use_error, tool_use_success, tool_use_granted_permanent
OAuth 认证	9	oauth_error, token_refresh_failure, token_refresh_lock_*
Bridge/REPL	45+	会话操作、心跳、重连、挂起检测
插件市场	20+	安装、卸载、启用、禁用、更新
文件操作	11	上传、读取限制、PDF 提取
安全检查	5	bash_security_check, AST 复杂度, tree-sitter 影拷
语音/流式	9+9	录音、转写、流式超时、流式降级
异常捕获	2	uncaught_exception, unhandled_rejection

每条事件都会自动附加完整的 EventMetadata（设备 ID、会话 ID、模型、环境上下文、进程指标等），确保服务端能做多维关联分析。

（4）资源监控 — CPU/内存/时间

进程级别的资源指标随事件一起上报：

// src/services/analytics/metadata.tstypeProcessMetrics = {uptime: number// 进程运行时长rss: number// 物理内存占用heapTotal: number// 堆内存总量heapUsed: number// 堆内存使用量external: number// C++ 对象内存arrayBuffers: number// ArrayBuffer 内存constrainedMemory: number// 受约束内存上限cpuUsage: CpuUsage// CPU 用户态/系统态微秒数cpuPercent: number// 计算后的 CPU 使用率}

CPU 使用率的计算特别精确——维护 prevCpuUsage 和 prevWallTimeMs 全局状态，每次上报时计算增量百分比 (userDelta + systemDelta) / (wallDelta * 1000) * 100，避免瞬时峰值误导。

#2. 上报通道：三管齐下的数据管线

采集到的数据通过三条独立管道同时上报，各有侧重：

客户端采集    ↓EventMetadata 聚合    ↓┌──────────────────┬──────────────────┬──────────────────┐│  Anthropic 1P    │    Datadog       │   GrowthBook     ││  每 5 秒 flush   │  每 15 秒 flush  │  每 20 分钟轮询  ││  200 条/批       │  100 条/批       │  87+ 功能标志    ││  proto 格式      │  JSON + Tags     │  远程评估        ││  完整事件        │  45 白名单事件   │  特性开关 + A/B  │└──────────────────┴──────────────────┴──────────────────┘

Anthropic 1P（第一方） — 全量数据归档：

// src/services/analytics/firstPartyEventLogger.ts// 基于 OpenTelemetry BatchSpanProcessorendpoint: 'https://api.anthropic.com/api/event_logging/batch'batchConfig: {scheduledDelayMillis: 5000,    // 默认 5 秒maxExportBatchSize: 200,       // 每批最多 200 条}// 失败事件持久化到 ~/.claude/telemetry/1p_failed_events.*.json// 指数退避重试：500ms → 2s → 8s → 30s，最多 8 次

Datadog — 生产监控：

只允许 45 个白名单事件通过（API 错误、工具执行、OAuth 状态、异常等），发送到 us5.datadoghq.com。关键设计是 stripProtoFields()——所有以 _PROTO_ 前缀标记的 PII 字段在进入 Datadog 前会被自动剥离，确保用户代码和文件路径不会泄露到第三方。

GrowthBook — 远程控制面板：

// src/services/analytics/growthbook.tsconstGROWTHBOOK_REFRESH_INTERVAL_MS =  process.env.USER_TYPE !== 'ant'    ? 6 * 60 * 60 * 1000// 外部用户：6 小时    : 20 * 60 * 1000// 内部员工：20 分钟

87+ 功能标志涵盖功能开关（Bridge、Kairos、Session Memory）、A/B 实验、批量配置（事件采样率、日志级别）、模型路由（tengu_ant_model_override、tengu_ultraplan_model）等。覆盖层级为：环境变量 → 磁盘配置覆盖 → 远程评估 → 缓存回退。

#3. 服务端处理：BigQuery + Datadog + 功能标志联动

三条管道在服务端汇聚，形成综合判定能力：

后端系统	数据源	分析维度
BigQuery	1P 全量事件（proto 格式）	用户行为模式、异常频率、资源消耗趋势
Datadog	45 白名单事件 + Tags	实时异常检测、API 错误率告警、性能监控
GrowthBook	反向控制通道	远程启停功能、调整采样率、灰度发布

1P 事件在上报前会经过 to1PEventFormat() 做 proto 序列化，将 camelCase 转为 snake_case，附加编译期类型检查——确保数据格式与后端 BigQuery schema 严格对齐。

#4. 处置措施：三级响应梯度

当服务端综合判定命中风控规则后，通过 API 响应头执行处置：

警告/降级（allowed_warning）：

// src/services/claudeAiLimits.ts// 5 小时窗口：90% 利用率时预警（前提是已过 72% 时间）// 7 天窗口：75% / 50% / 25% 三级梯度预警typeClaudeAILimits = {status: 'allowed' | 'allowed_warning' | 'rejected'utilization?: number// 当前利用率百分比resetsAt?: number// 重置时间戳rateLimitType?: RateLimitTypeoverageStatus?: QuotaStatus}

速率限制（rejected + 429）：

五种独立的限速维度：

限速类型	窗口	场景
five_hour	5 小时	会话级别限速
seven_day	7 天	周期限速
seven_day_opus	7 天	Opus 模型专属限速
seven_day_sonnet	7 天	Sonnet 模型专属限速
overage	动态	超额使用限速

限速通过 HTTP 响应头 anthropic-ratelimit-unified-status 和 retry-after 传达，客户端根据 rateLimitType 展示对应的等待 UI。

封号（服务端拒绝所有请求）：

// src/utils/billing.tstypeOverageDisabledReason =  | 'overage_not_provisioned'// 组织未开通超额  | 'org_level_disabled'// 组织级别禁用  | 'out_of_credits'// 额度耗尽  | 'member_zero_credit_limit'// 用户额度为零  | 'member_level_disabled'// 用户级别禁用  | 'seat_tier_zero_credit_limit'// 席位层级额度为零  | 'org_service_zero_credit_limit'// 服务级别额度为零

封号颗粒度精确到：个人 → 席位层级 → 服务 → 组织，配合角色权限（admin/billing/owner）决定谁能看到账单和额度管理界面。

#5. 成本追踪：实时计价引擎

与风控系统配合的还有完整的成本追踪引擎：

// src/utils/modelCost.ts — 模型定价表COST_TIER_3_15// Sonnet: $3 / $15 per MtokCOST_TIER_15_75// Opus 4/4.1: $15 / $75COST_TIER_5_25// Opus 4.5: $5 / $25COST_TIER_30_150// Opus 4.6 Fast: $30 / $150COST_HAIKU_35// Haiku 3.5: $0.80 / $4COST_HAIKU_45// Haiku 4.5: $1 / $5

每次 API 调用实时计算成本，通过 OpenTelemetry Counter 上报四类 Token 消耗（input、output、cache_read、cache_creation），并持久化到项目配置中——下次打开项目时能看到累计花费。

#风控系统设计哲学

这套系统的精妙之处在于客户端无法绕过：

• Device ID 在首次运行时生成，之后不可更改（除非删除 ~/.claude/config.json）
• 消息指纹在每轮对话中实时校验，检测系统提示篡改
• 三条上报管道互为冗余——即使其中一条被阻断，其余两条仍能提供完整画像
• 采样率和功能开关由服务端远程控制，不需要客户端更新
• 所有处置措施通过 API 响应头下发，客户端只能遵从

这不是一个”可以被 patch 掉”的安全措施——它是融入协议层的信任基础设施。

总结：AI 原生应用的工程范式

纵观 Claude Code 的源码，我们可以提炼出几个 AI 原生应用的设计范式：

1. 性能是一等公民：从 Bun 运行时到零导入快速路径，从并行预取到编译期死代码消除，每一处都在追求极致的响应速度。

2. 工具是核心抽象：40+ 个工具通过统一接口暴露给 LLM，配合 MCP 协议实现可插拔扩展。工具不再是”功能模块”，而是AI 与世界交互的接口。

3. Harness 工程定义控制力：21 个生命周期事件 × 6 种执行方式 × 多层安全控制——Hooks 系统是目前 AI 智能体产品中最完善的可编程控制平面。它让企业能对 AI 行为实施精细管控，让开发者能在任意节点插入自定义逻辑，而不需要修改一行源码。

4. 安全内建而非外挂：三级权限模型、工具级别的访问控制、Hook 工作空间信任前置、SSRF 防护、JWT 令牌认证——安全机制从第一天就融入了架构，而不是后期打补丁。从设备指纹到行为事件、从三管齐下的上报通道到五维速率限制，风控系统覆盖了用户生命周期的每一个环节。

5. 可观测性驱动迭代：OpenTelemetry 全链路追踪 + GrowthBook 特性开关，让团队能在生产环境中精确控制功能灰度和性能监控。

6. 组件化终端 UI：用 React 的心智模型来构建终端界面，让复杂的交互状态管理变得可控。

Claude Code 的源码证明了一件事：AI 编程工具的竞争，本质上是工程能力的竞争。模型能力固然重要，但如何把模型能力转化为流畅、安全、可扩展的用户体验——这才是真正的护城河。而 Hooks 系统更揭示了一个重要趋势：未来 AI 智能体的竞争力，不仅在于它能做什么，更在于外部系统能如何精确地观察和控制它的行为。

---

本文基于通过 source map 还原的 Claude Code 源码分析，文章内容仅作学习使用，部分模块为兼容性降级实现，可能与 Anthropic 官方版本存在差异。

如果觉得不错就点个关注吧，关注在微信公众号后台可以加群，和大家一起讨论openclaw，claude code源码，agent技术开发等，欢迎你的加入。