dsh-plugin-t-expert 0.4.51 → 0.4.57

package/CHANGELOG.md

@@ -16,6 +16,163 @@
 > 发布时**不要再跑 `npm version`**（那会把已提交好的版本又升一级，发出去的号与 CHANGELOG、tag 就对不上），
 > 只补一个 annotated tag（`git tag -a`，因为 `git push --follow-tags` 只推带注释的 tag）。
 
+## [0.4.57] — 未发布
+
+**清理残留的诊断 alert** —— 0.4.55 那次「移除诊断」的字符串替换没匹配上，`alert` 留到了源码里。
+
+- `settings.jsx` 删除 `alert('[头像诊断]…')` 残留（否则每次取头像都会弹窗）。
+- 更新过时注释：头像 effect 的依赖早已改成 `[avatarRev]`，注释却还写着「依赖用 []（只跑一次）」。
+
+### 教训
+
+用字符串替换「删除调试代码」不可靠 —— 匹配串与实际代码对不上时会**静默失败**，
+留下一段每次执行都弹窗的代码。删调试代码后要 `grep` 全库确认，而不是只看替换的返回。
+
+
+
+**点选专家下载完头像后，面板自动显示头像**（之前必须重开面板）。
+
+### 现象
+
+用户实测：点选专家 → 头像确实下载到了本地 → **但面板还是 emoji，要重开面板/重启才看得到**。
+
+### 原因
+
+`warmupAssets()`（点选预热）下载完成时只做了 `refresh(remote, true)` —— **刷新名册**；
+而**头像是在面板/弹窗挂载时单独取一次的**（`getAvatars`）—— 两者互不知情。
+结果名册刷新了、`assets` 状态更新了，但头像那份 state 还是旧的。
+
+### 修复
+
+`warmupAssets` 完成后额外广播 `t-team:avatars-changed`；面板与 `@` 弹窗各加一个监听，
+收到就把 `avatarRev` +1，带动取头像的 effect 重跑。
+
+### 教训
+
+**同一份数据被两处独立取用时，刷新必须一起刷** —— 只刷了名册、漏了头像，
+表现就是「东西明明下好了，界面纹丝不动」，看起来像功能根本没生效。
+
+
+
+**头像显示的真凶：RPC 返回值外面套着 `{ok, value}` 信封，我没解。**
+
+### 根因
+
+DSH 的 remote 调用返回值形如 `{ ok: true, value: 真实数据 }`，**必须用 `unwrap()` 解掉**
+（`src/client/catalog.js:21`，`getCatalog` 等所有既有调用都这么写）。新加的 `getAvatars` 漏了这一步，
+客户端拿到的是**信封本身** —— 诊断时打印 `Object.keys(map)` 得到 `["ok", "value"]`，
+而 `map["novel-generator"]` 永远是 `undefined` → 卡片全部回退 emoji。
+
+**把 `Object.keys(map)` 弹出来这一步是一击定位的关键**：那两个字段名直接暴露了信封结构。
+
+### 修复
+
+`settings.jsx` / `summon.jsx` 改用 `unwrap(await remote?.getAvatars?.(), "getAvatars")`，
+失败兜底成 `{}`；诊断代码移除。
+
+### 这一轮叠在一起的三个坑
+
+1. **`useEffect` 依赖 `[remote]` 不稳定** → effect 反复重挂 → `alive` 恒为 false →
+   `setAvatars` 一次都没执行（真 bug，0.4.54 已修）。
+2. **pnpm 的 `file:` 依赖是「拷贝」不是符号链接** → 改源码 + build 后 `desktop/node_modules`
+   里那份纹丝不动 → **前两次修复根本没到 App**，一直在看旧 client.js。必须
+   `rm -rf node_modules/dsh-plugin-t-expert && pnpm add file:...` 强制重挂
+   （`realpath` 看着像链接，很容易误判成软链 —— 这次就被它骗了一轮）。
+3. **RPC 返回值信封没解**（本条）。
+
+### 附带发现
+
+`~/.t-team/experts` 是 325（目录形态）+ 323（单文件）= **648**，而 `data/experts` 是 300 + 323 = **623** ——
+运行时目录**多 25 位历史残留**（删过但没同步回运行时），面板上的「专家 648」就是这么来的。
+不影响功能，要清需单独处理。
+
+
+
+**修掉「头像数据取到了却显示不出来」的 bug** —— 用户实测：诊断弹窗显示 RPC 返回 2 条，界面却全是 emoji。
+
+### 根因
+
+`settings.jsx` / `summon.jsx` 里取头像的 `useEffect` 依赖写成了 `[remote]`：
+
+```js
+React.useEffect(() => {
+  let alive = true;
+  (async () => { ... if (alive && ...) setAvatars(map); })();
+  return () => { alive = false; };
+}, [remote]);        // ← desktop 上 remote 走 /api 网关，引用不稳定
+```
+
+desktop 的 remote 是经 `/api` API Gateway 构造的，**引用不稳定** → 每次重渲染 effect 都重挂 →
+cleanup 把 `alive` 置回 `false` → **数据取到了也被 `if (alive …)` 丢掉**，state 永远停在空对象。
+
+`alert` 写在 `.then` 里、不看 `alive`，所以照样弹「OK 返回 2 条」—— 这个反差正是定位根因的关键。
+
+### 修复
+
+依赖改 `[]`（只跑一次）。`remote` 在组件生命周期内是稳定的，本来就不需要跟。
+
+### 教训
+
+**用 `alive` 防 setState-on-unmounted 时，依赖数组必须是稳定的** —— 否则它防的不是「卸载后 setState」，
+而是「一切 setState」，而且**完全静默**。另外这次能一步定位，靠的是把被 `catch(() => void 0)`
+吞掉的结果/错误暴露出来：**给静默失败装一个能看见的出口**，比反复猜快得多。
+
+
+
+**面板与 @ 弹窗显示专家头像** —— 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`：清理删过专家后留在桶里的孤儿对象。**