邓文兵 0686f1969c docs(article): 添加 Claude Code 源码分析文章及相关架构图

- 新增 008 号文章《51 万行源码意外曝光！我扒完了 Claude Code 的全部家底》
- 添加 8 个 Mermaid 架构图文件，涵盖整体架构、启动流程、查询循环等
- 新增项目配置文件 CLAUDE.md，定义自媒体写作规范
- 创建详细的架构分析文档 claude-arch-by-claude.md
- 包含权限系统、工具调度、多智能体等核心技术解析
- 记录反蒸馏机制、KAIROS 守护进程等隐藏功能发现
- 提供完整的工具清单及安全防护措施说明

2026-04-01 10:38:57 +08:00

28 KiB

Raw Permalink Blame History

Claude Code 源码泄漏深度架构分析

2026年3月31日，Anthropic 在 npm 发布 @anthropic-ai/claude-code@2.1.88 时，意外将一个 59.8MB 的 JavaScript Source Map 文件打包在内。这个 .map 文件指向了 Anthropic 自家 Cloudflare R2 存储桶上的完整 TypeScript 源码压缩包。安全研究员 Chaofan Shou 率先发现并公开了这个链接，数小时内，1,900 个 TypeScript 文件、512,664 行代码被完整镜像到了 GitHub 上。

本文将从架构层面，深入拆解这个"可能是当前最复杂的 AI 编程智能体"的内部实现。

一、技术栈总览

维度	技术选型
语言	TypeScript（1,884 个 `.ts/.tsx` 文件）
运行时	Bun（非 Node.js）
终端 UI	自研 Ink 分支 + React + Yoga Layout
Schema 校验	Zod v4
API 通信	Anthropic SDK + SSE 流式传输
构建系统	Bun Bundler（`bun:bundle` 特性开关）
实验平台	GrowthBook（`tengu_*` 前缀）
可观测性	OpenTelemetry + Datadog + Perfetto

二、整体架构

graph TB
    subgraph Entry["入口层"]
        CLI["cli.tsx<br/>CLI 入口"]
        MCP_ENTRY["mcp.ts<br/>MCP Server 入口"]
        SDK["agentSdkTypes.ts<br/>SDK 入口"]
    end

    subgraph Core["核心引擎"]
        MAIN["main.tsx<br/>4,683 行<br/>REPL 编排器"]
        QE["QueryEngine.ts<br/>1,295 行<br/>会话管理器"]
        QUERY["query.ts<br/>1,729 行<br/>流式查询循环"]
        API["claude.ts<br/>3,419 行<br/>Anthropic API 客户端"]
    end

    subgraph Tools["工具系统"]
        TOOL_DEF["Tool.ts<br/>792 行<br/>工具接口定义"]
        TOOL_REG["tools.ts<br/>389 行<br/>工具注册表"]
        TOOL_ORCH["toolOrchestration.ts<br/>并发调度"]
        TOOL_EXEC["toolExecution.ts<br/>1,745 行<br/>执行引擎"]
    end

    subgraph Agent["多智能体"]
        COORD["coordinatorMode.ts<br/>协调器"]
        AGENT_RUN["runAgent.ts<br/>973 行<br/>子智能体启动器"]
        TASKS["tasks/<br/>任务状态机"]
    end

    subgraph Infra["基础设施"]
        PERM["permissions/<br/>24 个文件<br/>权限系统"]
        MCP_CLIENT["mcp/client.ts<br/>3,348 行<br/>MCP 客户端"]
        BRIDGE["bridge/<br/>27 个文件<br/>IDE 桥接"]
        MEMDIR["memdir/<br/>9 个文件<br/>记忆系统"]
        INK["ink/<br/>终端渲染引擎"]
    end

    CLI --> MAIN
    MCP_ENTRY --> MAIN
    SDK --> QE

    MAIN --> QE
    QE --> QUERY
    QUERY --> API
    QUERY --> TOOL_ORCH

    TOOL_ORCH --> TOOL_EXEC
    TOOL_EXEC --> TOOL_DEF
    TOOL_REG --> TOOL_DEF

    TOOL_EXEC --> AGENT_RUN
    COORD --> AGENT_RUN
    AGENT_RUN --> TASKS
    AGENT_RUN --> QUERY

    TOOL_EXEC --> PERM
    MAIN --> MCP_CLIENT
    MAIN --> BRIDGE
    QE --> MEMDIR
    MAIN --> INK

三、启动流程

sequenceDiagram
    participant User as 用户终端
    participant CLI as cli.tsx
    participant Main as main.tsx
    participant GB as GrowthBook
    participant MCP as MCP Servers
    participant REPL as REPL 循环

    User->>CLI: claude 命令
    CLI->>CLI: 快速路径检查<br/>(--version, --dump-system-prompt)
    CLI->>Main: 动态 import main.tsx

    par 并行初始化
        Main->>GB: 加载特性开关
        Main->>Main: 读取 settings / MDM / keychain
        Main->>MCP: 连接 MCP 服务器
        Main->>Main: 加载工具 & 命令
    end

    Main->>Main: 构建系统提示词
    Main->>REPL: launchRepl()
    REPL->>User: 就绪，等待输入

关键设计：cli.tsx 仅 302 行，通过动态 import() 延迟加载 main.tsx（4,683 行），确保 --version 等快速路径毫秒级响应。所有重量级依赖（MCP、GrowthBook、keychain）都通过并行初始化加载。

四、核心查询循环

4.1 QueryEngine — 会话管理器

QueryEngine 是 SDK/headless 模式下的会话管理器，一个实例管理一次完整对话：

QueryEngine
├── mutableMessages: Message[]          // 消息历史（随对话增长）
├── abortController: AbortController    // 会话级中止控制
├── permissionDenials: SDKPermissionDenial[]  // 权限拒绝记录
├── totalUsage: NonNullableUsage        // Token 用量聚合
├── discoveredSkillNames: Set<string>   // 每轮发现的技能
└── loadedNestedMemoryPaths: Set<string> // 已加载的 CLAUDE.md 路径

核心方法 submitMessage() 是一个 AsyncGenerator<SDKMessage>，每次调用经历：

构建系统提示词（fetchSystemPromptParts()）
处理斜杠命令（processUserInput()）
持久化用户消息到 transcript
进入流式查询循环（query()），yield 出 SDKMessage
处理上下文压缩、权限、最大轮次限制

4.2 query.ts — 流式查询循环

flowchart TD
    START["用户消息"] --> BUILD["构建查询配置"]
    BUILD --> CALL["queryModelWithStreaming()<br/>调用 Anthropic API"]
    CALL --> STREAM["流式接收响应"]
    STREAM --> CHECK{是否有工具调用?}

    CHECK -->|有| RUN_TOOLS["runTools()<br/>执行工具"]
    RUN_TOOLS --> BUDGET["applyToolResultBudget()<br/>结果预算控制"]
    BUDGET --> HOOKS["executePostSamplingHooks()"]
    HOOKS --> COMPACT{"需要压缩?"}
    COMPACT -->|是| AUTO_COMPACT["autoCompactIfNeeded()"]
    AUTO_COMPACT --> CALL
    COMPACT -->|否| CALL

    CHECK -->|无| RECOVERY{max_output_tokens<br/>恢复?}
    RECOVERY -->|是,≤3次| CALL
    RECOVERY -->|否| STOP_HOOKS["handleStopHooks()"]
    STOP_HOOKS --> END["返回结果"]

关键机制：

Output Recovery：当模型因 max_output_tokens 截断时，自动重试最多 3 次
工具结果预算：大结果持久化到磁盘，用文件路径 + 预览替代，防止上下文窗口膨胀
自动压缩：接近上下文窗口限制时触发对话摘要压缩
依赖注入：QueryDeps 接口注入 callModel、microcompact、autocompact、uuid，方便单元测试

五、工具系统

5.1 Tool 接口

Tool<Input, Output, P> 是一个功能丰富的接口，定义了工具的完整生命周期：

classDiagram
    class Tool {
        +name: string
        +description(input, options): string
        +inputSchema: ZodSchema
        +call(args, context, canUseTool, parentMessage, onProgress?)
        +checkPermissions(input, context): PermissionResult
        +validateInput(input, context): ValidationResult
        +isReadOnly(input): boolean
        +isConcurrencySafe(input): boolean
        +isDestructive(input): boolean
        +maxResultSizeChars: number
        +shouldDefer: boolean
        +renderToolUseMessage(input, options): ReactNode
        +renderToolResultMessage(...): ReactNode
        +toAutoClassifierInput(input): string
    }

    class ToolUseContext {
        +options: Options
        +abortController: AbortController
        +appState: AppState
        +permissionContext: PermissionContext
        +fileStateCache: FileStateCache
        +sessionMetadata: SessionMetadata
    }

    Tool --> ToolUseContext : 接收

5.2 完整工具清单

源码中注册了 40+ 个工具，按功能分类：

分类	工具名	说明
文件操作	FileReadTool, FileWriteTool, FileEditTool, GlobTool, GrepTool, NotebookEditTool	文件读写、搜索、编辑
系统执行	BashTool, PowerShellTool	Shell 命令执行
网络访问	WebFetchTool, WebSearchTool	网页抓取、搜索
智能体	AgentTool, SendMessageTool, TeamCreateTool, TeamDeleteTool	多智能体生成与协调
任务管理	TaskCreateTool, TaskGetTool, TaskUpdateTool, TaskListTool, TaskStopTool, TaskOutputTool	后台任务管理
规划模式	EnterPlanModeTool, ExitPlanModeTool	只读规划模式切换
Worktree	EnterWorktreeTool, ExitWorktreeTool	Git Worktree 隔离
MCP	MCPTool, ListMcpResourcesTool, ReadMcpResourceTool	MCP 协议交互
其他	ToolSearchTool, SkillTool, AskUserQuestionTool, ConfigTool, BriefTool, LSPTool, TodoWriteTool	工具搜索、技能、配置等
KAIROS 专属	SleepTool, CronCreateTool, CronDeleteTool, CronListTool, MonitorTool, PushNotificationTool	自主守护模式工具

5.3 工具执行调度

flowchart LR
    subgraph Parallel["并发批次"]
        direction TB
        G1["GlobTool ✓"]
        G2["GrepTool ✓"]
        G3["FileReadTool ✓"]
    end

    subgraph Serial["串行执行"]
        direction TB
        S1["FileEditTool"]
        S2["BashTool"]
    end

    INPUT["工具调用列表"] --> PARTITION{"isConcurrencySafe?"}
    PARTITION -->|true| Parallel
    PARTITION -->|false| Serial
    Parallel --> MERGE["合并结果"]
    Serial --> MERGE

toolOrchestration.ts 将工具调用分为两类：

只读工具（isConcurrencySafe=true）：GlobTool、GrepTool、FileReadTool 等，最多 10 个并发执行
写入工具（isConcurrencySafe=false）：FileEditTool、BashTool 等，严格串行执行

六、权限系统

权限系统由 24 个文件组成，是 Claude Code 安全模型的核心。

6.1 权限模式

模式	说明
`default`	每次新操作提示用户确认
`plan`	只读规划模式，禁止写操作
`acceptEdits`	自动接受文件编辑
`bypassPermissions`	绕过所有权限检查
`dontAsk`	从不询问（自动拒绝未允许的操作）
`auto`	AI 驱动的自动审批（Anthropic 内部专用）

6.2 权限决策流程

flowchart TD
    REQ["工具调用请求"] --> DENY{"在 alwaysDeny 规则中?"}
    DENY -->|是| BLOCKED["❌ 拒绝"]
    DENY -->|否| ALLOW{"在 alwaysAllow 规则中?"}
    ALLOW -->|是| PASS["✅ 允许"]
    ALLOW -->|否| TOOL_CHECK{"工具自身<br/>checkPermissions()"}
    TOOL_CHECK -->|拒绝| BLOCKED
    TOOL_CHECK -->|允许| CLASSIFIER{"AI 分类器<br/>(auto 模式)"}
    CLASSIFIER -->|安全| PASS
    CLASSIFIER -->|危险| DIALOG{"shouldAvoidPermissionPrompts?"}
    DIALOG -->|是| BLOCKED
    DIALOG -->|否| USER["🔔 提示用户确认"]
    USER -->|允许| PASS
    USER -->|拒绝| BLOCKED

权限规则支持 glob 模式匹配，例如 Bash(git *) 允许所有 git 开头的 bash 命令。denialTracking.ts 追踪连续拒绝次数，超过阈值后触发降级到手动确认模式。

七、多智能体架构

7.1 协调器模式

graph TB
    subgraph Coordinator["协调器 (Coordinator)"]
        C["协调器智能体<br/>全局视角 + 任务分配"]
    end

    subgraph Workers["工作智能体 (Workers)"]
        W1["Worker 1<br/>文件探索"]
        W2["Worker 2<br/>代码修改"]
        W3["Worker 3<br/>测试验证"]
    end

    C -->|"AgentTool<br/>生成"| W1
    C -->|"AgentTool<br/>生成"| W2
    C -->|"SendMessageTool<br/>追加指令"| W1
    W1 -->|"task-notification<br/>XML 回报"| C
    W2 -->|"task-notification<br/>XML 回报"| C
    C -->|"AgentTool<br/>生成"| W3
    W3 -->|"task-notification<br/>XML 回报"| C
    C -->|"TaskStopTool<br/>终止"| W1

协调器系统提示词（300+ 行）定义了 四阶段工作流：

Research — 探索代码库，理解上下文
Synthesis — 综合发现，制定方案
Implementation — 并行执行代码修改
Verification — 验证结果，运行测试

关键原则写在 prompt 里而非代码里：

"Do not rubber-stamp weak work"（不要草率通过低质量工作）
"You must understand findings before directing follow-up work"（在指导后续工作前必须理解发现）

7.2 子智能体启动流程

runAgent.ts（973 行）是子智能体的核心启动器：

生成唯一 AgentId
创建独立的 FileStateCache
通过 createSubagentContext() fork 父级的 ToolUseContext
初始化智能体专属 MCP 服务器（来自 frontmatter）
运行独立的 query() 流式循环
注册 Perfetto tracing（性能追踪）
写入智能体元数据和 sidechain transcript

7.3 任务类型

classDiagram
    class TaskType {
        <<enumeration>>
        local_bash
        local_agent
        remote_agent
        in_process_teammate
        local_workflow
        monitor_mcp
        dream
    }

    class TaskStatus {
        <<enumeration>>
        pending
        running
        completed
        failed
        killed
    }

    class LocalAgentTask
    class InProcessTeammateTask
    class RemoteAgentTask
    class LocalShellTask
    class DreamTask

    TaskType <-- LocalAgentTask
    TaskType <-- InProcessTeammateTask
    TaskType <-- RemoteAgentTask
    TaskType <-- LocalShellTask
    TaskType <-- DreamTask

八、MCP（Model Context Protocol）集成

Claude Code 既是 MCP 客户端（连接外部 MCP 服务器），也可以作为 MCP 服务器运行。

8.1 支持的传输类型

传输方式	配置类型	说明
`stdio`	`McpStdioServerConfig`	标准进程通信
`sse`	`McpSSEServerConfig`	Server-Sent Events
`sse-ide`	—	IDE 专用 SSE
`http`	`McpHTTPServerConfig`	HTTP 直连
`ws`	`McpWebSocketServerConfig`	WebSocket
`sdk`	`McpSdkServerConfig`	SDK 内嵌

8.2 MCP 连接状态机

stateDiagram-v2
    [*] --> Pending: 初始化
    Pending --> Connected: 连接成功
    Pending --> Failed: 连接失败
    Pending --> NeedsAuth: 需要认证
    NeedsAuth --> Connected: OAuth 完成
    Connected --> Failed: 断开连接
    Connected --> Disabled: 用户禁用
    Failed --> Pending: 重连

mcp/client.ts（3,348 行）是最大的 MCP 相关文件，负责连接管理、工具发现、资源预取和认证流程（支持 OAuth 和 XAA 跨应用访问）。

九、记忆系统

graph LR
    MEMORY_MD["MEMORY.md<br/>记忆索引<br/>(≤200 行 / 25KB)"] --> NOTE1["user_role.md"]
    MEMORY_MD --> NOTE2["feedback_testing.md"]
    MEMORY_MD --> NOTE3["project_auth.md"]

    SYSTEM_PROMPT["系统提示词"] --> MEMORY_MD
    SYSTEM_PROMPT --> TYPES["记忆类型指令"]
    SYSTEM_PROMPT --> RULES["存取规则"]

    NOTE1 --> SEMANTIC["语义搜索<br/>findRelevantMemories()"]
    NOTE2 --> SEMANTIC
    NOTE3 --> SEMANTIC
    SEMANTIC --> INJECT["注入上下文"]

记忆系统（memdir/，9 个文件）采用文件驱动的设计：

MEMORY.md 作为入口索引文件，限制 200 行 / 25KB，注入到系统提示词中
每条记忆是独立的 Markdown 文件，带有 frontmatter（name、description、type）
支持语义搜索（findRelevantMemories()）
记忆老化/淘汰机制（memoryAge.ts）
团队共享记忆支持（teamMemPaths.ts，TEAMMEM 特性开关后）

十、终端渲染引擎

Claude Code 使用自研的 Ink 分支（非 npm 上的 Ink 库），基于 React + Yoga Layout 实现终端 UI。

ink/
├── root.ts          — render() / createRoot() 入口
├── dom.ts           — 虚拟 DOM 实现
├── frame.ts         — 渲染帧管理，防闪烁
├── focus.ts         — 键盘焦点管理
├── components/
│   ├── App.tsx      — 根组件
│   ├── Box.tsx      — 布局容器
│   ├── Text.tsx     — 文本组件
│   ├── ScrollBox.tsx — 滚动区域
│   └── AlternateScreen.tsx — 全屏覆盖
├── events/          — 自定义事件系统
├── hooks/           — use-input, use-app, use-animation-frame 等
├── termio/          — 原始终端 I/O
└── Ansi.tsx         — ANSI 转义码渲染组件

据泄漏分析文章指出，其终端渲染使用了 Int32Array 支持的 ASCII 字符池和位掩码编码的样式元数据，声称"在 token 流式传输期间将 stringWidth 调用减少约 50 倍"。

十一、系统提示词构建

系统提示词是分段动态组装的，带有缓存边界标记：

graph TB
    subgraph Static["静态段（全局可缓存 scope='global'）"]
        INTRO["getSimpleIntroSection()<br/>智能体身份 + 安全指令"]
        SYSTEM["getSimpleSystemSection()<br/>工具使用 + 权限模式"]
        TASKS_SEC["getSimpleDoingTasksSection()<br/>软件工程行为规范"]
        ACTIONS["getActionsSection()<br/>操作可逆性策略"]
        TOOL_GUIDE["getUsingYourToolsSection()<br/>工具使用指南"]
    end

    BOUNDARY["═══ SYSTEM_PROMPT_DYNAMIC_BOUNDARY ═══"]

    subgraph Dynamic["动态段（用户/会话级，不跨组织缓存）"]
        HOOKS_SEC["getHooksSection()<br/>用户钩子指令"]
        UNDERCOVER["Undercover 指令<br/>(ant-only)"]
        MEMORY["loadMemoryPrompt()<br/>记忆内容"]
        LANG["语言偏好"]
        CONTEXT["getUserContext()<br/>Git 状态 / CLAUDE.md / 平台信息"]
        MCP_INST["MCP 指令"]
    end

    Static --> BOUNDARY
    BOUNDARY --> Dynamic

这种设计让静态段可以跨会话缓存（通过 Anthropic API 的 cache_control 参数），而动态段每次重新构建。

十二、隐藏特性与彩蛋

12.1 反蒸馏机制（Anti-Distillation）

// services/api/claude.ts (301-313)
if (
  feature('ANTI_DISTILLATION_CC')
    ? process.env.CLAUDE_CODE_ENTRYPOINT === 'cli' &&
      shouldIncludeFirstPartyOnlyBetas() &&
      getFeatureValue_CACHED_MAY_BE_STALE(
        'tengu_anti_distill_fake_tool_injection', false)
    : false
) {
  result.anti_distillation = ['fake_tools']
}

当启用时，向 API 请求注入 anti_distillation: ['fake_tools']，服务端会在工具调用中混入虚假工具响应。目的：如果竞争对手录制 Claude Code 的 API 流量来训练模型，虚假工具数据会污染训练集。

绕过分析：MITM 代理可在请求到达 API 前剥离该字段；设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 环境变量可禁用；第三方 SDK 入口完全绕过。正如分析者所言："真正的保护可能是法律而非技术"。

12.2 伪装模式（Undercover Mode）

utils/undercover.ts — Anthropic 内部员工在外部开源仓库工作时自动启用：

禁止提及内部代码名（Capybara、Tengu 等）
隐藏内部 Slack 频道和仓库名称
删除所有 "Co-Authored-By" 标识
不暴露未发布的模型版本号

关键限制：没有强制关闭开关。注释明确写道："There is NO force-OFF. This guards against model codename leaks." 这是一扇单向门。

12.3 挫折感检测

// utils/userPromptKeywords.ts
const negativePattern =
  /\b(wtf|wth|ffs|omfg|shit(ty|tiest)?|dumbass|horrible|awful|
  piss(ed|ing)? off|piece of (shit|crap|junk)|what the (fuck|hell)|
  fucking? (broken|useless|terrible|awful|horrible)|fuck you|
  screw (this|you)|so frustrating|this sucks|damn it)\b/

仅在 Anthropic 内部版本中启用（外部构建通过死代码消除移除）。当检测到用户情绪消极时，弹出 transcript 分享提示，方便内部员工快速提交反馈。选用正则而非 LLM 的原因：比模型推理调用更快更便宜。

12.4 KAIROS — 自主守护智能体

KAIROS（古希腊语"恰当的时机"）是一个被提及 150+ 次的特性开关，代表着一个全新的交互范式——始终在线的后台智能体。

核心能力：

/dream 技能 — "夜间记忆蒸馏"
autoDream 守护进程 — 用户空闲时自动进行记忆整合
GitHub webhook 订阅 — 监听仓库事件
Cron 定时任务 — 每 5 分钟计划刷新
推送通知 — 主动通知用户

autoDream 触发条件：

距离上次整合 ≥ 24 小时
至少 5 个新会话
进程锁（同一时间只有一个进程执行整合）

12.5 Buddy 伴侣系统（愚人节彩蛋）

buddy/
├── companion.ts     — Mulberry32 PRNG 确定性生成
├── types.ts         — 物种、稀有度、属性定义
├── CompanionSprite.tsx — 500ms 刷新的终端动画精灵
├── sprites.ts       — ASCII 艺术帧
├── prompt.ts        — 系统提示词注入
└── useBuddyNotification.tsx — 预告逻辑

一个 Tamagotchi 风格的虚拟宠物系统：

18 种物种：鸭子、鹅、blob、猫、龙、章鱼、猫头鹰、企鹅、海龟、蜗牛、幽灵、美西螈、水豚、仙人掌、机器人、兔子、蘑菇、胖墩。物种名用十六进制字符数组编码，避免触发内部代码名扫描器
稀有度：普通(60%)、非凡(25%)、稀有(10%)、史诗(4%)、传说(1%)
RPG 属性：DEBUGGING、PATIENCE、CHAOS、WISDOM、SNARK
防篡改：骨骼数据（物种、稀有度、闪光）从 hash(userId) 确定性生成，不存储在配置中，无法伪造传说级
活跃窗口：2026 年 4 月 1-7 日（跨时区滚动上线）

十三、Bash 安全检查

tools/BashTool/bashSecurity.ts 实现了 23 项编号安全检查：

检查项	防御内容
命令替换	`$()`、`${}`、进程替换 `<()`、`>()`
Zsh 危险内置	`zmodload`、`emulate`、`sysopen`、`ztcp`、`zsocket`、`zf_rm` 等 18 个
Zsh 等号展开	`=curl` 绕过 curl 权限检查
Unicode 攻击	零宽空格注入、Unicode 空白字符
IFS 注入	空字节 IFS 注入
Shell 元字符	混淆标志、花括号展开、中间单词哈希
控制字符	不可见控制字符注入
注释/引号错位	注释与引号边界不对齐攻击
PowerShell	PowerShell 语法检测
HackerOne 发现	格式错误 token 绕过（安全审计中发现）

每次触发的检查都会记录 tengu_bash_security_check_triggered 事件（带数字 ID），用于安全监控和统计。

十四、Prompt 缓存经济学

services/api/promptCacheBreakDetection.ts 追踪 12+ 个缓存破坏维度：

系统提示词哈希 | 工具 Schema 哈希 | cache_control 哈希
单工具 Schema 变更 | 模型切换 | 快速模式
全局缓存策略 | Beta 头部 | effort 值
Auto 模式状态 | 超限状态 | 微压缩状态

当检测到缓存破坏（>5% 缓存读取 token 下降且 >2,000 绝对 token 下降）时：

触发 tengu_prompt_cache_break 分析事件
写入 diff 文件到 ~/.claude/tmp/cache-break-*.diff
区分服务端破坏 vs TTL 过期

正如源码注释所言："在按 token 付费时，缓存失效不再是计算机科学笑话，而是会计问题。"

十五、自动压缩与 250K API 调用浪费

services/compact/autoCompact.ts 中有一段引人注目的注释：

2026-03-10：BQ 分析显示 1,279 个会话在单次会话中有 50+ 连续自动压缩失败（最高达 3,272 次），全球每日浪费约 250,000 次 API 调用。

修复方案：三行代码。

const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3

添加一个断路器，连续失败 3 次后停止重试。

自动压缩参数：

缓冲区：13,000 tokens（AUTOCOMPACT_BUFFER_TOKENS）
警告阈值：上下文窗口 - 20,000 tokens
摘要输出预留：20,000 tokens（基于 p99.99 实际摘要为 17,387 tokens）

十六、IDE 桥接（Bridge）

graph LR
    subgraph IDE["IDE 端"]
        VSCODE["VS Code 扩展"]
        JETBRAINS["JetBrains 插件"]
    end

    subgraph Bridge["桥接层 (27 个文件)"]
        BRIDGE_MAIN["bridgeMain.ts<br/>2,999 行<br/>CCR WebSocket 服务器"]
        REPL_BRIDGE["replBridge.ts<br/>2,406 行<br/>REPL 远程模式"]
    end

    subgraph Cloud["claude.ai"]
        CCR["Claude Code Remote"]
    end

    subgraph Local["本地 CLI"]
        CLAUDE["claude 进程"]
    end

    VSCODE <-->|JWT 认证| BRIDGE_MAIN
    JETBRAINS <-->|JWT 认证| BRIDGE_MAIN
    BRIDGE_MAIN <-->|WebSocket| CCR
    REPL_BRIDGE <-->|WebSocket| CCR
    BRIDGE_MAIN --> CLAUDE
    REPL_BRIDGE --> CLAUDE

桥接系统支持：

WebSocket 双向通信
JWT 认证 + Token 刷新调度
指数退避重连
可信设备 Token 管理
容量感知唤醒（capacityWake.ts）
消息流控门（flushGate.ts）

十七、构建时特性开关系统

Claude Code 最精妙的设计之一是其构建时特性开关系统：

// 使用 bun:bundle 的 feature() 函数
if (feature('KAIROS')) {
  // 此代码在外部构建中被完整删除
  loadKairosModule()
}

// 用户类型检查也会被常量折叠
if ("external" === 'ant') {
  // 外部构建：编译为 if (false) → 死代码消除
  loadInternalOnlyFeature()
}

已知特性开关（44 个，部分列表）：

开关名	功能
`KAIROS` / `PROACTIVE`	自主守护智能体
`ANTI_DISTILLATION_CC`	反蒸馏保护
`COORDINATOR_MODE`	多智能体协调
`BRIDGE_MODE`	IDE 桥接
`DAEMON`	后台守护进程
`VOICE_MODE`	语音输入
`BUDDY`	伴侣系统
`HISTORY_SNIP`	历史裁剪
`WORKFLOW_SCRIPTS`	工作流脚本
`AGENT_TRIGGERS`	智能体触发器
`FORK_SUBAGENT`	分叉子智能体
`REACTIVE_COMPACT`	响应式压缩
`CONTEXT_COLLAPSE`	上下文折叠
`TRANSCRIPT_CLASSIFIER`	转录分类器
`NATIVE_CLIENT_ATTESTATION`	原生客户端证明
`TEMPLATES`	模板系统
`TORCH` / `ULTRAPLAN` / `UDS_INBOX`	未知内部功能

十八、语音输入

hooks/useVoice.ts 实现了按住说话的语音输入：

使用 Anthropic 的 voice_stream STT 端点（Deepgram 后端）
macOS 原生音频或 SoX 录制
WebSocket 连接到 conversation_engine 端点
支持多语言（BCP-47 编码，从系统 locale 自动检测）
"Keyterms" 注入提升识别准确度
5 次快速按键激活阈值（防止正常打字误触发）
通过 VOICE_MODE 构建开关完整移除

十九、关键架构模式总结

19.1 流式优先（Streaming-First）

从 submitMessage() 到 query() 到 queryModelWithStreaming()，整个链路都是 AsyncGenerator<SDKMessage>。工具执行期间通过 onProgress 回调发出进度消息。

19.2 依赖注入测试

QueryDeps 接口注入 callModel、microcompact、autocompact、uuid，避免测试中使用 spyOn。

19.3 上下文穿透

ToolUseContext 是贯穿整个工具执行链路的"胖上下文"对象。子智能体通过 createSubagentContext() 获得 fork 的副本。

19.4 双层特性门控

构建时：feature() 从 bun:bundle 常量折叠，死代码消除
运行时：GrowthBook 远程开关（tengu_*），支持灰度发布和 A/B 测试

19.5 分叉子智能体

后台任务（autoDream、压缩、会话记忆、推测执行）都通过 runForkedAgent() 运行——隔离的子智能体，有自己的查询来源，防止递归并共享父级的缓存安全参数。

二十、代码质量观察

指标	数据
总代码量	512,664 行 TypeScript
文件数	1,884 个 `.ts/.tsx`
最大文件	`cli/print.ts`（5,594 行，单函数 3,167 行，12 层嵌套）
第二大文件	`main.tsx`（4,683 行）
API 客户端	`claude.ts`（3,419 行）
MCP 客户端	`mcp/client.ts`（3,348 行）
桥接主模块	`bridgeMain.ts`（2,999 行）

一些值得注意的代码风格：

偏好单文件大函数而非过度抽象（print.ts 是极端案例）
大量使用 feature() 门控保持外部构建精简
独创的 analytics 安全类型：AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS——防止开发者意外将文件路径或代码片段发送到分析系统
tengu_ 前缀统一所有实验名和事件名（Tengu 是内部代号，讽刺的是在 Undercover Mode 的注释中被列为"不应暴露的代码名"示例）

结语

Claude Code 的 512,664 行源码揭示了一个工程复杂度远超预期的系统。它不仅仅是一个"LLM 套壳"——从自研终端渲染引擎到 23 项 Bash 安全检查，从多智能体协调到 prompt 缓存经济学，每一个模块都体现了在真实生产环境中打磨 AI 编程工具的深度工程投入。

最具战略意义的发现不是源码本身（它可以被重构），而是那 44 个特性开关背后的产品路线图：KAIROS 自主守护智能体、语音输入、团队协作记忆……这些代表着 Anthropic 对 AI 编程工具未来形态的判断。而这种战略意外，无法被 DMCA 撤回。

28 KiB Raw Permalink Blame History Unescape Escape