88 个 Feature Flags - 构建时特性门控全解

概述

Claude Code 使用 Bun 打包器的 bun:bundle 模块实现编译时特性门控。88+ 个 feature flags 控制着 AI 自主能力、基础设施、安全分类、工具扩展、UI 体验和实验性功能。在公开版本中，feature() 始终返回 false，被门控的代码虽保留但永远不会执行。

正文

feature() 是什么

Claude Code 使用 Bun 打包器的 bun:bundle 模块提供编译时特性门控：

// 源码中的用法（src/tools.ts 等）
import { feature } from 'bun:bundle'

const SleepTool = feature('PROACTIVE') || feature('KAIROS')
  ? require('@claude-code-best/builtin-tools/tools/SleepTool/SleepTool.js').SleepTool
  : null

在 Anthropic 的内部构建中，feature() 在打包时被求值——返回 true 的代码会被保留，返回 false 的代码会被 Dead Code Elimination (DCE) 彻底移除。

在我们的反编译版本中，feature 从 bun:bundle 导入（声明在 src/types/internal-modules.d.ts），在运行时始终返回 false：

// src/types/internal-modules.d.ts
declare module 'bun:bundle' {
  export function feature(name: string): boolean;
}

这意味着所有 88+ 个 feature flag 后的代码在运行时永远不会执行，但代码本身完整保留，可以阅读和分析。

Flags 分类全景

分类	数量	flags
Agent / 自动化	15	`KAIROS`, `KAIROS_BRIEF`, `KAIROS_CHANNELS`, `KAIROS_DREAM`, `KAIROS_GITHUB_WEBHOOKS`, `KAIROS_PUSH_NOTIFICATION`, `PROACTIVE`, `COORDINATOR_MODE`, `FORK_SUBAGENT`, `AGENT_MEMORY_SNAPSHOT`, `AGENT_TRIGGERS`, `AGENT_TRIGGERS_REMOTE`, `VERIFICATION_AGENT`, `BUILTIN_EXPLORE_PLAN_AGENTS`, `MONITOR_TOOL`
基础设施	10	`DAEMON`, `BG_SESSIONS`, `BRIDGE_MODE`, `CCR_AUTO_CONNECT`, `CCR_MIRROR`, `CCR_REMOTE_SETUP`, `DIRECT_CONNECT`, `SSH_REMOTE`, `SELF_HOSTED_RUNNER`, `BYOC_ENVIRONMENT_RUNNER`
安全 / 分类	6	`TRANSCRIPT_CLASSIFIER`, `BASH_CLASSIFIER`, `TREE_SITTER_BASH`, `TREE_SITTER_BASH_SHADOW`, `NATIVE_CLIENT_ATTESTATION`, `ABLATION_BASELINE`
工具 / 能力	10	`WEB_BROWSER_TOOL`, `TERMINAL_PANEL`, `CONTEXT_COLLAPSE`, `HISTORY_SNIP`, `OVERFLOW_TEST_TOOL`, `WORKFLOW_SCRIPTS`, `VOICE_MODE`, `MCP_RICH_OUTPUT`, `MCP_SKILLS`, `UDS_INBOX`
UI / 体验	8	`MESSAGE_ACTIONS`, `QUICK_SEARCH`, `HISTORY_PICKER`, `AUTO_THEME`, `STREAMLINED_OUTPUT`, `COMPACTION_REMINDERS`, `TEMPLATES`, `BUDDY`
平台 / 实验	10+	`DUMP_SYSTEM_PROMPT`, `UPLOAD_USER_SETTINGS`, `DOWNLOAD_USER_SETTINGS`, `EXPERIMENTAL_SKILL_SEARCH`, `ULTRAPLAN`, `ULTRATHINK`, `TORCH`, `LODESTONE`, `PERFETTO_TRACING`, `SLOW_OPERATION_LOGGING`, `HARD_FAIL`, `ALLOW_TEST_VERSIONS`

代码中的典型模式

Feature flags 在代码中主要有三种使用模式：

模式一：条件加载工具

// src/tools.ts — 最常见的模式
const MonitorTool = feature('MONITOR_TOOL')
  ? require('@claude-code-best/builtin-tools/tools/MonitorTool/MonitorTool.js').MonitorTool
  : null

当 flag 为 false 时，require() 调用被 DCE 移除，工具不会出现在可用工具列表中。

模式二：条件注册命令

// src/commands.ts — 注册斜杠命令
if (feature('VOICE_MODE')) {
  commands.push({ name: 'voice', description: '...' })
}

模式三：条件启用 API 特性

// src/constants/betas.ts — 控制发送给 API 的 beta header
export const AFK_MODE_BETA_HEADER = feature('TRANSCRIPT_CLASSIFIER')
  ? 'afk-mode-2026-01-31'
  : ''

[!info] 由于 feature() 在构建时求值，被 DCE 移除的代码不会增加最终打包体积。但在反编译版本中，这些代码全部保留——这正是我们能够进行完整分析的原因。

有趣的发现

KAIROS 家族最庞大——6 个相关 flag 控制从核心功能到推送通知的方方面面
ABLATION_BASELINE 是用于"科学对照实验"的——它会关闭 thinking、compaction、auto-memory 等高级功能，测量裸 API 调用的基线性能
BUDDY 是一个 AI 吉祥物/精灵系统——在 src/buddy/ 目录下有完整实现
ULTRAPLAN 和 ULTRATHINK 暗示着比当前 extended thinking 更高级的推理模式

关联笔记

growthbook-ab-testing - 运行时 A/B 测试体系
three-tier-gating - 三层门禁系统全景
hidden-features - 未公开功能深度解析

4.5 KiB Raw Permalink Blame History Unescape Escape