launchdarkly-flag-targeting

LaunchDarkly 功能标志定向与发布

你正在使用一项技能，它将引导你更改功能标志中谁能看到什么内容。你的任务是了解该标志的当前状态，为用户的需求确定合适的定向方式，安全地进行更改，并验证更改后的状态。

前提条件

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

必需的 MCP 工具：

• get-flag：在更改前了解当前状态
• toggle-flag：在某个环境中开启或关闭某个标志的定向
• update-rollout：更改默认规则（fallthrough）的变体或百分比发布
• update-targeting-rules：添加、删除或修改自定义定向规则
• update-individual-targets：在单独定向中添加或删除特定用户/上下文

可选的 MCP 工具：

• copy-flag-config：将定向配置从一个环境复制到另一个环境
• create-approval-request：当直接更改被阻止时创建审批请求
• list-approval-requests：查看某个标志的待处理审批请求
• apply-approval-request：应用已批准的审批请求

核心概念：评估顺序

在进行任何定向更改之前，请了解 LaunchDarkly 如何评估标志。这决定了你的更改实际会产生什么效果：

1. 标志为 OFF -> 向所有人提供 offVariation。其他一切都不重要。
2. 单独定向 -> 如果上下文匹配特定的目标列表，则提供该变体。优先级最高。
3. 自定义规则 -> 从上到下评估规则。第一个匹配的规则胜出。
4. 默认规则（fallthrough） -> 如果其他规则都不匹配，则提供此变体或发布。

这意味着：如果你添加了一条定向规则，但标志为 OFF，那么没有人会看到这一更改。如果你在默认规则上设置了百分比发布，但存在单独定向，那么该定向用户会绕过发布。

工作流

步骤 1：了解当前状态

在更改任何内容之前，先检查已经配置了什么。

1. 确认环境。 未指定环境的“把它打开”是有歧义的。始终确认用户指的是哪个环境。默认做法是询问，而不是假设。
2. 获取标志。 使用 get-flag 并指定目标环境，以查看：
   • on：定向当前是否已启用？
   • fallthrough：默认规则是什么？（变体或百分比发布）
   • offVariation：标志关闭时提供什么？
   • rules：是否有任何自定义定向规则？
   • targets：是否有任何单独定向的用户/上下文？
   • prerequisites：它是否依赖任何标志？
3. 评估复杂性。 没有规则也没有单独定向的标志很简单。具有多条规则、目标和前提条件的标志则需要更加谨慎。

第 2 步：确定合适的方案

根据用户的需求和你发现的情况，选择正确的工具和策略。完整参考见定向模式。

常见场景：

用户想要	工具	说明
“打开它”	toggle-flag 配合 on: true	最简单的改动
“关闭它”	toggle-flag 配合 on: false	向所有人提供 offVariation
“按 X% 逐步发布”	update-rollout 配合 rolloutType: "percentage"	权重之和必须为 100
“为 beta 用户启用”	update-targeting-rules：添加一条带子句的规则	规则内部为 AND，规则之间为 OR
“添加特定用户”	update-individual-targets	优先级最高，会覆盖所有规则

在编写规则、单个定向目标或百分比发布之前，请确认上下文支持它。 如果一条规则引用的上下文类型或属性不在标志的评估中携带，它将静默地永不匹配；单个定向目标匹配的是上下文键，而不是像 email 这样的属性；而发布只能按标志读取处存在的类型进行分桶。参见上下文可用性来选择一个真正会触发的上下文。 | “全量发布” | update-rollout 配合 rolloutType: "variation" | 向所有人提供同一个变体 | | “从 staging 复制” | copy-flag-config | 将经过测试的配置提升到生产环境 |

第 3 步：运行安全检查清单

在应用更改之前，尤其是在生产环境中，请逐项运行安全检查清单。关键检查项：

1. 环境正确吗？ 再次确认你定位的是预期的环境。
2. 需要审批吗？ 某些环境需要审批工作流。如果任何变更工具返回 requiresApproval: true：
   • 告知用户该环境需要审批。
   • 如果提供了 approvalUrl，请分享它。
   • 主动提出使用 create-approval-request 以相同的说明（在响应的 instructions 字段中返回）创建审批请求。
   • 不要尝试绕过审批或自动审批。
   • 完整流程见审批工作流。
3. 有前置标志吗？ 如果此标志有前置条件，必须先满足它们，定向才能按预期工作。
4. 规则顺序有影响吗？ 如果添加规则，请考虑它们在评估顺序中的位置。规则自上而下评估，第一个匹配的生效。
5. 添加注释。 始终添加审计追踪注释，尤其是对生产环境的更改。

第 4 步：应用更改

使用合适的工具进行更改。关键说明：

• toggle-flag：指定 on: true 或 on: false、env 以及 comment。
• update-rollout：使用 rolloutType: "percentage" 并搭配人类友好的权重（例如，80 表示 80%），权重之和为 100；或使用 rolloutType: "variation" 并搭配 variationIndex。
• update-targeting-rules：说明支持 addRule、removeRule、updateRuleVariationOrRollout、addClauses、removeClauses、reorderRules。
• update-individual-targets：说明支持 addTargets、removeTargets、addContextTargets、removeContextTargets、replaceTargets。

详细的说明示例见定向模式。

第 5 步：验证

应用更改后，确认结果：

1. 获取更新后的标志。 再次使用 get-flag 来验证新状态。
2. 确认是否符合用户的预期。 用通俗的语言描述最终的定向结果：
   • “该标志现在在生产环境中为 ON，向 25% 的用户提供 true，向 75% 的用户提供 false。”
   • “beta 用户现在看到变体 A。其他所有人获得默认值（变体 B）。”
3. 检查副作用。 如果存在规则或单个定向目标，请确保更改与它们正确交互。

处理需要审批的环境

当任何变更工具返回 requiresApproval: true 时，直接更改已被阻止，因为该环境需要审批。请遵循 审批工作流 参考文档：

1. 创建审批请求：使用 create-approval-request，并传入被阻止响应中的 instructions
2. 告知用户待处理的审批，并分享审批请求详情
3. 稍后检查审批状态：如有需要，使用 list-approval-requests
4. 应用请求：一旦审批人批准（reviewStatus 为 "approved"），使用 apply-approval-request
5. 验证结果：应用后使用 get-flag 进行验证

重要背景

• update-rollout 使用人类友好的百分比。 传递 80 表示 80%，而不是 80000。该工具会处理内部权重转换。
• 权重之和必须为 100。 对于百分比发布，所有变体的权重总和必须正好为 100。
• 规则顺序很重要。 规则从上到下评估。重新排序规则可能会改变行为，而不会改变任何单个规则。
• 单个目标具有最高优先级。 它们会覆盖所有规则和默认值。将某人添加为单个目标意味着规则不适用于他们。
• "Launched" 标志仍处于开启状态。 状态为 "launched" 的标志正在向所有人提供单个变体。如果你想移除该标志，请使用 cleanup skill，而不是更改定位。

参考

• 定位模式：发布策略、规则构建、单个定位以及跨环境复制
• 上下文可用性：规则、目标或发布可以使用哪些上下文类型/属性——将类型与读取标志的界面匹配、key 与 attribute 的区别，以及发布分桶
• 安全检查清单：变更前验证、审批工作流、环境感知
• 审批工作流：创建、检查和申请审批请求