configure-feature-flags

/configure:feature-flags

使用支持可插拔 Provider 的 OpenFeature 标准检查并配置功能开关基础设施。

何时使用此技能

适用场景……	适用其他方法的场景……
为新项目添加功能开关基础设施	在 YAML 中创建或编辑单个开关定义
使用 Provider（GOFF、flagd、LaunchDarkly）设置 OpenFeature SDK	调试特定开关的评估为何返回意外值
审核现有功能开关配置是否完整	编写使用功能开关的应用逻辑
配置中继代理基础设施（Docker、Kubernetes）	管理 LaunchDarkly 或 Split 控制面板设置
添加功能开关测试辅助工具和内存 Provider	配置错误跟踪（改用 /configure:sentry）

上下文

• Package JSON：!find . -maxdepth 1 -name \'package.json\'
• Python 项目：!find . -maxdepth 1 -name \'pyproject.toml\'
• Go 项目：!find . -maxdepth 1 -name \'go.mod\'
• Cargo 项目：!find . -maxdepth 1 -name \'Cargo.toml\'
• OpenFeature SDK：!find . -maxdepth 1 \( -name package.json -o -name pyproject.toml -o -name Cargo.toml -o -name go.mod \) -exec grep -l 'openfeature' {} +
• GOFF 配置：!find . -maxdepth 2 -name 'flags.goff.yaml' -o -name 'flags.goff.yml'
• Docker Compose：!find . -maxdepth 1 -name 'docker-compose*.yml' -o -name 'docker-compose*.yaml'
• 项目规范：!find . -maxdepth 1 -name \'.project-standards.yaml\'

参数

从 $ARGUMENTS 解析：

• --check-only：报告合规状态，不做修改
• --fix：自动应用所有修复，不提示
• --provider <provider>：覆盖 Provider 检测结果（goff、flagd、launchdarkly、split）

版本检查

重要：配置功能开关之前，使用 WebSearch 或 WebFetch 验证 SDK 和 Provider 的最新版本：

1. OpenFeature JS SDK：查看 npm
2. OpenFeature Python SDK：查看 PyPI
3. GO Feature Flag：查看 GitHub releases
4. flagd：查看 GitHub releases

执行

执行此功能开关配置工作流：

步骤 1：检测项目语言和现有设置

检查现有的功能开关基础设施：

指标	语言	检测到的 Provider
package.json 中包含 @openfeature/server-sdk	Node.js	OpenFeature（检查 Provider）
package.json 中包含 @openfeature/web-sdk	Browser JS	OpenFeature Web
package.json 中包含 @openfeature/react-sdk	React	OpenFeature React
pyproject.toml 中包含 openfeature-sdk	Python	OpenFeature Python
包含 @openfeature/go-feature-flag-provider	Node.js	GO Feature Flag
docker-compose 中包含 go-feature-flag-relay-proxy	任意	GO Feature Flag Relay
docker-compose/k8s 中包含 flagd	任意	flagd Provider

步骤 2：分析当前状态

检查功能开关设置是否完整：

1. 验证项目语言对应的 OpenFeature SDK 已安装
2. 检查 Provider 软件包是否已安装
3. 验证 Provider 是否在应用启动时初始化
4. 检查评估上下文配置
5. 检查 Hook 是否已配置（日志记录、遥测）
6. 对于 GOFF：验证开关配置文件是否存在，以及中继代理是否已配置
7. 对于 flagd：验证容器/服务是否已配置，以及 gRPC/HTTP 端点是否已配置

步骤 3：生成合规报告

打印格式化的合规报告：

Feature Flag Compliance Report
==============================
Project: [name]
Language: [detected]
Provider: [detected or None]

OpenFeature SDK:    [status per check]
Provider Config:    [status per check]
Infrastructure:     [status per check]

Overall: [X issues found]
Recommendations: [list specific fixes]

如果使用了 --check-only，则在此处停止。

步骤 4：安装 SDK 并配置提供程序（如果指定 --fix 或用户确认）

根据检测到的语言，安装并配置 OpenFeature SDK 和所选提供程序。使用 REFERENCE.md 中的代码模板。

1. 安装 OpenFeature SDK 和提供程序包
2. 创建功能标记客户端包装模块
3. 创建评估上下文辅助工具
4. 为 HTTP 框架（Express、FastAPI 等）创建中间件

步骤 5：创建标记配置

创建 flags.goff.yaml，其中包含涵盖常见模式的示例标记：

• 简单布尔标记
• 百分比推出
• 多变体标记（A/B 测试）
• 特定环境的标记
• 特定用户的覆盖项
• 计划推出

使用 REFERENCE.md 中的标记模板。

步骤 6：配置基础设施

1. 为中继代理创建 docker-compose 条目（本地开发）
2. 可选：为生产环境创建 Kubernetes 清单

步骤 7：创建测试配置

使用内存中提供程序创建测试文件，用于功能标记单元测试。

步骤 8：更新标准跟踪

更新 .project-standards.yaml：

components:
  feature_flags: "2025.1"
  feature_flags_sdk: "openfeature"
  feature_flags_provider: "[goff|flagd|launchdarkly]"

步骤 9：打印完成报告

打印所有更改的摘要，包括已安装的 SDK、已配置的提供程序、已创建的标记文件，以及后续步骤（启动中继、在应用中初始化、在代码中使用标记）。

如需了解详细的代码模板、标记配置模式和基础设施清单，请参阅 REFERENCE.md。

Agentic 优化

上下文	命令
快速合规性检查	/configure:feature-flags --check-only
使用 GOFF 提供程序自动修复	/configure:feature-flags --fix --provider goff
验证标记配置	goff lint --file flags.goff.yaml
检查中继代理运行状况	`curl -s http://localhost:1031/health
列出已配置的标记	`curl -s http://localhost:1031/v1/feature/flags
检查 SDK 是否已安装（JS）	`jq -r '.dependencies

标记

标记	说明
--check-only	报告状态，但不提供修复方案
--fix	无需提示，自动应用所有修复
--provider <provider>	覆盖提供程序检测结果（goff、flagd、launchdarkly、split）

示例

# Check compliance and offer fixes
/configure:feature-flags

# Check only, no modifications
/configure:feature-flags --check-only

# Auto-fix with GO Feature Flag provider
/configure:feature-flags --fix --provider goff

# Configure for LaunchDarkly
/configure:feature-flags --fix --provider launchdarkly

错误处理

• 未找到包管理器：无法安装 SDK，请提供手动操作步骤
• 不支持的提供程序：列出支持的提供程序，并建议替代方案
• 中继代理无法访问：检查 Docker/K8s 配置
• 标记语法无效：部署前使用 goff lint 验证

另请参阅

• /configure:all - 运行所有合规性检查
• /configure:sentry - 错误跟踪（常与功能标记搭配使用，以便回滚）
• OpenFeature 文档：https://openfeature.dev
• GO Feature Flag 文档：https://gofeatureflag.org