dsh-plugin-t-expert 0.4.53 → 0.4.58

package/CHANGELOG.md

@@ -16,7 +16,140 @@
 > 发布时**不要再跑 `npm version`**（那会把已提交好的版本又升一级，发出去的号与 CHANGELOG、tag 就对不上），
 > 只补一个 annotated tag（`git tag -a`，因为 `git push --follow-tags` 只推带注释的 tag）。
 
-## [0.4.53] — 未发布
+## [0.4.58] — 未发布
+
+**面板的 ☁️ 标识改成可点的下载入口** —— 之前它只是个 `<span>`，注释却写着「点选与召唤都会自动下载」。
+
+### 现象
+
+用户反馈：「部分专家有头像、部分怎么点都没有」。
+
+### 根因
+
+`warmupAssets`（下载预热）只挂在两处：
+
+- `@` 弹窗的 `pick()`（`summon.jsx`）
+- 输入框 `@` 菜单的 `onPick()`（`index.jsx`）
+
+**面板列表（`settings.jsx`）完全没有触发点**。于是规律很清楚：
+
+- **召唤过 / 在 @ 弹窗选过**的专家 → 附件已下载 → 有头像 ✓
+- **只在面板里看过**的专家 → 永远不触发下载 → 永远 emoji ✗
+
+而面板那个 ☁️ 标识本身是个 `<span>`（注释写着「只是个标识、不是按钮」），点它同样没用。
+
+### 修复
+
+把 ☁️ 改成 `<button>`，点击即 `warmupAssets(remote, expert)`；点完立刻收起标识
+（下载在后台跑，不给即时反馈会让人以为没生效）。CSS 加 `.t-team-cloud` 抹掉按钮默认外观。
+
+### 教训
+
+**同一个动作（下载预热）在三个入口里只挂了两处** —— 注释写的是「点选与召唤都会自动下载」，
+但面板那条路径压根没实现。写「A 和 B 都会做 X」这类注释时，得真的去核对 B。
+
+
+
+**清理残留的诊断 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 只做到数据链路，这一版接上最后一环。
 

package/lib/client.js

@@ -67,7 +67,7 @@ var SectionBoundary = class extends import_react.default.Component {
 
 // src/client/state.js
 var NS = "t-team";
-var CLIENT_BUILD_VERSION = "0.4.53";
+var CLIENT_BUILD_VERSION = "0.4.58";
 var PLUGIN_ID = "dsh-plugin-t-expert";
 var DIVISION_FALLBACK = "specialized";
 var NEW_DIVISION = "__new";
@@ -118,7 +118,13 @@ var warming = /* @__PURE__ */ new Set();
 function warmupAssets(remote, expert) {
   if (expert?.assets !== "missing" || warming.has(expert.slug)) return;
   warming.add(expert.slug);
-  void remote.fetchAssets(expert.slug).then(() => refresh(remote, true)).catch(() => void 0).finally(() => warming.delete(expert.slug));
+  void remote.fetchAssets(expert.slug).then(() => {
+    refresh(remote, true);
+    try {
+      window.dispatchEvent(new CustomEvent("t-team:avatars-changed"));
+    } catch {
+    }
+  }).catch(() => void 0).finally(() => warming.delete(expert.slug));
 }
 function displayDescription(expert, active) {
   return active === "en" ? expert.descriptionEn || expert.description : expert.description;
@@ -333,6 +339,7 @@ var CSS = `
 .t-team-prompt-body{margin:0;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px;line-height:19px;white-space:pre-wrap;word-break:break-word;color:var(--dsw-alias-label-secondary)}
 .t-team-avatar{display:flex;align-items:center;justify-content:center;width:44px;height:44px;border-radius:50%;background:var(--dsw-alias-bg-layer-3);font-size:22px;line-height:1}
 .t-team-avatar img{width:100%;height:100%;border-radius:50%;object-fit:cover;display:block}
+.t-team-cloud{border:0;background:none;padding:0;margin-inline-start:4px;cursor:pointer;font-size:inherit;line-height:1}.t-team-cloud:hover{opacity:.7}
 .t-team-identity{display:flex;min-width:0;flex-direction:column;padding-right:46px}
 .t-team-card-name{font-size:14px;font-weight:600;line-height:20px;color:var(--dsw-alias-label-primary);display:-webkit-box;-webkit-box-orient:vertical;-webkit-line-clamp:2;overflow:hidden}
 .t-team-card-division{font-size:13px;line-height:18px;margin-top:2px;color:var(--dsw-alias-label-secondary)}
@@ -21579,6 +21586,8 @@ function SettingsPanel({ t, ctx, remote, skillRemote, getActive, initialTab, vie
   const [snapshot, setSnapshot] = import_react5.default.useState(() => snapshotOf(remote) ?? null);
   const [query, setQuery] = import_react5.default.useState("");
   const [avatars, setAvatars] = import_react5.default.useState({});
+  const [avatarRev, setAvatarRev] = import_react5.default.useState(0);
+  const [cloudClicked, setCloudClicked] = import_react5.default.useState({});
   const [division, setDivision] = import_react5.default.useState("");
   const [status, setStatus] = import_react5.default.useState("");
   const [error62, setError] = import_react5.default.useState("");
@@ -21610,16 +21619,28 @@ function SettingsPanel({ t, ctx, remote, skillRemote, getActive, initialTab, vie
       alive = false;
     };
   }, [reload]);
+  import_react5.default.useEffect(() => {
+    const onAvatarsChanged = () => setAvatarRev((n) => n + 1);
+    window.addEventListener("t-team:avatars-changed", onAvatarsChanged);
+    return () => window.removeEventListener("t-team:avatars-changed", onAvatarsChanged);
+  }, []);
   import_react5.default.useEffect(() => {
     let alive = true;
     (async () => {
-      const map2 = await Promise.resolve(remote?.getAvatars?.()).catch(() => void 0);
-      if (alive && map2 !== void 0 && map2 !== null) setAvatars(map2);
+      let map2 = {};
+      try {
+        map2 = unwrap(await remote?.getAvatars?.(), "getAvatars") ?? {};
+      } catch {
+        map2 = {};
+      }
+      if (alive && map2 !== void 0 && map2 !== null) {
+        setAvatars(map2);
+      }
     })();
     return () => {
       alive = false;
     };
-  }, [remote]);
+  }, [avatarRev]);
   const active = getActive();
   async function openPrompt(expert) {
     setCopyState("");
@@ -21901,7 +21922,19 @@ function SettingsPanel({ t, ctx, remote, skillRemote, getActive, initialTab, vie
         /* @__PURE__ */ import_react5.default.createElement("span", { className: "t-team-group-chevron", "aria-hidden": "true" }, open2 ? "\u25BE" : "\u25B8")
       ), open2 && /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-grid" }, group.items.map((expert) => {
         const on = enabledSet.has(expert.slug);
-        return /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card", "data-enabled": on, key: expert.slug }, /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card-body" }, /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-avatar" }, avatars[expert.slug] === void 0 ? expert.emoji || "\u{1F9E9}" : /* @__PURE__ */ import_react5.default.createElement("img", { src: avatars[expert.slug], alt: "" })), /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-identity" }, /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card-name" }, displayName(expert, active), expert.custom === true && /* @__PURE__ */ import_react5.default.createElement(Tag2, { tone: "info" }, t("custom.badge")), expert.assets === "missing" && /* @__PURE__ */ import_react5.default.createElement("span", { title: t("assets.cloud"), style: { marginInlineStart: 4 } }, "\u2601\uFE0F")), /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card-division" }, divisionLabel(expert, active)), /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card-slug" }, expert.slug)), /* @__PURE__ */ import_react5.default.createElement("p", { className: "t-team-card-desc" }, displayDescription(expert, active)), expert.conflict === true && /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-conflict", style: { gridColumn: "1/-1" } }, t("settings.conflict"))), /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card-tools" }, /* @__PURE__ */ import_react5.default.createElement(
+        return /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card", "data-enabled": on, key: expert.slug }, /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card-body" }, /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-avatar" }, avatars[expert.slug] === void 0 ? expert.emoji || "\u{1F9E9}" : /* @__PURE__ */ import_react5.default.createElement("img", { src: avatars[expert.slug], alt: "" })), /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-identity" }, /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card-name" }, displayName(expert, active), expert.custom === true && /* @__PURE__ */ import_react5.default.createElement(Tag2, { tone: "info" }, t("custom.badge")), expert.assets === "missing" && cloudClicked[expert.slug] !== true && /* @__PURE__ */ import_react5.default.createElement(
+          "button",
+          {
+            type: "button",
+            className: "t-team-cloud",
+            title: t("assets.cloud"),
+            onClick: () => {
+              warmupAssets(remote, expert);
+              setCloudClicked((prev) => ({ ...prev, [expert.slug]: true }));
+            }
+          },
+          "\u2601\uFE0F"
+        )), /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card-division" }, divisionLabel(expert, active)), /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card-slug" }, expert.slug)), /* @__PURE__ */ import_react5.default.createElement("p", { className: "t-team-card-desc" }, displayDescription(expert, active)), expert.conflict === true && /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-conflict", style: { gridColumn: "1/-1" } }, t("settings.conflict"))), /* @__PURE__ */ import_react5.default.createElement("div", { className: "t-team-card-tools" }, /* @__PURE__ */ import_react5.default.createElement(
           Button2,
           {
             variant: "ghost",
@@ -22036,16 +22069,27 @@ function SummonButton({ t, ctx, remote, getActive, insertReference, insertSkillH
   const [popTab, setPopTab] = import_react6.default.useState(preview?.tab ?? "experts");
   const [skills, setSkills] = import_react6.default.useState(null);
   const [avatars, setAvatars] = import_react6.default.useState({});
+  const [avatarRev, setAvatarRev] = import_react6.default.useState(0);
+  import_react6.default.useEffect(() => {
+    const onAvatarsChanged = () => setAvatarRev((n) => n + 1);
+    window.addEventListener("t-team:avatars-changed", onAvatarsChanged);
+    return () => window.removeEventListener("t-team:avatars-changed", onAvatarsChanged);
+  }, []);
   import_react6.default.useEffect(() => {
     let alive = true;
     (async () => {
-      const map2 = await Promise.resolve(remote?.getAvatars?.()).catch(() => void 0);
+      let map2 = {};
+      try {
+        map2 = unwrap(await remote?.getAvatars?.(), "getAvatars") ?? {};
+      } catch {
+        map2 = {};
+      }
       if (alive && map2 !== void 0 && map2 !== null) setAvatars(map2);
     })();
     return () => {
       alive = false;
     };
-  }, [remote]);
+  }, [avatarRev]);
   const [skillQuery, setSkillQuery] = import_react6.default.useState("");
   const [skillsDiag, setSkillsDiag] = import_react6.default.useState("");
   import_react6.default.useEffect(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-t-expert",
-  "version": "0.4.53",
+  "version": "0.4.58",
   "type": "module",
   "description": "T Expert — a 623-expert, 22-division roster with full Chinese translations, as a standalone DeepSeek Harness plugin.",
   "icon": "icon.svg",