特性门控系统

Claude Code 使用 编译时特性门控（Feature Gates）实现条件编译，通过 feature() 函数在构建阶段进行 死代码消除（Dead Code Elimination），产出针对不同部署目标的精简构建产物。

工作原理

feature() 函数

typescript

// 构建时由 Bun bundler 内联为 true/false
function feature(flag: FeatureFlag): boolean {
  return FEATURE_FLAGS[flag] === true
}

// 使用示例
if (feature('VOICE_MODE')) {
  // 当 VOICE_MODE=false 时，整个分支被 tree-shake 消除
  const voiceEngine = await import('./voice/voiceEngine')
}

构建时处理

源代码                          构建产物 (VOICE_MODE=false)
─────────                      ──────────────
if (feature('VOICE_MODE')) {    // 整段被消除
  startVoice()                  // 
}                               // 

if (feature('BRIDGE_MODE')) {   if (true) {
  initBridge()                    initBridge()
}                               }

已知特性 Flag 完整列表

项目中使用了 ~47 个 编译时特性 Flag：

核心功能 Flag

Flag	用途	影响范围
`BRIDGE_MODE`	claude.ai Web 端 Bridge 通信	bridge/ 相关文件
`DAEMON`	守护进程/后台运行模式	进程管理、会话持久化
`BG_SESSIONS`	后台会话管理	多会话并发
`VOICE_MODE`	语音输入/输出	voice/、音频采集
`KAIROS`	高级时间/计划功能	定时任务、brief 模式
`KAIROS_BRIEF`	Kairos Brief 模式	简洁输出
`KAIROS_CHANNELS`	Kairos 频道功能	频道通信
`KAIROS_GITHUB_WEBHOOKS`	Kairos GitHub Webhook	PR 订阅
`TEMPLATES`	项目模板系统	初始化模板
`PROACTIVE`	主动建议模式	SleepTool 启用

工具与功能 Flag

Flag	控制的功能	说明
`AGENT_TRIGGERS`	CronCreate/Delete/ListTool	Agent 触发器
`WORKFLOW_SCRIPTS`	WorkflowTool	工作流编排（非 WORKFLOW_TOOL）
`WEB_BROWSER_TOOL`	WebBrowserTool	网页浏览器工具
`CONTEXT_COLLAPSE`	CtxInspectTool	上下文折叠
`HISTORY_SNIP`	SnipTool	历史裁剪
`UDS_INBOX`	ListPeersTool	UDS 收件箱
`FORK_SUBAGENT`	Fork 子代理	分支代理
`TORCH`	Torch 功能	Torch 命令
`TOKEN_BUDGET`	Token 预算系统	预算管理
`VERIFICATION_AGENT`	验证代理	验证工具

UI Flag

Flag	用途
`BUDDY`	Buddy 虚拟宠物系统
`MESSAGE_ACTIONS`	消息操作菜单
`STREAMLINED_OUTPUT`	精简输出模式
`CONNECTOR_TEXT`	连接器文本

企业/高级 Flag

Flag	用途
`COORDINATOR_MODE`	多 Agent 协调器
`ULTRAPLAN`	超级计划模式
`CCR_AUTO_CONNECT`	自动连接 CCR
`CCR_MIRROR`	CCR 镜像
`CCR_REMOTE_SETUP`	CCR 远程设置
`SELF_HOSTED_RUNNER`	自托管运行器
`BYOC_ENVIRONMENT_RUNNER`	BYOC 环境运行器
`NATIVE_CLIENT_ATTESTATION`	原生客户端认证
`DOWNLOAD_USER_SETTINGS`	下载用户设置
`FILE_PERSISTENCE`	文件持久化

内部/实验 Flag

Flag	用途
`ABLATION_BASELINE`	消融基线测试
`AWAY_SUMMARY`	离开摘要
`BASH_CLASSIFIER`	Bash 分类器
`BREAK_CACHE_COMMAND`	缓存破坏命令
`CACHED_MICROCOMPACT`	缓存微压缩
`CHICAGO_MCP`	Chicago MCP (含 computer-use)
`COMMIT_ATTRIBUTION`	提交归属
`DUMP_SYSTEM_PROMPT`	转储系统提示
`EXPERIMENTAL_SKILL_SEARCH`	实验性技能搜索
`EXTRACT_MEMORIES`	提取记忆
`HOOK_PROMPTS`	Hook 提示
`MCP_SKILLS`	MCP 技能
`TRANSCRIPT_CLASSIFIER`	转录分类器

文档修正说明

原文档列出的 REPL_TOOL、SLEEP_TOOL、NOTEBOOK_TOOL、POWERSHELL_TOOL、COMPUTER_USE、DREAM、PASSES、BUGHUNTER、STICKERS、QUICK_SEARCH、VIM_MODE、TEAM_MEMORY、SWARM、TELEPORT、SANDBOX、STRUCTURED_DIFF、DEEP_LINK、CLAUDE_IN_CHROME、ANT_SPECIFIC 等 Flag 在实际代码中不存在。

REPLTool 通过 process.env.USER_TYPE === 'ant' 控制
SleepTool 通过 feature('PROACTIVE') || feature('KAIROS') 控制
NotebookEditTool 始终导入（非 feature-gated）
PowerShellTool 通过 isPowerShellToolEnabled() 函数控制

GrowthBook 运行时门控

除编译时 feature() 外，还有 运行时 门控通过 GrowthBook 实现：

typescript

// 运行时特性检查（不被编译消除）
const isEnabled = growthbook.isOn('feature_name')

// 带缓存的特性检查
const cached = getCachedFeature('feature_name', {
  staleMs: 5 * 60 * 1000,  // 5 分钟缓存
  fallback: false
})

GrowthBook 与 feature() 的区别

维度	`feature()`	GrowthBook
时机	编译时	运行时
产物影响	代码被消除	代码保留
变更方式	重新构建	远程配置刷新
用途	构建变体（如 Mobile/Desktop）	A/B 测试、灰度发布
回退	无回退（固化）	有默认值和缓存

对代码结构的影响

CLI 路由 (cli.tsx)

cli.tsx 中约有 30 个 feature-gated 路径。在 main() 函数内使用 if (feature('FLAG')) 分支条件导入对应模块：

BRIDGE_MODE → 导入 bridge 模块
DAEMON → 导入 daemon 模块
BG_SESSIONS → 导入会话管理模块
等等

当 Flag 为 false 时，整个 if 分支（包括 import()）会被 Bun bundler 通过 tree-shaking 消除。

工具注册 (tools.ts)

getTools() 函数返回工具列表，内部通过多种门控方式注册工具：

始终包含：FileReadTool, FileEditTool, FileWriteTool, BashTool, GlobTool, GrepTool, AgentTool, WebFetchTool, WebSearchTool 等
环境变量门控：process.env.USER_TYPE === 'ant' 时添加 REPLTool, SuggestBackgroundPRTool
Feature Flag 门控：
- feature('PROACTIVE') || feature('KAIROS') → SleepTool
- feature('AGENT_TRIGGERS') → CronCreateTool, CronDeleteTool, CronListTool
- feature('WEB_BROWSER_TOOL') → WebBrowserTool
- feature('WORKFLOW_SCRIPTS') → WorkflowTool
- feature('UDS_INBOX') → ListPeersTool
- feature('HISTORY_SNIP') → SnipTool
- feature('CONTEXT_COLLAPSE') → CtxInspectTool
- 等等

快捷键定义 (keybindings)

部分快捷键仅在特定 Feature Flag 启用时生效，通过条件判断注册。例如 KAIROS、VOICE_MODE 等 Flag 会控制是否注册对应的快捷键绑定。

注意：实际代码中不存在 registerKeybinding 函数，快捷键通过 src/keybindings/ 目录中的模块管理。

构建变体

不同部署目标使用不同的 Feature Flag 组合：

构建目标	启用的 Flag	说明
CLI (标准)	大部分 Flag	完整 CLI 体验
SDK (-p 模式)	最小集	无 UI、无 Bridge
MCP Server	MCP 相关	仅 MCP 协议
Bridge Client	BRIDGE_MODE + 基础	claude.ai 桥接
Enterprise	全部 + TEAM_MEMORY	企业全功能

特性门控系统 ​

工作原理 ​

feature() 函数 ​

构建时处理 ​

已知特性 Flag 完整列表 ​

核心功能 Flag ​

工具与功能 Flag ​

UI Flag ​

企业/高级 Flag ​

内部/实验 Flag ​

GrowthBook 运行时门控 ​

GrowthBook 与 feature() 的区别 ​

对代码结构的影响 ​

CLI 路由 (cli.tsx) ​

工具注册 (tools.ts) ​

快捷键定义 (keybindings) ​

构建变体 ​