flag-ramp

flag-ramp

为 GrowthBook 功能标志规则创建和管理多步渐进发布计划。渐进发布计划会随时间逐步提高（或降低）规则的流量覆盖率，并在各步骤之间设置指定的等待时间。步骤可以是手动的（由操作人员推进），也可以由时间控制（经过指定时间后自动推进）。

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

渐进发布计划的工作方式

渐进发布计划关联到功能标志上的特定规则。发布后，渐进发布会立即开始运行——除非明确设置 startDate（不常见；大多数团队更倾向于在发布后通过 GrowthBook UI 手动触发渐进发布），否则不会自动延迟。

在每个步骤中，计划都会应用操作——即对规则进行补丁，通常会更改 coverage。步骤结束后：

• 如果步骤设置了 interval（秒），则在该时间段后自动推进。
• 如果 interval 为 null，则保持当前状态，直到团队成员在 UI 中手动推进。

所有步骤完成后，会应用 endActions（通常将覆盖率设为 1.0）。如果在任何时候回滚渐进发布，则会应用 startActions（恢复渐进发布前的状态）。

渐进发布计划会作为 rampActions 暂存到草稿版本中，并在发布时原子性地执行。

工作流

路径 A — 在现有规则上创建渐进发布计划

1. 确认规则：

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

显示规则列表。获取用户想要进行渐进发布的 force 或 rollout 规则的 ID。记下当前的 coverage。

2. 与用户一起设计渐进发布步骤：

确认：

• 初始覆盖率（例如，0.05 = 5%）
• 步骤递进过程（例如，5% → 25% → 50% → 100%）
• 每个步骤的等待时间：以秒为单位的数值（例如，86400 = 1 天），表示自动推进；或设为 null，表示保持当前状态，直到手动推进

等待审批的步骤：在需要人工签核后才能继续渐进发布的步骤中，添加 holdConditions: { "requiresApproval": true }。审批始终是最后一道关卡——如果步骤同时设置了 interval，必须先经过该时长，然后等待明确的审批调用。纯手动关卡（不包含时间条件）为 { "interval": null, "holdConditions": { "requiresApproval": true } }。混合示例：

• 观察一天后要求审批：{ "interval": 86400, "holdConditions": { "requiresApproval": true } }
• 仅要求审批，不设置等待时间：{ "interval": null, "holdConditions": { "requiresApproval": true } }

间隔结束后，如何通过 API 提交审批，请参阅路径 D。

startActions 应与规则的当前覆盖率（在第 1 步中记录）一致——这是回滚时渐进发布恢复到的状态。

3. 构建渐进发布计划载荷：

{
  "startActions": [
    { "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 0 } }
  ],
  "steps": [
    {
      "interval": 86400,
      "actions": [{ "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 0.1 } }]
    },
    {
      "interval": 86400,
      "holdConditions": { "requiresApproval": true },
      "actions": [{ "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 0.5 } }]
    }
  ],
  "endActions": [
    { "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 1.0 } }
  ]
}

startActions = 渐进发布开始时应用并在回滚时恢复的状态。将其设为渐进发布开始前规则的当前覆盖率——新规则通常为 0。 endActions = 所有步骤完成后的最终状态（通常为 100% 覆盖率）。

要为渐进发布添加护栏指标监控，请添加 monitoringConfig 块，并在每个步骤中设置 "monitored": true——参见 flag-monitoring。

除非用户明确要求，否则请省略 startDate 和 cutoffDate——参见护栏。

4. 通过草稿将渐进发布计划关联到规则：

echo '<payload>' \
  | gb-call PUT /api/v2/features/<flag-id>/revisions/new/rules/<rule-id>/ramp-schedule -

记录返回的 version。渐进发布计划会作为 rampAction 暂存到草稿中，并在草稿发布后生效。

5. 移交给 flag-publish。

路径 B — 一步创建新规则和渐进发布计划

同时创建规则和渐进发布计划时，先获取可用的 hashAttribute 候选项（rollout 规则必需）：

gb-call GET '/api/v1/attributes?projectId=<flag-project-id>'

根据功能标志的 valueType（从获取功能标志时记录）验证规则的 value。然后发送：

echo '{
  "rule": {
    "type": "rollout",
    "value": "<on-value>",
    "coverage": 0.05,
    "hashAttribute": "<hash-attr-id>",
    "enabled": true,
    "allEnvironments": false,
    "environments": ["<env-id>"]
  },
  "rampSchedule": {
    "steps": [
      {
        "interval": 86400,
        "actions": [{ "targetType": "feature-rule", "targetId": "new", "patch": { "coverage": 0.05 } }]
      },
      {
        "interval": 86400,
        "actions": [{ "targetType": "feature-rule", "targetId": "new", "patch": { "coverage": 0.25 } }]
      },
      {
        "interval": 86400,
        "actions": [{ "targetType": "feature-rule", "targetId": "new", "patch": { "coverage": 1.0 } }]
      }
    ],
    "startActions": [{ "targetType": "feature-rule", "targetId": "new", "patch": { "coverage": 0.0 } }],
    "endActions": [{ "targetType": "feature-rule", "targetId": "new", "patch": { "coverage": 1.0 } }]
  }
}' | gb-call POST /api/v2/features/<flag-id>/revisions/new/rules -

在渐进发布操作中使用 "targetId": "new" 作为占位符——服务器会在创建时将其替换为实际规则 ID。

路径 C — 从规则中移除渐进发布计划

gb-call DELETE /api/v2/features/<flag-id>/revisions/new/rules/<rule-id>/ramp-schedule

这会在草稿中暂存一个 detach 渐进发布操作。草稿发布后，线上计划将被移除。规则的覆盖率将保持为该计划最后设置的值。

路径 D — 管理线上渐进发布（发布后）

采取任何操作之前，建议用户打开功能页面，全面了解渐进发布进度——UI 会显示计划状态、步骤时间线和指标健康状况，而 API 仅返回原始值：

# macOS:
open <host>/features/<flag-id>
# Linux:
xdg-open <host>/features/<flag-id>

之后，如需通过 API 管理：从功能标记的规则中获取渐进发布计划 ID（规则上的 rampScheduleId 字段），或查询该 ID：

gb-call GET '/api/v1/ramp-schedules?featureId=<flag-id>'
# or more precisely:
gb-call GET '/api/v1/ramp-schedules?ruleId=<rule-id>'

检查状态：

gb-call GET /api/v1/ramp-schedules/<rs-id>/status

返回：当前步骤索引、decision（"advance" / "hold" / "rollback" / "waiting"）、健康信号，以及该步骤是否正在等待批准。

启动渐进发布（如果尚未自动启动）：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/start

批准等待批准的步骤（间隔时间已过后）：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/approve-step

如果间隔时间尚未结束或仍有其他暂停条件，将返回 400——请先轮询 /status，仅在该步骤等待批准时才批准。

推进到下一步（忽略所有暂停条件——用于 CI 流水线或强制覆盖）：

echo '{}' | gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/advance -
# Force past an unsatisfied approval gate (requires canBypassApprovalChecks permission):
echo '{"force":true}' | gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/advance -

暂停 / 恢复：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/pause
gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/resume

回滚（恢复 startActions 状态，并标记为 rolled-back）：

echo '{"reason":"<description>"}' | gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/rollback -

立即完成（跳过剩余步骤，应用 endActions）：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/complete

回滚后重新启动：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/restart
# then start again:
gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/start

紧急停用开关（比回滚更快）：通过 flag-toggle 禁用功能标记环境——无需渐进发布计划 ID，即可立即停用所有规则。

注意事项

• 贯穿使用草稿版本。 如果本次会话中之前的写入技能已提供版本号，请明确使用该版本号，而不是 new。从头开始时则使用 new。
• 渐进发布计划仅适用于 force 和 rollout 规则。 不适用于 experiment-ref 或 safe-rollout 规则。
• startActions 必须与规则渐进发布前的覆盖率一致。 在第 1 步记录该值，并将其用作回滚状态。除非渐进发布前规则的覆盖率为 0，否则不要将其默认设为 0。
• 间隔为 null 的步骤会一直暂停，直到在 UI 中手动推进。 适用于需要人工把关的检查点。设置了间隔的步骤会自动推进。
• startDate 为可选项——如果省略，渐进发布会在发布后立即启动。只有用户明确需要延迟启动时才询问此项；大多数团队倾向于在确认发布成功后手动触发。
• cutoffDate 是较少使用的安全措施。 仅在用户询问时提及——到达该期限时，它会自动回滚渐进发布。默认不要包含此项。
• 步骤中的覆盖率补丁必须在 0–1 范围内。 服务端会在发布时验证这一点。
• 检查目标环境是否已启用。 如果功能标记在目标环境中已禁用，渐进发布将不起作用——请提醒用户，并先转到 flag-toggle。
• 对于受监控的渐进发布（护栏指标、自动回滚信号），请使用 flag-monitoring。
• 渐进发布操作会暂存在草稿中。 发布前不会发生任何变化。如果草稿被丢弃，就不会创建渐进发布计划。
• 每条规则只能有一个渐进发布计划。 添加新计划会替换已有计划。

使用的端点

草稿（发布前）：

• GET /api/v2/features/:id — 获取标志和当前规则
• PUT /api/v2/features/:id/revisions/new/rules/:ruleId/ramp-schedule — 在草稿中暂存渐进发布计划
• DELETE /api/v2/features/:id/revisions/new/rules/:ruleId/ramp-schedule — 在草稿中暂存渐进发布计划解绑
• POST /api/v2/features/:id/revisions/new/rules — 创建带有内联 rampSchedule 的规则

实时渐进发布管理：

• GET /api/v1/ramp-schedules — 列出（featureId、ruleId、status 筛选条件）
• GET /api/v1/ramp-schedules/:id/status — 实时健康状况和决策
• POST /api/v1/ramp-schedules/:id/actions/start
• POST /api/v1/ramp-schedules/:id/actions/pause
• POST /api/v1/ramp-schedules/:id/actions/resume
• POST /api/v1/ramp-schedules/:id/actions/advance（正文：可选 { force: true }）
• POST /api/v1/ramp-schedules/:id/actions/approve-step
• POST /api/v1/ramp-schedules/:id/actions/rollback（正文：{ reason: string }）
• POST /api/v1/ramp-schedules/:id/actions/restart
• POST /api/v1/ramp-schedules/:id/actions/complete

交接

• flag-monitoring — 为渐进发布添加护栏指标和自动化监控信号
• flag-targeting — 在关联渐进发布计划前设置规则的定向条件
• flag-toggle — 如果需要立即停止渐进发布，可使用紧急熔断开关
• flag-publish — 发布草稿并激活渐进发布