flag-release

记录标志的自动发布

你正在使用一项技能：它针对一个已存在的功能标志（创建时为关闭状态），该标志用于控制某个拉取请求的变更，并记录一次自动推出，以便 PR 合并后安全发布变更——无需人工切换标志。它会根据环境分别遵循团队的发布策略，并尊重任何由人明确表达的发布意图。

这是 PR 标志工作流中的发布步骤，并且有意设计为原子操作：

步骤	负责方
决定是否使用标志	should-flag-change（提供建议）
创建标志并接入代码	launchdarkly-flag-create
记录发布	此技能

运行此技能时，标志已存在（处于关闭状态），且保护代码已接入并推送。此技能只记录推出操作——绝不会创建标志或修改代码。它可以由自动化框架直接驱动，也可以作为 flag-and-release-change 编排器的最后一步。

部署不等于发布。 合并会交付控制路径（标志处于关闭状态）；发布则是此推出操作随后执行的标志操作，并受环境策略控制。

正确处理暂停是必须做到的一点。 没有“暂停”发布类型，而且 policy 不是人工关卡。合并时，policy 会自动按照环境的发布策略执行发布（立即、渐进式或受保护），无需人工晋级步骤——即使是受保护的推出，也会在 PR 合并的那一刻自动启动。因此，将暂停的环境记录为 policy 并不会暂停该环境；它会在合并时发布，早于任何 notBefore 日期。暂停环境的唯一方式是将其完全排除在 environments 数组之外，这样该环境中的标志就会保持关闭。如果用户希望暂停某个环境（或直到某个日期才发布），请在调用中排除该环境，并报告它处于暂停状态。如有疑问，请排除。

前提条件

• 远程托管的 LaunchDarkly MCP 服务。
• 用于保护变更的标志已在 LaunchDarkly 中创建，初始状态为关闭，并带有约定的键和标签。
• 拉取请求引用（repoFullName + prNumber，或 prUrl），以便将推出与正确的合并绑定。

此技能使用的 MCP 工具：

• create-automated-rollout-config — 为该标志针对 PR 记录推出配置（交付内容）
• match-release-policies — 确定各环境适用的发布策略（提出计划前调用）
• list-release-policies — 查看项目的发布策略及其自动附加的指标
• get-flag — 确认标志存在且处于关闭状态，然后再进行记录

完整的发布模型——simple 与 policy、优先级、预览、前提条件、指标充分性：references/auto-release.md。

规划阶段

此阶段不记录任何内容。

1. 确认标志。 使用 get-flag 确认保护标志存在且处于关闭状态。如果尚不存在，请停止——创建标志是 launchdarkly-flag-create 的工作，而为缺失的标志记录发布会令人困惑地失败。
2. 选择目标环境。 使用用户或执行框架指定的环境。不要硬编码一组环境——某项变更不一定总能发布到所有环境。如果未指定任何环境，请列出项目实际使用的键，并确认环境集合，而不是自行假设。
3. 预览各环境的策略。 按 flagKey 和 environmentKey 调用 match-release-policies，确定性地解析每个环境中 policy 发布将执行的操作——winningReleaseMethod（immediate / progressive / guarded / none）。不要手动推断策略的适用范围。对于 guarded 获胜策略，请检查自动附加的指标是否确实能衡量此次变更（参见 references/auto-release.md 中的指标适用性说明）。
4. 了解用户的发布意图。 简要询问（如果尚未说明）：在合并时发布、暂缓（已记录但尚未发布），还是等到 notBefore 日期再发布？是否要先面向某个群组/细分群体？是否有一个此变更不得早于其启用的前置父标志？发布意图的优先级高于策略，并且必须得到遵循或明确暂缓——绝不能悄然忽略。
5. 展示各环境的计划并停止。 对每个环境，说明记录时将使用的 releaseType（simple / policy，以及合并时会执行什么操作），或说明该环境将被暂缓——从记录的配置中省略，使该标志在该环境保持关闭——并给出原因。等待确认，并根据反馈修改计划。

实施阶段

仅在确认后：

1. 将每个目标环境准确归入一个类别——RELEASE 或 HOLD。 在构建调用前完成此操作。没有第三个类别，releaseType 也不会创建第三个类别。

   类别	含义	调用中的处理方式
   RELEASE	合并后上线——立即上线，或按其策略上线	将 { environmentKey, releaseType } 添加到 environments 数组
   HOLD	暂不——等待日期、签核、细分群体或父级标志	不添加任何内容。 完全不将其放入 environments；在报告中注明其处于保留状态

   releaseType（simple 与 policy）只决定 RELEASE 环境如何上线——它永远不会让环境处于保留状态。两者都会在合并时上线：simple 会立即提供 true；policy 会自动运行该环境的策略（立即／渐进／受保护），无需人工晋级步骤。“policy 会遵循策略”——不是遵循你的决定，也不是等到某个日期。不要使用 policy 来暂缓某个环境：它会在合并时发布该环境，早于任何 notBefore。 唯一表示暂缓的方式是不将其加入数组。

2. 仅从 RELEASE 类别构建 environments——然后重新检查键。 数组必须包含所有 RELEASE 环境，且不包含任何 HOLD 环境。发送调用前，检查数组中的 environmentKey：如果其中出现了你要暂缓的任何环境，就删除该条目。此调用没有用于指定日期或暂缓状态的字段——如果你发现自己想在条目中添加 holdUntil、notBefore 或 hold（或将其保留为 policy，以便“等待”），这就说明该环境属于 HOLD：删除该条目，不要自行添加字段。 日期和原因应写在报告中，而不是调用中。

   示例——“合并时发布 staging，将 production 暂缓至 2026-09-01”：staging 属于 RELEASE，production 属于 HOLD。

   {
     "projectKey": "default",
     "flagKey": "new-checkout-flow",
     "environments": [{ "environmentKey": "staging", "releaseType": "simple" }],
     "repoFullName": "acme/storefront",
     "prNumber": 482
   }
   

   调用中不会出现 production。你应在报告中说明它将暂缓至 2026-09-01，原因是法律签核。采取失败时关闭策略：如果某个环境的意图不明确，则归入 HOLD，而不是 RELEASE。

3. 记录发布计划。 调用 create-automated-rollout-config，并传入 projectKey、flagKey、仅包含 RELEASE 环境的 environments 数组以及 PR 引用。如果已商定前置条件父级标志，且 MCP 接口支持，则将其关联；否则将其列为手动步骤。详情：references/auto-release.md。

4. 验证。 调用会返回 created、config_id 和规范化的各环境计划——记录 config_id。仅报告已验证的内容；对无法确认的事项应明确指出，不要将其当作事实陈述。

5. 报告各环境的发布计划和 config_id；说明哪些环境被暂缓（以及原因），哪些环境会在合并时发布；并说明合并时会发生什么（例如：“production 会解析策略 X → 合并时执行受保护的渐进发布；staging 立即提供 true；按意图将 production 暂缓至 2026-08-01”）。

边缘情况

情况	操作
标记尚不存在	停止 — 创建操作是 launchdarkly-flag-create。为缺失的标记记录发布会导致难以理解的失败。
此标记 + PR 已存在发布配置	不要再记录第二个 — 重复配置会让调度器混乱。引导用户修改现有配置中的计划。
PR 尚不存在时注册	simple 环境无需 PR 即可运行，但 policy 环境需要 repoFullName/prNumber 才能在合并时触发。最好在 PR 开放后再记录；如果提前记录，请说明 policy 要等 PR 完成关联后才会触发。
没有发布策略匹配某个环境	policy 会回退到默认值（通常是立即发布）。告知用户；可建议使用 simple，或引导用户设置发布策略。
用户希望暂缓发布，或设置 notBefore 日期	跳过这些环境的发布计划；说明这些环境处于暂缓状态并注明原因。绝不要违背用户已表明的意愿，悄悄进行发布。
变更依赖一个尚未生效的父标记	为它们建立关联并设置前置条件（如果 MCP 接口支持）；否则说明关联是必须手动完成的步骤。不要让此标记早于其父标记发布。
某个 policy 环境解析为受保护发布，但没有相关指标	请说明这一点 — 没有有意义的指标，就无法通过受保护发布进行指标防护。建议使用 simple，或引导用户设置指标。

不要执行的操作

• 不要创建标记或编辑代码 — 这些操作属于 launchdarkly-flag-create。此技能只记录发布。
• 不要自行启用标记，也不要在记录配置后切换其状态。 发布流程负责此事；重复切换会造成审计噪声并让调度器混乱。
• 不要跳过 match-release-policies。 在不了解 policy 会解析为什么结果的情况下提出它，就是在猜测。
• 不要违背用户已表明的暂缓发布要求或 notBefore，悄悄进行发布。 尊重用户意愿或继续暂缓 — 绝不要忽略它。
• 不要处理或打印凭据。 访问权限由环境注入。

参考资料

• references/auto-release.md：自动发布 / 发布策略模型、simple 与 policy、优先级（意图 → 覆盖项 → 策略 → 默认值）、预览、前置条件、指标充分性。（此技能的核心。）
• launchdarkly-guarded-rollout：适用于策略无法表达的定制发布 — 在此处将该环境设为 simple，并在合并后手动推进受保护发布。