update-ui-inventory

更新 UI 清单技能

何时启用

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

• 向引擎添加新的 UI 组件
• 移除或弃用组件
• 组件清单 CI 检查失败
• 想要验证文档中的组件数量是否与实际数量一致
• 合并添加或移除组件的 PR 后

涉及的文件

文件	用途
.github/component-inventory.json	组件数量的唯一事实来源
docs/design-system/COMPONENT-REFERENCE.md	面向用户的组件文档
libs/engine/src/lib/ui/components/	实际组件源文件

清单结构

清单跟踪 13 个组件类别：

{
	"components": {
		"total": 186,
		"breakdown": {
			"primitives": 45,
			"nature": 64,
			"ui": 29,
			"typography": 11,
			"chrome": 6,
			"terrarium": 7,
			"gallery": 4,
			"charts": 4,
			"content": 4,
			"states": 4,
			"forms": 3,
			"indicators": 3,
			"icons": 2
		}
	}
}

分步流程

1. 统计各类别中的组件数量

运行以下命令获取实际数量：

# Count .svelte files in each category
for dir in primitives nature ui typography chrome terrarium gallery charts content states forms indicators icons; do
  count=$(find libs/engine/src/lib/ui/components/$dir -name "*.svelte" 2>/dev/null | wc -l | tr -d ' ')
  echo "$dir: $count"
done

2. 与清单进行比较

读取当前清单并进行比较：

cat .github/component-inventory.json

3. 找出差异

检查以下情况：

• 新增组件：文件已存在，但未计入数量
• 已移除组件：数量包含了已不存在的文件
• 已移动组件：组件被移至其他类别

4. 更新清单 JSON

编辑 .github/component-inventory.json：

{
  "lastUpdated": "YYYY-MM-DD",
  "lastAuditedBy": "claude/<context>",
  "components": {
    "total": <sum of all categories>,
    "breakdown": {
      "<category>": <new count>,
      ...
    }
  }
}

5. 更新组件参考文档

编辑 docs/design-system/COMPONENT-REFERENCE.md：

1. 更新简介行：

   > 186 components organized by category...
   

2. 更新快速链接（锚点链接中包含数量）：

   - [ui/ - Core UI Components](#ui---core-ui-components-29)
   

3. 更新章节标题：

   ## ui/ - Core UI Components (29)
   

4. 将新组件添加到相关表格中（如果比较重要）： 对于 Glass 组件，将其添加到“其他 Glass 组件”表格中：

   | `GlassNewComponent` | Description of what it does |
   

5. 更新底部的最后更新日期：

   _Last updated: YYYY-MM-DD_
   

6. 提交更改

git add .github/component-inventory.json docs/design-system/COMPONENT-REFERENCE.md
git commit -m "docs: update component inventory

- Update <category> count: X -> Y
- Add <ComponentName> to COMPONENT-REFERENCE.md
- Bump total: A -> B"

快速参考：统计命令

# Single category count
find libs/engine/src/lib/ui/components/ui -name "*.svelte" | wc -l

# List all files in a category (to identify new ones)
ls libs/engine/src/lib/ui/components/ui/*.svelte

# Find Glass components specifically
ls libs/engine/src/lib/ui/components/ui/ | grep -i glass

# Total across all categories
find libs/engine/src/lib/ui/components -name "*.svelte" | wc -l

文档编写指南

向 COMPONENT-REFERENCE.md 添加组件时：

Glass 组件（始终记录）

Glass 组件定义了 Grove 的视觉语言——始终将其添加到“其他 Glass 组件”表格中，并附上清晰的说明。

标准组件

如果是通用包装器，则将其添加到“标准组件”表格中。

专用组件

对于特定类别的组件（自然、图表等），如果它比较重要或具有值得记录的独特属性，则将其添加到相应章节。

示例：添加新的 Glass 组件

添加 GlassStatusWidget.svelte 后：

1. 确认统计结果显示 ui 从 28 增至 29

2. 更新清单：

   "ui": 29,
   "total": 186,
   "lastUpdated": "2026-01-21"
   

3. 更新 COMPONENT-REFERENCE.md：

   • 第 3 行：> 186 components...
   • 第 13 行：- [ui/ - Core UI Components](#ui---core-ui-components-29)
   • 第 74 行：## ui/ - Core UI Components (29)
   • 在第 209 行之后，将以下内容添加到表格中：

     | `GlassStatusWidget` | 具有自动刷新的实时状态小组件 |
     

   • 最后一行：*Last updated: 2026-01-21*

CI 集成

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

• 在涉及 libs/engine/src/lib/ui/components/** 的 PR 中运行
• 统计实际组件数量，并与清单进行比较
• 数量不一致时失败
• 提供有助于排查问题的输出，显示差异

CI 失败时，运行此技能以修复差异。

检查清单

完成前，请确认：

• 所有类别的数量都与实际文件数量一致
• 总数等于所有类别数量之和
• lastUpdated 日期为今天
• COMPONENT-REFERENCE.md 中的数量与清单一致
• 已将重要的新组件添加到相应的文档表格中
• 如果章节标题发生变化，已更新快速链接锚点
• 已使用描述性消息提交更改