update-graft-inventory

更新 Graft 清单技能

何时启用

在以下情况下启用此技能：

• 通过 SQL 迁移添加新的功能标志
• 移除或弃用 graft
• graft 清单 CI 检查失败
• 想要验证清单是否与生产环境中的 D1 一致
• 应用添加 graft 的迁移后

涉及的文件

文件	用途
.github/graft-inventory.json	graft 计数和元数据的唯一事实来源
libs/engine/migrations/*.sql	定义 graft 的迁移文件
libs/engine/src/lib/platform/feature-flags/flags.ts	类型定义（KnownFlagId）
docs/guides/adding-grafts-and-flags.md	开发者指南（graft 是 Grove 对功能标志的称呼）

清单结构

清单会记录 graft 的完整元数据：

{
	"grafts": {
		"total": 10,
		"breakdown": {
			"platform": 8,
			"greenhouse": 2
		},
		"byType": {
			"boolean": 9,
			"number": 1
		}
	},
	"flags": [
		{
			"id": "fireside_mode",
			"name": "Fireside Mode",
			"type": "boolean",
			"greenhouseOnly": true,
			"migration": "040_fireside_scribe_grafts.sql",
			"description": "AI-assisted writing prompts"
		}
	]
}

分步流程

1. 从迁移中列出 Graft

# Extract all flag IDs from migration INSERT statements
grep -hoP "INSERT OR IGNORE INTO feature_flags.*?VALUES\s*\(\s*'\K[a-z_]+" libs/engine/migrations/*.sql | sort -u

2. 查询生产环境中的 D1

# Get actual flags from production database
npx wrangler d1 execute grove-engine-db --remote --command="SELECT id, name, flag_type, greenhouse_only, enabled FROM feature_flags ORDER BY id;"

3. 与清单进行比较

# Read current inventory
cat .github/graft-inventory.json | jq '.flags[].id' | sort

4. 找出差异

请查找以下情况：

• 新增 graft：存在于迁移文件或 D1 中，但不在清单中
• 已移除的 graft：存在于清单中，但不在 D1 中
• 元数据已更改：类型、greenhouse_only 或描述发生了变化

5. 更新清单 JSON

编辑 .github/graft-inventory.json：

1. 更新计数：

   "grafts": {
     "total": <new count>,
     "breakdown": {
       "platform": <non-greenhouse count>,
       "greenhouse": <greenhouse_only count>
     }
   }
   

2. 添加/移除标志条目：

   "flags": [
     {
       "id": "new_flag_id",
       "name": "Human Readable Name",
       "type": "boolean",
       "greenhouseOnly": false,
       "migration": "XXX_migration_name.sql",
       "description": "What this flag controls"
     }
   ]
   

3. 更新元数据：

   "lastUpdated": "YYYY-MM-DD",
   "lastAuditedBy": "claude/<context>"
   

6. 更新 KnownFlagId 类型

编辑 libs/engine/src/lib/platform/feature-flags/flags.ts：

export type KnownFlagId =
	| "fireside_mode"
	| "scribe_mode"
	| "meadow_access"
	| "jxl_encoding"
	| "jxl_kill_switch"
	| "new_flag_id"; // Add new flag

7. 提交更改

git add .github/graft-inventory.json libs/engine/src/lib/platform/feature-flags/flags.ts
git commit -m "docs: update graft inventory

- Add <flag_id> to inventory
- Update total: X -> Y
- Update KnownFlagId type"

快速参考命令

# Count grafts in migrations
grep -c "INSERT OR IGNORE INTO feature_flags" libs/engine/migrations/*.sql | awk -F: '{sum+=$2} END {print sum}'

# List all flag IDs
grep -hoP "INSERT OR IGNORE INTO feature_flags.*?VALUES\s*\(\s*'\K[a-z_]+" libs/engine/migrations/*.sql | sort -u

# Count greenhouse-only grafts
npx wrangler d1 execute grove-engine-db --remote --command="SELECT COUNT(*) FROM feature_flags WHERE greenhouse_only = 1;"

# Full flag details from production
npx wrangler d1 execute grove-engine-db --remote --command="SELECT * FROM feature_flags ORDER BY id;"

# Check which migrations haven't been applied
# Compare migration file flag IDs vs production D1 flag IDs

添加新 Graft（完整检查清单）

添加新 graft 时：

• 创建迁移文件：libs/engine/migrations/XXX_name.sql
• 应用迁移：npx wrangler d1 execute grove-engine-db --remote --file=...
• 在 flags.ts 的 KnownFlagId 类型中添加该标志
• 在 .github/graft-inventory.json 的 flags 数组中添加条目
• 更新清单计数（total、breakdown.platform/greenhouse、byType）
• 更新 lastUpdated 和 lastAuditedBy
• 一并提交所有更改

验证生产环境同步情况

更新后，验证生产环境是否一致：

# Expected count
jq '.grafts.total' .github/graft-inventory.json

# Actual count in production
npx wrangler d1 execute grove-engine-db --remote --command="SELECT COUNT(*) as count FROM feature_flags;"

如果不一致，可能需要应用迁移：

# Apply a specific migration
npx wrangler d1 execute grove-engine-db --remote --file=libs/engine/migrations/XXX_name.sql

CI 集成

.github/workflows/graft-inventory.yml 工作流：

• 在涉及 libs/engine/migrations/*.sql 的 PR 上运行
• 在涉及 libs/engine/src/lib/feature-flags/** 的 PR 上运行
• 解析迁移文件中的 INSERT 语句
• 将计数与清单进行比较
• 出现不匹配时在 PR 上发表评论
• 在定期运行时（周三）为偏差创建问题

CI 失败时，运行此技能以修复不匹配。

检查清单

完成前：

• 生产环境中的 D1 graft 计数与清单中的 total 一致
• D1 中的所有标志都在清单的 flags 数组中有对应条目
• KnownFlagId 类型包含所有标志 ID
• lastUpdated 日期为今天
• 计数总和正确：total = platform + greenhouse
• 类型细分准确
• 使用描述性消息提交更改