flag-default-value

flag-default-value

设置 GrowthBook 功能标志的默认值。当没有规则匹配某个用户时，SDK 会返回默认值——它是标志的基准状态，而不是定向规则。更改会通过草稿修订进行，必须发布后才会生效。

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

必需输入

• 标志 ID — kebab-case 键。如果用户提供的是描述，请使用 flag-search 解析。
• 新的默认值 — 必须与标志的 valueType 匹配。始终序列化为字符串。

工作流

1. 获取标志

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

记录 valueType 和当前的 defaultValue。向用户显示当前默认值，以便他们确认更改。

2. 验证新值

发送前先进行预验证——API 在写入时不会检测类型不匹配：

valueType	有效的 defaultValue
boolean	"true" 或 "false"（字符串，而非 JSON 布尔值）
number	可解析为数字的任意字符串："0"、"3.14"
json	任意有效的 JSON 字符串："{\"key\":\"value\"}"
string	任意非空字符串

如果用户提供的值不匹配，请停止并让他们修正。不要静默转换。

3. 通过草稿应用更改

echo '{"defaultValue":"<string>"}' \
  | gb-call PUT /api/v2/features/<flag-id>/revisions/new/default-value -

new 这个特殊版本会创建一个新草稿，或以原子方式将更改叠加到现有草稿上。记录返回的 version 编号。

4. 提议发布

询问：“现在发布此默认值更改，还是将其保留为草稿？”

更改默认值会影响所有未匹配任何规则的用户——这可能会产生重大影响。发布前，清楚说明行为变化：

将默认值从 <old> 更改为 <new> 会影响所有未匹配任何规则的用户。在 <env> 中，目前有 <rule-count> 条规则——未匹配其中任何规则的用户现在将获得 <new>，而不是 <old>。

将发布步骤交给 flag-publish。

防护措施

• 草稿版本传递。 如果本次会话中先前的写入技能已在上下文中提供版本编号，请显式使用该编号（例如 .../revisions/42/default-value），而不是 new。这样可确保所有更改都在同一草稿中。若从头开始，则使用 new——它会自动创建或复用最近更新的未关闭草稿。
• defaultValue 始终是字符串，与 valueType 无关。 API 会拒绝非字符串值。布尔值关闭时用 "false"，数值零用 "0"，空 JSON 对象用 "{}"。
• 默认值 ≠ 强制规则。 只有当所有规则都匹配失败时，才会应用默认值。如果用户想向定向用户提供特定值，他们需要的是 flag-targeting，而不是此技能。
• 这可能会产生广泛影响。 在每个已启用的环境中，默认值都会应用于所有未匹配任何规则的用户。若将其从“关闭”状态（例如 "false" → "true"）更改为开启状态，在没有规则时，可能会让生产流量接触到该功能。发布前请明确说明这一点。
• 对于布尔型标志，如果没有定向规则，更改默认值等同于全局开关。 请确认用户理解这一点。
• 类型不匹配会在 SDK 求值时暴露，而不是在写入时。 v2 默认值端点接受任意字符串。数字标志若设置 defaultValue: "not-a-number"，要等客户端对其求值时才会报错。

使用的端点

• GET /api/v2/features/:id — 获取标志的当前 defaultValue 和 valueType
• PUT /api/v2/features/:id/revisions/new/default-value（请求体：{ "defaultValue": "<string>" }）

交接

• flag-search — 如果用户提供的是描述而不是标志 ID
• flag-targeting — 添加或编辑向定向用户提供特定值的规则
• flag-cleanup — 如果不再需要此标志且应将其归档
• flag-publish — 发布草稿，并处理需要审批（400）和合并冲突（409）