vault backup: 2026-06-09 23:15:17
This commit is contained in:
@@ -1,12 +1,17 @@
|
||||
---
|
||||
title: "88 个 Feature Flags - 构建时特性门控全解"
|
||||
description: "深入剖析 Claude Code 的 88+ 个构建时 feature flags：bun:bundle 编译时门控机制，揭示被编译器删除的隐藏功能模块。"
|
||||
keywords: ["feature flags", "特性标志", "构建时门控", "bun:bundle", "条件编译"]
|
||||
tags: [feature-flags, claude-code, 构建时门控, bun, 条件编译]
|
||||
create time: 2026-06-09 22:30
|
||||
---
|
||||
|
||||
{/* 本章目标：完整梳理构建时 feature flag 系统的机制和所有 flag 的分类 */}
|
||||
# 88 个 Feature Flags - 构建时特性门控全解
|
||||
|
||||
## feature() 是什么
|
||||
## 概述
|
||||
|
||||
Claude Code 使用 Bun 打包器的 `bun:bundle` 模块实现编译时特性门控。88+ 个 feature flags 控制着 AI 自主能力、基础设施、安全分类、工具扩展、UI 体验和实验性功能。在公开版本中，`feature()` 始终返回 `false`，被门控的代码虽保留但永远不会执行。
|
||||
|
||||
## 正文
|
||||
|
||||
### feature() 是什么
|
||||
|
||||
Claude Code 使用 Bun 打包器的 `bun:bundle` 模块提供编译时特性门控：
|
||||
|
||||
@@ -32,51 +37,22 @@ declare module 'bun:bundle' {
|
||||
|
||||
这意味着所有 88+ 个 feature flag 后的代码**在运行时永远不会执行**，但代码本身完整保留，可以阅读和分析。
|
||||
|
||||
## Flags 分类全景
|
||||
### Flags 分类全景
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Agent / 自动化" icon="robot">
|
||||
**15 个 flags** — 控制 AI 的自主能力边界
|
||||
| 分类 | 数量 | 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` |
|
||||
|
||||
`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`
|
||||
</Card>
|
||||
|
||||
<Card title="基础设施" icon="server">
|
||||
**10 个 flags** — 控制运行环境和连接方式
|
||||
|
||||
`DAEMON` · `BG_SESSIONS` · `BRIDGE_MODE` · `CCR_AUTO_CONNECT` · `CCR_MIRROR` · `CCR_REMOTE_SETUP` · `DIRECT_CONNECT` · `SSH_REMOTE` · `SELF_HOSTED_RUNNER` · `BYOC_ENVIRONMENT_RUNNER`
|
||||
</Card>
|
||||
|
||||
<Card title="安全 / 分类" icon="shield-halved">
|
||||
**6 个 flags** — 增强权限判断的智能性
|
||||
|
||||
`TRANSCRIPT_CLASSIFIER` · `BASH_CLASSIFIER` · `TREE_SITTER_BASH` · `TREE_SITTER_BASH_SHADOW` · `NATIVE_CLIENT_ATTESTATION` · `ABLATION_BASELINE`
|
||||
</Card>
|
||||
|
||||
<Card title="工具 / 能力" icon="toolbox">
|
||||
**10 个 flags** — 新增的 AI 能力
|
||||
|
||||
`WEB_BROWSER_TOOL` · `TERMINAL_PANEL` · `CONTEXT_COLLAPSE` · `HISTORY_SNIP` · `OVERFLOW_TEST_TOOL` · `WORKFLOW_SCRIPTS` · `VOICE_MODE` · `MCP_RICH_OUTPUT` · `MCP_SKILLS` · `UDS_INBOX`
|
||||
</Card>
|
||||
|
||||
<Card title="UI / 体验" icon="palette">
|
||||
**8 个 flags** — 界面和交互改进
|
||||
|
||||
`MESSAGE_ACTIONS` · `QUICK_SEARCH` · `HISTORY_PICKER` · `AUTO_THEME` · `STREAMLINED_OUTPUT` · `COMPACTION_REMINDERS` · `TEMPLATES` · `BUDDY`
|
||||
</Card>
|
||||
|
||||
<Card title="平台 / 实验" icon="flask-vial">
|
||||
**10+ 个 flags** — 实验性和平台级功能
|
||||
|
||||
`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`
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 代码中的典型模式
|
||||
### 代码中的典型模式
|
||||
|
||||
Feature flags 在代码中主要有三种使用模式：
|
||||
|
||||
### 模式一：条件加载工具
|
||||
**模式一：条件加载工具**
|
||||
|
||||
```typescript
|
||||
// src/tools.ts — 最常见的模式
|
||||
@@ -87,7 +63,7 @@ const MonitorTool = feature('MONITOR_TOOL')
|
||||
|
||||
当 flag 为 `false` 时，`require()` 调用被 DCE 移除，工具不会出现在可用工具列表中。
|
||||
|
||||
### 模式二：条件注册命令
|
||||
**模式二：条件注册命令**
|
||||
|
||||
```typescript
|
||||
// src/commands.ts — 注册斜杠命令
|
||||
@@ -96,7 +72,7 @@ if (feature('VOICE_MODE')) {
|
||||
}
|
||||
```
|
||||
|
||||
### 模式三：条件启用 API 特性
|
||||
**模式三：条件启用 API 特性**
|
||||
|
||||
```typescript
|
||||
// src/constants/betas.ts — 控制发送给 API 的 beta header
|
||||
@@ -105,13 +81,18 @@ export const AFK_MODE_BETA_HEADER = feature('TRANSCRIPT_CLASSIFIER')
|
||||
: ''
|
||||
```
|
||||
|
||||
<Note>
|
||||
由于 `feature()` 在构建时求值，被 DCE 移除的代码不会增加最终打包体积。但在反编译版本中，这些代码全部保留——这正是我们能够进行完整分析的原因。
|
||||
</Note>
|
||||
> [!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]] - 未公开功能深度解析
|
||||
|
||||
Reference in New Issue
Block a user