Feature Flags¶

重要性：⭐⭐⭐ 目标读者：开发者 / 内部用户关联：topics/dce-deep-dive.md、analysis/dce-dead-code-elimination.md

1. 概览¶

Feature flags 通过 feature('X') 编译时门控 + bun:bundle DCE。

5 类： - AI / Agent - 集成 - 工具 - 安全 / 性能 - 内部 (ANT-ONLY)

2. 5 个 AI / Agent flag¶

2.1 `COORDINATOR_MODE`¶

if (feature('COORDINATOR_MODE')) {
  // 多 agent 协调
}

多 agent 协调。

2.2 `KAIROS`¶

if (feature('KAIROS') && assistantModule?.isAssistantMode()) {
  // assistant 模式
}

Assistant。

2.3 `PROACTIVE`¶

if (feature('PROACTIVE')) {
  // proactive 模式
}

Proactive。

2.4 `AGENT_TRIGGERS`¶

const useScheduledTasks = feature('AGENT_TRIGGERS') 
  ? require('...') : null

任务触发。

2.5 `TRANSCRIPT_CLASSIFIER`¶

const autoModeStateModule = feature('TRANSCRIPT_CLASSIFIER') 
  ? require('...') : null

Auto mode 分类。

3. 5 个集成 flag¶

3.1 `DIRECT_CONNECT`¶

if (feature('DIRECT_CONNECT')) {
  // cc:// 协议
}

cc:// 协议。

3.2 `LODESTONE`¶

if (feature('LODESTONE')) {
  // 深链 URI / macOS URL scheme
}

深链。

3.3 `SSH_REMOTE`¶

if (feature('SSH_REMOTE') && _pendingSSH) {
  // SSH 远程
}

SSH。

3.4 `BUDDY`¶

...(feature('BUDDY') ? [
  maybe('companion_intro', () => ...)
] : []),

桌宠。

3.5 `VOICE_MODE`¶

const useVoiceIntegration = feature('VOICE_MODE') 
  ? require('...') : null

语音。

4. 5 个工具 flag¶

4.1 `MCP_SKILLS`¶

const fetchMcpSkillsForClient = feature('MCP_SKILLS') 
  ? require('...') : null

MCP 技能。

4.2 `CHICAGO_MCP`¶

const computerUseWrapper = feature('CHICAGO_MCP') ? ... : null

Computer use。

4.3 `WEB_BROWSER_TOOL`¶

const WebBrowserPanelModule = feature('WEB_BROWSER_TOOL') 
  ? require('...') : null

Web 浏览器。

4.4 `MESSAGE_ACTIONS`¶

const disableMessageActions = feature('MESSAGE_ACTIONS') ?
  useMemo(() => isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_MESSAGE_ACTIONS), []) : false

消息操作。

4.5 `BASH_MODE_PROGRESS`¶

// bash 进度 UI

Bash 进度（推测）。

5. 5 个安全 / 性能 flag¶

5.1 `COMPACTION_REMINDERS`¶

...(feature('COMPACTION_REMINDERS') ? [
  maybe('compaction_reminder', () => ...)
] : []),

压缩提醒。

5.2 `HISTORY_SNIP`¶

...(feature('HISTORY_SNIP') ? [
  maybe('context_efficiency', () => ...)
] : []),

历史截断。

5.3 `UPLOAD_USER_SETTINGS`¶

if (feature('UPLOAD_USER_SETTINGS')) {
  void import('./services/settingsSync/index.js').then(...)
}

设置同步。

5.4 `EXPERIMENTAL_SKILL_SEARCH`¶

...(feature('EXPERIMENTAL_SKILL_SEARCH') && 
  skillSearchModules && !options?.skipSkillDiscovery
  ? [maybe('skill_discovery', () => ...)] : []),

实验性搜索。

5.5 其他（推测）¶

更多 flag 推测存在。

6. ANT-ONLY 双版本¶

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

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

6.1 ANT-ONLY 选项¶

Flag	商业版	ANT 版
`--delegate-permissions`	❌	✅
`--afk`	❌	✅
`--tasks`	❌	✅
`--agent-teams`	❌	✅
`--enable-auto-mode`	❌	✅
`--proactive`	❌	✅
`--brief`	❌	✅
`--assistant`	❌	✅
`--channels`	❌	✅
`--remote-control`	❌	✅
`--hard-fail`	❌	✅

11+ ANT-ONLY 选项。

6.2 ANT-ONLY 组件¶

组件	商业版	ANT 版
`AntModelSwitchCallout`	❌	✅
`UndercoverAutoCallout`	❌	✅
Buddy 桌宠	❌	✅
`AntModelSwitch`	❌	✅

4+ 组件。

7. 3 种 DCE 模式¶

7.1 feature gate + lazy require¶

const x = feature('X') ? require('./X.js') : null

最常见。

7.2 getter 包 require¶

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

循环依赖。

7.3 dynamic import¶

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

async lazy。

8. 完整 feature 列表（推测）¶

类别	Flag	默认（商业版）
AI	COORDINATOR_MODE	false
AI	KAIROS	false
AI	PROACTIVE	false
AI	AGENT_TRIGGERS	false
AI	TRANSCRIPT_CLASSIFIER	false
集成	DIRECT_CONNECT	true
集成	LODESTONE	false
集成	SSH_REMOTE	false
集成	BUDDY	false
集成	VOICE_MODE	false
工具	MCP_SKILLS	false
工具	CHICAGO_MCP	false
工具	WEB_BROWSER_TOOL	false
工具	MESSAGE_ACTIONS	false
工具	BASH_MODE_PROGRESS	false
性能	COMPACTION_REMINDERS	false
性能	HISTORY_SNIP	false
性能	UPLOAD_USER_SETTINGS	false
实验	EXPERIMENTAL_SKILL_SEARCH	false
ANT-ONLY	various	true

19+ flag。

9. 5 个最佳实践¶

编译时字面量 —— 用 "external" === 'ant' 不用 IS_ANT
null 兜底 —— module?.method?.()
类型联合 —— typeof import('./X.js') | null
NOOP stub —— 完整 API 兼容
不在 feature 内嵌套 —— feature(X) && feature(Y)

5 条。

10. 调试¶

# 列出所有 feature
grep "feature('X')" src/ -r

grep。

11. 5 个新增 flag 流程¶

需求 —— 新功能要门控
写 flag —— feature('MY_FEATURE')
lazy require —— require('./my-feature.js')
null 兜底 —— 类型 + 运行时
测试两版 —— 商业版 + 内部版

5 步。

12. 总结¶

Feature flags = 编译时门控 + DCE。

核心： - 25+ flag - 3 种 DCE 模式 - ANT-ONLY 双版本 - 节省 25000+ 行代码

下一步： - 看 dce-deep-dive.md - 看 analysis/dce-dead-code-elimination.md

Feature Flags¶

1. 概览¶

2. 5 个 AI / Agent flag¶

2.1 COORDINATOR_MODE¶

2.2 KAIROS¶

2.3 PROACTIVE¶

2.4 AGENT_TRIGGERS¶

2.5 TRANSCRIPT_CLASSIFIER¶