跳转至

DCE 编译时门控（Dead Code Elimination）

重要性：⭐⭐（编译时优化——feature() + bun:bundle + lazy require 三重门控） 范围：bun:bundle 编译产物 + 50+ feature flag 方法：grep feature( + bun:bundle + require( 模式

1. 3 重 DCE 门控

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

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

2. Layer 1: bun:bundle feature() 编译时

2.1 用法

import { feature } from 'bun:bundle'
if (feature('COORDINATOR_MODE')) { ... }

2.2 编译时替换

feature('COORDINATOR_MODE') 
  → 在外部构建：替换为 'false'（DCE 砍掉 if 块）
  → 在内部构建：替换为 'true'

编译时常量 —— 整段 if (false) { ... } 被 DCE 砍掉。

2.3 feature flag 数量

50+ feature flag（推测）—— 详细列表见 A3-12 dce-deep-dive.md（待写）。

2.4 典型 flag

feature('COORDINATOR_MODE')         // 协调器
feature('KAIROS')                   // assistant 模式
feature('PROACTIVE')                // proactive 模式
feature('AGENT_TRIGGERS')           // 任务触发
feature('TRANSCRIPT_CLASSIFIER')    // auto mode
feature('BUDDY')                    // 桌宠
feature('DIRECT_CONNECT')           // cc:// 协议
feature('LODESTONE')                // 深链
feature('SSH_REMOTE')               // SSH 远程
feature('MCP_SKILLS')               // MCP 技能
feature('CHICAGO_MCP')              // computer use
feature('COMPACTION_REMINDERS')     // 压缩提醒
feature('HISTORY_SNIP')             // 历史截断
feature('UPLOAD_USER_SETTINGS')     // 设置同步
feature('BASH_MODE_PROGRESS')       // bash 进度
feature('WEB_BROWSER_TOOL')         // web browser
feature('VOICE_MODE')               // 语音
feature('MESSAGE_ACTIONS')          // 消息操作
feature('EXPERIMENTAL_SKILL_SEARCH') // 实验性搜索

~20+ 已识别 —— 推测还有 30+。

3. Layer 2: lazy require() 运行时

3.1 模式

// 编译时门控 + 运行时 require
const coordinatorModeModule = feature('COORDINATOR_MODE') 
  ? require('./coordinator/coordinatorMode.js') as typeof import('./coordinator/coordinatorMode.js') 
  : null;

3.2 为什么用 require 而非 import

// ES import (静态)
import { x } from './x.js'  // 强制求值

// CJS require (动态)
const x = require('./x.js')  // 条件求值

require 是条件 —— feature()=false 时不执行。

3.3 循环依赖

const getX = () => require('./X.js') as typeof import('./X.js')

getter 包 require —— 第一次调用才执行。

3.4 dynamic import

const { x } = await import('./x.js')  // async lazy

async 变体 —— 用在 preAction 钩子。

4. Layer 3: null 兜底（类型安全）

4.1 模式

const module = condition ? require('./X.js') : null

// 使用时
module?.method?.()

可选链 —— null 安全。

4.2 类型

// 显式类型
const x: typeof import('./X.js') | null = condition ? require('./X.js') : null

显式类型 —— TS 知道可能是 null。

4.3 多个 null 模式

const NOOP = () => false
const NOOP_SUBSCRIBE = (_cb) => () => {}
const NOOP_OP = (...args) => false

const x = condition ? realModule : { 
  method: NOOP_OP,
  subscribe: NOOP_SUBSCRIBE,
}

fallback 对象 —— 提供完整 stub。

5. ANT-ONLY 双版本

5.1 编译时常量

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

"external" 字符串 —— 编译时替换。

5.2 双版本策略

外部版本 (commercial)         内部版本 (ant)
─────────────────────       ─────────────────────
feature('KAIROS') = false    feature('KAIROS') = true
feature('BUDDY') = false     feature('BUDDY') = true
"external" !== 'ant' = true  "external" !== 'ant' = false
"external" === 'ant' = false "external" === 'ant' = true

完全不同的代码 —— 编译时确定。

5.3 ANT-ONLY 例子

// 商业版：跳过
if ("external" === 'ant') {
  program.addOption(new Option('--delegate-permissions', '...').implies({ ... }));
}

// 商业版：反调试
if ("external" !== 'ant' && isBeingDebugged()) {
  process.exit(1);
}

不同行为 —— 一行代码编译时决定。

6. 详细 feature flag 分析（推测）

6.1 KAIROS

  • 作用：assistant 模式（Agent SDK daemon）
  • 影响：assistant/index.js, assistant/gate.js
  • 代码量：推测 ~5000+ 行

6.2 COORDINATOR_MODE

  • 作用：多 agent 协调
  • 影响：coordinator/coordinatorMode.js
  • 代码量：推测 ~3000+ 行

6.3 PROACTIVE

  • 作用：proactive 模式
  • 影响：proactive/index.js, proactive/useProactive.js
  • 代码量：推测 ~2000+ 行

6.4 BUDDY

  • 作用：桌宠
  • 影响：buddy/
  • 代码量：推测 ~1000+ 行

6.5 VOICE_MODE

  • 作用：语音输入
  • 影响：voice/, hooks/useVoiceIntegration.js
  • 代码量：推测 ~2000+ 行

6.6 WEB_BROWSER_TOOL

  • 作用：Web 浏览器工具
  • 影响：tools/WebBrowserTool/
  • 代码量：推测 ~3000+ 行

6.7 AGENT_TRIGGERS

  • 作用：agent 触发任务
  • 影响：hooks/useScheduledTasks.js
  • 代码量：推测 ~500+ 行

6.8 CHICAGO_MCP

  • 作用：computer use MCP
  • 影响：computerUseWrapper, isComputerUseMCPServer
  • 代码量：推测 ~1000+ 行

6.9 UPLOAD_USER_SETTINGS

  • 作用：用户设置同步
  • 影响：services/settingsSync/
  • 代码量：推测 ~500+ 行

7. DCE 节省的代码量（推测）

类别 代码量 节省（外部版）
KAIROS ~5000 行 5000 行
COORDINATOR_MODE ~3000 行 3000 行
PROACTIVE ~2000 行 2000 行
BUDDY ~1000 行 1000 行
VOICE_MODE ~2000 行 2000 行
WEB_BROWSER ~3000 行 3000 行
等等 ~10000+ 行 ~10000+ 行
总计 ~25000+ 行 ~25000+ 行

商业版 比 ANT 内部版少 25000+ 行。

压缩比 —— 商业版可能小 30-50%。

8. DCE 的限制

8.1 编译时确定

DCE 只对编译时可确定的代码 有效。

if (process.env.X) { ... }  // 运行时确定，DCE 不砍
if (feature('X')) { ... }   // 编译时确定，DCE 砍

8.2 字符串字面量

if ("external" === 'ant') { ... }  // 编译时确定 ✅
if ("external".toLowerCase() === 'ant') { ... }  // 运行时计算 ❌

字面量必须直白。

8.3 函数调用

if (isRunningWithBun()) { ... }  // 运行时计算，DCE 不砍

函数调用 不在 DCE 范围内。

9. DCE 与代码可读性

9.1 if (feature('X')) 比 env var 清晰

if (feature('X')) { ... }  // 编译时门控
if (process.env.X) { ... }  // 运行时门控

编译时门控更可靠 —— 不会被环境变量破坏。

9.2 if ("external" === 'ant') 比 boolean 清晰

if ("external" === 'ant') { ... }  // 自描述
if (IS_ANT) { ... }  // 需要查定义

字符串字面量 比 boolean 变量更自描述。

10. DCE 的风险

10.1 测试覆盖

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

DCE 砍掉的代码 在商业版本没测过。

10.2 文档

// 文档说 feature('X') 启用 X
// 但商业版不打包 X
// 用户找不到 X

功能在文档但代码不存在 —— 用户困惑。

10.3 第三方 plugin

// plugin 假设 feature('X') 存在
// 但商业版不打包 X
// plugin 崩溃

第三方假设 —— 可能与商业版不兼容。

11. DCE 调试技巧

11.1 编译时检查

bun build --target=bun-linux-x64 --production
# 检查 dist 中是否包含 feature('X') 块

检查输出 —— 确认 DCE 生效。

11.2 运行时检查

// ANT-ONLY: 打印所有 feature 状态
console.log({
  KAIROS: feature('KAIROS'),
  BUDDY: feature('BUDDY'),
  // ...
})

调试用 —— 列出所有 feature。

11.3 Fallback 行为

const x = condition ? real : null
console.log(x === null ? 'feature OFF' : 'feature ON')  // 调试

Fallback 即指示。

12. 与其他分析的关系

文件 关系
architecture-history.md 演进驱动力
performance-history.md 启动优化
extensibility.md feature 影响扩展
security-audit.md ANT-ONLY 反调试

13. 关键洞察

13.1 3 重 DCE 门控

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

13.2 feature('X') 50+

门控粒度细 —— 不影响其他功能。

13.3 lazy require 解循环

getter 包 require —— 经典。

13.4 null 兜底类型安全

module?.method?.() —— TS 友好。

13.5 ANT-ONLY 双版本

商业版 + 内部版 —— 编译时决定。

13.6 DCE 节省 25000+ 行

30-50% 体积 节省。

13.7 DCE 限制

只在编译时可确定 —— 函数调用不砍。

13.8 DCE 风险

测试覆盖 / 文档 / 第三方 plugin。

13.9 DCE 可读性

字符串字面量比 boolean 自描述。

13.10 bun:bundle 集成

bun:bundle 编译器原生支持。

14. 改进方向

14.1 文档化所有 feature

// 每个 feature 配 README
/**
 * @feature COORDINATOR_MODE
 * @since v0.5
 * @description 多 agent 协调
 */

文档同步 —— 防止用户困惑。

14.2 ANT 内部测商业版

# CI 跑两套
bun build --production
bun build --ant
# 都跑测试

双版本测试。

14.3 Plugin feature 矩阵

// plugin manifest 声明依赖
{
  "name": "my-plugin",
  "requires": { "KAIROS": false }  // 兼容矩阵
}

Plugin 兼容性。

15. 阅读建议

  1. grep feature('X') 全文 —— 50+ 分布
  2. grep bun:bundle —— 编译时集成
  3. grep require(...) 在 if/三元中 —— lazy require
  4. 看 main.tsx —— 综合例子
  5. 看 services/plugins/ —— plugin 系统如何用 DCE

16. 总结表

DCE 模式 数量 用途
feature('X') 编译时 50+ flag 静态门控
lazy require 运行时 5+ 模块 循环解 + 性能
null 兜底 配套 类型安全
ANT-ONLY 双版本 50+ 处 商业 + 内部
节省代码量 ~25000+ 行 体积优化

DCE 是商业级工程的标志 —— 多数开源项目不做。