flag-prerequisites

flag-prerequisites

在 GrowthBook 功能标志上添加、移除或检查功能级前置条件。功能级前置条件是一种布尔门控：如果指定的前置标志对某个用户处于关闭状态，当前标志就会跳过所有规则，并向该用户返回其 defaultValue。

功能级前置条件仅适用于布尔标志。 前置标志必须设置 valueType: "boolean"。门控条件始终为“前置标志已开启”（{"value": true}），不支持自定义条件。如果用户需要更细致的依赖关系（例如，根据字符串标志的值进行门控，或只门控单条规则），请转到 flag-targeting。

这与规则级前置条件不同（规则级前置条件用于门控单条规则，并支持更丰富的条件）：功能级前置条件会同时应用于该标志的所有规则。

所有 API 调用都通过随附的辅助程序进行：${CLAUDE_PLUGIN_ROOT}/scripts/gb-call。需要在环境中设置 GB_API_KEY，或通过 /growthbook:gb-setup 将其写入 ~/.config/growthbook/.env。

工作流

路径 A — 添加前置条件

1. 获取标志当前的前置条件：

   gb-call GET /api/v2/features/<flag-id>
   

   记录现有的 prerequisites 数组。下方的 PUT 会替换整个数组，因此需要先获取当前内容，以免覆盖现有前置条件。

2. 确认前置标志存在且为布尔类型：

   gb-call GET /api/v2/features/<prerequisite-flag-id>
   

   检查 valueType。如果不是 "boolean"，请停止操作：

   “功能级前置条件仅支持布尔标志。<prerequisite-flag-id> 是一个 <valueType> 标志。若要根据非布尔标志的值进行门控，请通过 flag-targeting 添加规则级前置条件。”

3. 构建新的前置条件数组。 将新项追加到所有现有条目之后。条件始终为 {"value": true}，表示“前置标志已开启”：

   [
     { "id": "<existing-prereq-id>", "condition": "{\"value\": true}" },
     { "id": "<new-prereq-id>", "condition": "{\"value\": true}" }
   ]
   

4. 通过草稿应用更改：

   echo '{"prerequisites":[...]}' \
     | gb-call PUT /api/v2/features/<flag-id>/revisions/new/prerequisites -
   

5. 移交给 flag-publish。

路径 B — 移除前置条件

1. 获取当前前置条件（见上方步骤 A-1）。
2. 显示列表并询问要移除哪项。
3. 构建移除该条目后的更新数组。
4. 使用筛选后的数组通过草稿应用更改（见上方步骤 A-4）。空数组 [] 会移除所有前置条件。
5. 移交给 flag-publish。

路径 C — 检查当前前置条件

gb-call GET /api/v2/features/<flag-id>

显示 prerequisites 数组。对于每个条目，获取对应前置标志，以显示其当前评估状态和类型。如有需要，使用 flag-graph 追踪完整的依赖链。

护栏

• 草稿版本贯穿。 如果本会话之前的写入技能已在上下文中提供版本号，请明确使用该版本号（例如 .../revisions/42/prerequisites），而不要使用 new。这样可确保所有更改都在同一草稿中。开始新流程时使用 new——它会自动创建或复用最近更新的开放草稿。
• PUT /prerequisites 会替换整个数组。 它不会追加内容。添加或修改前，务必先获取当前数组，并包含所有现有条目；否则会在不提示的情况下删除用户并未打算修改的前置条件。
• 前置条件标记的值必须是布尔值。 如果用户指定了非布尔值的标记作为前置条件，请暂停并转交给 flag-targeting。
• 条件始终为 {"value": true}。 对功能级前置条件，不要接受或生成自定义条件。后端允许这样做，但我们有意对此加以限制——该门槛表示“此标记已开启”。如果用户需要更复杂的条件（例如字符串标记等于某个值，或标记处于生效状态但不一定为 true），请转交给 flag-targeting，以配置规则级前置条件。
• 功能级与规则级前置条件。 此技能用于控制整个标记。如果用户希望前置条件仅作用于单条规则，请转交给 flag-targeting。
• 必须避免循环依赖。 如果标记 A 依赖标记 B，而标记 B 又依赖标记 A，两者都将无法通过评估。添加前置条件前，请通过 flag-graph 检查现有依赖链。
• 前置条件标记必须属于同一 GrowthBook 项目（或组织范围）。 根据 SDK 配置，跨项目的前置条件可能无法正确解析。
• 删除前置条件标记会破坏依赖它的所有标记。 依赖标记的前置条件将始终无法通过评估。用户通过 flag-graph 检查依赖关系并进行清理时，请告知此情况。

使用的端点

• GET /api/v2/features/:id — 获取标记状态，包括当前的 prerequisites 数组
• PUT /api/v2/features/:id/revisions/new/prerequisites（请求体：{ "prerequisites": [...] }）

移交

• flag-search — 用户提供名称时，用于查找前置条件标记的 ID
• flag-graph — 用于追踪完整依赖链并检测循环依赖
• flag-targeting — 用于添加规则级前置条件（仅作用于单条规则，而非整个标记）
• flag-publish — 用于发布草稿，并处理需要审批的情况（400）和合并冲突（409）