用途:在通过 SQL 迁移新增、移除或废弃 graft(Grove 对功能开关的称呼)后,保持 graft 清单与生产环境一致;也可在 graft-inventory CI 检查失败或需要核对清单与生产 D1 时使用。
涉及文件:.github/graft-inventory.json(计数与元数据的唯一来源)、libs/engine/migrations/*.sql(定义 graft 的迁移)、libs/engine/src/lib/platform/feature-flags/flags.ts(KnownFlagId 类型定义)、docs/guides/adding-grafts-and-flags.md(开发者指南)。清单记录 grafts 总数、platform/greenhouse 分解、byType 类型统计,以及每个 flag 的 id、name、type、greenhouseOnly、migration、description。
主要流程:从迁移的 INSERT 语句提取 flag ID;用 wrangler 查询生产库;与清单比对找出新增、移除或元数据变化的 graft;更新清单计数、flags 数组、lastUpdated 与 lastAuditedBy;同步更新 KnownFlagId 类型;一并提交。
常用命令: grep -hoP "INSERT OR IGNORE INTO feature_flags.?VALUES\s(\s*'\K[a-z_]+" libs/engine/migrations/*.sql | sort -u npx wrangler d1 execute grove-engine-db --remote --command="SELECT id, name, flag_type, greenhouse_only, enabled FROM feature_flags ORDER BY id;" cat .github/graft-inventory.json | jq '.flags[].id' | sort git add .github/graft-inventory.json libs/engine/src/lib/platform/feature-flags/flags.ts
CI:graft-inventory.yml 在涉及迁移或 feature-flags 的 PR 上运行,解析 INSERT 语句并与清单计数比对,不一致时评论 PR;定时任务(周三)发现漂移会创建 issue。
限制与校验:完成前需确认生产 D1 数量与清单总数一致、D1 中所有 flag 在清单中均有条目、KnownFlagId 覆盖全部 ID、日期为当天、总数等于 platform 加 greenhouse、类型统计准确。若数量不匹配,可能需应用相应迁移。其他细节资料未提供。