feature-flags

功能标记

GrowthBook 功能标记的领域路由器。每种标记工作流都位于 references/ 下的一个参考文件中。阅读此路由器，选择与用户意图相符的工作流，然后阅读对应文件并按其说明操作。

标记使用 v2 API（/api/v2/features）。环境、项目和已保存群组使用 v1。

所有 API 调用都通过捆绑的辅助程序进行。在 Claude Code 插件安装中，它位于 ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call（插件根目录）。通过 npx skills install 安装时，它位于相对于此技能目录的 scripts/gb-call。解析一次该路径，并在参考示例中出现 gb-call 时替换为此路径；不要假设 gb-call 已在 PATH 中。它会先从环境中读取 GB_API_KEY，然后回退到 ~/.config/growthbook/.env（由 gb-setup 写入）；环境变量优先。

当工作流需要提供 GrowthBook UI 链接时，具备 shell 功能的运行时应在每次对话中调用一次 gb-call app-origin，在工作流和领域切换期间保留返回的可信来源，并将其添加到参考文件中的根相对 UI 路径前。如果上下文中已有来源，则重复使用；不要针对每个链接都调用一次命令。已知可信应用来源的嵌入式适配器或 MCP 适配器可以直接解析相同路径。切勿从 GB_API_URL 推导应用来源；如果 app-origin 因可自托管配置不完整而拒绝执行，请转到 gb-setup。

选择工作流

根据用户要做的事情，准确阅读以下其中一个文件。如果有两个看起来都合适，请阅读更具体的那个。

阅读此文件	用户想要
references/flag-create.md	创建新标记
references/flag-search.md	查找、列出或审计标记——按项目、标签、所有者、环境状态或陈旧程度筛选（只读）
references/flag-graph.md	追踪标记依赖的对象、依赖该标记的对象，以及与其关联的实验或保留组（只读）
references/flag-toggle.md	在某个环境中启用或禁用标记——即紧急开关
references/flag-targeting.md	添加、编辑或移除强制 / 渐进发布规则、条件、已保存群组、规则级前置条件
references/flag-rules.md	列出、重新排序或删除规则，或路由到合适的规则类型工作流
references/flag-experiment.md	添加实验引用规则，使 A/B 测试通过标记运行
references/flag-schedule.md	为规则设置时间门控，指定开始和 / 或结束日期时间
references/flag-ramp.md	构建或推进多步骤渐进发布计划（随时间逐步扩大覆盖范围）
references/flag-monitoring.md	设置受监控 / 安全渐进发布——渐进发布加护栏指标，并可选择自动回滚
references/flag-prerequisites.md	通过另一个布尔标记控制整个标记是否生效
references/flag-default-value.md	更改没有规则匹配时提供的值
references/flag-metadata.md	更改描述、所有者、项目、标签、自定义字段或 JSON 架构
references/flag-revisions.md	查看有哪些草稿处于打开状态、由谁负责，以及开始或放弃草稿
references/flag-review.md	请求审核，或批准 / 请求修改 / 评论草稿
references/flag-publish.md	发布草稿、解决合并冲突、还原或放弃草稿
references/flag-cleanup.md	归档或删除陈旧标记；先在代码位置内联其值

值得在阅读前先消除的歧义：“关闭标记”如果指整个环境，则使用 flag-toggle；如果指单条规则，则使用 flag-rules。“逐步发布”如果指一次性百分比，则使用 flag-targeting；如果指计划，则使用 flag-ramp；如果需要由护栏指标控制，则使用 flag-monitoring。

通用约定

这些约定适用于所有功能开关工作流。参考文件均以此为前提。

• 所有变更都会通过草稿版本写入。 规则、元数据、默认值和开关都会创建或更新草稿，之后必须发布。flag-publish 负责发布步骤；写入工作流会将任务交给它。
• 在工作流链中传递草稿版本。 在同一会话中依次运行多个写入工作流时，应传递上一步返回的 version，而不是再次发送 new。new 会自动创建或复用草稿，这可能会在工作流链中途悄悄采用队友并发创建的草稿。只有在全新开始时，才使用 new（或 /revisions/latest?mine=true）。
• POST rules 会替换整个数组。 v2 规则数组位于顶层，并由 environments 或 allEnvironments 指定范围。进行任何局部编辑前，都要先 GET 当前规则。
• defaultValue 始终是字符串， 无论功能开关的值类型是什么。
• 向用户显示功能开关键（即 id），绝不显示内部 Mongo id。链接到 UI 路径 /features/<key>。
• UI 链接使用根相对路径。 切勿根据 GB_API_URL 推断 GrowthBook UI 的源地址。API 和 UI 的源地址不一定共享同一主机名。拥有受信任应用源地址的运行环境可以解析该路径；否则应直接显示根相对路径，不要猜测。
• 输出深层链接，不要打开它们。 此技能有意不授予浏览器权限——显示路径，让用户在运行环境可以解析时自行点击。

失败情况

已根据后端处理程序验证；不要将以下情况混为一谈。

• 发布端点返回 400 表示需要审批（This revision requires approval before publishing）。策略门槛按预期生效——交由 references/flag-review.md 处理。
• 会产生发布副作用的路径返回 403 表示同一问题，但来自不同代码路径：环境开关以及带有 {archived} 的 POST /v2/features/<id> 都会调用 createAndPublishRevision，它会抛出权限错误，而非错误请求错误。阅读响应正文——如果其中未提到审核，则表示令牌本身缺少权限，问题出在 GB_API_KEY。
• 发布时返回 409 表示草稿的基准已过期——线上功能开关已发生变更。不要自动变基。暂停操作，展示冲突，让用户解决。
• 发布时返回 422 表示发布门槛正在阻止操作。响应正文会列出哪些门槛可通过简单重试并设置 ignoreWarnings 来解除，哪些则需要相应权限。

只读与写入

flag-search 和 flag-graph 是只读的，必须保持只读——它们绝不会执行 POST、PUT 或 DELETE。其他所有工作流都会写入，并且都会说明各自的确认要求。flag-cleanup 的“归档—验证—删除”门槛是产品安全暂停，不是变更确认：即使用户听起来很确定，也不要跳过。

调用预算

GrowthBook 的速率限制为每分钟 60 次。flag-search 和 flag-graph 会跨分页列表发起多次请求——应明确限制循环次数，并在调用预算不明显时加以说明。

交接

• experiments 技能——用于设计、启动、分析或停止 A/B 测试。功能开关的实验引用规则属于此技能的职责；实验本身则不属于。
• analytics 技能——用于绘制产品数据图表，或浏览指标和事实表。
• gb-setup——当 gb-call 报告 GB_API_KEY 缺失或无效时使用。