flag-metadata

flag-metadata

更新现有 GrowthBook 功能标志的管理元数据。与其他所有标志变更一样，元数据变更（描述、所有者、项目、标签、自定义字段、JSON 架构）会经过草稿修订版 — 必须先发布才会生效。

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

必填输入

开始前收集：

• 标志 ID — kebab-case 键。如果用户提供的是描述，先使用 flag-search 解析。
• 要更改的内容 — 以下一项或多项：description、owner、project、tags、neverStale、customFields、jsonSchema。

工作流

1. 获取当前元数据

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

向用户展示他们即将更改的字段的当前值。在修改之前，确认拟议的新值。

2. 解析项目 ID（如果要更改项目）

API 不接受项目名称 — 先将名称解析为 ID：

gb-call GET /api/v1/projects

将用户提供的项目名称与返回列表匹配，并使用 id 字段。

3. 通过草稿应用元数据变更

echo '<payload>' | gb-call PUT /api/v2/features/<flag-id>/revisions/new/metadata -

new 这个特殊版本会创建一个新草稿，或以原子方式叠加到现有草稿上。

支持的字段及其类型：

{
  "description": "<string>",
  "owner": "<email or u_... userId>",
  "project": "<project-id or empty string to clear>",
  "tags": ["<tag>", "<tag>"],
  "neverStale": true,
  "customFields": { "<key>": "<value>" },
  "jsonSchema": { "<json-schema-object>" }
}

仅发送用户想要更改的字段。不要回传未更改的字段。

记录返回的 version 编号，以用于发布步骤。

4. 提议发布

询问：“现在发布此元数据变更，还是保留为草稿？”

元数据变更风险较低 — 默认立即提议发布。将发布步骤交给 flag-publish 处理，包括任何所需审批或合并冲突的处理。

防护措施

• 草稿版本传递。 如果本次会话中先前写入技能的上下文已有版本号，请明确使用该版本（例如 .../revisions/42/metadata），而不是 new。这样可确保所有变更都在同一草稿中。若是全新操作，则使用 new — 它会自动创建或复用最近更新的开放草稿。
• owner 接受电子邮件或 u_... 用户 ID。 请向用户索取要分配给的人员的电子邮件或用户 ID。如果他们想分配给自己，请索取其电子邮件或用户 ID — 没有可读取的环境变量默认值。如果用户提供的是姓名而非电子邮件，请要求澄清 — API 不接受显示名称。
• project 是 ID，不是名称。 设置前务必通过 GET /api/v1/projects 解析项目名称。空字符串 "" 会清除项目关联（将标志移回组织级范围）。
• tags 会替换整个数组。 它不是追加操作 — 如果标志已有标签，而用户只想添加一个，请先获取当前标签，追加后发送完整的更新数组。
• neverStale: true 会永久让该标志退出过期检测。 适用于紧急关闭开关、运维切换项和许可证门控。请提醒用户：设置后，即使数月未触碰，该标志也不会出现在过期标志报告中。
• jsonSchema 仅限企业版。 如果组织未启用此功能，API 会返回错误 — 请明确告知用户。
• 元数据变更仍会经过审批工作流。 看似无关紧要的描述变更也可能触发组织的审核关卡。请使用 flag-publish，并预期会遇到与其他修订版相同的所需审批／合并冲突失败情况。
• customFields 键必须与组织配置的自定义字段定义相匹配。 如果组织无法识别该键，API 可能会静默丢弃或报错。请确认自定义字段键名称正确。

使用的端点

• GET /api/v2/features/:id — 获取当前元数据以供确认
• GET /api/v1/projects — 将项目名称解析为 ID
• PUT /api/v2/features/:id/revisions/new/metadata — 将元数据变更应用到草稿

交接

• flag-search — 如果用户提供的是描述，而不是标志 ID
• flag-default-value — 更改没有规则匹配时标志所提供的内容
• flag-cleanup — 完全归档或删除标志
• flag-publish — 发布草稿，并处理需要审批的情况（400）和合并冲突（409）