flag-search

flag-search

搜索、列出并审查 GrowthBook 功能标志。此技能包含三项任务：列出完整清单、按条件筛选搜索，以及审查过时标志以寻找可清理的候选项。

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

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

工作流

根据用户的请求选择相应路径。

路径 A — 完整清单（“我们有哪些标志？”）

先获取轻量级的键列表：

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

返回所有标志 ID 组成的字符串数组——无需分页，调用成本最低。告知总数；如果发现规律，可按前缀分组（checkout-*、payments-*、infra-*）。

如果用户想查看完整集合或某个子集的详情，请分页获取：

gb-call GET '/api/v2/features?limit=100'
gb-call GET '/api/v2/features?limit=100&offset=100'   # next page

每页上限为 100 条。通过循环递增 offset，直到返回条数少于 100。

如果组织使用项目，请按项目分组输出。留意看起来像遗留测试／调试条目的标志键（test-、temp-、debug-、delete-me）。

路径 B — 按条件搜索

使用 /api/v2/features 列表端点和查询参数缩小结果范围。可用筛选条件：

# By project:
gb-call GET '/api/v2/features?projectId=<project-id>'

# By tag (exact match, single tag):
gb-call GET '/api/v2/features?tag=<tag>'

对于 API 不支持的筛选条件（所有者、环境状态、值类型），获取完整集合，并根据响应字段在客户端进行筛选。

常见搜索：

请求	方法
“由 X 所有的标志”	获取全部，然后按 owner.email 筛选
“布尔标志”	获取全部，然后按 valueType === "boolean" 筛选
“在生产环境中启用的标志”	获取全部，然后按 environmentSettings.production.enabled === true 筛选
“没有规则的标志”	获取全部，然后按 rules.length === 0 筛选
“带有 payments 标签的标志”	GET /api/v2/features?tag=payments
“项目 Y 中的标志”	将项目名称解析为 ID，然后调用 GET /api/v2/features?projectId=<id>

在大型组织中于客户端筛选时，先分页获取完整集合，再进行筛选。

路径 C — 过时标志审查（“哪些内容可以清理？”）

GrowthBook 将满足以下两个条件的标志定义为过时：（a）两周内没有更新；（b）没有启用的环境，或所有规则都将 100% 的流量路由到单个变体。

步骤 C-1：获取要审查的标志 ID。

可以使用用户明确提供的列表、通过代码库 grep 获取，或拉取所有 ID：

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

步骤 C-2：运行过时状态检查。

此端点要求明确提供 ID 列表（没有“查找所有过时标志”的快捷方式）：

gb-call GET '/api/v2/stale-features?ids=flag-a,flag-b,flag-c'

步骤 C-3：解读结果。

每个标志都会获得一个 staleReason：

staleReason	含义	操作
rules-one-sided	所有规则都将 100% 的流量路由到单个值——看起来像是已发布的功能	可以安全清理——将胜出的值内联
no-rules	标志完全没有规则	如果 defaultValue 已内联，则可以安全移除
toggled-off	在所有环境中都已禁用	如果不再需要，则可以安全移除
abandoned-draft	有未关闭的草稿，且近期没有活动	检查草稿；将其丢弃或继续处理
never-stale	已明确排除在过时状态检测之外	跳过——这是永久保留的刻意标志（紧急开关、运维开关）
recently-updated	最近两周内更新过	尚未过时——稍后再检查
active-draft	正在进行有效的草稿修订	有人正在处理——不要改动
has-dependents	其他标志将此标志列为前置条件	未更新依赖项时无法安全移除——先使用 flag-graph
active-experiment	关联到正在运行的实验	先通过 experiment-stop 停止实验
has-rules	有未将流量单边路由的有效规则	仍在使用中

步骤 C-4：提供报告。

按建议分组：

1. 清理候选项（launched、unused、abandoned）——附上建议的替代值
2. 排除项（never-stale）——单独列出，不要纳入清理建议
3. 仍在使用——跳过

对候选项显示 defaultValue 和胜出规则的值——用户需要这些值才能在移除前将其内联。

不要删除任何内容。实际移除操作交由 flag-cleanup 处理。

防护措施

• /stale-features 需要明确提供 ID。 不存在“查找所有过时标志”的端点。如果用户未提供 ID，请先从 /feature-keys 获取。
• /feature-keys 不分页；/features 会分页（每页 100 条）。 使用 /feature-keys 获取完整 ID 清单；使用 /features 查询详细信息。
• neverStale: true 标志不纳入清理建议。 它们会显示为 staleReason: "never-stale"——应单独列出，但绝不要建议移除。
• 不要自行判断标志是否过时。 使用 /stale-features 获取规范判定；它遵循 GrowthBook 自身的规则，并会提供无法在本地计算的替代值。
• 大型组织中的客户端筛选可能较慢。 速率限制为每分钟 60 次。如果需要分页检查数百个标志，请告知进度。
• v2 规则是扁平的。 在 v2 中，rules 数组位于标志对象顶层，每条规则按 allEnvironments/environments 指定范围——不像 v1 那样嵌套在各环境下。
• 只读。 此技能中绝不执行 POST、PUT、PATCH 或 DELETE。移除操作交由 flag-cleanup 处理。

使用的端点

• GET /api/v2/feature-keys — 完整 ID 列表，无分页上限
• GET /api/v2/features — 带完整配置的分页列表（limit、offset、projectId、tag 筛选器）
• GET /api/v2/features/:id — 单个标志的完整配置
• GET /api/v2/stale-features?ids=a,b,c — 过时状态审查（需要明确提供 ids）
• GET /api/v1/projects — 在项目范围的搜索中，将项目名称解析为 ID

交接

• flag-graph — 用于追踪特定标记的依赖关系（它依赖什么，以及哪些内容依赖它）
• flag-cleanup — 用于归档或删除在 Path C 中找到的待清理项
• flag-targeting、flag-rules — 用于确定需要更新的标记后进行更改
• flag-revisions — 用于检查搜索结果中标记是否有未完成的草稿