用途:这个技能用来判断某项工作是否需要功能开关,并规定声明、实现、灰度发布与回滚的完整流程。默认原则是:任何用户能看到的、产品行为发生变化的地方,都要放在功能开关之后,以便不用部署就能关掉;用户察觉不到行为变化的工作直接上线,需要时用普通回滚处理。
主要能力:
- 判断标准:新增或改动的流程、步骤、界面、标签页、选项、设置或工具,默认值变化,用户依赖的功能行为改变或被移除,新增产品区域、引擎、worker,以及对登录、聊天运行、同步、计费、访问控制等核心流程的重写,都需要开关。平台 /admin 页面与管理类 MCP 工具、修复预期行为的缺陷、不改变用户操作的打磨(间距、密度、图标、文案)、重构与内部工具不需要开关。拿不准时加开关;没有开关时,需在 PR 中说明为什么用户看不到行为变化。
- 注册表:在 packages/features/src/registry.ts(包 @openwork/features)中声明,键名使用 lowerCamelCase,且不能有连续大写;字段包括 label、description、category、added、since、author、docs、deployments、default(新功能为 false)等。category 取自注册表顶部的 FEATURE_CATEGORIES。author 为负责人的 GitHub 账号;docs 为仓库 docs/ 下的内部文档路径,可视化功能需附真实应用截图。随后运行 pnpm features:sync 并提交生成的 Helm 文件。
- 解析顺序:所有检查统一由一个函数 resolveFeature 解析,顺序为部署范围(cloud、self_hosted,代码固定)、全局关闭开关(优先级最高,等同于回滚)、运维锁定(Helm 配置 config.features.<key>)、成员覆盖、组织覆盖、全员开关。步骤 2、5、6 可在 /admin 或通过 MCP 工具 den_list_features、den_set_feature_rollout、den_set_org_capability 设置;每次变更都会记入 feature_change 表。/admin 中会显示每位功能成员的开启人数、最近 7 天和 30 天的使用人数以及最后使用时间。
- 代码接入方式:den-api 使用 organizationFeatureEnabled、getOrganizationFeatures 或路由守卫 requireFeature;事务内可传 { database: tx, lock: "share" };Den Web 使用 orgFeatureEnabled;没有组织的已退出登录桌面端读取 GET /v1/features。只有客户端的功能需在真正触发功能的动作处调用 markFeatureUsed;后台任务需在统一入口调用 markFeaturesUsed,并在注册表设置 outcomes: true 且注册读取器。界面被关闭时,按照 DESIGN.md P4 显示带原因的锁定入口。
- 上线流程:先对自己组织开启,再逐个组织开启并检查错误和使用情况,然后在 /admin 全员开启;出现问题时使用全局关闭开关。全员开启后把 default 设为 true,之后删除条目和所有检查;pnpm features:check 会在 since 之后六个月要求做出决定(permanent 条目除外)。评估环境通过 enableOrganizationCapabilities 按组织开启。
限制与禁止事项:不得为产品界面新增 DEN_*_ENABLED 环境变量,不得读写 organization.metadata.capabilities,不得手写 /admin 控件、/v1/org 字段或 Helm 行,不得误将功能发布到自托管环境,不得把仅 /admin 可用的控件放在开关后,不得声明无 author 的功能或无内部文档的新功能。上线前须确认:使用全局关闭开关时,进行中的工作、已存储数据和用户所见都能承受回滚。