# 画个标 · 素材与技能库读取指南（AI / 外部项目专用）

> 本目录是「画个标」系统对外暴露的**机器可读出口**：三份 JSON manifest + 本指南。
> 其他项目或 AI 要复用本库的素材/技能，**先读本指南 + 对应 manifest，再按需定向读数据文件**，即可准确命中，无需猜测文件名或解析大体积 JS 索引。

## 一、库里有什么（三套资源）

| 库 | manifest | 数据文件 | 数量（以对应 manifest 的 `total` 为准） |
|---|---|---|---|
| 共享图标库（LOGO/头像） | [icons.json](icons.json) | `js/data/sources/{id}.js` + `js/data/builtin-icons.js` | 222 源 / 370,268 图标 |
| 头像风格（DiceBear） | [icons.json](icons.json)（`dicebear` 字段） | `js/data/sources/dicebear-{style}.js` | 55 风格 |
| 海报素材库 | [posters.json](posters.json) | `js/data/posters/{id}.js` + `js/data/posters/{id}/files/` | 25 源 / 1,582 素材 |
| 共享技能 | [skills.json](skills.json)（`shared`） | 实现代码 `js/skills/*.js` | 48 个 / 7 类 |
| 海报技能 | [skills.json](skills.json)（`poster`） | 实现代码 `js/poster-skills/*.js` | 56 个 / 8 类 |
| 表情技能 | [skills.json](skills.json)（`sticker`） | 实现代码 `js/sticker-skills/*.js` | 12 个 / 2 类 |

> 注：上表数量为快照，**一切以对应 manifest 内的 `total` / `count` 字段为准**（构建时自动更新，本 README 为手写维护）。

## 二、manifest 结构（标准字段）

### icons.json / posters.json
```json
{
  "kind": "icons",                  // icons | posters
  "total": 367988,                  // 库内素材总数
  "builtAt": "2026-08-23T…",        // 构建时间（ISO）
  "idRule": "「源:名称」，如 lucide:graduation-cap",
  "sources": [                      // 每个源一条（含实际内置数 count）
    {
      "id": "lucide", "type": "icon",   // type: icon/emoji/brand（海报: palette/font/bg/decoration…）
      "name": "Lucide Icons", "nameCn": "Lucide 图标",
      "desc": "…", "style": "线条",
      "license": "ISC", "licenseNote": "…",   // 协议务必先读，商用需合规
      "home": "…", "github": "…", "npm": "…",
      "format": "sprite",            // 拉取方式：iconify/dir-files/gh-files/sprite/nodes/remix-files
      "coordText": "24 坐标", "variants": "…", "added": "2026-08-10",
      "count": 1767,                 // 该源实际内置数
      "file": "sources/lucide.js",   // 该源数据文件相对路径（js/data/ 下）
      "workspaces": ["logo","avatar"]
    }
  ]
}
```
- **图标 id 规范**：内置库 `源:名称`（`lucide:graduation-cap`）；行业图标为裸 id。
- **数据文件** `js/data/sources/{id}.js` 内容形态：`window['HGB_Source_{id}'] = { icons: [{ id, name, categoryCn, svg, type }] }`。`svg` 为归一化到 24 viewBox 的 body 片段（含 path/几何），渲染时套 `<svg viewBox="0 0 24 24">`。
- **头像**：`js/data/sources/dicebear-{style}.js` = `window.HGB_Dicebear_{style} = {…DiceBear 定义…}`（渲染器规则见 DiceBear 官方 schema）。

### posters.json
- **素材 id**：`源:相对路径`（如 `fontsource-inter:latin-400-normal.woff2`）。
- 数据文件 `js/data/posters/{id}.js` = `window['HGB_PosterSource_{id}'] = { items: [{ id, name, categoryCn, type, svg?|file?|data? }] }`；二进制（字体/位图）在 `js/data/posters/{id}/files/` 按 `file` 引用直读；配色为内联 `data`。

### skills.json
```json
{
  "kind": "skills",
  "shared": {
    "total": 48,
    "skills": [{
      "id": "contrast-check", "name": "对比度检查", "category": "color",
      "emoji": "🎨", "scene": "…", "summary": "…", "params": "…", "source": "自研",
      "step": 3,          // 设计流水线步骤 1品牌洞察/2方案生成/3方案评审/4迭代优化/5交付导出
      "kind": "check",    // gen 生成建议 / check 方案检查 / deliver 交付导出
      "workspaces": ["logo","avatar","poster"]
    }]
  },
  "poster": { "total": 56, "skills": [ …同字段（无 step/kind，按 category 8 类）… ] },
  "sticker": { "total": 12, "skills": [ …同字段（无 step/kind，按 category motion/emotion 2 类）… ] }
}
```
- 技能元数据是纯数据可直接当知识用；**run/test 是函数实现**，仅供系统执行（`HGB_Skills.run(id, args)` / `HGB_Skills.test(id)`），外部如需「执行技能」请加载 `js/skills/*.js`（含数据依赖）后调用 API。
- 表情技能（`sticker`）实现代码 `js/sticker-skills/*.js`，API 为 `HGB_StickerSkills.run(id, args)` / `HGB_StickerSkills.test(id)`，`workspaces` 统一 `["emoji"]`；其动画决策依赖 `js/core/motion.js`（ANIMS 注册表，预览与导出逐帧采样共用同一套 `apply`）。

## 三、AI 推荐读取流程

1. 先读本指南（README.md）了解库结构与 id 规范；
2. 读对应 manifest 定位「有哪些源 / 每源多少 / 协议是否合规」；
3. 需要具体素材时，按 manifest 的 `file` 字段定向读 `js/data/sources/{id}.js`（或 `posters/{id}.js`），避免读 2.4MB 单行索引 `builtin-icons.js`；
4. 协议存疑（BY-SA/BY-NC/BY-ND/GPL）不商用；多色源（type emoji/brand）保留原色。

## 四、维护（构建后 manifest 自动更新）

- 图标：`node scripts/build-icons.js` → 重写 `builtin-icons.js` + `sources/{id}.js` + `manifest/icons.json`
- 海报：`node scripts/build-posters.js` → 重写 `poster-builtin.js` + `posters/{id}.js` + `manifest/posters.json`
- 技能：`node scripts/build-skill-manifest.js` → 重写 `manifest/skills.json`（技能元数据；技能代码改动后需重跑）
- 前端页面 sources.html / poster-sources.html 优先读 manifest（fetch 失败自动回退内置配置），skills 页面直接读技能 API（与 manifest 同源）。