dsh-plugin-t-expert 0.4.9 → 0.4.36

package/CHANGELOG.md

@@ -16,6 +16,744 @@
 > 发布时**不要再跑 `npm version`**（那会把已提交好的版本又升一级，发出去的号与 CHANGELOG、tag 就对不上），
 > 只补一个 annotated tag（`git tag -a`，因为 `git push --follow-tags` 只推带注释的 tag）。
 
+## [0.4.36] — 未发布
+
+**修掉两个挡住 `npm publish` 的问题** —— 附件上云之后第一次真正走发布流程才暴露出来。
+
+### 修复
+
+- **`tools/verify.mjs` 的 `npm pack` 在发布环境里打出空包**：`npm publish --dry-run` 会把 dry-run
+  灌进**环境变量**，于是 verify 里再调起的 `npm pack` 也进了 dry-run —— 一个文件都不写，
+  自检报「打不出 tgz」、后续断言连环崩（而手动跑 verify 却一切正常，所以一直没暴露）。
+  现在显式剥掉继承来的 `npm_config_dry*` / `npm_config_pack_destination`；tgz 名也改成
+  **扫目标目录**取，不再从 stdout 最后一行猜（那个格式随环境变，实测在发布环境里取到过非文件名）。
+- **`tools/sync-data.mjs --check` 把已上云的附件判成「缺失」**：运行时目录里附件还在、包内快照里
+  没有，这是**设计如此**，但检查会因此退 1、把 `prepublishOnly` 整个挡住。
+  现在按 `data/roster.json` 跳过这些路径；另外把下载器写的 `.assets.json`（本机运行时状态，
+  不是名册内容）加进 JUNK 集，不让它进快照。
+
+### 效果
+
+`npm publish` 现在能完整跑通：**8.5 MB（tgz）/ 21.3 MB 解包 / 2909 个文件**
+（附件上云前是 126 MB / 328 MB / 14887 个文件）。
+
+## [0.4.35] — 未发布
+
+**「下载附件」按钮换成 `☁️` 标识** —— 用户口径：既然点选与召唤都会自动下载，按钮是多余的。
+
+### 变更
+
+- **`@` 召唤弹窗**与**插件设置页**：删掉「⬇ 下载附件」按钮，改成纯标识 **`☁️`**（悬停提示
+  「配套资源在云端，点选或召唤时会自动下载」）。只在 `assets === "missing"` 时出现，
+  下载完成后随名册刷新一起消失。
+- 随之删掉两处的下载状态机（`downloading` / `assetsNote` / `assetsError` 与 `downloadAssets`）：
+  没有按钮就不需要「下载中／成功／失败」的即时反馈了。真正的兜底仍在 `warmupAssets`
+  （点选预热）与 `fetch_expert_assets`（模型侧补救）。
+- i18n 收成一条 `assets.cloud`（原 `assets.download` / `.downloading` / `.done` / `.failed` 删除）。
+
+## [0.4.34] — 未发布
+
+**点选即预热** —— 在选择器里点了某位专家，就立刻开始下载它的附件。
+
+### 变更
+
+- **`@` 召唤弹窗**与 **`@` 触发器菜单**：点选专家（往输入框插入 `@专家名`）时，后台同时开始
+  拉取它的附件。用户口径（2026-09-29）：「用户既然点了肯定是要使用的」。
+  插入引用这个动作**仍然是瞬时的**（`warmupAssets` 不 await），失败也**静默** —— 这只是提前量，
+  真正用到时还有召唤时的后台预取与 `fetch_expert_assets` 工具兜底。下完再刷新一次名册，
+  UI 上那个「未下载」标记随之消失。
+- 在此之前附件只会在**真正召唤**时才开始下载，于是「召唤后专家立刻要读 SKILL.md」会正好撞上
+  那几秒空窗。现在把起点提前到了「点选」这一步。
+
+## [0.4.33] — 未发布
+
+**未下载的专家可以一键下载** —— `@` 召唤弹窗与插件设置页都给「附件未下载」的专家加了入口。
+
+### 新增
+
+- **remote 方法 `fetchAssets(slug)`**（host）：两处 UI 的下载按钮走它。幂等 —— 附件已就绪时
+  直接返回、**不发网络请求**；附件随包发布的专家返回 `status: "local"`（没有要下载的东西）。
+- **名册快照多一个 `assets` 字段**（`local` / `ready` / `missing`）：客户端据此知道哪位专家的
+  附件还没下载。代价是每次 snapshot 多 322 次 `.assets.json` 存在性检查，实测可忽略。
+- **`@` 召唤弹窗**：未下载的专家在标签行多一个「⬇ 下载附件」，点了当场拉取，完成后刷新名册。
+- **插件设置页**：未下载的专家卡片上多一个「下载附件」按钮（官方 `Button`），带下载中禁用态。
+
+### 说明
+
+- 弹窗里那个入口只能用带 `role="button"` 的 `span` —— 整张卡片本身就是一个 `<button>`，
+  嵌套真的 `<button>` 是非法 HTML。
+- 设置页的下载失败**刻意不复用页面顶部的 `error`**：那个渲染时会被包上「保存失败」的壳，
+  附件失败塞进去会显示成「保存失败：附件下载失败：…」，所以单开了一个状态。
+
+## [0.4.32] — 未发布
+
+**附件上云第三步：接进召唤流程** —— 路径改写 + 召唤时后台预取 + `fetch_expert_assets` 工具。
+
+### 新增
+
+- **`fetch_expert_assets(expert)` 工具**（C 路径）：模型需要某位专家的技能或数据文件、而按路径
+  读取失败时显式拉取。返回资源根路径与可用目录清单。附件小于阈值（随包发布）的专家直接返回
+  `status: "local"`，**不做任何网络请求**；拉取失败时返回 `status: "failed"` 与原因，
+  并提示模型「人格仍可用，但不要假装读过那些文件」。
+
+### 变更
+
+- **persona 路径改写**（`annotatePersona`）：目录形态专家的正文里，`skills/xxx/SKILL.md` 这类
+  **相对路径**的基准是「当前会话的工作目录」而不是专家包目录 —— 模型照抄去 `Read` **必然落空**。
+  实测 645 位里 126 位（20%）的正文引用了资源路径，其中目录形态 115 个（占 322 个包的 36%）；
+  也就是说不改写的话，这批专家的技能与数据文件即使下载完整也用不上。
+  现在召唤前统一改写成包内绝对路径，并在正文顶部补一段资源说明（含附件未下载时的拉取指引）。
+  改写规则刻意收窄：只碰已知附件目录名开头的路径、**只改包内确实存在的那个**（把模型指向不存在
+  的文件比不改更糟）、不动 `~/.workbuddy/...` 这类别人的路径（用负向后顾实现 —— 第一版没加，
+  实测把 `skills-marketplace/skills/xxx` 里的第二段误改了）。
+- **召唤时后台预取**（A 路径）：`summon_t_expert` 返回人格的同时异步拉取该专家的附件，**不 await**
+  —— 人格在本地、立即可用，召唤不该被网络拖住；结果只写日志。同一专家被并发召唤时，
+  由 `ensureAssets` 的 in-flight 表合并成一次下载。
+- `prompt(slug, division)`（面板按需取正文）同样走改写，保证两条读人格的路径行为一致。
+
+### 自检
+
+- 新增 4 条断言：工具数为 4 且名字正确（`fetch_expert_assets`）、路径改写「存在的改成绝对路径、
+  不存在的原样保留」、「不动 `~/.workbuddy/...`」、「顶部补上资源目录与拉取工具说明」。
+  路径改写的测试用**临时目录构造确定性输入**，不依赖真实名册里某个包的附件是否还在本地。
+- 自检项数 519 → 523。
+
+## [0.4.31] — 未发布
+
+**附件上云第二步：下载器** —— 从 OBS 拉取附件、校验 sha256、解包回原位。
+
+### 新增
+
+- `lib/fetch-assets.js`：附件下载器（`loadRoster` / `packInfoFor` / `assetUrl` / `assetsState` /
+  `ensureAssets` / `dropAssets`）。
+  - **原地解包**：附件回到 `<root>/<分区>/<slug>/` 的原位置，下载前后目录结构完全一致，
+    `catalog.js` 的剪枝判断与 `packDir` 语义都不用改。
+  - **幂等**：`<packDir>/.assets.json` 记下已解包的 sha256，与清单一致就**不发任何网络请求**。
+  - **并发去重**：同一位专家被并发请求（召唤与显式拉取）只会下载一次。
+  - **先删旧目录再解包**：避免版本升级后新旧附件混在一起。
+- `tools/assets.mjs`：手动命令（本步的验收工具）。
+  `status` 看哪些附件已就位；`fetch <slug>` / `fetch --all` 拉取；
+  `verify <slug>` 把「OBS 下载后解包的结果」与「本地 tar 解包的结果」逐文件比对 sha256。
+
+### 修复
+
+- **打包非确定性**（`tools/pack-assets.mjs`）：`tar -czf` 会把**当前时间**写进 gzip 头，同一份
+  内容两次打包得到两个 sha256 —— 清单里记的那个随即失效、而远端还是旧对象。实测踩过：改完脚本
+  重跑一次打包、忘了重传，下载器就报「sha256 不匹配」，而远端对象其实完好。
+  现在拆成 `tar -cf` + `gzip -n`（不写时间戳），已实测两次打包结果一致。
+- **上传流程加固**（`tools/upload-obs.mjs`）：上传完成后**自动把远端对象下载回来重算 sha256**，
+  不一致即非零退出并明确提示「先别 prune」；新增 `--no-verify` 可跳过。
+  因为「清单与远端脱节」这种状态在本地看起来完全正常（`--prune` 照跑），只有真的去下载才会暴露。
+- `lib/fetch-assets.js` 纳入 `tsconfig.json` 的 `include`，并修掉三处 JSDoc 写法问题
+  （`@param options.x` 缺 `@param {object} options` 前缀，tsc 报 TS8032）。自研 host 文件一旦带
+  `// @ts-check` 就必须在 include 里列名，否则那个标记是**死的** —— 自检 [20] 盯着这条不变量。
+
+### 说明
+
+- 仍然**没有接进召唤流程**：第 3 步（召唤时后台预取 + `fetch_expert_assets` 工具 +
+  persona 路径改写）随后单独提交。本版可用 `node tools/assets.mjs fetch <slug>` 手动拉取。
+
+## [0.4.30] — 未发布
+
+**附件上云第一步：打包 → 上传 OBS → 瘦身本地** —— `data/experts` 从 342 MB 降到 **23 MB**。
+
+### 新增
+
+- `tools/pack-assets.mjs`：把专家包里**超过阈值**（默认 50 KB）的附件打成
+  `dist/assets/<分区>/<slug>.tar.gz`，并生成 `data/roster.json`（路径 / 字节数 / sha256 /
+  内含目录清单）。开关：`--dry-run` / `--threshold 200KB` / `--prune`（删本地已上传的附件）。
+- `tools/upload-obs.mjs`：上传到华为云 OBS 公共读桶。用 OBS v2 签名，凭据**只从环境变量读**
+  （`OBS_ACCESS_KEY_ID` / `OBS_SECRET_ACCESS_KEY`，不落盘、不进包），每个对象带
+  `x-obs-meta-sha256` 元数据；开关：`--dry-run` / `--only <slug>` / `--verify`
+  （把远端对象下载回来重算 sha256）。
+- `data/roster.json`：云端分发清单，**随包发布**（已加入 `package.json` 的 `files` 白名单
+  与自检的 data 根层白名单）。
+
+### 变更
+
+- `data/experts` **342 MB → 23 MB**：200 个包的附件（原 292.3 MB）移到 OBS，压缩后
+  **115.8 MB / 201 个对象**（含清单本身）；122 个附件不足 50 KB 的小包原样留在本地。
+- **`.codebuddy-plugin/` 绝不上云**：它是 `lib/catalog.js` 判定「目录形态专家包」的标志
+  （`isExpertPack` 要求 `plugin.json` 与 `persona.md` **同时**存在），挪走会让专家从名册里直接消失。
+
+### 修复
+
+- **提示段把名册规模数成了 `.md` 总数**：`rosterScale()` 递归数 `data/experts` 下所有 `.md`，
+  把附件里的 agents 提示词、skills 下的 SKILL.md 也算成专家 —— 645 位被显示成 **6838** 位。
+  此前包内快照与运行时目录都有完整附件、**两边错得一模一样**，而自检断言比的正是「两者相等」，
+  所以一路绿灯；附件上云、包内快照瘦身后两边口径分叉，问题才暴露出来。
+  现在口径统一交给新增的 `catalog.countExperts()`（同步版，与 `walkMarkdown` 的剪枝规则一致），
+  自检也改用同一函数取值，不再两边各数一遍。
+
+### 说明
+
+- **本版只做了上传，还没有下载器**：附件此刻不在本地，运行时读不到专家的技能与数据文件。
+  第 2 步（`lib/fetch-assets.js` 下载器）与第 3 步（召唤时后台预取 + `fetch_expert_assets`
+  工具 + persona 路径改写）随后单独提交。
+
+## [0.4.29] — 未发布
+
+**修复：名册新增的专家进不了 `@` 菜单** —— 面板显示 645 位、`@` 弹窗却只有 323 位。
+
+### 修复
+
+- `seedDefaultEnabled()` 原本只看「策略版本号有没有追上」，追上就再也不播种。于是名册从 323 扩到
+  645 之后，老用户（`enabledSeedVersion` 早已是 1）那 322 位新专家**永远进不了启用名单**：
+  面板的 645 是名册总数、不受影响，而 `@` 菜单只列「已启用」的，于是只显示 323。
+  现在改为按**名册基线**（新增字段 `enabledSeedRoster`）做增量 —— 只把名册里新出现的补进
+  `enabled`，用户自己停用过的（已在基线里）不会被重新打开；名册没变化时什么都不写。
+  基线缺席的老数据以现有 `enabled` 当基线：于是「从未播种」= 整份名册都算新增（全启用），
+  「老用户升级」= 只有新导入的那批算新增。这比单纯把版本号 +1 精确 —— 后者会把用户手动停用的
+  专家一并重新打开。
+- `tools/verify.mjs`：设置 mock 支持 `enabledSeedRoster`，并新增断言「名册新增的专家自动补入
+  启用名单（用户自己的启停不受影响）」。自检项数 518 → 519。
+
+## [0.4.28] — 未发布
+
+**清理 13 个「换了名字重复收录」的影子专家** —— 名册 658 → 645。
+
+### 修复
+
+- 上一版导入 WorkBuddy 专家时，`tools/import-workbuddy.py` 只按 slug 与**职业名**判重，
+  漏掉了 13 个「职业名不同、正文却与 T专家 现存专家一字不差」的包（例如
+  `design/sprint-priority-manager` 与 `product/product-sprint-prioritizer.md`）。
+  它们会让面板出现内容相同的影子专家。现在导入器增加了**正文哈希**兜底判重
+  （去掉 frontmatter、抹平空白后比对），这 13 个已清除，并保证以后重跑也不会再进来。
+
+### 变更
+
+- 名册 658 → **645** 位（323 单文件形态 + 322 目录形态专家包）。
+- README、npm description、THIRD-PARTY-NOTICES、vendor 许可说明与 `tools/verify.mjs`
+  的断言/计数同步到 645。
+
+## [0.4.27] — 未发布
+
+**名册扩到 658 位：接入 WorkBuddy 专家市场（含完整专家包形态）** —— 用户口径：「把 WorkBuddy 专家整合到 T专家」。
+
+### 新增
+
+- **目录形态专家包**：名册除 `<分区>/<slug>.md` 单文件外，新增支持 `<分区>/<slug>/` 目录形态 ——
+  以包内 `persona.md` 为名册入口，原始 `agents/`、`skills/`、`references/`、`Databases/` 等附件
+  原样保留。识别标志是 `.codebuddy-plugin/plugin.json` 与 `persona.md` 同时存在。
+- `tools/import-workbuddy.py`：WorkBuddy 专家导入脚本。含分区映射（复用现有 22 个分区、不新建分类）、
+  多角色团队合成单份 persona、同 slug / 同职业去重（保留 updatedAt 较新者）、打包者本机路径清洗。
+
+### 变更
+
+- 名册从 323 位扩到 **658 位**（323 单文件 + 335 目录形态），分类数不变（22 个）。
+- `lib/catalog.js`：`walkMarkdown` 遇到专家包时**剪枝**（不再递归进包内 —— 否则包内
+  `skills/**/SKILL.md`、`references/*.md` 会被当成一堆独立专家扫进名册）；`ingest` 参数化以同时
+  支持两种形态；`discoverDivisions` 识别「只含专家包」的分区；专家条目新增 `packDir` 字段。
+- `tools/sync-data.mjs`：专家计数改为「单文件 + 专家包」两种形态，不再数所有 `.md`。
+- 发布包体积从 ~12MB 涨到 **126MB**（tgz）/ 328MB（解包），随包分发 14887 个文件。
+
+### 修复
+
+- `tools/verify.mjs`：`spawnSync("npm", ["pack", …])` 的 `maxBuffer` 从默认 1MB 提到 64MB ——
+  包内文件数近 1.5 万后，npm 的 tarball 清单（走 stderr）超过 1MB，进程被 SIGTERM，
+  表现为「打不出 tgz」而实际打包是成功的。
+- 导入时清洗 WorkBuddy 官方包内残留的打包者本机绝对路径（`/Users/...`，实测 100 处），
+  否则会随包发布泄露他人信息。
+
+### 说明
+
+- WorkBuddy 专家的版权与许可归腾讯及其各自的专家作者所有。本插件只做本地聚合与形态转换，
+  已在 `THIRD-PARTY-NOTICES` 与 `vendor/third-party-licenses/README.md` 中声明。
+
+## [0.4.26] — 未发布
+
+**放大头像 emoji、并让淡色底看得见** —— 用户口径：「给这些图标加一个淡淡的背景，现在 emoji 都很小，
+看着很不协调」。
+
+### 变更
+
+- emoji 字号 **22 → 26px**（44px 的圆里更饱满，上下各留 9px）。
+- 专家的淡色圆底 alpha **14% → 24%**（`color-mix`）：14% 铺在白卡片上几乎看不出圆 ——
+  圆没边、里面又是个小 emoji，整体就显得飘。
+- 没有 `color` 时的兜底底色从近白的 `--dsw-alias-bg-layer-3` 换成淡灰的
+  `--dsw-alias-interactive-bg-hover`（老数据、或颜色名在宿主上不被支持时，也还看得见一个圆）；
+  技能卡的 🧰 本来就用这档淡灰，两边因此是同一套观感。
+
+### 自检
+
+- 同一条断言改写：`tintOf` 的 alpha 24%、头像字号 26px，并加了一条否定条件 ——
+  兜底底色不许再回到 `bg-layer-3`（那正是"看不见圆"的老写法）。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/
+  verify（**518/518**）全绿。
+
+## [0.4.25] — 未发布
+
+**面板改成不透明实色、去掉毛玻璃** —— 用户口径：在「保持官方材质 / 改不透明实色 / 缩小模糊半径」
+三选一里选了 **B**。
+
+### 变更
+
+- `.t-team-pop-official`（官方 `MenuSurface` 那条路径）与 `.t-team-pop`（缺官方件时的兜底）都改成
+  **实色 `--dsw-alias-bg-layer-3`**，两条规则里的 `backdrop-filter` 全部拿掉。
+- **只换父级底色不够**：官方材质层是 `MenuSurface` 内部那个 `aria-hidden` 的绝对定位兄弟
+  （`inset:0` 铺满，`background` 与 `backdrop-filter` 都挂在它身上），所以补了一条
+  `.t-team-pop-official > [aria-hidden="true"]{display:none}` 把它关掉 —— 否则它照样在跑 `blur(40px)`。
+- 这是面板上**仅剩的大合成开销**：面板内容是实心卡片，本来也不需要透出背后内容。代价是失去
+  「与官方菜单同款毛玻璃」的观感（最初「材质交给官方」时就明说过这条代价）。
+- 顺带更新 css.js 里「用 `--dsw-specific-menu` 填色就必须配 `backdrop-filter`」那条历史注释：
+  规矩仍适用于别处还在用菜单材质的地方（如 `.t-team-expert-pick-panel`），但面板自己不再走这条路。
+
+### 自检
+
+- 改写 1 条断言（官方材质那条从「清掉自绘材质」改成「铺实色 + 关掉官方材质层」），新增 1 条：
+  **两条容器规则里都不许再有真的 `backdrop-filter`**（允许 `backdrop-filter:none`）。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/
+  verify（**518/518**，`ci.yml` 同步）全绿。
+
+## [0.4.24] — 未发布
+
+**回到系统 emoji 头像** —— 用户口径：「还是采用系统 emoji，（太）卡了」。
+
+### 回退
+
+- 撤销 0.4.23 的 Fluent Emoji 方案（`git revert 5731cbb`）：删掉内联的 22 枚 SVG
+  （`src/client/fluent-icons.jsx`）、`DivisionIcon`、`.t-team-div-icon`，连同它们的许可声明与自检断言。
+  头像回到 **专家自己的 emoji + 名册 `color` 的淡色圆底**（0.4.21 / 0.4.22 那一版），
+  回退链简化为 emoji → 🧩。
+- **为什么卡**（回退时的分析）：那 22 枚是 Fluent 的 **Color** 档，每枚 5–27 KB，内含大量
+  `feGaussianBlur` / `feColorMatrix` 复合滤镜与渐变；它们以 data URI 形式各是一份**独立 SVG 文档**，
+  每张卡片一个 `<img>` —— 浏览器要逐张解析 XML、解码并光栅化，还叠在面板已有的
+  `backdrop-filter` 毛玻璃上。系统 emoji 是**字体字形**，走字体缓存、几乎零成本；
+  这也是「换上去就卡、换回来就好」的直接原因。客户端产物同时从 1.29 MB 回到约 950 KB。
+- **保留** `tools/sync-fluent-icons.mjs`（22 枚的映射表与上游 sha256 都在里面）：将来若想要
+  统一插画风，跑一次就能重新生成；脚本头部已注明「当前未启用」与原因。
+
+### 自检
+
+- 随回退一并还原：断言数 519 → **517**（`ci.yml` 同步），`[13b]` 的随包许可清单不再列 Fluent。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/
+  verify（**517/517**）全绿。
+
+## [0.4.22] — 未发布
+
+**补上「颜色名」形态的色底** —— 0.4.21 的淡色圆底只认 `#RRGGBB`，而名册里 308 位专家有 **182 位**
+写的是 CSS 颜色名（`blue` / `teal` / `navy` / `gold`…），这些人的头像当时会退回中性灰底。
+
+### 修复
+
+- `tintOf` 改用 `color-mix(in srgb, <color> 14%, transparent)`：hex 与颜色名两种写法都吃，
+  也不用自己算 rgba（颜色名后面拼 alpha 后缀是无效值，整条声明会被丢掉）。
+  只放行「#RRGGBB 或纯字母颜色名」两种形态。
+- 老宿主不支持 `color-mix` 时该声明失效，退回 CSS 的中性底色（不影响布局，只是少了那个性色）。
+
+### 自检
+
+- 断言补上颜色名那条正则与 `color-mix` 写法 —— 原来钉的是 `${value}24`，那正是 0.4.21 漏掉
+  颜色名的原因：断言把实现钉死在了 hex 上。
+- typecheck / check-client / render-smoke 9/9 / verify（**517/517**）全绿。
+
+## [0.4.21] — 未发布
+
+**卡片头像改回彩色 emoji（配专家专属色底）** —— 用户口径：「有没有更好的图标库，最好带颜色的」。
+
+### 变更
+
+- 头像内容**优先用专家自己的 emoji**：系统 emoji 本身就是彩色的，而且名册里 323 位专家各自带一个
+  （跟分区无关、每人不同），配上名册 `color` 压出的淡色圆底，正是参考图那种「淡色圆 + 彩色图形」。
+  0.4.20 换上的官方线性图标退居**回退位**：没有 emoji 的老数据才用它，最后兜 🧩。
+- 技能卡头像从官方 `Skill` 图标换回彩色 emoji 🧰（技能没有 color，保留固定灰底）。
+- 淡色底 alpha 12%→14%（`1f`→`24`）：里面放的是彩色图形，底色要再显一点才看得出圆。
+- emoji 字号 20→22px（44px 的圆里更饱满）。顺带删掉不再使用的 `SKILL_ICON` 导出。
+
+### 彩色图标库调研（都是第一手许可文件核过的）
+
+| 库 | 许可 | 单枚体积（实测） | 风格 |
+|---|---|---|---|
+| **Fluent Emoji — Flat** | MIT | **1–3 KB** | 扁平彩色（推荐，22 枚约 30–50KB） |
+| Fluent Emoji — Color | MIT | 5–22 KB | 微软 3D 感插画（22 枚约 200–350KB） |
+| Twemoji | 图形 CC-BY 4.0（需署名） | 1–3 KB | 扁平 |
+| OpenMoji | CC BY-SA 4.0 | — | ShareAlike 对插件许可有传染性，不建议 |
+| DiceBear | MIT | — | 生成式头像，但 323 位要生成/内联 323 张，太重 |
+
+本轮先落地**零依赖那一条**（专家自带 emoji）。要统一插画风的话，下一步可把 Fluent Emoji 的
+22 枚按分区内联（Flat 约 30–50KB / Color 约 200–350KB，MIT，加一条 THIRD-PARTY-NOTICES）——
+预览图已给用户看过，等他定。
+
+### 自检
+
+- 更新 2 条断言：头像改为「emoji 优先 + 回退分区图标 → 🧩」（含 22px 字号与 `24` alpha），
+  技能卡改为「彩色 emoji + 固定灰底」；图标替身数量断言 23 → 22（`SKILL_ICON` 已删）。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/
+  verify（**517/517**）全绿。
+
+## [0.4.20] — 未发布
+
+**专家卡照新参考图重做（官方图标头像 + 大名字 + 底部标签），并修掉「名称不在左边」** ——
+用户口径：「对话框 t 专家弹窗里面的卡片都设计成这种风格，名称都靠左，更换图标，网上找找有没有精美点的图标」。
+
+### 新增
+
+- **头像换成官方图标**：22 个分区各配一个宿主自带的官方产品图标（`Icon*OutlineMedium`），
+  技能卡固定用官方 `Skill` 图标；底色用名册 frontmatter 里的 `color` 压一层 12% 的淡色圆、
+  图标本身用同色实色 —— 就是参考图那种「淡色圆 + 同色图形」。
+  逐级回退：分区图标 → 专家自己的 emoji → 🧩（宿主换图标命名也不会空着）。
+  为什么不去外链图标库：宿主 `primitives` 的 280 个导出里本来就有一百多个 `Icon*`
+  （用它们等于跟官方同一套视觉语言，本插件一贯的口径）；引 CDN 在离线/内网会白给；
+  第三方库（Lucide / Tabler / Phosphor）内联几十 KB 虽然可行，但要连带许可署名与后续升级，
+  收益只是「换一套线性风格」。真要换我再动。
+- **底部标签行**（参考图里那排胶囊）：专家卡放「分区 [+ 自建]」、技能卡放「技能 [+ 仅用户]」；
+  「仅用户」从副标题挪到这里，不再两处重复。
+- 尺寸照参考图再放大一轮：圆角 12→16、头像与头部 40→44、名称 14→15、底高 114→146
+  （14+44+8+36+8+20+14+2），`contain-intrinsic-size` 同步到 146px。
+
+### 修复
+
+- **「名称都靠左」是一处真 bug，不是排版口味**：`.t-team-pop-head` 这个名字同时被**面板标题行**
+  （顶栏「T专家 + 关闭」）用着，而那条规则带 `justify-content:space-between` —— 于是卡片里的
+  「头像 + 名称」被推成两端对齐，名称跑到右边去了。现在用 `.t-team-pop-item .t-team-pop-head`
+  这条更高特异性的规则把它掰回 `flex-start`。断言把两件事同时钉住：卡片头必须覆盖它，
+  而面板标题行那条 `space-between` 也必须在（那才是顶栏该有的样子）。
+
+### 自检
+
+- 更新 3 条（头像 40→44、卡片 114→146、底部标签"回来"了所以那条否定断言改为"带标签但不带召唤按钮"）；
+  新增 5 条：图标 + `color` 淡色底与逐级回退、技能卡头像、名称靠左的修正、底部标签内容、
+  **替身补齐全部 23 个官方图标**（缺一个，那个分区就会静默走 emoji，「图标能渲染」这条等于没覆盖）。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/
+  verify（**517/517**，`ci.yml` 计数同步）全绿。
+- 又双叒踩了一次 CSS 模板的裸反引号（这次是在注释里写 `justify-content:…`），
+  `check-client-refs` 报出行号、esbuild 直接报 `Expected ";" but found "justify"` —— 已改。
+
+## [0.4.19] — 未发布
+
+**箭头圆改成实色、并且真正是正圆** —— 用户口径：「为什么是半透明的？还有要正圆」。
+
+### 修复
+
+- **半透明的来源是圆自己，不是面板**：上一版底色用了 `--dsw-alias-interactive-bg-hover`，
+  这个 token 本身就是 alpha 色（fallback `#0000000d`，约 5% 黑）—— 叠在半透明的官方菜单材质上，
+  整个圆都透出底下的内容。现在换成**实色**的 `--dsw-alias-bg-layer-3`（fallback `#f7f8fa`）。
+- **正圆两处**：
+  · 分类标签与圆**同高 32px**（原先标签 30px、圆 32px）。圆是绝对定位、不参与布局，行高由标签决定
+    —— 两者不等时圆会上下各溢出一部分到行外，看着就是个「被切过的圆」；
+  · 垂直居中去掉 `top:50% + translateY(-50%)`，改成 `top:0;bottom:0;margin:auto 0`：半像素高度下
+    `translateY` 会把圆落在 .5px 上、边缘被重采样，这是「看着不圆」的另一个原因。
+
+### 说明（面板本身的半透明）
+
+如果问的是**整块弹窗**透出下面内容：那是官方菜单材质（`--dsw-menu-surface-fill` 是半透明色
++ `backdrop-filter: blur(40px)`），属于上一轮「材质交给官方 `MenuSurface`」的既定行为，与这次的圆无关。
+要改成不透明实色完全可行（在 `.t-team-pop-official` 上覆盖背景并去掉 backdrop-filter），
+代价是观感与官方菜单不再一致、也会失去 macOS 下的 vibrancy 底层 —— 这一条等确认后再动。
+
+### 自检
+
+- 「箭头」那条断言重写为钉住这次的两件事：底色必须是 `bg-layer-3`（并加了一条**否定**条件：
+  圆底色不许再出现 `interactive-bg-hover`），垂直居中必须是 `top:0;bottom:0;margin:auto 0`
+  且规则里不许出现 `translateY`；同一断言里再钉住标签与圆同高（`height:32px`）。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/
+  verify（**512/512**）全绿。
+
+## [0.4.18] — 未发布
+
+**分类行两端的箭头照参考图放大成实心圆** —— 用户口径：「这种圆形风格行吗，再大一点点」
+（附参考图：浅灰实心圆 + 深灰箭头，没有明显描边）。
+
+### 变更
+
+- 直径 **26px → 32px**，箭头字号 **15px → 18px**（参考图里箭头约占圆的 40%）。
+- 底色 `--dsw-alias-bg-layer-2` → `--dsw-alias-interactive-bg-hover`：参考图里那层灰比底板明显深，
+  而 `layer-2` 铺在半透明菜单材质上几乎融进背景 —— 这其实是上一轮「看着不明显」的另一半原因
+  （不只是没有边线）。
+- 描边随之**收淡**：`border-l2` → `border-l1`（保留一条收边、不再抢眼），hover 时回到 `border-l2`
+  并把箭头颜色提到 `label-primary`。
+- 让位内边距 **32px → 38px**（= 直径 32 + 6px 间隙）：箭头是绝对定位的浮层元素、不占布局高度，
+  这条 padding 是唯一能把它压住的最后一个标签让出来的手段，尺寸一变它必须跟着变。
+
+### 自检
+
+- 「对齐」那条断言里的让位值同步改成 38px；「箭头」那条断言重写为钉住参考图的四件：
+  `box-sizing:border-box` + `width/height:32px`、`border:1px solid var(--dsw-alias-border-l1)`、
+  `background:var(--dsw-alias-interactive-bg-hover…)`、`font-size:18px`，以及 hover 收边到 `border-l2`。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/
+  verify（**512/512**）全绿。
+
+## [0.4.17] — 未发布
+
+**分类行两端的箭头加上描边** —— 用户口径：「左右滚动的图标 < > 最好添加一个表边线，现在看着不明显」。
+
+### 修复
+
+- `.t-team-div-scroll` 原先 `border:0` + 只有一层浅灰底：它浮在半透明的官方菜单材质上，圆的边界
+  与底板糊在一起，看着像一个"没画完"的灰点。现在改成与卡片同一套描边 —— `1px solid
+  var(--dsw-alias-border-l2)`（浅色下约 10% 黑），hover 时加深到 `border-l3`
+  （与 `.t-team-pop-item:hover` 同一档）。
+- 加描边必须同时补 `box-sizing:border-box`：这个圆是 `width/height:26px` 且原本没有
+  `box-sizing`，边框会把外径撑到 28px、把分类行的高度顶起来 —— 分类行的高度直接决定面板高度上限。
+
+### 自检
+
+- 新增 1 条断言钉住这两点：`.t-team-div-scroll` 规则里必须同时有 `box-sizing:border-box` 与
+  `border:1px solid var(--dsw-alias-border-l2)`，且 hover 规则要加深到 `border-l3`。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/
+  verify（**512/512**，`ci.yml` 计数同步到 512）全绿。
+- 又踩了一次 CSS 模板的裸反引号（这次是把 `border:0` 括进了反引号里），`check-client-refs` 立刻报出行号。
+
+## [0.4.16] — 未发布
+
+**分类行支持鼠标滚轮左右滚；顺手治了「弹窗有点卡」** —— 用户口径：「分类这一行要支持鼠标滚轮滚动，
+就是分类可以左右滚动，还有我感觉弹窗页面有点卡，也分析检查下」。
+
+### 新增
+
+- 分类行支持**鼠标滚轮左右滚**（触控板横滑也认，`deltaX` 优先）。用**原生**
+  `addEventListener("wheel", …, { passive: false })` 而不是 React 的 `onWheel`：React 17 起 wheel 是
+  passive 委托，回调里 `preventDefault()` 不生效（还会在控制台告警），纵向滚轮会在滚完分类行之后
+  继续滚下面的列表。现在只在**真的还能往那个方向滚**时才拦，滚到两端就放手 —— 滚轮自然回到列表上，
+  不会「卡住不动」。
+- 分类行去掉了 `scroll-behavior:smooth`：滚轮要的是「转多少走多少」的跟手，平滑只留给那两颗箭头按钮
+  （它们各自传 `scrollBy({ behavior: "smooth" })`）。
+
+### 性能（「弹窗有点卡」的四处收紧）
+
+先说清**卡在哪**，按影响从大到小（每一条都能在代码里指到位置）：
+
+1. **浮层位置每帧 setState，把 300 多张卡片整棵树重新 diff 一遍**（最大的一条）。官方
+   `useAnchoredPosition` 每次重算都是 `setPosition({ left, top })` —— **新对象**，React 必然重渲染
+   拥有这个 state 的组件；而这个 state 原先住在 `SummonButton` 里。更糟的是它监听 `scroll`（捕获阶段），
+   **列表自己滚动也算** —— 「在专家列表里滚一下」于是等于每帧重渲染整棵面板。两处收紧：
+   ① `ui.jsx` 新增 `FloatingPop` 组件把外壳（定位 / 材质 / 关闭）收进去，位置变化只重渲染它，
+   而 `children` 是父级传进来的**同一个 element 引用**，React 直接跳过它的子树（同引用 bailout）；
+   ② 本插件自己的几何重算跳过「浮层内部滚动」（`panelRef.current.contains(event.target)` 就 return）。
+2. **派生数据每个 state 变化都重算**：`experts` 过滤、分类表、`visible`、`grouped`、`visibleSkills`
+   原先都写在渲染函数体里 —— 浮层位置、分类行溢出标记这类完全无关的 state 也会把 300+ 项重新过滤、
+   重新分组。现在六处全部 `useMemo`，依赖写清楚。
+3. **搜索串每次输入都重拼**：`matchExpert` 原本每次调用都把五项字段拼起来再 `toLowerCase()`，
+   323 项 × 每敲一个字符 = 上千次字符串拼接。改成按对象缓存的 `WeakMap`（名册刷新后旧对象自动回收）。
+   本机量化（临时基准 `/tmp/panel-bench.mjs`，323 项 × 200 轮 = 6.46 万次匹配）：
+   **旧 37.1 ms → 新 5.5 ms（约 6.7×）**。
+4. **首屏把 323 张卡片全画出来**：面板一打开就是 323 张卡片 / 2621 个元素 / 191 KB HTML
+   （`renderToString` 中位数 6.2 ms；浏览器还要建真实 DOM、跑 grid 布局、合成毛玻璃，量级更高）。
+   等高卡片（114px，见卡片那段的说明）正好适合 `content-visibility:auto`
+   + `contain-intrinsic-size:auto 114px`：屏幕外的卡片跳过样式 / 布局 / 绘制，真正要画的是可视区那十几张。
+
+**仍可能让人觉得"卡"、这次刻意没动的**：官方菜单材质 `backdrop-filter: blur(40px)` 铺满整块面板，
+大面积毛玻璃合成本身就贵（这是"与官方观感一致"的代价）；面板也没有上真正的虚拟列表
+（`content-visibility` 是低风险的等效手段）。如果实机还是卡，下一步的候选是：材质降级为不透明底色、
+或给列表上虚拟滚动 —— 都等你实机感受后再定。
+
+### 自检
+
+- 新增 7 条断言：滚轮横向滚（原生非 passive + 两端放手）、滚轮跟手 / 箭头平滑（分类行不许再写
+  `scroll-behavior`）、`FloatingPop` 收口（且父级不许写成 `{open && <FloatingPop`）、内部滚动不重算几何、
+  六处 `useMemo`、卡片 `content-visibility`、`matchExpert` 的 `WeakMap` 缓存。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/
+  verify（**511/511**，`ci.yml` 计数同步到 511）全绿。
+
+## [0.4.15] — 未发布
+
+**分类行两端都能滚** —— 用户口径：「点更多分类按钮后，左边也应该有这个按钮，这样用户才能回到左侧」。
+
+### 修复
+
+- 分类行原来只有右端的圆形箭头，滚到中间之后**没有任何回到左侧的入口**（只能手动横向拖）。
+  现在左侧会出现一个同款的 `‹`：
+  · 左端在「已经滚过去了」时出现（`scrollLeft > 1`），右端在「右边还有没露出来的」时出现
+    （`scrollLeft + clientWidth < scrollWidth - 1`），滚到两端时对应的箭头自己消失；
+  · 两个方向各滚一屏的 80%（左为负、右为正），带 `behavior:"smooth"`；
+  · 两个箭头都是 26px 圆形、各贴一侧（`.t-team-div-scroll[data-dir="prev"|"next"]`）。
+- 给箭头让位的内边距**只在那一侧的箭头真的出现时才加**（`.t-team-divbar[data-back="true"]` /
+  `[data-more="true"]`）：没滚动时左侧不加 `padding-left`，第一个标签仍与搜索框左边缘对齐 ——
+  上一轮用户点的那条「对齐宽度」不受影响。
+
+### 自检
+
+- 「对齐」那条断言补上左侧让位规则；「溢出」那条扩成两端：两个 `data-dir` 规则、两个方向的滚动量
+  （一正一负）、`setDivBack(node.scrollLeft > 1)` 与 `setDivMore(...)` 都在；文案断言补 `pop.divisionsPrev`。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/ verify（**504/504**）全绿。
+- 顺手记一笔：这条断言的标签里第一次误用了英文双引号，把 JS 字符串截断了 —— 本仓库中文文案一律用「」。
+
+## [0.4.14] — 未发布
+
+**输入区面板的搜索框下面加一行分类标签** —— 用户口径：「对话框的 T专家 弹窗在搜索框下面增加一行
+分类标签，注意对齐宽度」（附了一张分类标签行的参考图：圆角标签、选中项浅灰底、右端一个圆形箭头）。
+
+### 新增
+
+- 专家标签页的搜索框下方新增**分类筛选行**：第一项「全部」，后面依次是名册里出现过的分区
+  （学术、公司经营、设计、工程、金融… 就是列表里那些分组标题，随界面语言显示中文或英文名）。
+  点一个只看那一类；与搜索词**叠加**生效（选了分类还能继续搜），切换时列表回到顶部。
+- 选项**从名册现算**并保持首次出现的顺序，与下面列表里分组标题的顺序、文案完全一致
+  （列表本来就按 `snap.experts` 的顺序分组）；不学设置页那样按 slug 排序，免得同一屏里两处顺序对不上。
+  名册还没到、或一位专家都没有时不渲染这一行。
+- **横向滚动**：22 个分区在一屏里放不下（浮层宽度跟输入框走），所以这一行横向滚动、隐藏滚动条，
+  并在溢出时于右端露出一个圆形箭头按钮（点一下滚一屏的 80%）。箭头挂在行外层 `.t-team-divbar` 上
+  而不是滚动容器里 —— 滚动容器的绝对定位子元素会跟着内容一起滚走。
+- 只在**专家**标签里出现：技能没有分类概念，技能页保持原样。
+
+### 对齐宽度（用户特别点的那句）
+
+- 这一行与搜索框、下面的卡片对齐靠的是**结构**而不是数值：它就是 `.t-team-pop` 的直接子元素，
+  和别的行一样吃 `> *:not([aria-hidden])` 的 10px 右内边距，左边同样由容器自己的 `padding-left` 提供。
+  所以这一行（以及里面两个容器）都**不许**写左右内边距 —— 写下就会比搜索框窄一截或偏一截。
+  唯一允许的一处 padding 是给右端箭头让位的 `padding-right:32px`，且它挂在 `[data-more="true"]` 上，
+  没溢出时根本不生效。
+- 自检里把这两件事都钉住了：三处选择器的**精确**写法（`.t-team-divbar{…min-width:0}` /
+  `.t-team-pop-divs{…overflow-x:auto` / 那条 `> *:not([aria-hidden])` 规则），
+  以及"唯一那条 data-more 上的 padding"。
+
+### 自检
+
+- 新增 5 条断言：分类行在搜索框下面且只在专家标签、选项从名册现算（「全部」+ 分区 + 叠加筛选）、
+  对齐宽度（上面那组精确写法）、溢出处理（横向滚动 + 箭头在 bar 上 + 点击滚动量）、
+  两种语言的文案都在且被字面量引用。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/
+  verify（**504/504**，`ci.yml` 计数同步到 504）全绿。中途又踩了一次 CSS 模板的裸反引号
+  （注释里写「> *」时手滑加成反引号），`check-client-refs` 立刻报出行号。
+
+## [0.4.13] — 未发布
+
+**输入区「T专家」面板的外壳改用官方 primitives** —— 用户口径：这个弹窗要拉齐官方。
+定位与跟随、视口钳制、外部点击关闭、菜单材质四件事交回官方；官方**没有**的那几件仍由本插件负责。
+
+### 变更
+
+- 外壳（`ui.jsx` 新增 `useFloatingShell` / `PopSurface`）走官方三件：
+  · `useAnchoredPosition` —— 坐标与跟随（`scroll` 捕获 / `resize` / 面板自身 `ResizeObserver`）；
+  · `useDismissOnOutsidePointer` —— `pointerdown` 落在浮层外就关（顺带覆盖触屏与笔）；
+  · `MenuSurface` —— 菜单材质，外加 macOS 下给 Chromium 用的 vibrancy 底层。
+  为什么只换外壳、不整块照搬官方：官方 primitives 里**没有浮层组件**，只有 hooks 与材质容器，
+  官方自己也按需组合 —— `dsh-client-ui-conversation` 的 ContextMeter 是
+  `useAnchoredPosition`（`side` 写死 `"top"`）+ `useDismissOnOutsidePointer` + **手写 Escape**；
+  `dsh-client-ui-input-trigger` 的 `/` 菜单则把位置交给布局，只用 `useAnchoredMaxHeight` 钳高度。
+- **翻转、宽度、高度上限、Escape 四件仍由本插件负责**，逐条都有理由（都对着上游源码核过）：
+  · **翻转**：官方 `side` 是静态入参，全部 4 个 `useAnchoredPosition` 调用点都是字面量，没有
+    「上方不够就翻下去」的先例；而这条正是我们修过的 bug（新会话输入框居中时面板顶部被裁）。
+    判据沿用改造前的行为（哪边空间多朝哪边、相等时朝上），交互不变；
+  · **宽度**：官方 `useAnchoredPosition` 不管宽度（只用面板自身宽度钳右边界），「和输入框一样宽」
+    继续走 `--t-team-pop-w`；
+  · **高度上限**：官方 `useAnchoredMaxHeight` 是给「底边由布局固定」的浮层用的（读自身 `bottom` 算上界），
+    而我们的位置由高度反推（`top = 锚点顶 - 间距 - 高度`），拿它算会因为 `bottom` 随位置一起动而
+    **不收敛**，所以自己按**同一套上界规则**算；
+  · **Escape**：官方 hook 不管它。
+- **上边界改按官方规则让位**：新增 `overlayTopMargin`（算法照抄 primitives：框架顶部占用区
+  `--dsh-frame-top-clearance` + 20px，原生全屏时不算占用区）。桌面端向上弹时面板因此比之前矮一点、
+  不再顶到窗口框架那一带。
+- **兜底与老宿主**：三件官方件任一缺席（老宿主、自检替身）就退回本插件的等价实现（同样的算法与重算时机），
+  材质退回 `.t-team-pop` 自绘那一套 —— 与 `ui.jsx` 顶部「官方优先、缺了退回自绘」同一条约定。
+  走官方材质时容器多加 `t-team-pop-official`，把自绘的边框/底色/滤镜清掉：官方材质是父级内部一个
+  `aria-hidden`、`z-index:-1` 的兄弟层，父级自己再铺一层底色就会把它整个盖住。
+- 顺带修一处会被材质层踩到的 CSS：`.t-team-pop > *` 补 10px 右内边距那条要排除 `[aria-hidden]`
+  （否则官方材质层少吃一条、右边露出底色）。
+
+### 自检
+
+- 新增 6 条断言：官方三件都被探测并使用、翻转仍自写、顶部让位按官方规则、官方材质模式下自绘材质被清掉、
+  Escape 仍自写、**替身补齐三件**（缺一件，官方分支在自检里就等于没有覆盖）。
+- 改写 2 条旧断言（手算的 `place()` / `wantedLeft` 已删）：宽度与左边缘对齐改为钉「宽度变量 + 官方
+  `align:"start"`」；右边界钳制改为钉「官方 hook + 兜底实现里同一句钳制」。
+- typecheck / check-client（13 个文件 0 处未定义标识符）/ render-smoke（9/9）/ verify（**499/499**，
+  `ci.yml` 里的计数同步到 499）全绿。
+
+### 待真机确认（本机没有真实布局，离线复现不了的三件事）
+
+- 面板打开时**不抖动**：定位 hook 的 `top` 依赖面板高度、高度上限又由本插件算，两者靠 `ResizeObserver` 收敛；
+- 向上弹时按官方顶部让位（桌面 48+20）后的高度，观感是否可接受；
+- 官方 `MenuSurface` 的 macOS vibrancy 底层在桌面壳里没有黑块或闪烁。
+
+## [0.4.12] — 未发布
+
+### 新增
+
+- **提示词弹窗加了「复制」按钮**（用户要求：放在关闭按钮旁边）。官方 `Modal` 的标题栏只有
+  「标题 + 关闭」两个位置、**没有插槽**，所以按钮渲染在正文之前，靠 CSS 绝对定位"落"到关闭
+  按钮左侧：定位基准是官方 `.dialog`（`Modal.module.css` 给它 `position: relative`），
+  因此正文滚动时按钮不动；偏移量照着官方 `.header` 的 padding 与 `.close` 的 28×28 算 ——
+  `top:22px`（header 的 padding-top）、`right:50px`（14px 右内边距 + 28px 关闭按钮 + 8px 间隔）。
+  点一下变「已复制」，写不进去变「复制失败」，1.6s 后回到「复制」。
+  **失败也要出声**：Clipboard API 在非安全上下文里缺席是常态，点了毫无反应只会被当成按钮坏了。
+  复制走官方的 `writeClipboard`（异步 Clipboard API + `execCommand` 兜底），不是裸
+  `navigator.clipboard`。正文还在读、读失败、或本身为空时按钮禁用 —— 复制一段"正在读取…"
+  没有意义。换一位专家会重置反馈，免得把上一位的"已复制"看成这一位的。
+
+### 修复
+
+- **新增一道构建前门禁：CSS 模板里的裸反引号**。`css.js` 整个 CSS 是一个 JS 模板字符串
+  （`export const CSS = ...`），注释里再写一个反引号就会把它提前终止；
+  而 esbuild 报的是 `Expected ";" but found "max"` 并指向 **CSS 内容本身**，完全看不出是
+  模板字符串被截断。而且它只在真正构建时炸，`lib/client.js` 又是提交进仓库的产物 ——
+  构建失败意味着产物悄悄停在上一版。2026-09-28 一次会话里连踩三次（顺手把
+  `max-height: 100%`、`min(380px,100%)`、`position: relative` 用反引号括了起来）。
+  现在 `check-client-refs.mjs`（build / verify / prepublishOnly 都会先跑它）会扫描
+  `css.js` 的模板体并报出首个反引号的行号；已用「故意插一个」反向验证过能拦住。
+
+### 自检
+
+- 490 → **493 项**：新增三条 —— 复制按钮接入且文案走字典（禁硬编码）、
+  定位规则在位（丢了按钮会掉进正文按钮流，不在关闭按钮旁边）、
+  复制优先走官方 `writeClipboard`（退回裸 API 会在非安全上下文静默失败）。
+  「CSS 模板裸反引号」那道门禁落在 `check-client-refs.mjs` 里（build 的前置），不在 verify 计数内。
+  ci.yml 计数同步到 493。
+- typecheck / check-client / build / verify（493/493）全绿；`lib/client.js` 已重建（对齐 0.4.12）。
+
+## [0.4.11] — 未发布
+
+弹窗**形状**：0.4.10 治了「漫出屏幕」，但没治「长得不对」—— 用户接着反馈「太长 太窄」。
+
+### 修复
+
+- **提示词弹窗恢复成适合阅读的形状**。官方 `.dialog` 的 `min(380px, 100%)` 宽 + 不设高度
+  上限，是给**确认框**设计的尺寸（一句话 + 两个按钮）；拿它装专家 persona 全文（动辄上万行）
+  就成了又高又窄的窄条：380px 宽意味着长行几乎每句都折行，再撑满视口高度，读起来像从门缝
+  里看。0.4.10 只解决了"内容漫出视口"，形状问题当时没看见 —— 这两件事得分开修。
+  现在按内容类型给尺寸：
+  - 提示词弹窗（纯阅读）→ `width:min(960px,94vw)` + `max-height:min(84vh,800px)`；
+  - 编辑器弹窗（有表单）→ `width:min(860px,94vw)` + `max-height:min(84vh,800px)`
+    （宽度是 0.4.10 恢复的那条，这次补上高度上限）。
+  两档高度一致，来回切不会跳。
+  ⚠️ 这两条**必须写在 `.t-team-modal-fit` 之后**：同为单类选择器、特异性相同，`max-height`
+  谁在后面谁生效；顺序一反，`max-height:100%` 就会盖掉弹窗自己的高度上限，表现正是
+  "又占满整屏"。这条顺序本身也进了自检。
+
+### 自检
+
+- 488 → **490 项**，新增两条：提示词弹窗的宽高约束在位、两条尺寸规则确实写在
+  `.t-team-modal-fit` 之后。第二条**当场抓到一处真问题** —— 编辑器那条规则被写了两遍
+  （第一轮的 860px 留在文件开头，第二轮又写了一份），开头那份会让顺序约束失效。
+  ci.yml 计数同步到 490。
+- typecheck / build / verify（490/490）全绿；`lib/client.js` 已重建（版本对齐 0.4.11）。
+
+## [0.4.10] — 未发布
+
+两个**弹窗**的回归：都是「改用官方 `Modal`」那一批留下的，用户看到的是"弹窗样式出问题"。
+
+### 修复
+
+- **查看提示词时弹窗漫出屏幕**（用户 2026-09-28 报）。官方 `Modal` 的 `.dialog`
+  **没有 `max-height`** —— `Modal.module.css` 的注释把这件事明确交给调用方
+  （*cards size against this padding box: consumers cap growth with `max-height: 100%`*），
+  而它同时 `createPortal(…, document.body)`、`.root` 只负责居中不做滚动。于是内容一长就
+  整体顶出视口：专家 persona 动辄上万行，弹窗被撑到远超屏幕高度，看起来就是"样式崩了、
+  文字漫出来"，而不是一个能滚的对话框。
+  修法按官方约定分三层，缺一层都不生效：
+  - `.t-team-modal-fit` → dialog 相对 `.root` 的 padding box 兜住高度（`max-height:100%`）；
+  - `.t-team-modal-fit-content` → 官方 `.content` 允许收缩（flex 子项默认 `min-height:auto`
+    会把父级继续撑破）；
+  - `.content > div:last-child`（官方 `.body`）自己 `overflow:auto` —— 标题栏与关闭按钮
+    因此固定在顶部、始终可点。
+  这一层做在 `ui.jsx` 的 `Modal` 封装里，**所有调用方自动受益**，不必各自处理高度。
+- **自建专家编辑器被压窄到 380px**（同一批改动的遗漏）。`.t-team-editor-modal`
+  （`width:min(860px,94vw)`）是自绘 Modal 时代的类名，改用官方封装后**没有任何代码再引用它**
+  —— 而官方 `.dialog` 默认只有 `min(380px,100%)` 宽，编辑器要编辑 persona 正文（多行
+  Markdown），380px 挤不下。现已把该类名重新接到 editor 弹窗上（死代码复活）。
+  同类死规则 `.t-team-editor-body`（含它的 `.t-team-picker-list` 上限）确认无引用者，删除。
+- 顺带修正 `.t-team-prompt-body` 的职责：提示词正文原先复用自绘兜底 Modal 的内部类名
+  `.t-team-modal-body`，会带上不属于它的 `padding:14px`（官方 `.body` 已有 `padding:0 24px`，
+  叠加成 38px）。现在两者各用各的名字，滚动交给上面那层 `.body`。
+
+### 自检
+
+- 483 → **488 项**，[6b] 新增 5 条专钉这次的两个回归与一个死代码：官方 Modal 的三层高度约束
+  齐备、`Modal` 封装**真把限高类交给了官方组件**（只断言"CSS 里有这个类名"挡不住
+  "封装没传"，那正是这次的成因）、提示词正文不再复用兜底类名、编辑器宽度约束在位、
+  `.t-team-editor-body` 死样式没长回来。ci.yml 两处计数同步到 488。
+- typecheck / build / verify（488/488）全绿；`lib/client.js` 已重建（内嵌版本常量对齐 0.4.10）。
+
 ## [0.4.9] — 未发布
 
 对宿主版本的 peer 范围收敛为**只保留下限**：内核以后升级，这一行不用再改。