# 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 |

---

## 二、整体架构

```mermaid
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
```

---

## 三、启动流程

```mermaid
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>`，每次调用经历：

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

### 4.2 query.ts — 流式查询循环

```mermaid
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>` 是一个功能丰富的接口，定义了工具的完整生命周期：

```mermaid
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 工具执行调度

```mermaid
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 权限决策流程

```mermaid
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 协调器模式

```mermaid
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+ 行）定义了 **四阶段工作流**：

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

关键原则写在 prompt 里而非代码里：
- *"Do not rubber-stamp weak work"*（不要草率通过低质量工作）
- *"You must understand findings before directing follow-up work"*（在指导后续工作前必须理解发现）

### 7.2 子智能体启动流程

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

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

### 7.3 任务类型

```mermaid
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 连接状态机

```mermaid
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 跨应用访问）。

---

## 九、记忆系统

```mermaid
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 倍"。

---

## 十一、系统提示词构建

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

```mermaid
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）

```typescript
// 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 挫折感检测

```typescript
// 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 触发条件**：
1. 距离上次整合 ≥ 24 小时
2. 至少 5 个新会话
3. 进程锁（同一时间只有一个进程执行整合）

### 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 调用。

修复方案：**三行代码**。

```typescript
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）

```mermaid
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 最精妙的设计之一是其构建时特性开关系统：

```typescript
// 使用 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 撤回。