claude-code/docs/outline-output/design/05-feature-flags.md

# 第五章：Feature Flag 系统的三个硬约束

> `feature()` 不是普通函数，它是 Bun 编译器用来做死代码消除的语法标记。

打开 `src/types/internal-modules.d.ts:10`，你会看到这样一行声明：

```ts
declare module 'bun:bundle' {
  export function feature(name: string): boolean
}
```

这是一个虚假的模块声明 -- `bun:bundle` 不存在于文件系统上，也不是 npm 包。它是 Bun 编译器在打包（`Bun.build()`）时内建的编译期原语。当 `Bun.build()` 看到 `feature('X')` 时，它会根据构建配置中的 `features` 列表决定把调用点替换为 `true` 或 `false`，然后对所有不可达分支执行死代码消除（Dead Code Elimination，DCE）。

反编译重建之后，这个原语不再由编译器直接提供，必须通过类型声明 + 双构建管线各自模拟。这带来了三个硬约束，贯穿了整个代码库的每一个 feature-gated 代码块。

## 约束一：`feature()` 只能出现在 `if` 条件或三元表达式的位置

CLAUDE.md 里有一条铁律：

> `feature()` 只能直接用在 `if` 语句或三元表达式的条件位置，不能赋值给变量、不能放在箭头函数体里、不能作为 `&&` 链的一部分。

打开 `src/hooks/useReplBridge.tsx:117`，你能看到一段注释精确解释了为什么：

```ts
// feature() check must use positive pattern for dead code elimination —
// negative pattern (if (!feature(...)) return) does NOT eliminate
// dynamic imports below.
if (feature('BRIDGE_MODE')) {
```

这个约束的根源是 Bun 编译器 AST 模式匹配的局限性。编译器只识别两种模式：

1. `if (feature('X')) { ... }` -- 把 `feature('X')` 替换为 `false` 后，整个代码块变成 `if (false) { ... }`，DCE 可以整块删除。
2. `feature('X') ? a : b` -- 替换后变成 `false ? a : b` 或 `true ? a : b`，DCE 可以删掉不会走的分支。

如果你写成 `const enabled = feature('X'); if (enabled) { ... }`，编译器看到的是对变量 `enabled` 的判断，无法确定其值为常量，整个 feature-gated 代码块都会保留在产物里。

**反事实推演**：如果 `feature()` 能赋值给变量，整个 `tools.ts` 的条件导入模式就不需要那么别扭的 `feature('X') ? require(...) : null` 三元表达式了。你可以写 `const enabled = feature('X'); const tool = enabled ? require(...) : null;`，代码可读性会好很多。但代价是：所有被 gate 的代码（包括 `require()` 引用不存在的文件）都会被打进产物，运行时可能触发 `MODULE_NOT_FOUND` 崩溃。

### 正面模式与负面模式的陷阱

`src/hooks/useReplBridge.tsx:117` 提到了另一个细微之处：**正面模式**（`if (feature('X'))`）才能触发 DCE，**负面模式**（`if (!feature('X')) return`）不行。

打开 `src/entrypoints/cli.tsx:165` 看一个正面模式的例子：

```ts
if (!feature('DAEMON')) {
  console.error('Error: --daemon-worker requires DAEMON feature...');
  process.exitCode = 1;
  return;
}
```

这里用了 `!feature('DAEMON')`，但注意后面的 `return` 是从 `main()` 函数退出的，不是 return 从一个 require 块。DCE 只需要把 `feature('DAEMON')` 替换为 `false` 后变成 `if (!false)` 即 `if (true)`，保留这个检查分支没问题。真正的问题是当 feature 为 true 时，Bun 需要把 `require('../daemon/workerRegistry.js')` 打进产物 -- 这要求文件存在。如果 DAEMON 在构建 features 列表里，一切正常；如果不在，那 `require()` 所在的分支因为 `!feature()` 为 `false` 会被 DCE 删掉。

关键区别在于：**`if (feature('X'))` 包裹的 `require()` 路径在 `X=false` 时被 DCE 删除**，所以文件可以不存在。但 **`if (!feature('X'))` 包裹的 `require()` 路径在 `X=true` 时必须存在**，因为 DCE 保留的是 `else` 分支。

## 约束二：`if (false)` 必须在 parse 阶段可见，否则 bundler 会崩溃

这是 Vite/Rollup 构建管线独有的约束。打开 `scripts/vite-plugin-feature-flags.ts:29`，你会看到注释：

```ts
/**
 * Vite/Rollup plugin that replaces `feature('X')` calls with boolean literals
 * at the transform stage, BEFORE the bundler resolves imports.
 *
 * This approach is necessary because some feature-gated code blocks contain
 * require() calls to files that don't exist (e.g. hunter.js inside
 * feature('REVIEW_ARTIFACT')). The bundler must see these as dead code
 * (`if (false) { ... }`) before attempting import resolution.
 */
```

打开 `src/skills/bundled/index.ts:44`，看这个致命的模式：

```ts
if (feature('REVIEW_ARTIFACT')) {
  /* eslint-disable @typescript-eslint/no-require-imports */
  const { registerHunterSkill } = require('./hunter.js')
  /* eslint-enable @typescript-eslint/no-require-imports */
  registerHunterSkill()
}
```

文件 `src/skills/bundled/hunter.js` **不存在**。你可以在终端里验证：`ls src/skills/bundled/hunter.js` 返回 "No such file or directory"。代码库中完全找不到任何名为 `hunter*` 的文件。

这在 `Bun.build()` 管线下不是问题 -- Bun 的打包器知道 `feature('REVIEW_ARTIFACT')` 返回 `false`（因为它不在 `DEFAULT_BUILD_FEATURES` 列表里，见 `scripts/defines.ts:72` 的注释），直接 DCE 掉整个 `if` 块，从来不会尝试解析 `./hunter.js`。

但 Vite/Rollup 不同。Rollup 的处理管线是：resolve imports -> transform -> bundle。如果 Vite 在 transform 之前尝试 resolve imports，它会看到 `require('./hunter.js')` 然后 `MODULE_NOT_FOUND` 崩溃。

这就是为什么 `vite-plugin-feature-flags.ts` 必须在 `transform` 阶段（而非 `load` 或 `resolveId` 阶段）替换 `feature('X')` 调用。打开 `scripts/vite-plugin-feature-flags.ts:54`，`transform` 函数用正则匹配替换：

```ts
transform(code, id) {
  if (id.includes('node_modules')) return null
  let transformed = code.replace(FEATURE_CALL_RE, (match, flagName) => {
    return features.has(flagName) ? 'true' : 'false'
  })
  // ...
}
```

替换发生在 `resolveId` 之后、bundle 之前。这样 Rollup 看到 `if (false) { require('./hunter.js') }` 就知道整个分支不可达，不会尝试解析 `./hunter.js`。

插件还提供了一个虚拟模块解决 `import { feature } from 'bun:bundle'` 的 "module not found" 错误（`scripts/vite-plugin-feature-flags.ts:47`）：

```ts
load(id) {
  if (id === resolvedVirtualModuleId) {
    return 'export function feature(name) { return false; }'
  }
}
```

这个 stub 的 `return false` 在运行时永远不会被调用，因为所有 `feature()` 调用都在 `transform` 阶段被替换成了字面量。它存在的唯一意义是让 Rollup 不报 unresolved import 错误。

**反事实推演**：如果 `transform` 替换不够早，Vite 构建管线在遇到任何引用不存在文件的 feature-gated `require()` 时都会崩溃。这意味着所有被注释掉的 feature（`CONTEXT_COLLAPSE`、`UDS_INBOX`、`REVIEW_ARTIFACT` 等）在 Vite 管线下都是"定时炸弹" -- 只要它们的代码块里有 `require()` 指向不存在的文件，替换时机不对就会炸。

## 约束三：Vite 的 `using` 声明必须 transpile，否则 Node.js 崩溃

`vite-plugin-feature-flags.ts` 在 feature flag 替换之外还承担了一项额外职责。打开 `scripts/vite-plugin-feature-flags.ts:68`：

```ts
// 2. Transpile `using _ = expr;` to `const _ = expr;` for Node.js compat.
//    Node.js v22 does not support `using` declarations (Explicit Resource Management).
//    Safe because: SLOW_OPERATION_LOGGING is not enabled, so slowLogging returns
//    a no-op disposable whose [Symbol.dispose]() is empty.
if (transformed.includes('using _')) {
  transformed = transformed.replace(/\busing\s+(_\w*)\s*=/g, 'const $1 =')
  modified = true
}
```

这段正则把所有 `using _x = expr` 替换成 `const _x = expr`。注释解释了安全性前提：`SLOW_OPERATION_LOGGING` 未启用时，`slowLogging` 返回的 disposable 的 `[Symbol.dispose]()` 是空操作，所以 `using` 和 `const` 行为等价。

但这里有一条脆弱的依赖链：如果有人启用了 `SLOW_OPERATION_LOGGING` 并在 Vite 构建产物上用 Node.js 运行，资源清理就不会执行 -- `using` 的 `Symbol.dispose` 语义被丢弃了。

**反事实推演**：如果不做这个 transpile，Vite 构建的产物在 Node.js v22 上会直接 `SyntaxError: Unexpected token 'using'`。这意味着整个 "产物兼容 bun/node" 的承诺（`build.ts` 的 post-build `import.meta.require` 补丁）在 Vite 管线上多了一个前提条件。

## 三层切换机制：Build 默认、Dev 全开、运行时环境变量

打开 `scripts/defines.ts:39`，你会看到 `DEFAULT_BUILD_FEATURES` 列表，65+ 个 feature flag 中大约有 40 个默认启用，其余被注释掉。打开 `scripts/dev.ts:39`，dev 模式使用同一个列表：

```ts
const allFeatures = [...new Set([...DEFAULT_BUILD_FEATURES, ...envFeatures])]
const featureArgs = allFeatures.flatMap(name => ['--feature', name])
```

但 dev 模式可以通过 `FEATURE_<NAME>=1` 环境变量额外启用。例如 `FEATURE_REVIEW_ARTIFACT=1 bun run dev` 会尝试启用 `REVIEW_ARTIFACT`，然后代码会尝试 `require('./hunter.js')`，由于文件不存在而崩溃。

三层机制的行为差异：

| 层级 | 何时生效 | feature() 的值 | DCE 是否生效 |
|------|----------|---------------|-------------|
| `Bun.build()` | 构建时 | 编译期常量 | 是 -- 不可达代码被删除 |
| `vite build` | 构建时（通过 transform 插件） | transform 后的字面量 | 是 -- Rollup 删除不可达分支 |
| `bun run dev` | 运行时（通过 `--feature` flag） | 运行时布尔值 | 否 -- 所有分支都在内存中 |

这意味着 dev 模式下所有 feature-gated 的 `require()` 路径都必须实际存在，否则运行时会崩溃。对 Bun 原生 dev 来说 `--feature` flag 是 Bun 运行时提供的；对 Vite dev 来说 `feature()` 被 transform 插件替换为字面量，运行时不存在 `bun:bundle` 模块。

## 反编译产物的 stub 陷阱：两类禁用，一个混淆

`DEFAULT_BUILD_FEATURES` 中被注释掉的 feature 可以分为两类。打开 `scripts/defines.ts:62-72`，看注释中的措辞差异：

**第一类：反编译丢失导致的空壳 stub**：

```ts
// 'CONTEXT_COLLAPSE', // 已禁用：实现是空壳 stub，启用后会抑制 auto compact 导致上下文管理完全失效
// 'HISTORY_SNIP',     // 已禁用：snip 功能暂时关闭
```

这些 feature 在原始 Claude Code 中是完整功能，反编译过程中逻辑丢失，留下的实现要么是空壳（`CONTEXT_COLLAPSE`），要么会破坏核心功能（`HISTORY_SNIP` 启用后 `SnipTool` 出现但上下文管理不正常）。启用它们不是"多了一个功能"，而是"引入了一个损坏的功能"。

**第二类：功能原本就 stubbed 或已废弃**：

```ts
// 'SKILL_LEARNING',  // 已禁用
// 'TEAMMEM',         // 已禁用：依赖 COORDINATOR_MODE，邮箱文件无限增长
// 'REVIEW_ARTIFACT', // 已禁用：代码审查产物（API 请求无响应，待排查 schema 兼容性）
```

`SKILL_LEARNING` 和 `TEAMMEM` 在原始版本中也是 stubbed 或内部工具，并非完整的对外功能。`REVIEW_ARTIFACT` 更有趣 -- 它的 `hunter.js` 根本不存在于反编译产物中，说明要么原始代码中也是动态加载的（但反编译时丢失了），要么是整个 hunter 子系统在某个版本中被删除但 feature gate 的引用没清理干净。

打开 `src/tools.ts:148`，`ReviewArtifactTool` 的条件加载用的是标准的三元模式：

```ts
const ReviewArtifactTool = feature('REVIEW_ARTIFACT')
  ? require('@claude-code-best/builtin-tools/tools/ReviewArtifactTool/ReviewArtifactTool.js')
      .ReviewArtifactTool
  : null
```

打开 `packages/builtin-tools/src/tools/ReviewArtifactTool/` 验证一下 -- 这个目录是存在的，工具实现也完整。但 `hunter.js`（注册 hunter skill 的模块）不存在。这意味着 `REVIEW_ARTIFACT` 是"工具存在但 skill 不存在"的半死状态。

**如果不区分这两类**，有人可能觉得"注释掉的 feature 只要改一行配置就能启用"。对第二类也许可以，但对第一类，启用 `CONTEXT_COLLAPSE` 会让 auto compact 失效、启用 `UDS_INBOX` 会让 Node.js 构建卡住（`scripts/defines.ts:68` 的注释明确说了）。

## `const x = feature()` 为什么到处存在

CLAUDE.md 说 "不能赋值给变量"，但你打开 `src/main.tsx:119` 就能看到违反这条规则的代码：

```ts
const coordinatorModeModule = feature('COORDINATOR_MODE')
  ? (require('./coordinator/coordinatorMode.js') as typeof import('./coordinator/coordinatorMode.js'))
  : null;
```

这不矛盾。CLAUDE.md 说的"不能赋值给变量"指的是你不能把 `feature()` 的返回值单独赋给变量然后在 `if` 里用那个变量。但 `feature() ? a : null` 是三元表达式 -- `feature()` 在条件位置。Bun 编译器的 DCE 看到的是 `feature('X')` 这个 AST 节点在三元条件的根，它知道可以替换。

同样的模式在 `src/tools.ts:140-158` 中大量出现：

```ts
const SnipTool = feature('HISTORY_SNIP')
  ? require('@claude-code-best/builtin-tools/tools/SnipTool/SnipTool.js').SnipTool
  : null
const ReviewArtifactTool = feature('REVIEW_ARTIFACT')
  ? require('@claude-code-best/builtin-tools/tools/ReviewArtifactTool/ReviewArtifactTool.js').ReviewArtifactTool
  : null
```

这是 "feature gate + 条件 require + null fallback" 三合一模式。如果 `feature()` 在条件位置，DCE 生效，`require()` 路径在 false 时不会被解析。如果写成 `const enabled = feature('X'); const tool = enabled ? require(...) : null;`，第二行的 require 不在 `feature()` 的 AST 子树里，DCE 无法保证它在 false 时被消除。

打开 `src/main.tsx:703`，看一个更微妙的三元用法：

```ts
const _pendingConnect: PendingConnect | undefined = feature('DIRECT_CONNECT')
  ? {
      url: undefined,
      authToken: undefined,
      dangerouslySkipPermissions: false,
    }
  : undefined;
```

这里不是 require，而是一个对象字面量。`feature('DIRECT_CONNECT')` 在三元条件位置，DCE 可以把 false 分支（对象字面量）消除。如果不这么做，`PendingConnect` 类型可能引用的内部模块会被全量引入。

## feature 字符串本身的 DCE

还有一个容易被忽略的 DCE 细节。打开 `src/components/TokenWarning.tsx:87`：

```ts
// Each feature() block stands alone so the flag strings DCE from
// external builds independently.
if (feature('REACTIVE_COMPACT')) {
  if (getFeatureValue_CACHED_MAY_BE_STALE('tengu_cobalt_raccoon', false)) {
    reactiveOnlyMode = true;
  }
}
if (feature('CONTEXT_COLLAPSE')) {
  const { isContextCollapseEnabled } =
    require('../services/contextCollapse/index.js');
  // ...
}
```

注释说 "each feature() block stands alone"。为什么不合并成一个 `if (feature('A') || feature('B'))` 块？因为合并后，即使 `A` 和 `B` 都为 false，`else` 分支中的 feature flag 字符串 `'REACTIVE_COMPACT'` 和 `'CONTEXT_COLLAPSE'` 可能不会从产物中消除。独立的 `if` 块让每个 flag 字符串在自己的 DCE 作用域里 -- `feature('X')` 替换为 `false` 后，整个 `if (false) { ... }` 块包括其中的字符串字面量都会被删除。

这对内部工具来说很重要：feature flag 的名称（如 `CONTEXT_COLLAPSE`）本身可能泄露内部项目代号或功能名称。独立 DCE 确保外部构建的产物里找不到任何被注释掉的 feature 名称。

## 延伸阅读

- 想看 feature flag 如何与代码分割交互（为什么 600+ chunks 中的某些 chunks 只在特定 feature 启用时加载），见 [第一章：Code Splitting 不是优化，是生存需求](./01-code-splitting.md)
- 想看入口函数如何用 feature gate 实现零模块加载的快速路径，见 [第二章：入口的 Fast-Path 优先级链](./02-fast-path.md)
- 想看工具系统如何用 feature gate 实现延迟加载与白名单过滤，见 [第六章：工具系统的延迟加载与 CORE_TOOLS 白名单](./06-tools-deferred.md)
- 想看 biome.json 关闭 42 条规则背后的反编译痕迹，见 [第十五章：biome.json 的 42 条规则关闭](./15-biome-42-rules.md)