dsh-connect-trae 3.4.1 → 3.4.3

package/CHANGELOG.md

@@ -1,5 +1,165 @@
 # Changelog
 
+## 3.4.3 (2026-10-13)
+
+> **保存模型列表时终于有了「正在进行」的反馈。** 本版对齐同族 `dsh-connect-workbuddy` 4.4.2
+> 对忙碌遮罩做的修正（该处修的是同族共有的缺陷），并把当初核实过的依据一并带过来。
+
+### 新增
+
+- **保存 / 写设置时有一层忙碌遮罩**（新增 `src/client/BusyOverlay.tsx`，共用组件）：
+  - **此前完全没有。** 保存状态只表现为控件变灰加按钮文案从「保存」变「保存中…」——
+    用户盯着某个具体行等它落地时，屏幕上没有任何「正在进行」的迹象。
+  - 遮罩由卡片的**两条**写路径共同驱动：`saveModels` 的 `saving`（保存模型列表）与
+    `writePreference` 的 `savingSettings`（跟随登录 / 输入框读数两个开关）。
+  - 遮罩在该写路径的 `finally` 里随忙碌标记一起落下，也就是 **Host 重读落地的时刻**——
+    延迟从「看不见」变成「看着它发生」。
+
+### 修复
+
+- **遮罩的配色与动效改用宿主自己的令牌与节奏**（对齐同族 workbuddy 4.4.2）：
+  - **遮罩卡片底色**若沿用同族的旧值 `--dsw-alias-bg-primary`，那个变量**在宿主令牌集里根本不存在**
+    （实测宿主 bundle 零命中；宿主只有 `bg-base` / `bg-layer-1..3` / `bg-module-platform` / `bg-overlay` 等），
+    于是一路回退到写死的近黑 —— 卡片变成一块黑板子，上面的字看不清。现改用宿主给弹层用的
+    `--dsw-alias-bg-layer-2`，亮暗两套主题各自成立；阴影也从手写的 drop shadow 换成宿主的
+    `--dsw-elevation-prominent`。
+  - **遮罩底色**原写死 `rgba(0,0,0,.38)`，既不跟随主题、也没有宿主的模糊。改用宿主自己遮罩用的
+    `--dsw-alias-bg-mask-1`（亮 `.24` / 暗 `.5`）+ `--dsw-mask-blur`，与外壳里其他遮罩一致。
+  - **提示行**用 `label-secondary` —— 原先的 `label-tertiary` 是宿主最暗的一档
+    （亮 `neutral-bluish-600`、暗 `neutral-bluish-400`），给元数据用的，不该承载一句要等的人必须读的话。
+  - **spinner 换成宿主同款弧线**。此前那种 18px 的 CSS border 环、`.7s` 匀速转，比宿主自己的状态
+    转圈（`_dsh-state-dot-spin`：SVG 弧线 + dash 呼吸、`1.5s`）快了近一倍 —— 比起形状本身，
+    **这个速度差才是它看着廉价的主因**。现按宿主 bundle 实测到的几何逐条对齐：
+    `viewBox 0 0 20 20`、`r=8`、`stroke-width 2`、track `opacity .25`、弧线 `stroke-dasharray 12 150`
+    与 dash 呼吸、`1.5s`、`currentColor` 继承所在层级；reduced-motion 降级为**静态弧线**
+    （与宿主降级方式一致），并补 `aria-hidden`，免得 `role="status"` 之外多报一次。
+
+### 测试
+
+- **+4**（`tests/card-styles.spec.tsx` 5 → 9，全仓 **594 → 598**）：
+  - 遮罩选择器守卫：逐条钉住五个遮罩规则，且要求整条 `{` 结尾匹配，避免改名前缀后被子串误判为存在。
+  - 弧线节奏守卫：钉住 `dsm-trae-veil-dash` 关键帧与 reduced-motion 降级，防止退回到自绘 border 环。
+  - **渲染守卫（唯一能证明「遮罩真的出现」的断言）**：jsdom 不做层叠，前几条都只证明样式表里有这些
+    名字。这条在 `scope.set` 挂起的条件下点「跟随 Trae 当前登录的账号」，断言遮罩确实进 DOM
+    （`role=status` / `aria-busy=true` / `aria-live=polite`）、文案为 `row.veilSaving`、弧线与卡片都在，
+    写盘落地后卸载。
+  - 令牌白名单补三条（`--dsw-alias-bg-mask-1` / `--dsw-mask-blur` / `--dsw-elevation-prominent`），
+    三者均经宿主 bundle 实测存在。白名单断言「大小必须等于实际用到的令牌数」，遮罩引入新令牌后必须同步补齐。
+  - 变异验证（各自变红后恢复）：把 `.dsm-trae-veil{` 改成 `.dsm-trae-veilz{` → 仅选择器守卫变红；
+    把 `visible={saving || savingSettings}` 改成 `visible={false}` → 仅渲染守卫变红。
+  - **一处诚实记录，不夸大守卫能力**：本仓库的 `vite/oxc` 与 `tsdown` 比 workbuddy 严格，模板字符串被
+    反引号截断后会**直接报解析错误**（构建同样失败），所以「顶层语句数」那条截断守卫在本仓库
+    不会比它们更早报警。真正拦不住截断的是 `tsc`（实测被截断的文件 `tsc` 仍 `exit 0`）——
+    这正是同族当初能静默中招的原因。那条守卫作为「解析器不再拦时的兜底」保留。
+
+### 文档
+
+- 无。本版只含上述新增、修复与配套测试。
+
+## 3.4.2 (2026-10-13)
+
+> **插件现在与它自己解析到的那份 `@earendil-works/pi-ai` 代数对齐了**——这是 [issue #27](https://github.com/dingminhua/dsh-connect-trae/issues/27)
+> 的修复。起因是报告人用任意模型都拿到 `PI_AI_ERROR / Cannot read properties of undefined (reading 'length')`，
+> 且 usage 恒为 0：崩溃发生在**请求发出之前**的本地 token 估算里，所以既与模型无关，也看不到任何 HTTP 痕迹。
+> 取证见 `docs/ISSUE27_DIAGNOSIS.md`。
+
+### 修复
+
+- **插件现在会在两种上下文形状之间双向适配，而不是把宿主的形状原样交给自己的 api**（issue #27）：
+  - **原行为**：`createTraeAdapter` 把 `openAICompletionsApi()` 直接交给 `createProvider`，没有任何适配层。
+    插件声明 pi-ai 为 peer（`>=0.85.1`），所以它解析到哪一份**由安装环境决定**，未必是宿主那一份。
+  - **为什么这是必崩**：pi-ai **0.86 起**在每个公开入口调一次 `normalizeContext()`，于是 provider 收到的是
+    *归一化 transcript*：`{ messages: [ { role:'system', content:<字符串>, toolsAdded }, … ] }`——系统提示与工具声明
+    **只**挂在这条 system 消息上，顶层 `systemPrompt` / `tools` 已被删除。而 ≤0.85 的 `estimateMessageTokens`
+    **没有 `role === 'system'` 分支**：它 `for (const block of message.content)` 迭代一个**字符串**，逐字符拿到
+    `block`，再读 `block.name.length` → `TypeError`。因为这一步位于 `buildBaseOptions` 内、早于任何 HTTP 构造，
+    所以现象就是「105ms 内本地崩溃 + usage 恒 0 + 换模型无效」。
+  - **两个方向都要修**，因为 **DSH 自己也横跨两代**（`dsh-llm-pi-ai` ≤0.2.0-rc.1 声明 `^0.85.1`，0.2.0-rc.2 起声明
+    `^0.87.1`，0.2.1-alpha.2 已到 `^1.0.2`），而本插件声明支持 `>=0.1.7-rc.1 <0.3.0-0`：
+    - **新宿主 + 旧库**（issue #27 本尊）：必崩。
+    - **旧宿主 + 新库**：不崩，但现代 api 只从 system 消息读提示与工具，顶层字段被**静默忽略** → 系统提示与
+      **全部工具声明**丢失（模型永远不会产生 toolCall）。只修前者会把一个响亮的故障换成一个安静的故障。
+  - **改后**：新增 `withContextAdaptation(api, generation)`，按**本插件自己解析到的那一代**决定折返方向；
+    两个适配函数都以**形状**做幂等短路（普通路径返回同一个对象，零分配）。
+    - `adaptLegacyPiAiContext`（transcript → 旧形状）：把 system 文本提升为 `systemPrompt`，并把
+      `toolsRemoved`/`toolsAdded` **按序回放**成顶层 `tools`——工具那一步不能省，`normalizeContext` 之后它是
+      工具声明的**唯一**载体。
+    - `adaptModernPiAiContext`（旧形状 → transcript）：把 `systemPrompt`/`tools` 提到一条首部 system 消息上，
+      并移除顶层字段，避免后续的形状判据误判。
+  - **提示文本的三条载体都要搬，`sections` 不能漏**：新代 `SystemMessage` 的提示文本有 `content` 与
+    `sections` 两条载体（`Record<string, string | null>`），库自己的 `getSystemMessageText` 是
+    「`content` + 全部非 null section」按空行连接。只读 `content` 会让以 section 形态到达的提示整体折成
+    `undefined`——与该适配器要防的「静默丢失」完全同类。现已逐字对齐库的语义（`content` 在前、
+    按声明顺序接 section、跳过 `null`）。
+  - **折上的语义与 `normalizeContext` 逐字对齐，包括「混合形状」**：当上下文**同时**带顶层字段和
+    system 消息时（部分归一化的宿主），pi-ai 自己的做法是**前插**（于是有两条 system 消息，provider 再按
+    空行折叠），本插件因此同样前插。实测该输出经真实 0.87.1 的 `resolveTranscript` 折叠后，与
+    `normalizeContext` 的结果**逐字相同**。早先版本在混合形状下直接原样返回，会静默丢掉顶层提示与其
+    工具——这条是评审的变异测试暴露的（见「测试」）。
+- **代际判据落在 0.86，不是 0.87**（issue #27）：
+  - 报告与兄弟插件的既有实现都按 `>= 0.87 → modern` 划分。实测**真实边界是 0.86.0**——
+    `dist/utils/transcript.js`、`normalizeContext`、估算器的 system 分支、以及「不再读 `systemPrompt`/`tools`」
+    四件事**同时**出现在 0.86.0。
+  - **为什么这个偏差有害**：若插件解析到 **0.86.x**，`>= 0.87` 的判据会把它当旧代而执行折返，而 0.86+ 的 api
+    根本不读顶层字段 → 系统提示与全部工具被静默丢弃。即「照抄现成实现」反而会引入一个新的静默故障。
+- **新增 `src/pi-ai-runtime.ts`：世代探测不依赖版本号字符串**（issue #27）：
+  - 主判据是解析到的那份包 manifest 的版本，用**数值**比较（`major > 0` 或 `minor >= 86` 即现代），
+    因此 `0.9.0` 不会被误判为高于 `0.86.0`，已发布的 `1.x` 也无需改动即可正确归类。
+  - 版本读不到时退化为**包布局**判据（`dist/utils/transcript.js` 是否存在）。
+  - **刻意不使用 `import.meta.resolve()` 做能力探测**：bundler 风格的解析器（vite，以及在它之上的 vitest）
+    会把 exports map 里的 `"./utils/*"` 通配符展开成路径**并直接返回，不检查文件是否存在**，于是对 0.85.1
+    也回答「有」——实测该假阳性会把 0.85.1 判成 modern，从而**在声称按能力判断的同时放过 issue #27**。
+    读包目录则不会被这样骗过。
+  - 解析不到 pi-ai（宿主外探测的市场安装）时取 `modern` 透传：每个做归一化的宿主都同时提供现代代，
+    且透传不可能破坏一个本来就正确的上下文。
+
+### 诊断
+
+- **启动时打印解析到的 pi-ai 版本与代数**（issue #27）：混代安装是「安静坏掉」的那一类，日志里一行
+  `dsh-connect-trae: pi-ai 0.85.1 (legacy generation)` 让它在下次出现时立刻可见，而不是只表现为一次崩溃。
+
+### 测试
+
+- **全仓 549 → 594（+45）**：
+  - `tests/pi-ai-context.spec.ts`（38 例）：代际判定（含 0.86/0.87 边界、数值排序、`1.x`、不可读版本）、
+    `decidePiAiGeneration` 的三条分支（含本机**永不可达**的「什么都没探测到」——市场安装的默认答案，
+    必须显式钉住）、折返（提示提升、**工具提升**、`toolsRemoved`/`toolsAdded` 顺序回放、既有顶层 `tools`
+    权威、空文本 system 消息只丢文本不丢工具、文本块、**`sections` 三条载体**、混合形状、畸形输入）、
+    折上（提升、移除顶层字段、幂等、空提示、**混合形状前插**）、
+    `withContextAdaptation`（两个入口都适配、同形状透传为**同一对象**、保留 `fetchDeferred` 等其余字段），
+    以及**对真实解析到的那份 pi-ai 的集成对拍**：`estimateContextTokens` 不抛错、`convertMessages` 后
+    `messages[0].role === 'system'` 且 `tools` 仍在。
+  - `tests/pi-ai-adapter-wiring.spec.ts`（7 例）：**接线层**用例。上面那批函数级用例在把适配层从工厂里删掉后
+    **依然全绿**（已用变异验证），正是「函数没问题、只是没人调用」这一原始缺陷的形状；本文件 mock 掉
+    `openai-completions.lazy`，经 `adapter.current() → piProvider → streamSimple` 走真实装配路径断言交付给
+    api 的形状。
+  - **变异验证 8 次，8 次全部被抓**（①–⑤ 为自查，⑥–⑧ 由独立评审提出）：
+    ① 工厂里移除适配层 → 5 例失败；② 折返只搬 prompt 不搬 tools → 6 例失败；③ 边界写成 `>= 87` →
+    1 例失败；④ 折上时不移除顶层字段 → 2 例失败；⑤ 折返不做幂等短路 → 5 例失败；
+    **⑥ 折返忽略 `sections` → 2 例失败**；**⑦ 折上跳过多 system 消息的混合形状 → 1 例失败**；
+    **⑧ 不可探测时默认 `legacy` → 1 例失败**。恢复后 57 文件 594 例全绿。
+  - 确认新增用例真的在跑：改动前基线 **549**、改动后 **594**，净增 45，与新增用例数一致。
+
+### 独立评审
+
+发布前由独立评审对 diff 做了对抗性复核（真实发布包 + 真实 api 模块），确认：双向四组合均不丢提示、
+不丢工具、不重复 system 消息；**0.86 边界**在 0.85.1/0.86.0/0.86.1/0.87.1/1.0.2 五个真实 tarball 上
+逐项复核成立；**`import.meta.resolve` 的假阳性被独立复现**（该模块在 0.85.1 磁盘上不存在，vite 仍返回
+其 URL）；接线层用例确实覆盖工厂路径。
+
+评审同时提出 **3 条有效缺陷**，均已修复并补上用例（即上表 ⑥⑦⑧）：`sections` 载体被漏读、
+混合形状下折上会静默丢弃顶层提示与工具、以及不可探测分支的默认值无任何用例约束。
+
+### 文档
+
+- `docs/ISSUE27_DIAGNOSIS.md`：对外部报告的逐条核验——链路 6 跳的取证、双向错配四组合矩阵的实测结果、
+  DSH 各版本与 pi-ai 代数对照，并明确指出该报告的 **3 处硬错误**（代际边界实为 0.86 而非 0.87；
+  CASE B 实测为 `{"tokens":25}` 而非 `15`；`undefined maxTokens` 实为 `NaN` 而非「夹回正整数」）
+  与 **2 处需修正的修复建议**（「收紧 peer 即可在安装期被拒」不成立——DSH 内核预检
+  `evaluatePluginCompatibility` 只覆盖 `@deepseek-ai/dsh*`，pi-ai 不在其中，报告引用的 `install-compat`
+  告警来自 dshmarket 社区插件且属只告警不阻止的 `soft-incompatible`；以及「升级 DSH」解决不了问题，
+  报告人本就在最新的 0.2.0-rc.2 上，而升级只会把他更牢地留在「新宿主」一侧）。
+
 ## 3.4.1 (2026-10-12)
 
 > **`4011` 的含义改正了：它是 Trae 对 SOLO 通道的限流，不是「该 function 不提供此模型」。**

package/README.en.md

@@ -138,6 +138,25 @@ Restart the DSH process after install/update/uninstall.
 **Requires DSH 0.1.7-rc.1 and up** (since 2.3.0 the plugin no longer targets hosts older than 0.1.7; the peer dependency ranges are narrowed accordingly).
 **The peer upper bound is `<0.3.0-0`, so both the 0.1.7 and the 0.2 line are supported.**
 
+### Both pi-ai context generations are supported (since 3.4.2)
+
+DSH itself spans two generations of `@earendil-works/pi-ai`, and **which one this plugin resolves to is decided by your install**, not by the host — declaring it a peer is correct, but the two generations disagree on what a context looks like:
+
+| | legacy (≤0.85) | modern (0.86+) |
+| --- | --- | --- |
+| shape | `{ systemPrompt, tools, messages }` | `{ messages: [ {role:'system', content, toolsAdded}, … ] }` |
+| system prompt | top-level `systemPrompt` | **only** on that system message |
+| tool declarations | top-level `tools` | **only** on that system message's `toolsAdded` |
+
+A mismatch breaks **in both directions**, so since 3.4.2 the plugin adapts bidirectionally according to the generation it resolved (issue #27):
+
+- **Modern host + legacy library**: a guaranteed crash — the legacy token estimator has no `role === 'system'` branch, so it iterates a string and throws `Cannot read properties of undefined (reading 'length')`. This happens before the request is built, which is why it looks like "every model crashes, within milliseconds, with all-zero usage".
+- **Legacy host + modern library**: no crash, but the modern api reads only that system message and silently ignores the top-level fields — the system prompt and **every tool declaration** are lost, so the model can never emit a tool call. Quieter, and also fixed.
+
+The generation gate is the copy **this plugin resolved** (its manifest version; package layout when that is unreadable), **not the host version** — a nested older copy shadows a newer host copy and vice versa. Startup logs one line, `dsh-connect-trae: pi-ai <version> (<generation>)`; `legacy` means your install resolved to the ≤0.85 line.
+
+The boundary is **0.86**: `dist/utils/transcript.js`, `normalizeContext`, the estimator's system branch, and the switch away from the top-level fields all land in 0.86.0 together. Gating on `0.87` misclassifies 0.86.x as legacy and folds a context the modern api consumes natively, destroying the prompt and the tools.
+
 The 0.2.0 line breaks **no** contract this plugin consumes — a symbol-by-symbol check confirmed every API it imports is unchanged ([full 0.2.0-rc.1 impact check](https://github.com/dingminhua/dsh-connect-trae/blob/main/docs/DSH_0.2.0_RC1_IMPACT_CHECK.md)). But since 0.1.7 DSH enforces a **bundle-level peer gate**: a bundle whose peers are unsatisfied is skipped **whole**, with one line on stderr and nothing in the UI — the plugin simply disappears.
 
 ### Why the upper bound is not `<0.2.0`
@@ -232,7 +251,7 @@ pnpm run check   # typecheck + test + build
 Local dev via a `link:` install to the desktop profile (restart DSH Desktop after editing):
 
 ```sh
-dsh plugin --profile desktop add /Users/dmh2002/DshProject/dsh-connect-trae
+dsh plugin --profile desktop add /path/to/dsh-connect-trae
 ```
 
 ## Acknowledgements

package/README.md

@@ -143,6 +143,33 @@ npm install dsh-connect-trae
 **要求 DSH 0.1.7-rc.1 及以上**（2.3.0 起不再支持 0.1.7 之前的宿主；peer 依赖范围已按此收窄）。
 **peer 上界为 `<0.3.0-0`：0.1.7 与 0.2 两条线均受支持。**
 
+### 同时支持 pi-ai 的两代上下文（3.4.2 起）
+
+DSH 自己横跨 `@earendil-works/pi-ai` 的两代，而**本插件解析到哪一代由你的安装环境决定**，
+未必是宿主那一代——插件声明它是 peer，这是对的，但两代对「上下文长什么样」的定义不同：
+
+| | 旧代（≤0.85） | 新代（0.86+） |
+| --- | --- | --- |
+| 形状 | `{ systemPrompt, tools, messages }` | `{ messages: [ {role:'system', content, toolsAdded}, … ] }` |
+| 系统提示 | 顶层 `systemPrompt` | **只**挂在那条 system 消息上 |
+| 工具声明 | 顶层 `tools` | **只**挂在那条 system 消息的 `toolsAdded` 上 |
+
+错配**两个方向都会坏**，所以 3.4.2 起插件会按自己解析到的那一代双向适配（issue #27）：
+
+- **新宿主 + 旧库**：必崩——旧代的 token 估算没有 `role === 'system'` 分支，会去迭代一个字符串并抛
+  `Cannot read properties of undefined (reading 'length')`。这一步在请求构造之前，所以表现为
+  「任意模型都崩、耗时极短、usage 恒为 0」。
+- **旧宿主 + 新库**：不崩，但现代 api 只读那条 system 消息，顶层字段被**静默忽略**——系统提示与
+  **全部工具声明**丢失（模型永远不会产生 toolCall）。这类故障更隐蔽，同样已修。
+
+代际判据是**本插件自己解析到的那份包**（读它的 manifest 版本；读不到时看包布局），
+**不是宿主版本**——因为嵌套的旧副本会盖过宿主的新副本，反之亦然。启动时日志里会有一行
+`dsh-connect-trae: pi-ai <版本> (<代数>)`，`legacy` 表示你这份安装解析到了 ≤0.85 的旧代。
+
+分界线是 **0.86**：`dist/utils/transcript.js`、`normalizeContext`、估算器的 system 分支、
+以及「不再读顶层字段」这四件事同时出现在 0.86.0。按 `0.87` 划分会把 0.86.x 误判成旧代而错误折返，
+反而丢掉提示与工具。
+
 0.2.0 线对本插件**没有契约破坏**——逐符号核对确认插件消费的 API 全部未变（[完整的 0.2.0-rc.1 影响面核对](https://github.com/dingminhua/dsh-connect-trae/blob/main/docs/DSH_0.2.0_RC1_IMPACT_CHECK.md)）。但 0.1.7 起 DSH 有一道**bundle 级 peer 门禁**：
 peer 范围不满足的 bundle 会被**整体跳过**，只往 stderr 写一行，界面上表现为「插件凭空消失」。
 
@@ -242,7 +269,7 @@ pnpm run check   # typecheck + test + build
 本地开发用 `link:` 安装到 desktop profile（改码后重启 DSH Desktop 生效）：
 
 ```sh
-dsh plugin --profile desktop add /Users/dmh2002/DshProject/dsh-connect-trae
+dsh plugin --profile desktop add /path/to/dsh-connect-trae
 ```
 
 ## 致谢