# Leego Icon Service · 2.28.0
通用 `ui.*` 已更新为136项B1/B3双版本：`outline`默认纯线、`solid`纯面；`mono`与`outline`哈希相同，兼容已有引用。完整几何、尺寸与语义迁移见 [通用图标家族](common-icon-family.md)。库发布不自动修正业务中错误借用的ID。
接入前先请求下述 stable 地址，确认可用版本与目录哈希。2.25.0 的本地实现/安装不等于公网已发布；发布未完成或端点不可达时使用已校验的本地资产，不把计划中的生产地址当已可用服务。
六款 `system.*` 使用 V018 家族（产品中心为 V019 扩展）。将远端条目的 variant SHA-256 与 `assets/system-identity-family.json` 对照；若远端仍是旧版，不用旧图替代，使用本地 `assets/icons/system-identities/` 已校验文件。当前目录快照另见 `assets/icon-library.json`。2.25.4 修复目录绑定漏更新，是否上线仍须核验公网实际哈希。
## 选择与复用
官网图标库： https://smalltypeui.qiaokiai.com/skills/leego-design-ui/site/icons
接入文档： https://smalltypeui.qiaokiai.com/skills/leego-design-ui/site/icons/docs
先按语义查询目录与稳定 ID，使用真实存在的版本，不重画已采纳品牌，不为每个业务项目复制整套资产。兼容的历史 Skill 资产暂保留；新项目首选远程图像与本地小适配器。没有远程能力时使用关键本地回退，不阻塞主要任务。
API 根地址：`https://smalltypeui.qiaokiai.com/skills/leego-design-ui/site/icon-api/v1`。
| GET 路径 | 结果与缓存 |
|---|---|
| `/channels/stable.json` | 当前版本、目录 URL、SHA-256；60秒后重新验证 |
| `/releases/2.25.0.json` | 固定目录快照；一年 immutable |
| `/icons/skill.leego-ui/app` | 307 到当前原件；60秒缓存；适合独立图片 |
| `/assets/{sha256}.{svg\|png\|webp}` | 不可变原件；一年缓存，ETag |
支持 GET/HEAD/OPTIONS、匿名跨域 CORS、If-None-Match → 304；无凭证、无遥测。未知 ID/版本/格式为404，参考素材为403，不存在的变体为404；响应 JSON `{error: "..."}`。错误不缓存。API v1 是协议版本，不是设计资产版本。
目录包含 `schemaVersion/version/base/categories/entries`。每项包括 `id/label/aliases/category/source/rights/defaultVariant/variants`；变体包含相对 `url/sha256/format/bytes`。`reference-only` 条目没有可调用资产，不允许用官网参考原图绕过此限制。
## Web
单张静态 HTML 可用稳定链接：
```html
```
整套系统使用 [client.ts](../assets/icon-service/client.ts) 与 [LeegoIcon.tsx](../assets/icon-service/LeegoIcon.tsx) 本地审阅后随应用打包，不从 stable 下载执行 JS。并非已发布 npm 包。
```tsx
import {loadIconSnapshot} from './icons/client';
import {LeegoIcon, LeegoIconContext} from './icons/LeegoIcon';
// 浏览器启动阶段，只加载一次；SSR 阶段使用已固定的初始目录或关键本地回退。
const {snapshot, fromCache} = await loadIconSnapshot({storage: localStorage});
// 在应用入口提供同一 snapshot；不要让每个图标单独拉目录。
```
快照按启动/刷新/用户允许的安全边界更换，不能在操作中热替换品牌家族。`fromCache` 表示最近一次验证成功的目录；它不保证此前从未加载过的图片离线可用。适配器校验目录哈希和资产URL，目录缓存失败则保留内存；原件依赖浏览器 HTTP 缓存。关键导航传入本地 `fallback`。固定版本传 `{version:'2.25.0'}`。
品牌用 `![]()
` 保真。通用单色图标可通过受信来源的 CSS mask 使用 `currentColor`；不要依赖跨域 SVG `