flag-review

flag-review

针对 GrowthBook 功能标志草稿修订版请求并提交审批评审。仅当组织配置了审批工作流时才需要此操作；如果不需要审批，flag-publish 会处理完整流程，无需评审步骤。

此技能有两种角色：起草者（请求评审，不能自行批准）和评审者（提交评审决定）。

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

审批流程

draft → [request-review] → pending-review → [approve]           → approved → [publish]
                                           → [request-changes]  → changes-requested → [edit + re-request] → pending-review
                                           → [comment]          → pending-review (status unchanged)

工作流

路径 A — 请求评审（起草者请求审批）

1. 确定修订版。如果用户提供了版本号，则使用该版本号。否则先尝试 /latest（仅有一个草稿时的理想路径），必要时再回退到列表查询：

   gb-call GET /api/v2/features/<id>/revisions/latest
   # or if version is known:
   gb-call GET /api/v2/features/<id>/revisions/<version>
   

   接受 draft 或 changes-requested 状态。对于其他任何状态，展示该状态，并使用 flag-revisions 中的状态表说明其含义。

2. 请求评审：

   echo '{"comment":"<optional context for reviewers>"}' \
     | gb-call POST /api/v2/features/<id>/revisions/<version>/request-review -
   

   修订版将变为 pending-review。告知用户，必须有评审者批准后，才能通过 flag-publish 发布。提醒用户不能自行批准，必须由其他团队成员进行评审。

路径 B — 提交评审（评审者处理处于 pending-review 状态的修订版）

1. 确定修订版。仅有版本号还不够——还需要功能标志 ID（版本号是每个功能标志独立计数的，并非全局唯一）。收集用户已有的信息，然后据此查询：

   已知功能标志 ID 和版本号 → 直接获取：

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

   已知功能标志 ID，版本号未知 → 列出该功能标志上处于 pending-review 状态的修订版：

   gb-call GET '/api/v2/features/<id>/revisions?status=pending-review'
   

   已知作者邮箱或 userId → 按作者跨功能筛选：

   gb-call GET '/api/v2/flag-revisions?status=pending-review&author=<email-or-userid>'
   

   已知作者姓名，但不知道邮箱 → 获取所有处于 pending-review 状态的修订版，并在客户端根据 createdBy 匹配姓名进行筛选：

   gb-call GET '/api/v2/flag-revisions?status=pending-review'
   

   每个修订版都有一个 createdBy 字段（显示名称或 "API"）。筛选出 createdBy 包含用户提供姓名的条目，然后在继续操作前向用户确认。

   没有任何已知信息 → 执行相同的广泛查询，展示所有结果并请用户确认哪个是自己的。

2. 对于任何不简单的情况，先提出打开 GrowthBook UI——并排差异对比和审批控件比文本更清晰：

   # macOS:
   open <host>/features/<flag-id>?v=<version>
   # Linux:
   xdg-open <host>/features/<flag-id>?v=<version>
   

   从 GB_API_URL 推导 <host>，将 api. 替换为 app.。如果评审者更愿意在 UI 中操作，则在此处停止。

   对于基于 API 的评审，获取修订版和线上功能，以展示完整的前后差异：

   gb-call GET /api/v2/features/<id>/revisions/<version>   # draft state
   gb-call GET /api/v2/features/<id>                       # current live state
   

   展示以下内容：规则（新增／编辑／删除）的变化、defaultValue 变化、元数据变化、环境开关变化、前置条件变化——比较草稿字段与线上功能。

3. 询问评审者希望执行哪项操作：

   • approve — 变更看起来没问题，可以发布
   • request-changes — 发现问题，需要作者更新
   • comment — 仅提供反馈，不更改状态

4. 提交评审：

   echo '{"action":"approve","comment":"<optional>"}' \
     | gb-call POST /api/v2/features/<id>/revisions/<version>/submit-review -
   

   状态转换：

   • approve → approved — 告知用户通过 flag-publish 发布
   • request-changes → changes-requested — 告知评审者接下来会发生什么（作者编辑后重新请求评审）
   • comment → 保持 pending-review 不变 — 记录评论

路径 C — 检查评审状态

如果不知道版本号，先尝试 /latest：

gb-call GET /api/v2/features/<id>/revisions/latest
# or with a known version:
gb-call GET /api/v2/features/<id>/revisions/<version>

报告状态以及接下来需要采取的操作：

状态	下一步
draft	作者准备好后请求评审
pending-review	评审者提交决定
approved	作者通过 flag-publish 发布
changes-requested	作者编辑草稿，然后重新请求评审

审核规范

• 服务端禁止自我审批。 API 会拒绝由草稿作者本人提交的审核。如果用户提到草稿是自己创建的，请在调用 submit-review 前停止：“这是你创建的草稿 — 必须由其他团队成员审批。”否则，由服务端执行此规则；如果触发错误，请将错误告知用户。
• 只有状态为 draft 或 changes-requested 时才能请求审核。 如果用户尝试对其他状态的草稿请求审核，请告知其实际状态。
• 只有状态为 pending-review 时才能提交审核。 如果状态不符，请告知其实际状态。
• changes-requested 不代表草稿已丢弃。 草稿仍然存在；作者应编辑草稿，然后通过路径 A 再次请求审核。除非作者明确表示要放弃这些更改，否则不要建议丢弃草稿。
• 更改时重置审核状态。 如果组织启用了此设置，对 approved 草稿进行任何编辑都会将其状态重置为 draft。如果用户即将编辑已批准的修订版本，请提醒：“编辑此修订版本会重置其审批状态 — 你需要再次请求审核。”
• 审批 ≠ 发布。 状态为 approved 的草稿尚未上线。作者仍需运行 flag-publish。
• 此技能不会发布。 审批完成后，请交由 flag-publish 处理。

使用的端点

• GET /api/v2/features/:id/revisions/:version — 操作前检查修订版本
• GET /api/v2/features/:id/revisions（状态筛选）— 查找某个功能标记中待审核的修订版本
• GET /api/v2/flag-revisions（状态、mine 筛选）— 查找所有功能标记中待审核的修订版本
• POST /api/v2/features/:id/revisions/:version/request-review（请求正文：可选评论）
• POST /api/v2/features/:id/revisions/:version/submit-review（请求正文：操作 + 可选评论）

交接

• flag-revisions — 列出并检查所有未完成的草稿
• flag-publish — 审批完成后，将草稿发布上线