第 03 课：Feature Gate 双层体系

王小酱
3 阅读9分钟

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

学习目标

完成本课后，你将能够：

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

3.1 为什么需要两层 Feature Gate？

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

维度编译时 Feature Gate运行时 Feature Flag
时机打包时决定应用运行时决定
工具Bun feature()GrowthBook
效果代码物理移除，不在产物中代码存在但不执行
切换成本需要重新打包发布即时生效，无需部署
适用场景内部/外部构建隔离A/B 测试、灰度发布、紧急关闭
安全性代码不可被逆向发现代码可被逆向发现
数量~92 个~1100+ 个

决策逻辑：

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

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 功能

Flag控制的功能说明
KAIROS始终在线 Assistant主动式 Agent，不等用户输入
PROACTIVE主动行为KAIROS 的前置依赖
KAIROS_BRIEFBrief 命令KAIROS 的精简输出模式
KAIROS_CHANNELS频道系统KAIROS 多频道通信
KAIROS_DREAM做梦系统后台记忆整合
KAIROS_PUSH_NOTIFICATION推送通知向用户设备推送
KAIROS_GITHUB_WEBHOOKSGitHub Webhooks监听 GitHub 事件
COORDINATOR_MODE多 Agent 协调Coordinator-Worker 编排
ULTRAPLAN远程规划30 分钟 Opus 规划会话
ULTRATHINK深度思考扩展推理能力

工具与执行

Flag控制的功能
WEB_BROWSER_TOOLWeb 浏览器工具
MONITOR_TOOLMCP 监控工具
OVERFLOW_TEST_TOOL溢出测试工具
HISTORY_SNIP历史片段工具
WORKFLOW_SCRIPTS工作流脚本
UDS_INBOXUnix Domain Socket 收件箱
CHICAGOMCPComputer Use（截屏+点击）

上下文与记忆

Flag控制的功能
REACTIVE_COMPACT反应式上下文压缩
CONTEXT_COLLAPSE上下文折叠
EXTRACT_MEMORIES记忆提取
FILE_PERSISTENCE文件持久化
CONNECTOR_TEXT连接器文本

连接与远程

Flag控制的功能
BRIDGE_MODEclaude.ai 集成
DAEMON后台守护进程
SSH_REMOTESSH 远程连接
DIRECT_CONNECT直连模式
CCR_REMOTE_SETUP云容器远程设置
CCR_AUTO_CONNECT云容器自动连接
CCR_MIRROR云容器镜像
AGENT_TRIGGERSAgent 触发器
AGENT_TRIGGERS_REMOTE远程 Agent 触发器

UI 与体验

Flag控制的功能
BUDDYTamagotchi 宠物系统
VOICE_MODE语音输入
TERMINAL_PANEL终端面板
HISTORY_PICKER历史选择器
STREAMLINED_OUTPUT精简输出
NATIVE_CLIPBOARD_IMAGE原生剪贴板图片

安全与分析

Flag控制的功能
TRANSCRIPT_CLASSIFIER对话分类器（自动权限）
NATIVE_CLIENT_ATTESTATION客户端认证
LODESTONE未知（可能是分析系统）
TORCH未知（可能是调试系统）
PERFETTO_TRACING性能追踪

其他

Flag控制的功能
FORK_SUBAGENT进程 Fork 子 Agent
MCP_SKILLSMCP 技能集成
MCP_RICH_OUTPUTMCP 富文本输出
EXPERIMENTAL_SKILL_SEARCH实验性技能搜索
BUILDING_CLAUDE_APPS构建 Claude 应用
BUILTIN_EXPLORE_PLAN_AGENTS内置探索/规划 Agent
TEMPLATES模板系统
AWAY_SUMMARY离开摘要
QUICK_SEARCH快速搜索
TREE_SITTER_BASHTree-sitter Bash 解析
VERIFICATION_AGENT验证 Agent
SELF_HOSTED_RUNNER自托管运行器
HARD_FAIL硬失败模式

死代码消除的实际效果

编译前（源码）：
├── 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')

为什么接受过时数据？

方案延迟准确性选择
每次实时查询 GrowthBook 服务器高（网络往返）100% 准确✗
缓存 + 定期后台刷新零（本地读取）可能过时几分钟✓

对 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' 用户独占功能

功能说明
Staging API连接 claude-ai.staging.ant.dev 测试环境
CLI Internal Betacli-internal-2026-02-09 HTTP 头
Undercover Mode在公开仓库中隐藏 AI 身份
ConfigTool修改配置的内部工具
TungstenTool高级内部工具
REPLTool交互式 REPL 工具
Debug Prompt Dump将 prompt 转储到 ~/.config/claude/dump-prompts/
Fault InjectionBridge 模式故障注入测试
GrowthBook Config UI/config 命令查看/修改运行时 flag
ANT_ONLY_SAFE_ENV_VARSBash 中可访问的内部环境变量白名单
Fennec 迁移migrateFennecToOpus.ts 内部模型迁移
SuggestBackgroundPRTool建议后台 PR 工具

三层协作示例

以 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 内部功能的完整地图。

本课小结

要点内容
双层设计编译时（代码消除）+ 运行时（动态控制）
编译时 flag~92 个，控制内部功能的物理存在
运行时 flag~1100+ 个 tengu_ 前缀，GrowthBook 管理
缓存策略CACHED_MAY_BE_STALE — 性能优先，接受过时
用户隔离USER_TYPE === 'ant' — 第三层功能隔离
Beta 协商HTTP 头告知 API 客户端支持的实验性功能

下一课预告

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

avatar
文章
阅读
粉丝