dsh-plugin-t-expert 0.4.48 → 0.4.53

package/CHANGELOG.md

@@ -16,6 +16,145 @@
 > 发布时**不要再跑 `npm version`**（那会把已提交好的版本又升一级，发出去的号与 CHANGELOG、tag 就对不上），
 > 只补一个 annotated tag（`git tag -a`，因为 `git push --follow-tags` 只推带注释的 tag）。
 
+## [0.4.53] — 未发布
+
+**面板与 @ 弹窗显示专家头像** —— 0.4.52 只做到数据链路，这一版接上最后一环。
+
+### 做法
+
+- **host**：`lib/index.js` 的 catalog 服务加 `avatars()` —— 扫本地各专家包的
+  `avatars/avatar.webp`，返回 `{ slug: dataUrl }`。**只含已下载过资源的专家**（没下载的本地
+  根本没这个文件，自然不在返回里），这正是「没下载过显示默认头像」的落地方式。
+- **remote**：`lib/remote.js` 加 `getAvatars` 描述符 + 转发方法，**并加进 `exposeRemoteMethods`
+  的装饰清单** —— 漏这一步 `remoteMethods()` 就扫不到它，verify 的「方法与描述符一一对应」会直接拦下。
+- **客户端**：`src/client/remote.js` 加配对的 direct 声明；`settings.jsx`（面板卡片）与
+  `summon.jsx`（@ 弹窗）各取一次头像 map，**有头像渲染 `<img>`、否则回退原来的 emoji / 分区图标**；
+  `css.js` 给两个头像圆各加 `img{width:100%;height:100%;border-radius:50%;object-fit:cover}`。
+- **代价**：只返回本地已有的那些，未下载过资源的专家不产生任何数据传输，列表加载不受影响。
+
+### 自检
+
+546/546（「卡片头像」那条断言已更新以反映新渲染）。
+
+
+
+**专家头像：从 WorkBuddy 取回、压成 128px WEBP，随资源包按需下发（不进 npm 包）。**
+
+### 背景
+
+WorkBuddy 的头像在**拉取阶段**就被丢弃了（`workbuddy-expert-fetch` 默认不保存头像，省 315 MB），
+面板此前只有 emoji。现在按用户口径加回来：**没下载过的专家显示默认（emoji），下载过的显示真实头像**。
+
+### 做法
+
+- **拉取**：`--only <281 位> --with-avatars --force`，只拉现役专家，已删的不拉。
+- **压缩**：新增 `tools/import-avatars.py` —— 取 `plugin.json` 的 `avatar` 字段指定的**主头像**，
+  压成 **128px WEBP**，统一命名为 `avatars/avatar.webp`，**原图一概不留**。
+  实测原图是 1024² PNG、约 200 KB～1.5 MB，压后 **3.4 KB/张**，281 位合计 **0.94 MB**。
+- **上云**（`pack-assets.mjs` 两处）：
+  ① `avatars` 列入**强制上云** —— 它只有 5 KB、远低于 50 KB 阈值，否则会被塞进 npm 包；
+  ② 附件本来就小（≤ 阈值）但含头像的包，**tar.gz 只装 avatars**，其余（skills 等）继续随 npm 包
+     发布、立即可用 —— 不因为一张头像就把整个包挪上云端。
+- **运行时**：`ASSET_DIRS` 加 `avatars`；解包逻辑不用改（它按 roster 的 `dirs` 走）。
+
+### 自检
+
+roster **181 → 289 条**（105 个「只装头像」的小包 + 若干含头像的大包），云端 174 MB；546/546。
+抽验 `marketing/seo-content-team` 的 sha256 与 OBS 元数据一致 ✓。
+
+### 遗留
+
+面板显示头像还差**客户端与 host 那一层**：浏览器读不到本地文件，需要 host 提供读取接口。
+
+### 教训
+
+本轮**又踩了一次「别单独手跑 `pack-assets.mjs`」** —— 附件早已 prune，它按「本地还能打包的包」
+重算，把 181 条 roster 清成了 281 条纯头像条目。靠 `git checkout -- data/roster.json` 恢复，
+再用 `assets.mjs fetch --all` 把附件拉回本地，才重新打对。
+
+## [0.4.51] — 未发布
+
+**`upload-obs.mjs` 新增 `--delete-orphans`：清理删过专家后留在桶里的孤儿对象。**
+
+### 新增
+
+    node tools/upload-obs.mjs --delete-orphans        # 只列不删
+    node tools/upload-obs.mjs --delete-orphans --yes  # 真删
+
+- 用 ListObjects（自动翻页）扫 `<prefix>/packs/`，与 `roster.json` 引用的 path 集合比对，
+  列出没被引用的对象；**只扫 `packs/` 前缀**，不碰桶里其它东西，免得误删手工放进去的。
+- **默认只列不删**，要 `--yes` 才真删（破坏性操作两道闸）。
+- 实现细节：OBS v2 签名里 `prefix` / `marker` / `max-keys` **不属于**要签的子资源，
+  桶级 LIST 的 CanonicalizedResource 只有 `/<bucket>/` —— 所以直接复用 `authorize({ key: "" })`。
+
+### 实测（这就是加它的原因）
+
+```
+桶里 244 个对象 / 清单引用 181 个 / 孤儿 63 个 / 合计 529.0 MB
+```
+
+其中 `vietnam-finance-tax-expert.tar.gz` 一个就 495.6 MB（占 93.7%），其余 62 个来自更早的几次删除：
+内部依赖专家（`omics-*`、`fundus-disease-analysis`…）与「去分区前缀重名」那批
+（`ui-designer`、`backend-architect`、`frontend-developer`… —— 判重修复之前导入的）。
+
+## [0.4.50] — 未发布
+
+**移除 `finance/vietnam-finance-tax-expert`（495.6 MB）** —— roster 里最大的包，是第二名的 12.5 倍。
+
+### 为什么
+
+它是个「**离线 RAG 型**」专家：自带 723 篇越南财税法规语料，外加
+
+| 文件 | 大小 |
+|---|---|
+| `tfidf_matrix.npz`（预计算检索索引）| **382.9 MB** |
+| `chunks_metadata.json`（分块元数据）| 41.7 MB |
+| 法规原文（PDF/HTML/TXT）| 约 70 MB |
+
+功能上很完整（不联网就能查越南税法，还配了企业所得税／工资／关税／选址四个计算器），
+但**单个专家 495.6 MB 太重**（第二名 `legal/malaysia-hr-admin` 才 39.6 MB），
+按需下载的设计不值得为它付这个代价。
+
+名册 **624 → 623**；roster **182 → 181**；README / npm description / THIRD-PARTY-NOTICES /
+许可说明 / source.json / verify 数字同步校准。
+
+### 遗留
+
+OBS 上的 `packs/finance/vietnam-finance-tax-expert.tar.gz`（495.6 MB）现在是**孤儿对象** ——
+`roster.json` 里没有它，不会有任何客户端去下载，但占着云端空间。清理方式见技能
+`t-expert-roster-sync` 的说明（`tools/upload-obs.mjs` 目前只有上传与校验，没有删除）。
+
+## [0.4.49] — 未发布
+
+**远端清单的两个缺陷：一个是功能性的（495 MB 附件拿不到），一个是我自己设错的上限。**
+
+### 背景
+
+按用户要求实测「召唤专家能否下载附件」：两位专家（`seo-content-team`、`fin-research-expert`）
+都下载成功，sha256 与清单**逐字节一致**，解包后文件齐备。但顺带查出远端清单的两个问题。
+
+### 修复
+
+1. **远端清单改成「并集合并」而非替换**。远端可能比包内**旧**（改了专家但还没重传 roster），
+   直接替换会让包内独有的条目查不到 —— 表现是那位专家被判成「没有云端附件」，附件**永远下载不下来**。
+   实测踩到：`finance/vietnam-finance-tax-expert`（**495.6 MB**）在包内清单里有、远端那份是旧的因而没有，
+   它的 `agents/` 与 `references/` 一直缺失。
+   现在 `mergeRosters(bundled, remote)`：远端同名条目优先（那是新版本），包内独有条目保留（兜底）。
+   **所有返回路径都过合并**（含缓存命中 —— 否则插件升级后、缓存 TTL 内，包内新增条目会因
+   「缓存还新鲜」而丢失）。
+2. **单包体积上限 200 MB → 2 GB**。这是我上一版设错的：roster 里真实存在 495.6 MB 的包，
+   200 MB 上限会把它当异常条目**整条拒掉**，同样导致附件拿不到。
+
+### 自检
+
+新增 5 条断言（并集的覆盖/保留/undefined 回退 + 「495 MB 大包必须放行」），541 → **546**。
+端到端验证：包内 182 条 ∪ 远端 203 条 = **204 条**，那条 495.6 MB 的条目现在查得到。
+
+### 运维提醒
+
+远端 `agetn/roster.json` 目前比包内**旧**（它是删掉那批内部依赖专家之前上传的：多 22 条孤儿条目、
+少 1 条）。并集逻辑已保证不影响使用，要让它干净就重跑一次 `node tools/upload-obs.mjs`。
+
 ## [0.4.48] — 未发布
 
 **逐行审查 0.4.47 的远端清单代码，修掉一个会导致「远端故障时频繁打远端」的 bug。**

package/README.md

@@ -1,6 +1,6 @@
 # T专家（dsh-plugin-t-expert）
 
-dsh-plugin-t-expert 插件：包含 **22 个分类 / 624 位专家**的名册（中文名、简介全量覆盖）。
+dsh-plugin-t-expert 插件：包含 **22 个分类 / 623 位专家**的名册（中文名、简介全量覆盖）。
 
 装上以后你能做两件事：
 
@@ -89,7 +89,7 @@ remote 入口 `lib/skill-gate-remote.js`（wire 名仍是 `skillGate`，客户
 
 ```
 ~/.t-team/
-├── experts/              名册：<分类>/<slug>.md 或 <分类>/<slug>/（包内快照 22 个分类、624 位；你自建的另计）
+├── experts/              名册：<分类>/<slug>.md 或 <分类>/<slug>/（包内快照 22 个分类、623 位；你自建的另计）
 ├── zh/                   中文侧车：names.json、descriptions.json、<分类>/<slug>.md
 ├── custom/               你在面板里自建的专家
 ├── source.json           名册清单（专家数 / 分类 / 更新时间）

package/THIRD-PARTY-NOTICES

@@ -11,10 +11,10 @@
 | 英文名册 | The Agency / AgentLand（`msitarzewski/agency-agents`）— MIT，Copyright (c) 2025 AgentLand Contributors。完整文本随包：`vendor/third-party-licenses/agency-agents.LICENSE` |
 | 中文译文 | `jnMetaCode/agency-agents-zh`（中文翻译与本地化）— MIT，Copyright (c) 2025 Michael Sitarzewski（英文原版）、Copyright (c) 2026 jnMetaCode（中文翻译与本地化）。完整文本随包：`vendor/third-party-licenses/agency-agents-zh.LICENSE` |
 | 分发形态 | 上述两部分内容随 `@michengai/dsh-agency-agents` 一同分发（该包自身的 TypeScript 源码与构建脚本为 Apache-2.0，**本插件不打包其任何代码**） |
-| 位置 | `data/experts/`（22 个分类 / 624 位）、`data/zh/`（中文名字 / 简介 / 人格正文 / 分类标签） |
+| 位置 | `data/experts/`（22 个分类 / 623 位）、`data/zh/`（中文名字 / 简介 / 人格正文 / 分类标签） |
 | 维护方式 | 上述内容随本插件分发（`data/` 是发布源，不再从上游重新镜像）；`data/source.json` 是该名册的清单（专家数 / 分类 / 更新时间） |
 
-名册的构成分五部分（总计 624 位）：
+名册的构成分五部分（总计 623 位）：
 
 - **279 位来自 `msitarzewski/agency-agents`**（上表英文名册一行）。
 - **35 位来自 `@michengai/dsh-agency-agents` 的包内快照**（company / hr / legal / supply-chain
@@ -34,7 +34,7 @@
 
   它们没有中文译文正文（`data/zh/` 已冻结）；作为例外，中文名与中文简介手写在
   `data/zh/names.json` 与 `data/zh/descriptions.json` 里，人格正文回退英文。
-- **301 位来自 WorkBuddy 专家市场**（腾讯 CodeBuddy 的公开专家市场，2026-09-29 导入）。
+- **300 位来自 WorkBuddy 专家市场**（腾讯 CodeBuddy 的公开专家市场，2026-09-29 导入）。
   它们以「目录形态专家包」随包分发：`<分类>/<slug>/persona.md` 是名册入口，原始 `agents/`、
   `skills/` 与全部附件（references、Databases 等）一并保留在包内。
   **其版权与许可归腾讯及其各自的专家作者所有**，本插件只做本地聚合与形态转换，不声称对其拥有