分类 Feature Flag 与按需启用

分类 Feature Flag 与按需启用

学习目标

本章分析 Chrome DevTools MCP 的分类 Feature Flag 系统。你将理解：

• ToolCategory 枚举与 OFF_BY_DEFAULT_CATEGORIES 的设计
• categoryFlag 自动生成与 CLI 参数映射
• 工具注册时（非运行时）的启用检查逻辑
• 实验性功能的 condition 检查
• 用户体验：如何构造包含具体启用命令的错误信息

前置知识

• Feature Flag 策略 — Feature Flag 的分类与演进

---

项目实践

工具分类枚举

enum ToolCategory {
  INPUT = 'input',           // 输入自动化（点击、填写等）
  NAVIGATION = 'navigation', // 导航（页面管理）
  EMULATION = 'emulation',   // 设备模拟
  PERFORMANCE = 'performance', // 性能分析
  NETWORK = 'network',       // 网络调试
  DEBUGGING = 'debugging',   // 通用调试
  EXTENSIONS = 'extensions', // Chrome 扩展（默认关闭）
  THIRD_PARTY = 'experimentalThirdParty', // 第三方工具（默认关闭）
  MEMORY = 'memory',         // 内存检测
  WEBMCP = 'experimentalWebmcp', // WebMCP（默认关闭）
}

默认关闭的分类：

const OFF_BY_DEFAULT_CATEGORIES = [
  ToolCategory.EXTENSIONS,       // 仅 pipe 连接支持
  ToolCategory.THIRD_PARTY,      // 页面暴露的自定义工具
  ToolCategory.WEBMCP,           // 需要 Chrome 149+
];

这些分类默认关闭的原因：

• 依赖特定连接模式（extensions 需要 pipe）
• 需要特定 Chrome 版本（webmcp 需要 149+）
• 实验性功能，稳定性未验证

Flag 自动生成

function buildFlag(category: ToolCategory): string {
  return `category${category.charAt(0).toUpperCase() + category.slice(1)}`;
}
// Input → categoryInput
// performance → categoryPerformance
// experimentalThirdParty → categoryExperimentalThirdParty

CLI 参数如 --categoryExtensions=true 自动映射到 serverArgs.categoryExtensions。

启用检查流程

getToolStatusInfo(tool, serverArgs):
  ↓
1. 检查 tool.category 是否在 OFF_BY_DEFAULT_CATEGORIES
   ├─ 是 → 检查 flagValue 是否为 true
   │  └─ 未启用 → { disabled: true, reason: "Enable it by running..." }
   │
2. 检查 tool.annotations.conditions[]
   ├─ 每个 condition 检查 serverArgs[condition]
   │  └─ 未满足 → { disabled: true, reason: "requires experimental feature..." }
   │
3. 全部通过 → { disabled: false }

注册时检查（非运行时）

在 ToolHandler 构造函数中：

this.shouldRegister = !(disabled && !serverArgs.viaCli);

• MCP Server 模式：禁用的工具不会注册到 McpServer，Agent 看不到这些工具
• CLI 模式（viaCli: true）：即使禁用也注册，但执行时返回错误提示

这种双重行为确保：

• MCP Client 的工具列表简洁（不显示不可用的工具）
• CLI 用户能看到所有工具并获得启用提示

用户体验：友好的错误信息

Tool install_extension is in category Extensions which is currently disabled.
Enable it by running chrome-devtools start --categoryExtensions=true.
For more information check the README.

错误信息包含三个要素：

1. 原因：哪个分类未启用
2. 修复命令：具体的 CLI 参数
3. 参考链接：README

设计取舍

取舍	选择	原因
注册时隐藏 vs 运行时返回错误	两者结合	MCP 隐藏保持列表简洁，CLI 保留获得提示
全局 Flag vs 工具级别 Flag	分类级 Flag	批量管理，不需要为每个工具单独配置
环境变量 vs CLI 参数	CLI 参数	明确的启动配置，而非隐式环境状态

陷阱与对策

陷阱	后果	对策
Flag 命名不一致	CLI 参数与代码不匹配	buildFlag() 自动生成，避免手拼字符串
新分类忘记添加到 OFF_BY_DEFAULT	默认启用可能不稳定的功能	OFF_BY_DEFAULT_CATEGORIES 显式声明
条件检查遗漏	实验性工具在不可用时注册	getToolStatusInfo 统一检查

参考来源

• Chrome DevTools MCP Categories 源码
• Feature Flags 最佳实践