Feature Flags 路线图

OMO 扩展说明：本文描述的 Feature Flags 系统（89 个 Flags、opencode flags list 命令、feature_flags 配置字段）是 oh-my-openagent (OMO) 对 OpenCode 的扩展增强。原生 OpenCode 不包含 Feature Flags 系统。OMO 版本 v4.13.x，OpenCode 版本 v1.17.x。

OMO 89 个 Feature Flag 不是随机的功能列表，它是产品迭代的仪表盘——告诉你哪些能力已经就绪、哪些正在开发、哪些即将到来。 适合读者: 技术负责人 · 架构师

文章概述

Feature Flag（功能开关 / Feature Toggle）是一种渐进式交付机制。新功能以 Flag 形式隐藏在代码中，按需开启或关闭，而不是等到全部开发完成才一次发布。OMO（oh-my-openagent）拥有 89 个 Feature Flag，覆盖 Agent（智能体） 能力、安全策略、性能优化、集成生态和用户体验五大领域。理解这些 Flags 的当前状态和演进方向，就是读懂产品的迭代路线图。

本文首先介绍 Feature Flag 机制的工作原理——什么是 Feature Flag，为什么 OMO 需要 89 个 Flags（模块化设计 + 渐进式发布 + A/B 测试），以及 Flag 的完整生命周期。然后按领域分类讲解 Flags 的路线图：Agent 类、安全类、性能类、集成类、体验类。接着介绍如何查看当前 Flags 的状态、如何配置 Flags 的开启和关闭，以及如何参与社区讨论影响 Flags 的优先级。最后通过一个完整的 Flag 启用流程示例，帮助读者理解从发现到启用的实操步骤，并说明 Flag 的版本演进和废弃机制。读完本文，你将能够理解 OMO 的 89 个 Feature Flag 布局、按需启用新功能并参与社区影响产品迭代方向。

⏱ 时间有限？先读这些： Flag 机制 → 路线图概览 → 按领域分类 → 配置方法

内容要点

1. Feature Flag 机制 — 什么是 Feature Flag（功能开关），OMO 为什么需要 89 个 Flag（模块化架构 + 渐进式发布 + 灰度实验），Flag 的生命周期（开发中、实验性、稳定版、废弃）。

2. 路线图概览 — 按领域分类展示 Flags 的当前状态：已实现（可直接使用）、开发中（即将发布）、计划中（路线图规划）。Flag 的版本分布和预期发布时间线。

3. 按领域分类 — 五大领域 Flags 的详细介绍：Agent 类（新的编排模式、Agent 派生类型、路由策略）、安全类（新增权限模式、隔离策略、注入防御）、性能类（缓存优化、压缩算法、并行策略）、集成类（新 MCP 协议支持、Plugin（插件） 扩展点）、体验类（交互改进、日志增强、调试工具）。

4. 如何跟进 — 查看当前 Flags 的方法（命令行或配置查看），配置 Flags（按项目或全局启用/禁用），A/B 测试策略（不同团队使用不同 Flag 配置），参与社区决策（Issue 讨论、投票影响优先级）。包含一个完整的 Flag 从发现到启用的操作流程。说明 Flag 的版本演进和废弃机制（标记为废弃到最终移除的周期）。

Feature Flag 机制

什么是 Feature Flag

Feature Flag 是一个条件开关，控制特定功能是否在运行时生效。最简单的实现是一个布尔值：

{
  "feature_flags": {
    "agent_parallel_orchestration": true,
    "sandbox_enhanced_isolation": false
  }
}

当 agent_parallel_orchestration 为 true 时，Agent 调度器使用新的并行编排模式；否则回退到默认的串行模式。Flag 的改变不需要重新部署，修改配置后下次会话生效。

为什么需要 89 个 Flag

你可能觉得 89 个 Flag 太多。但这不是随意堆出来的数字，而是三个需求共同作用的结果。

模块化架构。OpenCode 的功能模块是高度解耦的——Agent 引擎、安全沙箱、缓存层、MCP（模型上下文协议） 集成、日志系统……每个模块都有自己的演进节奏。给每个独立能力配一个专属 Flag，意味着团队可以独立测试和发布各个模块的改进，而不需要等所有模块同步就绪。

渐进式发布。新功能不应该是“一把梭“式的发布。先在小范围验证，确认稳定后再逐步开放。Flag 让这个过程可控制、可回滚。一个高风险新功能可能在 v0.5 就进入代码库，但被 Flag 关闭着，直到 v0.8 才默认开启。

A/B 测试。同一个功能可能有多个实现方案。比如 Agent 的路由策略，可以用最短路径优先，也可以用历史成功率加权。通过 Flag 配置，不同团队可以使用不同的策略，实际对比效果后再决定哪个方案胜出。

这三个需求叠加，89 个 Flag 不是太多，而是刚刚好。

Flag 的生命周期

每个 Feature Flag 都经历四个阶段：

in-development（开发中）。功能正在实现，Flag 默认关闭。只有开发者自己和参与测试的早期用户会开启它。这个阶段的 Flag 可能随时改动，不保证稳定性。

experimental（实验性）。功能基本可用，Flag 默认关闭，但可以通过配置手动开启。这个阶段的 Flag 已经通过了基本的单元测试和集成测试，但在真实场景中的表现还需要更多验证。文档可能还不完整。

stable（稳定版）。功能经过充分验证，Flag 默认开启。生产环境推荐使用。这个阶段的 Flag 有完善的文档、测试覆盖和错误处理。除非发现严重问题，否则行为不会变化。

deprecated（废弃）。功能有了更好的替代方案，Flag 被标记为废弃。默认值可能保持不变，但在后续的某个大版本中会被移除。配置工具会在检测到废弃 Flag 时给出警告，引导用户迁移到替代方案。

stateDiagram-v2
    [*] --> in_development: 新功能立项
    in_development --> experimental: 基础验证通过
    experimental --> stable: 生产验证通过
    stable --> deprecated: 出现更优替代
    deprecated --> [*]: 大版本移除
    experimental --> [*]: 验证失败，取消
    stable --> experimental: 重构需要重新验证
    deprecated --> stable: 替代方案未达预期，回退

    note right of in_development: 默认关闭
    note right of experimental: 默认关闭，可手动开启
    note right of stable: 默认开启
    note right of deprecated: 警告提示，引导迁移

这个状态机中有两条重要的回退路径。stable → experimental 说明即使是稳定功能，如果引入了重大重构，也会降级回实验阶段重新验证。deprecated → stable 说明如果替代方案没达到预期，废弃的 Flag 可以被救回。版本不是单向的陡坡，一切以实际效果为准。

按领域分类

89 个 Feature Flag 分布在五个领域。以下是完整的分类关系：

mindmap
  root((Feature Flags<br/>89 total))
    Agent 类
      编排模式
      Agent 派生类型
      路由策略
      上下文聚合
      任务调度
    Security 类
      权限模式
      隔离策略
      注入防御
      Secret 管理
      审计日志
    Performance 类
      缓存优化
      压缩算法
      并行策略
      预加载
      GC 策略
    Integration 类
      MCP 协议
      Plugin 扩展
      Tool 注册
      Transport 层
    Experience 类
      交互改进
      日志增强
      调试工具
      通知系统
      CLI 改进

每个领域的 Flags 数量和成熟度不同，反映了产品在不同阶段的侧重点。

Agent 类（28 Flags）

Security 类（18 Flags）

Performance 类（16 Flags）

Integration 类（15 Flags）

Experience 类（12 Flags）

路线图概览

版本分布

Feature Flags 随 OpenCode 版本迭代逐步开放。以下是在各版本中的分布概览：

gantt
    title Feature Flag 版本分布与预计发布时间
    dateFormat  YYYY-MM
    axisFormat  %Y-%m

    section Agent 类 (28)
    并行编排          :done, a1, 2025-09, 2026-01
    Agent 派生 (8)    :active, a2, 2025-11, 2026-06
    路由策略 (6)      :done, a3, 2025-08, 2026-02
    上下文聚合        :active, a4, 2026-01, 2026-05
    任务调度          :a5, 2026-04, 2026-09

    section Security 类 (18)
    权限模式          :done, s1, 2025-07, 2026-01
    隔离策略          :active, s2, 2025-10, 2026-04
    注入防御          :active, s3, 2025-12, 2026-06
    Secret 管理       :s4, 2026-03, 2026-08
    审计日志          :s5, 2026-05, 2026-09

    section Performance 类 (16)
    缓存优化          :done, p1, 2025-06, 2025-12
    压缩算法          :active, p2, 2025-10, 2026-03
    并行策略          :active, p3, 2025-11, 2026-04
    预加载            :p4, 2026-03, 2026-07

    section Integration 类 (15)
    MCP 协议          :active, i1, 2025-09, 2026-03
    Plugin 扩展       :active, i2, 2025-11, 2026-05
    Tool 注册         :done, i3, 2025-08, 2026-01

    section Experience 类 (12)
    交互改进          :done, e1, 2025-08, 2026-02
    日志增强          :active, e2, 2025-12, 2026-04
    调试工具          :active, e3, 2026-01, 2026-06
    通知系统          :e4, 2026-04, 2026-06

当前状态一览

截至 OMO v4.5.0，89 个 Feature Flag 的状态分布：

已实现的 Flags 可以直接在生产环境中使用。实验性的 Flags 适合想尝鲜的团队——风险可控，功能基本可用，但文档和边界情况处理可能不够完善。开发中的 Flags 你可以参与讨论，你的反馈会影响它们的最终设计。已规划的 Flags 是下一阶段的重点，社区投票会决定它们的优先级。

预期发布时间线

所有时间线都基于当前规划的版本节奏估算。OpenCode 采用滚动发布模式，大约每 6-8 周一个版本：

• OMO v4.5.x（已发布）：31 个 experimental Flags 可用，24 个 stable
• OMO v4.6.x（已发布）：新增约 8 个 Flags，3 个 experimental 升级为 stable
• OMO v4.13.x（当前）：新增约 10 个 Flags，5 个 experimental 升级为 stable
• OMO v5.0（预计 Q4 2026）：规划中 Flags 基本完成，首个大版本

如何跟进

Feature Flags 的意义不在于“我知道有这个功能“，而在于“我知道怎么用、什么时候用、怎么参与它的演进“。

查看当前 Flags

方式一：命令行

opencode flags list

输出示例（简化）：

  AGENT (28)               SECURITY (18)           PERFORMANCE (16)
  ✔ agent_parallel_...     ✔ perm_least_priv...    ✔ cache_multi_level
  ✔ agent_tester           ✗ perm_approval_...     ✗ compress_token_...
  ✗ agent_documenter       ✗ defense_context_...   ✔ parallel_agent_...

支持过滤：opencode flags list --domain security（按领域）、--status experimental（按状态）、--since OMO v4.5.x（按版本）。详细信息用 opencode flags show --name <flag> 查看，输出包含 Domain/Status/Introduced/Description/Deprecates/ReplacedBy 和对应的 GitHub Issue 链接。

配置 Flags

通过 opencode.json 配置（全局）或 .opencode/config.json（项目级覆盖），也支持环境变量 OPENCODE_FEATURE_FLAGS 临时覆盖（优先级最高）。例如：

// opencode.json 全局开启
{ "feature_flags": { "agent_parallel_orchestration": true } }

# 环境变量临时覆盖
OPENCODE_FEATURE_FLAGS='{"agent_parallel_orchestration":true}' opencode run

A/B 测试策略

对比不同 Flag 组合的效果：在配置中定义实验组（control/treatment），观察一周后对比平均响应时间、成功率和 Token 消耗。例如路由策略 A/B 测试——A 组用 route_shortest_queue，B 组用 route_success_rate。

// 完整 experiments 配置示例见 opencode.json experiments 字段

参与社区决策

每个 Flag 有对应的 GitHub Issue（标签 flag/[domain]/[flag-name]）。用 +1 投票影响优先级——每季度前 5 名自动进入下一开发周期。design-discussion 阶段公开征求意见，是影响 Flag 行为的最佳时机。如需新 Flag，用模板 flag-proposal 提交 Issue。

完整操作流程

以启用 agent_parallel_orchestration 为例：

1. 确认状态：opencode flags show --name agent_parallel_orchestration → experimental，OMO v4.5.x+
2. 了解限制：见 Issue #892——不支持嵌套并行，默认并发数 4，依赖外部服务的工具不适合并行
3. 本地启用：在配置中添加 "agent_parallel_orchestration": true
4. 验证效果：对比开启前后 opencode run --task ... --duration --measure 的结果
5. 观察回退：异常时关闭 Flag 即可，无需重新部署
6. 参与反馈：在 Issue 中回复使用体验，直接影响何时进入 stable

废弃机制

Flag 标记 deprecated 后的生命周期：运行时警告（3 个版本）→ 默认值变更（2 个版本）→ 代码移除（1 个版本）→ 配置解析器不再识别。整个过程约 6-9 个月。opencode flags list --status deprecated 查看废弃 Flags，配置工具会提示替代方案和迁移指引。

常见反模式

打开所有实验性 Flag

现象：看到 31 个 experimental Flags，觉得“新的就是好的“，全部打开。

原因：想“体验所有新功能“，忽略了实验性 Flag 可能不稳定、不完全或有冲突。

对策：一次只启用 1-2 个实验性 Flag，观察一周后再考虑添加。启用前阅读对应 Issue 了解限制和已知问题。启用后如果遇到异常行为，先关闭最近打开的 Flag 确认是否由它引起。

从不参与社区反馈

现象：使用了实验性 Flag 后遇到问题或有不满意的地方，只是在本地换回老配置，不在对应 Issue 中反馈。

原因：认为“反馈了也没用“或“没时间“。

对策：每个 Flag 在 experimental 阶段的设计决策高度依赖社区反馈。你的使用体验和意见直接影响该 Flag 何时进入 stable。哪怕只是一个“我用了一周，遇到两个问题“的简单回复，对开发团队都有价值。

Flags 配置与文档脱节

现象：配置文件中启用了某些 Flag，但团队成员之间没有同步，文档中也没有记录。新成员加入后不知道哪些 Flag 已经启用、为什么启用。

原因：认为“Flag 配置是私人的事情“。

对策：将 Feature Flag 的启用决策记录在项目文档中。在 AGENTS.md 中说明哪些 Flag 已启用及其目的。定期审查启用的 Flag 列表，关闭不再需要的。新增启用时通知团队。

常见错误与陷阱

生产环境启用未经验证的实验性 Flag

场景：在线上生产环境中启用了 agent_parallel_orchestration（experimental）而没有先在预发布环境做充分测试。

后果：并行编排引入了竞态条件，导致 Agent 任务完成率从 95% 骤降到 70%。

预防：实验性 Flag 使用前必须在非生产环境验证一周以上。对比开启前后的关键指标（任务完成率、平均延迟、Token 消耗）。通过 A/B 测试方式逐步放量。

Flag 废弃后未迁移

场景：Flag 被标记为 deprecated 并提示了替代方案，但配置文件中的旧 Flag 一直没有更新。

后果：运行了 6 个版本后，旧 Flag 的代码被移除，OpenCode 启动时报错“未识别的配置项“，配置解析失败。

预防：查看 opencode flags list --status deprecated 获取废弃列表。每个版本升级时检查配置文件中的 Flag 是否需要更新。配置测试流程中包括 Flag 兼容性检查。

环境变量 Flags 遗忘在 Shell 配置中

场景：为了临时测试某个 Flag，在 ~/.zshrc 中设置了 OPENCODE_FEATURE_FLAGS='{"flag_name":true}'。

后果：两个月后大家都忘了这个环境变量，所有会话都受影响。排查问题时找不到根因，因为很少有人检查 Shell 配置中的环境变量。

预防：环境变量只用于临时测试（当次 Session）。确定要使用后，将 Flag 配置写入 opencode.json。定期审查 Shell 配置中的 OpenCode 相关环境变量。

适用场景与限制

Feature Flag 的最佳场景

• 需要渐进式发布新功能的团队
• 需要在不同环境中使用不同功能组合的场景（开发环境开启 debug Flag，生产环境只开 stable Flag）
• 希望参与产品演进方向、提前尝鲜的社区用户

Feature Flag 的局限

• Flag 配置增加了复杂度：89 个 Flag 意味着 89 个配置决策，每个决策都有潜在影响
• 实验性 Flag 可能被取消：不是所有 experimental Flag 最终都会进入 stable，有些可能因技术原因取消
• Flag 的影响范围可能不明确：某些 Flag 的文档不够详细，启用后可能产生未预期的影响

什么时候不需要 Feature Flag

如果你是个人用户、不需要尝鲜新功能、当前配置已经满足需求，完全可以只使用 stable Flag。Feature Flag 系统的设计兼顾了“激进尝鲜“和“保守稳定“两种模式。

关联章节

• ← 性能调优与成本管理（性能优化相关的 Flags 详解）
• ← 沙箱与 Hook 系统（安全类 Flags 的执行机制）
• ← 上下文压缩与Token 预算（压缩算法 Flags 的技术背景）
• → 全书

验证标准

完成本文学习后，你应该能：

1. 解释 OpenCode 的三种 Flag 类型（stable/beta/experimental）及其风险等级差异
2. 在配置中启用或禁用一个 Feature Flag，并说明其对应的行为变化
3. 描述 Flag 从实验阶段到废弃的完整生命周期（deprecated → 默认值变更 → 代码移除）
4. 使用 opencode flags list 命令按领域或状态筛选 Flag
5. 设计一个分阶段灰度发布策略，利用 Flag 控制新功能的逐步放量