flag-schedule

flag-schedule

为 GrowthBook 功能标志规则添加定时激活窗口。计划规则会在开始时间自动激活，并且／或者在结束时间自动停用，无需每次都手动发布。

计划功能适用于 force 和 rollout 规则类型。不适用于 experiment-ref 或 safe-rollout 规则。

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

计划功能的工作方式

GrowthBook 支持为规则设置两种计划机制：

简单计划（创建规则时设置 schedule 字段）——推荐的方式。将 startDate 和／或 endDate 指定为 ISO 8601 时间戳。服务端会自动设置底层的 scheduleRules。

旧版 scheduleRules——一个包含 2 个元素的数组 [start, end]，其中每个元素的格式为 { timestamp: "<ISO 8601 or null>", enabled: <bool> }。API 仍然接受此格式；对于新规则，简单的 schedule 字段更清晰。

OFF 状态的工作方式

计划规则是一种规则级机制，而非标志级开关。当规则处于非活动状态（不在其计划窗口内）时，会在评估时跳过该规则，标志会继续匹配规则列表中的后续规则，最终使用 defaultValue。

这意味着：

• 规则应在活动窗口期间提供 ON 值（对于布尔标志，即 "true"）。
• 当没有规则匹配时，defaultValue 就是 OFF 状态。发布前请确认其设置正确。
• 对于新规则，计划规则应当是规则数组中的最后一条，以免其下方的规则在计划规则未激活时意外提供 ON 值。对于现有规则，请检查该规则下方的内容——任何能够提供匹配值的规则，都会在计划规则关闭时生效。

工作流

路径 A — 创建带计划的新规则

1. 获取标志：

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

   记录 valueType、defaultValue、environmentSettings 和当前规则。

   检查目标环境是否已启用。 如果 environmentSettings.<env>.enabled 为 false，计划规则将不会生效——请提醒用户：

   “该标志目前在 <env> 中处于禁用状态。启用标志之前，计划规则不会触发。请通过 flag-toggle 启用（此操作可以和本次更改一起提交到同一草稿中）。”

   检查 defaultValue 是否为 OFF 状态。 对于布尔标志，该值应为 "false"。如果不是，请提醒用户：

   “计划规则未激活时，标志将返回 <defaultValue>。这是预期的关闭状态吗？如果不是，请先通过 flag-default-value 更新。”

   检查规则顺序。 新规则会追加到底部。如果上方的现有规则会无条件向所有用户提供 ON 值，它们会先于计划规则触发——请提醒用户，并建议添加后通过 flag-rules 检查规则顺序。

2. 收集计划时间：

   询问：

   • 开始时间（或 null，表示“立即”）
   • 结束时间（或 null，表示“永不过期”）
   • 用户的时区，除非用户已在时间字符串中明确指定时区

   API 接受带时区偏移的 ISO 8601 格式——直接使用用户的本地时区，无需转换为 UTC。请使用对应日期的正确偏移量（考虑夏令时）：

   "tomorrow at midnight" in US Eastern (summer, EDT) → "2026-05-30T00:00:00-04:00"
   "right after Christmas" in US Eastern (winter, EST) → "2026-12-26T00:00:00-05:00"
   

   对于自然语言时间，请使用上下文中的 currentDate 来确定相对日期（如“明天”“下周五”）。对于“圣诞节后不久”或“促销结束时”等含义不明确的说法，请在继续之前与用户确认确切日期和时间。构建载荷之前，务必向用户确认解析后的完整日期和时间。

3. 构建载荷并提交：

   根据标志的 valueType（在步骤 1 中记录）预先校验 value：布尔标志必须使用 "true"/"false"，数字标志必须可解析为数字，json 标志必须是有效 JSON。

   echo '{
     "rule": {
       "type": "force",
       "value": "<on-value>",
       "description": "<optional>",
       "enabled": true,
       "allEnvironments": false,
       "environments": ["<env-id>"]
     },
     "schedule": {
       "startDate": "2026-05-30T00:00:00-05:00",
       "endDate": "2026-12-26T00:00:00-05:00"
     }
   }' | gb-call POST /api/v2/features/<flag-id>/revisions/new/rules -
   

   如果某一侧没有边界，则省略 startDate 或 endDate。

4. 记录返回的 version。交由 flag-publish 处理。

路径 B — 为现有规则添加计划

1. 获取标志并确定规则：

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

   显示规则列表。获取用户想要设置计划的规则 id（UUID）。记录该规则在数组中的当前位置——如果它不是最后一条，请检查它下方的规则是否会在此计划未激活时提供意外的值。

2. 收集计划时间（与路径 A 步骤 2 相同）。

3. 构建 scheduleRules 补丁：

   {
     "scheduleRules": [
       { "timestamp": "2026-05-30T00:00:00-05:00", "enabled": true },
       { "timestamp": "2026-12-26T00:00:00-05:00", "enabled": false }
     ],
     "scheduleType": "schedule"
   }
   

   • 元素 0：开始事件（enabled: true——规则在此时间启用）
   • 元素 1：结束事件（enabled: false——规则在此时间停用）
   • 时间戳使用 null 表示省略该边界（开放式开始或结束）
   • scheduleType 必须为 "schedule"

4. 应用补丁：

   echo '<patch>' | gb-call PUT /api/v2/features/<flag-id>/revisions/new/rules/<rule-id> -
   

5. 记录返回的 version。交由 flag-publish 处理。

路径 C — 移除规则的计划

echo '{
  "scheduleRules": [
    { "timestamp": null, "enabled": true },
    { "timestamp": null, "enabled": false }
  ],
  "scheduleType": "none"
}' | gb-call PUT /api/v2/features/<flag-id>/revisions/new/rules/<rule-id> -

将所有时间戳设为 null 并将 scheduleType 设为 "none"，即可清除计划。该规则将始终处于激活状态（受其 enabled 字段和条件约束）。

注意事项

• 草稿版本沿用。 如果本次会话中之前的写入技能已提供版本号，请明确使用该版本号（例如 .../revisions/42/rules），而不是 new。这样可以让所有更改保留在同一份草稿中。开始新的草稿时，才使用 new。
• 关闭状态由 defaultValue 决定，而不是由切换操作决定。 调度在规则层级生效——在活动时段之外，规则会被跳过，标记会回退到 defaultValue。发布前务必确认 defaultValue 是预期的关闭状态。
• 将新建的定时规则放在最后。 规则按从上到下的顺序评估；未激活的定时规则会被直接跳过。如果它下方的另一条规则无条件提供开启值，那么在非活动时段就会触发该规则。新建规则时，放在最后最安全。
• API 接受带时区偏移量的 ISO 8601 格式。 使用用户本地时区的偏移量格式发送时间，例如："2026-12-26T00:00:00-05:00"。无需转换为 UTC。构建请求载荷前，先与用户确认解析后的日期时间——绝不能默认假定时区。
• 明确解析自然语言时间。 对于相对日期（“明天”“下周五”），使用上下文中的 currentDate。对于含糊的表述（“圣诞节之后马上”“促销结束时”），继续操作前先与用户确认确切日期和时间。
• scheduleRules 是一个包含 2 个元素的数组。 元素 0 = 开始事件（enabled: true），元素 1 = 结束事件（enabled: false）。服务端会强制要求这种结构——它不是由任意事件组成的列表。
• 新建规则时使用 schedule 字段，修补现有规则时使用 scheduleRules。
• 定时规则的 enabled 必须为 true。 在评估周期内，调度控制规则何时生效；但如果规则的 enabled 为 false，则会完全覆盖调度设置。
• 发布后，调度才会生效。 如果发布因审批而延迟，且开始时间在修订上线前已过，那么该规则会在发布时立即生效，而不是在预定时间生效。
• 对于多阶段渐进式发布，请使用 flag-ramp。 此技能仅处理开启/关闭时段。

使用的端点

• GET /api/v2/features/:id — 获取标记和当前规则
• POST /api/v2/features/:id/revisions/new/rules — 使用 schedule 字段创建规则（请求体包含 rule + schedule）
• PUT /api/v2/features/:id/revisions/new/rules/:ruleId — 修补现有规则的 scheduleRules 和 scheduleType

后续交接

• flag-targeting — 在调度之外构建规则的定向条件
• flag-ramp — 用于分阶段提高覆盖范围、且阶段之间设有间隔的渐进式发布
• flag-rules — 添加定时规则后重新排列规则
• flag-publish — 发布草稿