flag-revisions

flag-revisions

检查并管理 GrowthBook 功能标志的草稿修订。每次功能标志变更都会先经过草稿修订，之后才会生效——这是用于了解“当前有哪些变更正在进行”的技能。使用此技能可以查看未完成的草稿、了解其状态，并管理其生命周期（创建、丢弃）。实际的功能标志变更（规则、元数据、开关、默认值）由相应的 flag-* 写入技能处理，这些技能会自动创建和管理草稿。

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

修订状态参考

状态	含义	接下来会发生什么
draft	正在编辑，尚未提交	继续编辑，然后请求审核或发布
pending-review	已请求审核，等待批准	审核者通过 flag-review 提交决定
approved	已批准，可以发布	通过 flag-publish 发布
changes-requested	审核者指出了问题	作者编辑草稿，然后重新请求审核
published	已生效，不可修改	可以通过 flag-publish 回滚
discarded	已放弃	无需进一步操作
pending-parent	由渐进式发布计划自动管理	不要手动丢弃

工作流

选择与用户请求相符的路径。

路径 A — 列出特定功能的活动草稿

询问用户想查看自己的草稿，还是此功能的所有草稿，然后相应地查询：

# User's own active drafts:
gb-call GET '/api/v2/features/<id>/revisions?status=all-drafts&mine=true'

# All active drafts on this flag:
gb-call GET '/api/v2/features/<id>/revisions?status=all-drafts'

all-drafts 会展开为所有四种活动草稿状态（draft、pending-review、approved、changes-requested）。在 v2 中省略 status 的效果相同。若要指定部分状态：?status=draft,pending-review。

对每个修订展示：版本号、状态、创建者、日期和评论。指出需要处理的事项——pending-review 需要审核者处理，changes-requested 需要作者采取行动。

路径 B — 列出我在所有功能中的草稿

gb-call GET '/api/v2/flag-revisions?mine=true&status=all-drafts'

省略 mine=true 可查看组织中的所有活动草稿。在 v2 中省略 status 时，默认值为 all-drafts。

按功能分组展示结果，便于阅读。说明有多少项需要处理。

路径 C — 检查特定修订

gb-call GET /api/v2/features/<id>/revisions/<version>

展示与当前生效版本相比的变更：defaultValue、rules 数组、元数据字段、各环境的 environmentsEnabled 以及 prerequisites。同时展示 baseVersion（此草稿从哪个生效版本分支而来）和 status。

若要在不知道版本号的情况下获取最近更新的活动草稿，请先询问用户想查看自己的草稿，还是任何人最近更新的草稿——这样可以避免不经意间查看队友的草稿：

# User's own most recent draft:
gb-call GET '/api/v2/features/<id>/revisions/latest?mine=true'

# Most recently updated draft by anyone:
gb-call GET /api/v2/features/<id>/revisions/latest

返回单个修订。如果有多个未完成的草稿，它会静默选择最近更新的一个——要查看全部草稿，请使用路径 A。

路径 D — 创建草稿：隐式与显式

创建草稿有两种方式。两种方式都有效，具体使用哪种取决于情况。

**隐式（所有写入技能的默认方式）：**在任意写入端点中将 new 作为版本传入。服务会自动创建一个新草稿，或将更改叠加到最近更新的未关闭草稿上。

# Example — the "new" magic used in write skills:
echo '<payload>' | gb-call PUT /api/v2/features/<id>/revisions/new/default-value -

适用于：进行单项更改，或只有一个未关闭草稿且叠加更改符合预期的情况。

**显式（先创建，再指定目标）：**先创建一个空白草稿，记录版本号，然后在后续所有写入调用中指定该版本，而不是使用 new。这是一个三阶段流程——不要跳过任何阶段。

阶段 1 — 设置（进行任何标记更改之前）：

echo '{"comment":"<optional intent note>"}' | gb-call POST /api/v2/features/<id>/revisions -
# Returns { revision: { version: <N>, status: "draft", ... } }

记下版本号 <N>。阶段 2 中的所有更改都必须针对此版本。

阶段 2 — 所有标记更改（完成所有更改后再继续）：

使用相关写入技能（flag-targeting、flag-toggle、flag-metadata、flag-default-value、flag-prerequisites 等），在每个端点路径中用 <N> 替换 new：

echo '<payload>' | gb-call PUT /api/v2/features/<id>/revisions/<N>/default-value -
echo '<payload>' | gb-call POST /api/v2/features/<id>/revisions/<N>/rules -
echo '<payload>' | gb-call PUT /api/v2/features/<id>/revisions/<N>/metadata -

在所有预期更改都已应用之前，不要进入阶段 3。

阶段 3 — 发布（仅在所有更改完成后）：

将版本 <N> 交由 flag-publish 处理。

适用于：用户希望创建一个不受现有未关闭草稿影响的全新草稿；进行必须合并到同一修订中的多项协同更改；或存在多个未关闭草稿且需要指定接收编辑内容的草稿。

注意：可在阶段 1 的请求正文中传入 baseVersion，以从指定的已发布修订分支，而不是从当前线上版本分支。

路径 E — 丢弃草稿

gb-call POST /api/v2/features/<id>/revisions/<version>/discard

丢弃前请确认：“要丢弃 <flag-id> 上的修订 <version> 吗？此操作无法撤销——此草稿中的所有待处理更改都会丢失。”

任何非终止状态都可以丢弃——draft、pending-review、approved 和 changes-requested 均可直接丢弃。只有 published 和 discarded 会被服务端阻止。

防护措施

• status 接受逗号分隔的值。?status=draft,approved 会返回匹配任一状态的修订。使用 ?status=all-drafts 可简写为所有四种活动草稿状态。在 v2 端点中，省略 status 时默认为 all-drafts。
• **pending-parent 修订由系统自动管理。**它们会作为渐进发布计划的一部分自动创建和发布。切勿手动丢弃；如果发现某个修订卡住，请联系 GrowthBook 支持团队。
• **一个标记可以有多个未关闭草稿。**始终显示所有草稿——不要假设只有一个。
• **version=new 是标准写入模式。**其他写入技能会使用它以原子方式创建或复用草稿。只有用户希望在编辑前创建空白草稿时，才显式调用 POST /revisions。
• **丢弃操作无法撤销。**草稿及其所有待处理更改都会消失。如果用户在“我会重做”的语境中随口说“丢弃”，请确认他们明白这些更改不会保留。
• **changes-requested ≠ 已丢弃。**草稿仍然存在，可以继续编辑。作者修复问题后，通过 flag-review 再次调用 request-review。
• **此技能仅用于读取和管理。**如需更改标记的规则、元数据、默认值或环境切换，请使用相关写入技能。

使用的端点

• GET /api/v2/features/:id/revisions — 列出某个功能的修订（可按状态、作者、条数和偏移量筛选）
• GET /api/v2/flag-revisions — 列出所有功能的修订（可按本人、状态、功能 ID 和作者筛选）
• GET /api/v2/features/:id/revisions/:version — 检查指定修订
• GET /api/v2/features/:id/revisions/latest — 获取最新草稿（可使用 mine=true 筛选）
• POST /api/v2/features/:id/revisions — 创建新的空白草稿
• POST /api/v2/features/:id/revisions/:version/discard — 丢弃草稿

交接

• flag-review — 请求或提交对草稿的审批审核
• flag-publish — 发布草稿、解决合并冲突，或还原到之前的修订版本
• flag-rules、flag-targeting、flag-toggle、flag-metadata、flag-default-value、flag-prerequisites — 创建和修改草稿的写入技能