Add app details and icon cache (T-204)

docs/api.md

@@ -76,6 +76,19 @@
 
 T-201 已把该签名域接入正式客户端加载链路并用客户端测试向量覆盖。`softbox-catalog` 发布端仍必须补跨实现向量测试;密钥 ID/轮换字段尚未定稿,在单公钥协议升级前不得另造签名域。
 
+### 1.2 图标内容引用与本地缓存
+
+Catalog `icon` v1 是 `sha256:<64 hex>` 内容引用,不是可直接请求的 URL。最终分发字段仍由发布端定稿;客户端通过注入的 IconFetcher 把引用解析为图标字节,不得在 UI 中拼接或猜测 URL。
+
+客户端缓存合约:
+
+1. 请求键为 `(icon digest, DPI)`;DPI 接受 48～768 的整数值。
+2. 加载顺序为内存 → 磁盘 → 注入 Fetcher;磁盘文件名为 `<digest>-<dpi>.icon`。
+3. 远端和磁盘字节都必须复核 SHA-256,并通过图片解码、2 MiB 默认字节上限与 2048×2048 默认尺寸上限。
+4. 只有验证成功的远端字节可用同目录临时文件原子写入磁盘;损坏的普通缓存文件删除后可重新获取,symlink/非普通文件按不安全布局拒绝。
+5. 新进程断网时可读取再次验证成功的磁盘缓存;缓存损坏且远端不可用时返回 `no valid icon available`,UI 使用稳定占位图。
+6. 后台完成 `IconCache.Load` 与 `DecodeIcon` 后调用 Gio `ApplyIcon`;Layout 只复用内存 `paint.ImageOp`。
+
 ## 2. 标准软件包协议 v1(ZIP)
 
 ```text
@@ -267,6 +280,6 @@ V1.1:命名管道 `\\.\pipe\softbox.<app-id>`,盒子发送 `{"command": "prepare
 
 - 清单密钥 ID/轮换字段定稿后同步 `schemas/`。
 - 错误码完整枚举表。
-- 图标资源的分发方式(内嵌哈希 vs 独立 URL)。
+- 图标资源从内容哈希到下载位置/分辨率变体的发布端映射格式。
 - 撤销名单的结构与宽限期时长。
 - machine_hash 的标识来源清单与加权算法(平台层内部文档)。