Claude Code 源码精读:第 03 课:Feature Gate 双层体系

模块一：基础认知 | 前置依赖：第 02 课 | 预计学习时间：60 分钟

学习目标

完成本课后，你将能够：

1. 1. 区分编译时 Feature Gate 和运行时 Feature Flag 的适用场景
2. 2. 列出 Claude Code 中至少 20 个编译时开关及其控制的功能
3. 3. 解释 GrowthBook 缓存策略 CACHED_MAY_BE_STALE 的性能取舍
4. 4. 理解 USER_TYPE === 'ant' 如何实现内部/外部功能隔离

3.1 为什么需要两层 Feature Gate？

Claude Code 同时使用编译时和运行时两层功能开关，它们解决不同问题：

决策逻辑：

• • 不想让外部用户看到（即使反编译）→ 编译时
• • 想要动态控制（无需发版）→ 运行时

3.2 编译时 Feature Gate：Bun feature()

基本模式

// 模式 1：条件导入（最常见）
const SleepTool = feature('PROACTIVE') || feature('KAIROS')
  ? require('./tools/SleepTool/SleepTool.js').SleepTool
  : null

// 模式 2：条件代码块
if (feature('COORDINATOR_MODE')) {
  // 这整个块在外部构建中被移除
  initCoordinatorMode()
}

// 模式 3：带类型断言的条件导入
const reactiveCompact = feature('REACTIVE_COMPACT')
  ? (require('./services/compact/reactiveCompact.js')
     as typeof import('./services/compact/reactiveCompact.js'))
  : null

编译时开关完整分类

核心 Agent 功能

工具与执行

上下文与记忆

连接与远程

UI 与体验

安全与分析

其他

死代码消除的实际效果

编译前（源码）：
├── tools/SleepTool/           ← KAIROS 专用
├── services/compact/reactiveCompact.ts  ← REACTIVE_COMPACT 专用
├── coordinator/               ← COORDINATOR_MODE 专用
├── assistant/                 ← KAIROS 专用
└── buddy/                     ← BUDDY 专用

编译后（外部发布包）：
├── (SleepTool 不存在)
├── (reactiveCompact 不存在)
├── (coordinator 不存在)
├── (assistant 不存在)
└── (buddy 不存在)

体积影响估算： 这些 feature-gated 模块可能占源码总量的 30-40%。编译时消除让外部发布包显著更小。

3.3 运行时 Feature Flag：GrowthBook

GrowthBook 是什么？

GrowthBook 是一个开源的 Feature Flag 和 A/B 测试平台。Claude Code 用它管理 1100+ 个运行时开关，前缀统一为 tengu_（Claude Code 的内部项目代号）。

初始化流程

服务启动
  → services/analytics/growthbook.ts
    → initializeGrowthBook()（记忆化，只执行一次）
      → 创建 GrowthBook 客户端
      → 检查 OAuth 认证状态变化
      → 等待 initialized promise
      → setupPeriodicGrowthBookRefresh()（定期刷新）

缓存策略：CACHED_MAY_BE_STALE

这是整个 Feature Flag 系统中最重要的设计决策：

// 获取 feature flag 值 — 可能过时但绝不阻塞
const value = getFeatureValue_CACHED_MAY_BE_STALE('tengu_some_flag')

为什么接受过时数据？

对 Feature Flag 来说，几分钟的过时是完全可以接受的。但如果每次判断都要等网络请求，用户会明显感受到延迟 — 尤其是在 Agent 循环中每轮都要检查多个 flag 的场景下。

tengu_ Flag 分类（采样）

1100+ 个 flag 太多无法全部列出，以下是按功能域的采样：

配置与行为控制

tengu_plan_mode_interview_phase    — 规划模式是否启用面试阶段
tengu_ant_model_override           — 内部用户模型覆盖
tengu_max_version_config           — 版本号上限配置
tengu_cicada_nap_ms                — 某个定时器的休眠毫秒数
tengu_penguins_off                 — Fast Mode 的紧急关闭开关
tengu_streaming_tool_execution2    — 流式工具执行（第 2 版）

Bridge 与远程

tengu_ccr_bridge       — 云容器 Bridge
tengu_ccr_mirror       — 云容器镜像
tengu_bridge_repl_v    — Bridge REPL 版本
tengu_harbor           — Harbor 功能
tengu_cobalt_lantern   — 未知（代号系统）
tengu_cobalt_harbor    — 未知（代号系统）

工具与 Agent

tengu_advisor_tool_token_usage  — Advisor 工具的 token 用量
tengu_tool_search_unsupported_models — 工具搜索不支持的模型列表
tengu_auto_background_agents    — 自动后台 Agent
tengu_scratch                   — Scratchpad 跨 Worker 共享目录
tengu_amber_flint               — Agent Teams/Swarm 功能

会话与记忆

tengu_agent_memory_loaded           — Agent 记忆加载状态
tengu_auto_compact_succeeded        — 自动压缩成功标记
tengu_orphaned_messages_tombstoned  — 孤立消息墓碑化

分析与监控

tengu_1p_event_batch_config     — 第一方事件批量配置
tengu_event_sampling_config     — 事件采样配置
tengu_miraculo_the_bard         — 未知（可能是分析相关）

3.4 USER_TYPE === 'ant'：第三层隔离

除了编译时和运行时两层，还有一个用户类型检查层：

// 当用户是 Anthropic 员工时
if (USER_TYPE === 'ant') {
  // 启用内部功能
}

'ant' 用户独占功能

三层协作示例

以 KAIROS（始终在线 Assistant）为例：

第一层：编译时 — feature('KAIROS')
  → 外部构建中，KAIROS 的所有代码被物理移除
  → 即使拿到发布包也看不到任何相关代码

第二层：运行时 — tengu_kairos_cron_config
  → 即使在内部构建中，KAIROS 的具体行为也可以通过 GrowthBook 动态调节
  → 例如：调整定时器间隔、启用/禁用特定频道

第三层：用户类型 — USER_TYPE === 'ant'
  → 某些 KAIROS 的调试功能只对 Anthropic 员工可见
  → 例如：查看 KAIROS 的内部日志、手动触发做梦

3.5 API Beta 协商：constants/betas.ts

Claude Code 还通过 HTTP 头与 API 协商启用实验性功能：

// constants/betas.ts — 每个常量对应一个 Beta 版本标识
export const INTERLEAVED_THINKING_BETA_HEADER = 'interleaved-thinking-2025-05-14'
export const CONTEXT_1M_BETA_HEADER = 'context-1m-2025-08-07'
export const STRUCTURED_OUTPUTS_BETA_HEADER = 'structured-outputs-2025-12-15'
export const WEB_SEARCH_BETA_HEADER = 'web-search-2025-03-05'
export const EFFORT_BETA_HEADER = 'effort-2025-11-24'
export const TASK_BUDGETS_BETA_HEADER = 'task-budgets-2026-03-13'
export const FAST_MODE_BETA_HEADER = 'fast-mode-2026-02-01'
export const REDACT_THINKING_BETA_HEADER = 'redact-thinking-2026-02-12'
export const TOKEN_EFFICIENT_TOOLS_BETA_HEADER = 'token-efficient-tools-2026-03-28'
export const AFK_MODE_BETA_HEADER = 'afk-mode-2026-01-31'          // Feature-gated
export const ADVISOR_BETA_HEADER = 'advisor-tool-2026-03-01'
export const CLI_INTERNAL_BETA_HEADER = 'cli-internal-2026-02-09'  // ant only

这些 Beta 头在 API 请求中被附加，告诉服务端"我支持这些实验性功能"。服务端据此决定响应格式。

课后练习

练习 1：搜索并统计

在代码库中搜索所有 feature( 调用。回答：

• • 哪个文件包含最多的 feature() 调用？
• • 哪些 flag 在多个文件中被检查（说明它们影响多个模块）？

练习 2：Feature Gate 决策

对以下功能，判断应该用编译时还是运行时 gate，并说明理由：

• • a) 一个新的实验性工具，只想让 1% 的用户试用
• • b) 一个内部调试面板，绝不能出现在外部版本中
• • c) 一个新的压缩算法，想在出问题时快速回滚
• • d) Computer Use 功能，只对付费用户开放

练习 3：追踪 GrowthBook 初始化

从 services/analytics/growthbook.ts 开始，追踪 GrowthBook 的完整初始化链路。回答：

• • 初始化在应用启动的哪个阶段发生？
• • 缓存刷新的频率是多少？
• • 如果 GrowthBook 服务器不可达，会怎样？

练习 4：内部功能地图

搜索所有 USER_TYPE === 'ant' 的使用点，画出 Anthropic 内部功能的完整地图。

本课小结

下一课预告

第 04 课：入口与启动流程 — 从 cli.tsx 的快速路径检查到 init.ts 的 17 步初始化序列，再到 main.tsx 的 Commander.js 组装，追踪应用从冷启动到 REPL 就绪的完整链路。