flag-graph

flag-graph

追踪 GrowthBook 功能开关周围的依赖关系。在重命名、归档或删除等结构性变更前使用此技能，了解影响范围；也可用于建立功能开关之间依赖关系的整体认知。

只读——此技能绝不会写入数据。

所有 API 调用都通过捆绑的辅助工具完成：${CLAUDE_PLUGIN_ROOT}/scripts/gb-call。需要在环境变量中设置 GB_API_KEY，或由 /growthbook:gb-setup 写入 ~/.config/growthbook/.env。

工作流

1. 获取功能开关

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

记录：prerequisites（功能级）、rules（检查规则级前置条件、experiment-ref 条目、safe-rollout 条目）、holdout。

2. 此功能开关依赖什么？（正向依赖）

对于功能开关 prerequisites 数组中的每个前置条件：

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

显示：前置功能开关 ID、其当前状态（已启用的环境、默认值），以及当前功能开关针对它检查的条件。如果该前置功能开关也有前置条件，则递归一层——显示完整链路，并注明链路的终点。

同时检查 rules 数组中的规则级前置条件——每条规则都可以有自己的 prerequisites 字段。将这些内容作为规则范围的依赖关系列出。

3. 哪些内容依赖此功能开关？（反向查找）

GrowthBook 没有反向前置条件 API 端点。要完整反向查找，需要扫描所有功能开关：

gb-call GET /api/v2/feature-keys

然后分页遍历所有功能开关，查找任何在其 prerequisites 中列出目标功能开关的条目：

gb-call GET '/api/v2/features?limit=100'
gb-call GET '/api/v2/features?limit=100&offset=100'   # continue until exhausted

对于返回的每个功能开关，检查 prerequisites[*].id 和 rules[*].prerequisites[*].id 是否与目标功能开关 ID 匹配。

警告用户：这是一次针对所有功能开关的 O(n) 扫描。在拥有数百个功能开关的大型组织中，可能需要多次分页调用。

4. 哪些实验关联到此功能开关？

检查功能开关 rules 数组中的实验引用规则（type: "experiment-ref" 的规则上的 experimentId 字段）。对于每条规则：

gb-call GET /api/v1/experiments/<experiment-id>

列出：实验名称、状态（运行中/已停止/草稿），以及功能开关的 id 是否为该实验的 trackingKey。

同时检查是否有实验在其 linkedFeatures 中列出此功能开关：

gb-call GET '/api/v1/experiments?trackingKey=<flag-id>'

这可以捕获按惯例连接的实验（experiment-launch 会设置 trackingKey === flag-id）。此外，还要结合上述实验引用规则扫描，以覆盖手动连接的实验。

5. 保留组关联

如果功能开关设置了 holdout 字段，记录保留组 ID 并警告："此功能开关参与了保留组 <holdout-id>。删除或大幅更改此功能开关可能会影响保留组分析。"

6. 提供依赖关系报告

Dependency graph for `<flag-id>`:

DEPENDS ON (forward):
  → flag-Y (prerequisite, condition: value === true)
      → flag-Z (flag-Y's prerequisite, condition: value === "v2")

DEPENDED ON BY (reverse, scanned <N> flags):
  ← flag-A (feature-level prerequisite)
  ← flag-B (rule-level prerequisite on rule "Beta testers")
  [limitation: reverse lookup scanned all flags; may miss any created after this scan]

EXPERIMENTS:
  exp_abc123 "Checkout experiment" — status: running, trackingKey matches

HOLDOUTS:
  holdout_xyz — flag participates; remove cautiously

SAFE TO DELETE?: <yes / no / caution — explain why>

防护措施

• 反向查找需要完整扫描——注意速率限制。 速率限制为每分钟 60 次请求。如果组织有超过 600 个功能开关，扫描需要 10 次以上 API 调用。开始前说明数量，并询问是否继续。
• 反向查找反映的是某一时点的状态。 扫描后创建的功能开关不会出现在结果中。在报告中注明扫描时间戳。
• 没有反向前置条件查询 API。 不存在 GET /features?dependsOn=<id> 端点。扫描是唯一可靠的方法。
• 扫描实验 trackingKey 可以捕获常见情况。 按照惯例，experiment-launch 会设置 trackingKey === flag-id。手动连接（trackingKey 不同，通过 linkedFeatures 关联）可能无法通过 trackingKey 查询捕获——第 4 步中的规则扫描是额外的检查。
• 只读。 此技能绝不会写入数据。要更改前置条件，请使用 flag-prerequisites。要删除功能开关，请使用 flag-cleanup。
• 循环依赖检测。 在遍历正向依赖时，如果遇到指回起始功能开关的功能开关，将其列为循环依赖警告——这意味着该功能开关永远无法完成求值。

使用的端点

• GET /api/v2/features/:id — 获取标记及其依赖项
• GET /api/v2/feature-keys — 完整标记 ID 列表，用于反向查找
• GET /api/v2/features（分页，limit/offset）— 扫描全部标记，用于反向查找
• GET /api/v1/experiments/:id — 获取关联实验的详细信息
• GET /api/v1/experiments?trackingKey=<flag-id> — 按约定查找关联的实验

交接

• flag-prerequisites — 添加、移除或修改功能级前置条件
• flag-cleanup — 确认影响范围后归档或删除标记
• experiment-stop — 如果关联实验正在运行，需要在移除标记前停止实验
• flag-search — 查找所有符合条件的标记（范围比单个标记依赖追踪更广）