flag-and-release-change

为 PR 变更添加标记并发布

你正在使用一项技能，它会端到端处理需要通过功能标记发布的拉取请求：判断是否需要标记、创建用于保护变更的标记、在 PR 分支上将新行为置于标记控制之下，并记录一次自动发布，以便 PR 合并后安全地发布变更。

部署不等于发布。 合并会发布控制路径——标记创建时处于关闭状态，因此部署始终提供变更前的行为。发布是自动推出流程随后执行的标记操作，受环境策略约束。创建关闭状态的标记与记录发布是有意分开的两件事。

此技能是一个可移植的 PR 编排器。它不负责标记机制或发布机制，而是组合三项专门技能，并补充 PR 工作流（读取差异、在克隆仓库中工作、推送到分支）以及计划→实施的顺序：

步骤	负责方	此技能的职责
判断是否需要标记	should-flag-change（建议性、只读）	若结果为“是”，则采取行动；如果尚未运行，则自行判断
创建标记并接入代码	launchdarkly-flag-create	针对该变更调用它；不要在此重复讲解标记创建或 SDK 模式
记录发布	flag-release	标记创建且代码推送后移交；不要在此重复讲解推出机制

不要在此重复任何组合技能的机制。此技能唯一独有的内容是PR 封装流程（克隆、三点差异、提交并推送到分支）以及将这三项技能串联起来的计划→实施流程。

自动化说明。 编排框架（例如 PR 流水线）可以跳过此技能，直接调用组合技能——should-flag-change → launchdarkly-flag-create → flag-release——并自行处理 git 操作和步骤编排。此技能是面向开发者手动处理 PR、有人参与其中的可移植流程。

此流程分为两个阶段——计划，然后是实施——并在两阶段之间与用户确认。计划阶段绝不创建或修改任何内容。

前置条件

• 远程托管的 LaunchDarkly MCP 服务。
• 能够读取 PR 仓库并推送变更的 git CLI。
• 可用的组合技能：launchdarkly-flag-create（创建标记并接入代码）和 flag-release（记录推出）。如果尚未决定是否需要标记，则使用 should-flag-change。

MCP 工具通过组合技能使用——create-flag/get-flag 通过 flag-create 使用，match-release-policies/create-automated-rollout-config 通过 flag-release 使用。此技能不会直接调用任何 MCP 工具。

处理拉取请求

从克隆仓库开始工作，这样你就可以读取变更，并将标记接入代码后推回对应分支。凭据由环境提供——绝不要索要、打印或存储令牌。

git clone https://github.com/<owner>/<repo>.git && cd <repo>
git fetch origin pull/<pr_number>/head
git diff origin/HEAD...<head_sha>       # three-dot: change relative to the PR's base

三点差异（base...head）会准确显示 PR 引入的内容。阅读理解变更及其风险所需的已更改文件。在两个阶段中都使用此克隆仓库——实施阶段会在此编辑、提交并推送。完整的 PR 操作流程（克隆、三点差异、提交并推送到分支）：references/pr-wiring.md。

规划阶段

此阶段不创建任何内容。

1. 确认是否应该添加标记。 如果 should-flag-change 已经运行，请按其判定执行。否则，采用相同的判断标准：面向用户的变更或有风险的变更优先添加标记；仅涉及配置、依赖升级、基础设施、测试或文档的变更则跳过。如果显然不需要添加标记，请说明并停止。
2. 了解变更和惯例。 阅读三点差异和已更改的文件——了解其作用及影响范围。然后遵循 flag-create 的第 1 步，了解此代码库现有的标记用法（SDK、封装层、键常量、命名）。不要在此重复探索。
3. 设计标记。 通常只需在新路径外加一个布尔型紧急关闭开关（flag-create 的 flag-types 介绍了如何选择）。不要提出超出变更所需的标记。如果第 1 步（或 should-flag-change）发现依赖尚未启用的父级标记／功能，请注明——发布步骤可以通过前置条件将它们关联起来。
4. 规划发布。 遵循 flag-release 的规划阶段：选择目标环境，使用 match-release-policies 预览每个环境，并记录用户的发布意图（合并时发布／暂缓／notBefore／分群／前置条件）。不要在此重新推导发布模型——这是 flag-release 的工作。
5. 展示完整计划并停止。 总结：标记（key、name、布尔值、标签）及其为何用于控制此项变更；代码中添加保护判断的位置；各环境的发布计划及记录的发布意图（以及任何需要暂缓的内容）。然后等待。根据反馈修改；只有在获得明确批准后才能继续。如果确实缺少信息（项目键、环境、缺失的策略），请提出有针对性的问题，不要猜测。

实施阶段

仅在获得批准后执行：

1. 创建标记并接入代码，使用 launchdarkly-flag-create（其第 3–4 步）：按约定的键和标签创建处于关闭状态的标记，并添加带有安全默认值的求值保护，遵循代码库现有模式。**创建失败时必须默认关闭：**只有“已存在”结果可视为复用成功。其他任何创建标记失败（身份验证、权限、未找到、服务器错误）都必须立即停止——不要接入代码、记录发布或报告成功。谎称“标记已创建”会导致绿色 PR 引用一个实际不存在的标记，这比如实报告失败更糟。说明错误并停止。
2. 添加成对的标记开启／关闭测试。 如果仓库有测试套件，就为受保护路径的每种状态添加测试：标记开启时提供新行为，关闭时保留旧行为；遵循仓库的测试框架和标记模拟惯例。运行测试，全部通过后才能继续。测试范围应限定于受标记控制的路径，而非一般覆盖率。如果仓库没有测试，请跳过并说明。
3. 提交并推送到 PR 分支。 提交接入代码的变更，并推送到 PR 现有分支，使其包含在同一个 PR 中——不要新建 PR，也不要改动目标分支。参见 references/pr-wiring.md。
4. 记录发布，移交给 flag-release 的实施阶段：记录自动发布，并遵循已记录的发布意图（暂缓任何意图未允许发布的环境），然后返回 config_id。不要在此重复讲解发布机制。
5. 报告完整变更：标记键和 LaunchDarkly 链接（创建时为关闭状态）；接入代码的文件和路径；新增的测试；各环境的发布计划及 config_id；哪些内容被暂缓（及原因），哪些会在合并时发布。只报告已经核实的内容。

边缘情况

情况	操作
变更不值得创建标记	说明原因（仅配置、依赖升级、基础设施、仅测试、文档），然后停止。不要创建标记。
标记已存在	复用它——“已存在”即表示成功。接入现有键；不要重复创建。
因其他原因（身份验证、权限、5xx）导致标记创建失败	立即停止。不要接入代码、记录发布或声称成功——应呈现错误。
代码库没有 LaunchDarkly SDK	接入代码无法评估标记——SDK 安装是单独的步骤（onboarding/sdk-install）。
防护逻辑需要的不只是布尔值	优先使用布尔型紧急开关。只有当变更需要不同变体时才使用多变量；请参阅 flag-create 的 flag-types。
特定于发布的情况（hold/notBefore、前置条件、没有匹配的策略、重复配置、没有有用的指标）	由 flag-release 处理——请参阅其中的边缘情况。

不要做的事

• 不要在计划阶段创建任何内容。 计划阶段提出方案；实施阶段负责创建。
• 不要在此处重新说明标记创建、SDK 防护或推出机制——这些内容属于 launchdarkly-flag-create 和 flag-release。请链接到它们。
• 不要自行启用标记。 由已记录的发布负责启用；创建处于关闭状态的标记才是关键。
• 不要过度使用标记。 一个紧急开关胜过多个推测性标记。
• 不要处理或打印凭据。 Git 访问权限由系统注入。

参考资料

• references/pr-wiring.md：PR 操作——克隆、三点差异、提交到 PR 分支。（这是此技能唯一独有的参考资料。）
• should-flag-change：判断变更是否值得创建标记。
• launchdarkly-flag-create：标记创建和各 SDK 的防护模式。
• flag-release：记录自动推出（以及其 auto-release.md 发布模型）。