DCE 深度拆解专题¶

重要性：⭐⭐（编译时门控深度——feature flag 详细列表 + 模式 + 影响） 真实位置：全文 feature('X') + bun:bundle + require() + "external" === 'ant' 角色：通过编译时 DCE 控制商业版 vs 内部版本关联：analysis/dce-dead-code-elimination.md

1. DCE 3 层架构¶

┌─────────────────────────────────────────┐
│  Layer 1: bun:bundle feature()  (编译时) │  ← 静态字面量替换
├─────────────────────────────────────────┤
│  Layer 2: lazy require()       (运行时)  │  ← 动态加载
├─────────────────────────────────────────┤
│  Layer 3: null 兜底             (类型)    │  ← TS 编译通过
└─────────────────────────────────────────┘

3 层 —— 编译时 + 运行时 + 类型。

2. 25+ Feature Flag 详细列表¶

2.1 AI / Agent 类¶

Flag	用途	影响文件
`COORDINATOR_MODE`	多 agent 协调	coordinator/, services/swarm/
`KAIROS`	assistant 模式	assistant/, kairosGate
`PROACTIVE`	proactive 模式	proactive/, useProactive
`AGENT_TRIGGERS`	任务触发	hooks/useScheduledTasks
`TRANSCRIPT_CLASSIFIER`	auto mode 分类	utils/permissions/autoModeState

5 个 AI 类。

2.2 集成类¶

Flag	用途	影响文件
`DIRECT_CONNECT`	cc:// 协议	bridge/, server/
`LODESTONE`	深链 URI	utils/deepLink/
`SSH_REMOTE`	SSH 远程	services/ssh/
`BUDDY`	桌宠	buddy/, CompanionSprite
`VOICE_MODE`	语音输入	voice/, useVoiceIntegration

5 个 集成类。

2.3 工具类¶

Flag	用途	影响文件
`MCP_SKILLS`	MCP 技能	services/mcp/skills/
`CHICAGO_MCP`	computer use	computerUseWrapper
`WEB_BROWSER_TOOL`	web 浏览器	tools/WebBrowserTool/
`MESSAGE_ACTIONS`	消息操作	hooks/useMessageActions
`BASH_MODE_PROGRESS`	bash 进度	components/BashModeProgress

5 个 工具类。

2.4 安全 / 性能¶

Flag	用途
`COMPACTION_REMINDERS`	压缩提醒
`HISTORY_SNIP`	历史截断
`UPLOAD_USER_SETTINGS`	设置同步
`EXPERIMENTAL_SKILL_SEARCH`	实验性搜索

4 个 安全/性能。

2.5 推测更多¶

Flag	用途（推测）
`RESUMABLE_TASKS`	恢复任务
`TELEMETRY_V2`	新遥测
`PRICING_MODEL_V2`	新定价
...	...

10+ 推测 —— 总数 30-50+。

3. ANT-ONLY 双版本策略¶

3.1 编译时常量¶

"external" === 'ant'   // 商业版：false
"external" !== 'ant'   // 商业版：true

字符串字面量 —— 编译时替换。

3.2 双版本差异¶

项	商业版 (external)	内部版 (ant)
调试	❌ 阻止	✅ 允许
`--delegate-permissions`	❌ 无	✅ 有
`--afk`	❌ 无	✅ 有
`--tasks`	❌ 无	✅ 有
`--agent-teams`	❌ 无	✅ 有
`--hard-fail`	❌ 无	✅ 有
BUDDY 桌宠	❌ 无	✅ 有
`--proactive`	❌ 无	✅ 有
`--brief`	❌ 无	✅ 有
`--remote-control`	❌ 无	✅ 有

10+ 差异 —— 商业版和内部版。

3.3 完整 ANT-ONLY 例子¶

if ("external" === 'ant') {
  program.addOption(new Option('--delegate-permissions', '[ANT-ONLY] Alias for --permission-mode auto.')
    .implies({ permissionMode: 'auto' }));
  program.addOption(new Option('--afk', '[ANT-ONLY] Deprecated alias for --permission-mode auto.')
    .hideHelp().implies({ permissionMode: 'auto' }));
  program.addOption(new Option('--tasks [id]', '[ANT-ONLY] Tasks mode: watch for tasks and auto-process them.')
    .argParser(String).hideHelp());
  program.option('--agent-teams', '[ANT-ONLY] Force Claude to use multi-agent mode');
  program.addOption(new Option('--enable-auto-mode', 'Opt in to auto mode').hideHelp());
  program.addOption(new Option('--proactive', 'Start in proactive autonomous mode'));
  program.addOption(new Option('--brief', 'Enable SendUserMessage tool for agent-to-user communication'));
  program.addOption(new Option('--assistant', 'Force assistant mode (Agent SDK daemon use)').hideHelp());
  program.addOption(new Option('--channels <servers...>', 'MCP servers whose channel notifications...').hideHelp());
  program.addOption(new Option('--dangerously-load-development-channels <servers...>', 'Load channel servers not on the approved allowlist...').hideHelp());
}

10+ ANT-ONLY 选项 —— 全部打包在内。

4. 50+ Feature 推断完整列表¶

已知： - COORDINATOR_MODE, KAIROS, PROACTIVE, AGENT_TRIGGERS, TRANSCRIPT_CLASSIFIER - DIRECT_CONNECT, LODESTONE, SSH_REMOTE, BUDDY, VOICE_MODE - MCP_SKILLS, CHICAGO_MCP, WEB_BROWSER_TOOL, MESSAGE_ACTIONS, BASH_MODE_PROGRESS - COMPACTION_REMINDERS, HISTORY_SNIP, UPLOAD_USER_SETTINGS, EXPERIMENTAL_SKILL_SEARCH

19 个已识别。

推测： - BUDDY - CHICAGO_MCP - DCE_DEEP_DIVE（自己） - EARLY_ACCESS - FAST_MODE - 等等

推测总数 30-50+。

5. lazy require 模式分类¶

5.1 3 种主要模式¶

// 模式 1: feature gate + lazy require + null 兜底
const x = feature('X') ? require('./X.js') : null

// 模式 2: getter 包 require（循环依赖）
const getX = () => require('./X.js') as typeof import('./X.js')

// 模式 3: dynamic import（async）
const { x } = await import('./X.js')

3 种 —— 各自用途。

5.2 完整 lazy require 列表（推测）¶

const coordinatorModeModule = feature('COORDINATOR_MODE') 
  ? require('./coordinator/coordinatorMode.js') as typeof import('./coordinator/coordinatorMode.js') 
  : null;
const assistantModule = feature('KAIROS') 
  ? require('./assistant/index.js') as typeof import('./assistant/index.js') 
  : null;
const kairosGate = feature('KAIROS') 
  ? require('./assistant/gate.js') as typeof import('./assistant/gate.js') 
  : null;
const proactiveModule = feature('PROACTIVE') || feature('KAIROS') 
  ? require('../proactive/index.js') : null;
const useProactive = feature('PROACTIVE') || feature('KAIROS') 
  ? require('../proactive/useProactive.js').useProactive : null;
const useScheduledTasks = feature('AGENT_TRIGGERS') 
  ? require('../hooks/useScheduledTasks.js').useScheduledTasks : null;
const autoModeStateModule = feature('TRANSCRIPT_CLASSIFIER') 
  ? require('./utils/permissions/autoModeState.js') : null;
const VoiceKeybindingHandler = feature('VOICE_MODE') 
  ? require('../hooks/useVoiceIntegration.js').VoiceKeybindingHandler : () => null;
const useVoiceIntegration = feature('VOICE_MODE') 
  ? require('../hooks/useVoiceIntegration.js').useVoiceIntegration : () => ({...});
const AntModelSwitchCallout = "external" === 'ant' 
  ? require('../components/AntModelSwitchCallout.js').AntModelSwitchCallout : null;
const UndercoverAutoCallout = "external" === 'ant' 
  ? require('../components/UndercoverAutoCallout.js').UndercoverAutoCallout : null;
const WebBrowserPanelModule = feature('WEB_BROWSER_TOOL') 
  ? require('../tools/WebBrowserTool/WebBrowserPanel.js') : null;
const getTeammateUtils = () => require('./utils/teammate.js') as typeof import('./utils/teammate.js');
const getTeammatePromptAddendum = () => require('./utils/swarm/teammatePromptAddendum.js') as typeof import('./utils/swarm/teammatePromptAddendum.js');
const getTeammateModeSnapshot = () => require('./utils/swarm/backends/teammateModeSnapshot.js') as typeof import('./utils/swarm/backends/teammateModeSnapshot.js');

15+ 个 lazy require。

6. NOOP Stub 模式¶

const PROACTIVE_NO_OP_SUBSCRIBE = (_cb: () => void) => () => {}
const PROACTIVE_FALSE = () => false
const SUGGEST_BG_PR_NOOP = (_p: string, _n: string): boolean => false

4 种 NOOP stub： - 返回空函数 - 返回 false - 返回 null - 返回 noop 对象

7. 字符串字面量 vs 变量¶

7.1 字符串字面量（推荐）¶

if ("external" === 'ant') { ... }  // 编译时确定

自描述 + 编译时 —— 推荐。

7.2 boolean 变量¶

const IS_ANT = "external" === 'ant'
if (IS_ANT) { ... }  // 间接

间接 —— DCE 可能不砍。

7.3 函数调用¶

if (isRunningWithBun()) { ... }  // 运行时

不 DCE。

字符串字面量 是最佳 DCE 友好方式。

8. DCE 与测试¶

8.1 测试覆盖¶

// 内部版本测试
if (feature('X')) {
  testFeatureX()  // 测试可能漏
}

DCE 砍掉的代码 在商业版未测。

8.2 解决¶

// CI 跑两套
bun build --production  // 商业版
bun build --ant         // 内部版
// 都跑测试

双版本测试。

9. DCE 失败案例¶

9.1 字符串拼接不 DCE¶

const ant = 'ant'
if ("external" === ant) { ... }  // 变量，DCE 可能不砍

变量不 DCE。

9.2 复杂表达式不 DCE¶

if ("external".toLowerCase() === 'ant') { ... }  // 运行时计算

计算不 DCE。

9.3 函数返回值不 DCE¶

if (isAnt()) { ... }  // 函数

函数不 DCE。

10. DCE 节省（推测）¶

类别	代码量
KAIROS	~5000 行
COORDINATOR_MODE	~3000 行
PROACTIVE	~2000 行
BUDDY	~1000 行
VOICE_MODE	~2000 行
WEB_BROWSER	~3000 行
等等	~10000+ 行
总计	~25000+ 行

商业版 比 ANT 版少 25000+ 行。

压缩比 30-50%。

11. 关键设计模式¶

11.1 3 重 DCE 门控¶

编译时 + 运行时 + 类型。

11.2 25+ feature flag¶

细粒度门控。

11.3 ANT-ONLY 双版本¶

商业 + 内部。

11.4 字符串字面量¶

DCE 友好。

11.5 3 种 lazy require¶

getter / feature gate / dynamic。

11.6 null 兜底¶

类型安全。

11.7 NOOP stub¶

完整 API 兼容。

11.8 15+ lazy require¶

循环解 + 性能。

12. 关键洞察¶

12.1 3 重门控¶

编译时 + 运行时 + 类型三保险。

12.2 25+ feature flag¶

细粒度。

12.3 商业版 25000+ 行节省¶

30-50% 体积。

12.4 字符串字面量¶

DCE 友好方式。

12.5 15+ lazy require¶

循环依赖解。

12.6 NOOP stub¶

API 兼容。

12.7 ANT-ONLY 10+ 选项¶

双版本差异。

12.8 DCE 失败¶

变量 / 函数不 DCE。

12.9 测试挑战¶

DCE 砍的代码未测。

12.10 bun:bundle¶

编译器原生支持。

13. 改进方向¶

13.1 文档化所有 feature¶

/**
 * @feature COORDINATOR_MODE
 * @since v0.5
 */

文档同步。

13.2 ANT 内部测商业版¶

bun build --production
bun build --ant
# 都跑测试

双版本测试。

13.3 Plugin feature 矩阵¶

{
  "requires": { "KAIROS": false }
}

Plugin 兼容性。

13.4 DCE metrics¶

{ featureCount, antSize, externalSize }

监控。

14. 阅读建议¶

grep feature('X') 全文 —— 25+ flag
grep require(...) 在 if/三元 —— lazy require
grep "external" === 'ant' —— ANT-ONLY
看 main.tsx 顶部 200 行 —— 综合例子
看 services/plugins/ —— plugin 系统

15. 与其他专题的关系¶

文件	关系
`analysis/dce-dead-code-elimination.md`	概述
`extensibility.md`	plugin feature 矩阵
`security-audit.md`	ANT-ONLY 反调试