86 lines
5.7 KiB
Markdown
86 lines
5.7 KiB
Markdown
# 画个标 · 素材与技能库读取指南（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 同源）。
|