flag-create

flag-create

在 GrowthBook 中创建新的功能标志。我们始终在负载中为每个环境显式设置 {enabled: false}，因此无论组织对新环境的默认状态设置如何，该标志创建后都会处于禁用状态——用户必须在创建后手动启用。功能标志的键是永久的；请谨慎选择名称。

所有 API 调用都通过随附的辅助工具执行：${CLAUDE_PLUGIN_ROOT}/scripts/gb-call。它需要 GB_API_KEY——可在 shell 中设置，或由 /growthbook:gb-setup 写入 ~/.config/growthbook/.env。如果缺少或无效，gb-call 的错误消息会指引你返回 /growthbook:gb-setup。

工作流

1. 确认意图。 用一句话重述该标志将控制什么。如果用户想运行 A/B 测试（根据当前已有的上下文，将其转交给适当的实验技能），或想为现有标志添加规则（转交给 flag-rules），则停止。

2. 检查键是否已被占用。

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

   确认拟定的键不在返回列表中。如果已被占用，请提出一个变体；API 会拒绝重复项，而且键创建后无法重命名。

3. 选择值类型。 可选类型为 string、number、boolean、json。开关型标志默认使用 boolean。仅当标志携带配置时（变体文案、阈值或结构化负载），才使用 string 或 json。

4. 解析项目（可选）。 如果用户提到了项目名称，请列出项目并选择 ID：

   gb-call GET /api/v1/projects
   

   将标志限定到项目范围，比放在默认的组织级存储桶中更便于管理。如果不明确，请询问用户。

5. 解析环境。 GrowthBook 要求创建负载包含列出所有环境的 environments 映射。获取环境：

   gb-call GET /api/v1/environments
   

   构建映射，并将每个环境设为禁用。

6. 确认命名。 v2 端点的正则表达式接受 [a-zA-Z0-9_.:|-]（面向用户的文档和错误消息建议使用范围更窄的 [a-zA-Z0-9_-]）。默认采用 kebab-case（new-checkout-flow、dark-mode、pricing-experiment-2026-q2）——这符合文档建议，能让各团队的键保持一致，也可避免正则表达式日后收紧的影响。创建前向用户展示拟定的键。

7. 构建负载并创建标志。 构造一个 JSON 对象：

   {
     "id": "<kebab-case-key>",
     "valueType": "boolean",
     "defaultValue": "false",
     "description": "<short description>",
     "environments": {
       "production": { "enabled": false },
       "staging":    { "enabled": false }
     },
     "project": "<project-id, omit if org-wide>"
   }
   

   然后 POST：

   echo '<payload-json>' | gb-call POST /api/v2/features -
   

8. 说明接下来会发生什么。 明确告知用户：该标志在所有环境中均处于禁用状态，并且尚无任何规则。提供两个后续操作：

   • 如需在某个环境中启用该标志或添加定向规则，请使用 flag-targeting。
   • 如需将此标志用作 A/B 测试中的变体开关，请使用 experiment-design，并提供该标志的 ID。

防护措施

• 功能键是永久的。 GrowthBook 不允许在创建后重命名标志的 id。调用 API 前，请向用户确认拟定的名称。
• owner 默认为令牌所属用户。 从创建载荷中省略 owner——API 会将标志归属到 GB_API_KEY 所属的用户。只有当用户想将标志分配给其他人时，才明确设置 owner（邮箱或 u_... userId）。
• ID 字符集：优先使用 kebab-case。 v2 端点的正则表达式仍接受 [a-zA-Z0-9_.:|-]，但面向用户的文档和错误消息推荐 [a-zA-Z0-9_-]。不要建议使用包含 .``:``| 的 ID——未来版本可能会收紧规则。现有包含这些字符的旧键可以保留。
• 始终为每个环境显式设置 {enabled: false}。 不要依赖组织的“新环境默认状态”设置——该设置可配置，默认值可能是启用。请告知用户该标志在所有环境中均已禁用；静默的零评估（甚至更糟，意外启用评估）是 GrowthBook 中最容易踩的坑之一。
• defaultValue 始终序列化为字符串。 布尔值关闭时使用 "false"，数值使用 "0"，json 使用 JSON 编码文本。API 会拒绝非字符串值。
• v2 的环境映射中，每个环境仅包含 {enabled: bool}。 规则不再嵌套在各环境下——它们是标志上的顶层数组，之后通过 flag-targeting（或直接通过 v2 revision 端点）添加。不要在每个环境中包含 rules: []。
• 如果用户想要实验，请先暂停创建。 转交给 experiment-design。创建标志却不创建对应实验，是常见的困惑来源，会产生孤立标志。
• 有疑问就询问，不要猜测。 如果 valueType、defaultValue 或项目不明确，请询问。标志是永久的。

使用的端点

• GET /api/v2/feature-keys — 列出所有功能标志键（无分页上限）
• GET /api/v1/projects — 列出项目，用于将项目名称解析为 ID
• GET /api/v1/environments — 列出环境，用于构建 environments 映射
• POST /api/v2/features — 创建标志

创建后

响应包含标志的完整配置。向用户显示标志 ID，提醒其该标志在所有环境中均已禁用，并提供 GrowthBook UI 中该标志的链接。通过将 GB_API_URL 中的 api. 替换为 app. 来推导 <host>（云端默认值：https://app.growthbook.io）。链接：<host>/features/<flag-id>。

转交

• flag-toggle — 在某个环境中启用标志
• flag-rules — 添加规则（会转到适当的规则类型技能）
• flag-default-value — 更改没有匹配规则时提供的回退值
• flag-metadata — 创建后设置项目、标签、描述或所有者
• flag-experiment — 将此标志关联到 A/B 实验
• experiment-design — 如果用户实际需要完整的 A/B 测试（先创建实验，再创建标志）