launchdarkly-flag-create

LaunchDarkly 功能标志创建与配置

你正在使用一项技能，它会引导你将新功能标志引入代码库。你的工作是探索此代码库中已有的标志使用方式，以符合现状的方式在 LaunchDarkly 中创建标志，添加与现有模式匹配的评估代码，并验证所有内容都已正确接入。

前提条件

此技能要求在你的环境中配置远程托管的 LaunchDarkly MCP 服务。

必需的 MCP 工具：

• create-flag：在项目中创建新功能标志
• get-flag：验证标志已正确创建

可选的 MCP 工具（增强工作流）：

• list-flags：浏览现有标志，以了解命名约定和标签
• update-flag-settings：更新标志元数据（名称、描述、标签、临时/永久状态）

工作流

第 1 步：探索代码库

在创建任何内容之前，先了解此代码库如何使用功能标志。

1. 查找 SDK。 搜索 LaunchDarkly SDK 的导入或初始化：

   • 在导入中查找 launchdarkly、ldclient、ld-client、LDClient
   • 检查 package.json、requirements.txt、go.mod、Gemfile 或等效文件中是否有该 SDK 依赖项
   • 确定正在使用的是哪个 SDK（服务端 Node、React、Python、Go、Java 等）

2. 查找现有的标志评估。 搜索 variation 调用，以了解此代码库使用的模式：

   • 直接调用 SDK：variation()、boolVariation()、useFlags() 等
   • 包装模式：此代码库是否将标志抽象在某个服务或工具之后？
   • 常量定义：标志键是否在某个地方定义为常量？
   • 按语言查看模式，请参阅 SDK Evaluation Patterns

3. 理解约定。 查看现有标志以了解：

   • 命名约定：键是 kebab-case、snake_case，还是 camelCase？
   • 组织方式：标志键是与功能放在一起，还是集中在常量文件中？
   • 默认值：现有评估使用什么默认值？
   • 上下文/用户构造：此代码库如何构建传递给 SDK 的用户/上下文对象？这决定了未来任何定向投放可以使用的上下文种类和属性——并且它因场景而异（服务端、客户端、匿名）。在规划规则、单个目标或发布之前，请参阅 Context Availability。

4. 检查 LaunchDarkly 项目约定。 可选地使用 list-flags 查看现有标志：

   • 常用哪些标签？
   • 标志被标记为临时还是永久？
   • 项目中存在哪些命名模式？

第 2 步：确定正确的标志类型

根据用户的需求，选择适当的标志配置。完整指南请参阅 Flag Types and Patterns。

快速决策：

用户意图	标志类型	变体
“开启/关闭某个功能”	boolean	true / false
“逐步发布某个功能”	boolean	true / false
“在多个选项之间做 A/B 测试”	multivariate（字符串）	用户定义的值
“配置数值阈值”	multivariate（数字）	用户定义的值
“提供不同的配置对象”	multivariate（JSON）	用户定义的值

要应用的默认设置：

• 设置 temporary: true，除非用户明确表示这是永久/长期存在的标志。大多数标志都是发布标志，最终应被清理。
• 如果未提供 key，则根据名称生成一个（例如，“New Checkout Flow” -> new-checkout-flow），但如果代码库已有命名约定，则与之匹配。
• 根据用户提到的功能领域、团队或上下文，建议相关标签。

步骤 3：在 LaunchDarkly 中创建 Flag

使用 create-flag，并采用步骤 2 中确定的配置。

创建后：

• 该 flag 在所有环境中创建时均为 targeting OFF。
• 在开启 targeting 之前，该 flag 会向所有人提供 offVariation。
• 提醒用户，他们需要使用 flag targeting skill 将其开启，并可选择设置 rollout 规则。

步骤 4：将 Flag 评估添加到代码中

现在添加用于评估该 flag 的代码，并匹配你在步骤 1 中找到的模式。

1. 使用代码库已有的相同 SDK 模式。 如果存在 wrapper，就使用该 wrapper。如果存在 constants，就将新 key 添加到 constants 文件中。
2. 使用合适的默认值。 代码中的默认（fallback）值应为“安全”行为：通常是引入 flag 之前的现有行为。这可确保 SDK 无法连接到 LaunchDarkly 时该功能保持关闭。
3. 添加条件逻辑。 将新行为包裹在 flag 检查中。
4. 处理两个分支。 确保每个 variation 的代码路径都清晰且完整。

有关按语言和框架划分的实现示例，请参见 SDK Evaluation Patterns。

步骤 5：验证

确认该 flag 已正确设置：

1. 代码可编译/通过 lint。 运行项目的 build 或 lint 步骤。
2. Flag 存在于 LaunchDarkly 中。 使用 get-flag 确认它已使用正确的配置创建。
3. 两个代码路径都正常。 flag-off 路径保留现有行为；flag-on 路径启用新功能。
4. 默认值是安全的。 如果 LaunchDarkly 无法访问，代码会回退到默认值：确保这是现有的/安全的行为。

更新 Flag 设置

如果用户想要更改 flag 元数据（而非 targeting），请使用 update-flag-settings。支持的更改：

更改	指令
重命名	{kind: "updateName", value: "New Name"}
更新描述	{kind: "updateDescription", value: "New description"}
添加 tag	{kind: "addTags", values: ["tag1", "tag2"]}
移除 tag	{kind: "removeTags", values: ["old-tag"]}
标记为临时	{kind: "markTemporary"}
标记为永久	{kind: "markPermanent"}

多个指令可以在单次调用中批量执行。这些更改是项目级别的，而非环境特定的。

重要： 元数据更新（上文）与 targeting 更改（toggle、rollout、rules）是分开的。如果用户想要更改谁看到什么，请引导他们前往 flag targeting skill。

重要背景

• Flag key 不可变。 一旦创建，flag 的 key 就无法更改。请谨慎选择。
• Flag 初始为 OFF。 创建 flag 从不会启用它。这是一项安全特性。
• 代码中的默认值是你的安全网。 当 SDK 无法连接到 LaunchDarkly 时，提供的正是这个值。始终使用“安全”/现有行为作为默认值。
• 遵循现有代码库约定。 最常见的错误是引入与团队既有做法不匹配的 flag 模式。步骤 1 的存在就是为了防止这一点。

参考

• Flag Types and Patterns：Boolean 与 multivariate、命名约定、配置最佳实践
• SDK Evaluation Patterns：如何在每个 SDK 中评估 flag，包括常见 wrapper 模式
• Context Availability：targeting 可以使用哪些 context 类型/属性，并与读取该 flag 的界面相匹配（当该 flag 将进行 targeting，而不是作为简单的 on/off 开关时，这一点很有用）