@bokutake/dsh-connect-qoder 0.0.0-stage → 1.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,348 @@
1
+ # DSH 0.2.1-rc.1 升级跟进调研 —— dsh-connect-qoder
2
+
3
+ > 调研日期:2026-10-17
4
+ > 宿主:DSH Desktop `0.2.1-rc.1`(`runtime/primary-runtime/runtime.json` → `desktopVersion`)
5
+ > 插件:`@dmh2002/dsh-connect-qoder` 1.0.0 → 1.1.2(1.1.2 补 rc.2 实测与两套 semver 语义的更正,见 §2.2/§2.2b)
6
+ > 参考:同级仓库 `dsh-connect-workbuddy` 的 [`docs/DSH-0.2.1-RC1-FOLLOWUP.md`](../../dsh-connect-workbuddy/docs/DSH-0.2.1-RC1-FOLLOWUP.md)
7
+ > 基线:本机 0.1.7-rc.1 依赖树上 **599 用例通过 / 7 跳过**(`npx vitest run`,32 文件)。
8
+
9
+ ---
10
+
11
+ ## 零、结论摘要 —— 与参考文档**最重要的分歧**
12
+
13
+ | 层 | 结论 | 所需动作 |
14
+ |---|---|---|
15
+ | **pi-ai 0.85 → 1.x 的上下文契约** | 🔴 **真实存在,但根因与参考文档说的不同**(见 §1) | **已改代码**(P0) |
16
+ | **peer 版本范围** | 🔴 `0.2.1-rc.1` 与 pi-ai `1.x` 都不满足现声明 | **已改**(P1) |
17
+ | 宿主 API / 客户端外壳 | ✅ 无破坏性变更 | 无 |
18
+ | 账号池体验 | 🔴 继承了上游 issue #70;`pool.enabled` 对换号完全无效 | **已修**(§3) |
19
+
20
+ ### ⚠️ 与参考文档的关键分歧(必读)
21
+
22
+ 参考文档 §1 的结论是:
23
+
24
+ > 「`dsh-llm-pi-ai` 从不归一化上下文 … pi-ai 1.1.0 只读 `messages` …
25
+ > **modern 分支是空的**,所以请求体丢失 system prompt 与全部工具声明」
26
+
27
+ **这个结论在真实的 0.2.1-rc.1 宿主栈上不成立。** 我按文档推荐的方式复现时,得到的是**相反**的结果。逐条实测如下。
28
+
29
+ #### 分歧点一:归一化发生在 **Models 层**,不在 api 模块
30
+
31
+ 参考文档把上下文喂给 `openAICompletionsApi()`(api 模块)后,直接断言「top-level `systemPrompt` / `tools` 从未被读取」。这在 api 模块内部是对的,但它**假设了调用方会把原始 envelope 直接交给 api 模块**。真实链路不是这样:
32
+
33
+ ```
34
+ dsh-llm-pi-ai (PiAiAdapter)
35
+ └── pi-ai createModels().stream/streamSimple ← 归一化在这里
36
+ └── normalizeContext(context)
37
+ └── provider.stream(requestModel, transcript, …)
38
+ └── createProvider 的 api (openai-completions)
39
+ ```
40
+
41
+ `PiAiAdapter.current()` 里 `models.setProvider(profile.piProvider)`(`dsh-llm-pi-ai/lib/index.js:1763`),而 pi-ai 的 `Models.streamSimple` 第一行就是:
42
+
43
+ ```js
44
+ // pi-ai 1.1.0 与 1.3.0 的 dist/models.js
45
+ streamSimple(model, context, options) {
46
+ const transcript = normalizeContext(context);
47
+ ...
48
+ return provider.streamSimple(requestModel, transcript, requestOptions);
49
+ }
50
+ ```
51
+
52
+ **实测**(真实 `createModels` + 真实 `openAICompletionsApi`,窗口见 §5.1):
53
+
54
+ | pi-ai 版本 | 输入 | api 模块收到的形状 | 线上 `body.tools` | 线上 system |
55
+ |---|---|---|---|---|
56
+ | 1.1.0 | 原始 envelope | `messages[0].role === 'system'`(已归一化) | **1** ✅ | 原样 ✅ |
57
+ | 1.3.0 | 原始 envelope | 同上 | **1** ✅ | 原样 ✅ |
58
+ | 0.85.1 | 原始 envelope | 原始 envelope(0.85 不归一化) | 1 ✅ | 原样 ✅ |
59
+
60
+ 即:**在真实宿主栈上,原始 envelope 会被自动归一化,prompt 与工具都不会丢。**
61
+
62
+ #### 分歧点二:真正的 0.2.1-rc.1 回归在 **`generationOf()`**,不在 `withLegacyContext`
63
+
64
+ 既然 1.x 的 Models 层会归一化,那 1.x 收到的是 **transcript**。此时若适配器把它当成 `legacy` 处理,`adaptLegacyPiAiContext` 就会把 transcript **逆折叠**回扁平 envelope —— 交给一个**只读 `messages`** 的 1.x api。这才是丢 prompt 与工具的那条路径。
65
+
66
+ 而 `generationOf()` 恰好就会这么判:
67
+
68
+ ```ts
69
+ // 修复前
70
+ const match = /^0\.(\d+)\./u.exec(version) // ← 只认 "0.x."
71
+ if (match === null) return 'legacy' // ← "1.1.0" 落这里
72
+ return Number(match[1]) >= 87 ? 'modern' : 'legacy'
73
+ ```
74
+
75
+ 实测 `generationOf`:
76
+
77
+ | 版本 | 修复前 | 应为 |
78
+ |---|---|---|
79
+ | `0.85.1` | `legacy` | legacy |
80
+ | `0.87.1` | `modern` | modern |
81
+ | **`1.0.0` / `1.1.0` / `1.3.0`** | **`legacy`** ❌ | **modern** |
82
+
83
+ **在真实 0.2.1-rc.1 + pi-ai 1.3.0 栈上实测的线上请求体**(真实 `PiAiAdapter` + 真实 `createModels` + 真实 api,只切换适配器分支):
84
+
85
+ | 适配器分支 | 线上 `messages[].role` | 线上 system 文本 | 线上 `body.tools` |
86
+ |---|---|---|---|
87
+ | `legacy`(**修复前**的实际行为) | `["user"]` | `null`(prompt 丢了) | **0**(工具全丢) |
88
+ | `modern`(应选的分支) | `["system","user"]` | `SYS-PROMPT-MARKER` | **1** ✅ |
89
+
90
+ #### 分歧点三:因此 **modern 分支必须保持空(pass-through)**
91
+
92
+ 参考文档 §1.4 建议「modern 分支改为归一化(折叠)」并推荐方案 A(内联折叠)。**这个建议在本仓库会导致新的缺陷**:
93
+
94
+ 1. 1.x 的 Models 层已经归一化过,适配器再折一次会**多出一条空的 system 消息**;
95
+ 2. 本仓库 checkout 解析到 **pi-ai 0.85.1**(`pnpm-workspace.yaml` 的 overrides 钉死),在 0.85 上跑「modern + 折叠后的 transcript」会直接崩在 `transformMessages` 的 `Cannot read properties of undefined (reading 'length')` —— 我实测到了这个崩溃,它恰恰证明 0.85 读不懂 transcript。
96
+
97
+ 所以本仓库的修法是:**`generationOf` 认 1.x → modern;`withLegacyContext` 的 modern 分支保持原样透传。** 参考文档「不要为 rc 版本扭曲声明」的判断没有问题,问题只在于它把病灶定位到了错的那一层。
98
+
99
+ > 参考文档那套用例之所以「全绿」,除了它自己指出的 `skipIf` 之外,还有一个更根本的原因:它只覆盖了 **api 模块**这一层,而缺陷发生在 **Models 层 → api 模块**之间。这恰好也是我第一版测试踩的坑 —— 见 §5.2。
100
+
101
+ ---
102
+
103
+ ## 一、P0:pi-ai 1.x 被判成 legacy(已在代码中修复)
104
+
105
+ ### 1.1 症状
106
+
107
+ 宿主 0.2.1-rc.1 下,模型**不再调用任何工具**,且**不报错**。Qoder 网关接受无 prompt 的请求体,所以网关侧也没有报错可看。
108
+
109
+ ### 1.2 根因链
110
+
111
+ 1. `pi-ai` 1.x 的 `createModels().stream*` 调用 `normalizeContext()`,把 `{systemPrompt, tools, messages}` 折成 `{messages:[{role:'system', content, toolsAdded}]}`;
112
+ 2. 适配器拿到的 `generation` 来自 `generationOf(version)`,而它的正则 `/^0\.(\d+)\./` **不匹配 `1.x.y`** → 返回 `legacy`;
113
+ 3. `withLegacyContext` 走 legacy 分支 → `adaptLegacyPiAiContext(transcript)` 把 transcript 逆折回扁平 envelope;
114
+ 4. 1.x 的 api 只读 `context.messages`,顶层 `systemPrompt`/`tools` 一字不读 → **prompt 与工具静默消失**。
115
+
116
+ ### 1.3 修法
117
+
118
+ - `src/pi-ai-runtime.ts`:`generationOf` 改为解析 `major.minor`,`major >= 1` → `modern`;`0.87+` → `modern`;其余保守 `legacy`。
119
+ - `src/adapter.ts`:`withLegacyContext` 的 modern 分支**保持 pass-through**(附完整注释说明为什么折叠反而是错的);`adaptLegacyPiAiContext` 加 LEGACY-ONLY 注记。
120
+
121
+ ### 1.4 为什么守卫测试此前全绿
122
+
123
+ `tests/pi-ai-runtime.spec.ts` 原来那条用例**把错误公式抄了一遍**:
124
+
125
+ ```ts
126
+ const minor = Number(/^0\.(\d+)\./u.exec(info.version)?.[1])
127
+ expect(info.generation).toBe(minor >= 87 ? 'modern' : 'legacy')
128
+ ```
129
+
130
+ 对 `1.3.0`,`exec` 返回 `null` → `minor` 是 `NaN` → `NaN >= 87 === false` → 断言 `legacy`。**它认证了这个缺陷。**
131
+
132
+ 现在改为对**已知语义的显式版本表**求值,不再从版本号现推公式。
133
+
134
+ ### 1.5 新守卫(均已做变异验证)
135
+
136
+ | 套件 | 钉住什么 | 变异验证结果 |
137
+ |---|---|---|
138
+ | `tests/pi-ai-runtime.spec.ts` | `generationOf` 的版本表(0.85→legacy、0.87+→modern、**1.x→modern**、不可读→legacy) | 退回旧正则 → **2 红** |
139
+ | `tests/adapter-outgoing-body.spec.ts` | 真实 api 构建出的**线上 body** 带着 prompt 与 tools(legacy 世代) | — |
140
+ | `tests/fixtures/pi-ai-modern/` | **真实 pi-ai 1.1.0** 上:modern 直通 → tools=1/prompt 原样;legacy 逆折 → tools=0/prompt=null | 见 §5.2 |
141
+ | `tests/dsh-line.spec.ts` | pi-ai 范围接受 1.x GA、拒绝 2.x 与未验证的预发布 | — |
142
+
143
+ ---
144
+
145
+ ## 二、P1:peer 范围
146
+
147
+ ### 2.1 semver 事实(npm `semver@7.8.5` 实算)
148
+
149
+ 现状 `>=0.1.7-rc.1 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0`:
150
+
151
+ | 版本 | 满足? |
152
+ |---|---|
153
+ | `0.1.7-rc.1` / `0.2.0-rc.1` / `0.2.0` | ✅ |
154
+ | **`0.2.1-rc.1`** | ❌ **(宿主当前版本)** |
155
+ | `0.2.1`(GA) | ✅ |
156
+
157
+ 原因仍是「预发布悬崖」:预发布版本只在其 `major.minor.patch` 元组上存在**带预发布标签的比较符**时才被放行。`>=0.2.0-rc.1` 只对 `0.2.0` 开口。
158
+
159
+ ### 2.2 修法与已知局限
160
+
161
+ ```jsonc
162
+ ">=0.1.7-rc.1 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0 || >=0.2.1-rc.1 <0.3.0-0"
163
+ ```
164
+
165
+ 实测:`0.2.1-rc.1` ✅ ADMIT,`0.3.0-0` / `0.3.0-rc.1` ❌ 仍被挡。
166
+
167
+ > ⚠️ **两套语义并存**(1.1.2 实测更正,原文「没有任何静态范围能覆盖任意 0.2.x 预发布」**只对一半成立**):
168
+ >
169
+ > | 读取方 | 实现 | `0.2.2-rc.1` | `0.2.9-rc.99` | `0.3.0-rc.1` |
170
+ > |---|---|---|---|---|
171
+ > | npm / pnpm 安装 | `semver.satisfies(v, range)` 标准语义 | ❌ 拒 | ❌ 拒 | ❌ 拒 |
172
+ > | 宿主插件兼容门禁 | `semver.satisfies(v, range, { includePrerelease: true })` | ✅ 放行 | ✅ 放行 | ❌ 拒 |
173
+ >
174
+ > 宿主那一行的证据:`dsh-app-boot/lib/index.js` 的 `unmetRequirements()` 调 `satisfies()`,而 `satisfies()` 的实现是 `semver.satisfies(runtimeVersion, range, { includePrerelease: true })`。实测 `evaluatePluginCompatibility(manifest, {}, '0.2.2-rc.1')` 返回 `undefined`(= 兼容)。
175
+ >
176
+ > 所以:**新补丁号的 rc 对 npm 安装仍需手工加分支**(`UNGATED_PRERELEASES` 是这份待办),但**宿主门禁不会因为少了那条分支而拦住用户**。两套语义都钉在 `tests/dsh-line.spec.ts` 的 `host gate` 组里,任何一边行为变化都会红。
177
+
178
+ ### 2.2b 宿主 0.2.1-rc.2 实测(1.1.2 补充)
179
+
180
+ 宿主从 `0.2.1-rc.1` 升到 `0.2.1-rc.2` 之后重新核对,结论:**1.1.1 的声明范围无需改动**。
181
+
182
+ | 检查项 | rc.1(1.1.0 时) | rc.2(1.1.2 时) |
183
+ |---|---|---|
184
+ | 全部 `@deepseek-ai/dsh-*` | `0.2.1-rc.1` | `0.2.1-rc.2` |
185
+ | `dsh-llm-pi-ai` 声明的 pi-ai 依赖 | `^1.1.0` | `^1.1.0`(未变) |
186
+ | **实际解析到的 pi-ai** | **`1.3.0`** | **`1.1.0`**(`^1.1.0` 重新解析的结果回退) |
187
+ | `generationOf` 判定 | `modern` ✅ | `modern` ✅ |
188
+ | 请求体实测 | `roles=["system","user"]`、`tools=1` | 同左 ✅ |
189
+ | `evaluatePluginCompatibility(manifest, {}, '0.2.1-rc.2')` | — | `undefined`(= 兼容)✅ |
190
+
191
+ **pi-ai 回落到 1.1.0 是刻意要记一笔的**:同一个 `^1.1.0` 范围先解析出 1.3.0、后解析出 1.1.0,说明宿主锁文件变了而不是依赖声明变了。我们的 pi-ai 范围 `>=0.85.0 <0.88.0 || >=1.0.0 <2.0.0` 两端都接得住,`generationOf` 对 1.1.0 与 1.3.0 都判 `modern`——这两个版本在归一化行为上一致(`createModels().stream/streamSimple` 都先调 `normalizeContext`)。实测两端都得到 `roles=["system","user"]`、`system="SYS"`、`tools=1`。
192
+
193
+ **api 模块结构契约未变**:`pi-ai@1.1.0` 的 `dist/models.js:444,455` 仍在 `stream`/`streamSimple` 里调 `normalizeContext`;`dist/api/openai-completions.js` 里 `context.systemPrompt` / `context.tools` 出现 **0** 次。这正是 `generationOf` 判定 `modern` 的依据,与 1.3.0 相同。
194
+
195
+ ### 2.3 pi-ai 范围
196
+
197
+ ```jsonc
198
+ ">=0.85.0 <0.88.0 || >=1.0.0 <2.0.0"
199
+ ```
200
+
201
+ 实测:`0.85.0/0.85.1/0.87.1/1.0.0/1.0.2/1.1.0/1.3.0/1.99.0` → true;`2.0.0`、`2.0.0-rc.1`、`0.84.0`、`0.88.0` → false。
202
+
203
+ > **刻意不用 `>=1.0.0-0`**:那个写法会把 `1.0.0-rc.1` 也放进来,而 1.x 的上下文契约只在已发布 GA 上实测过。实测对比:`>=1.0.0-0` 下 `1.0.0-rc.1` → **ADMIT**(不要);`>=1.0.0` 下 → reject(要这个)。
204
+
205
+ > 注:宿主 `dsh-app-boot` 的 `evaluatePluginCompatibility()` 只校验 `@deepseek-ai/dsh*` 命名空间,所以 **pi-ai 那条 peer 从不参与宿主校验**。改它主要是 npm 安装行为与文档的正确性;真正保护用户的是 §1 的代码修复。
206
+
207
+ ---
208
+
209
+ ## 三、账号池体验:对齐 workbuddy
210
+
211
+ 参考文档本身没写账号池,但工作项要求「在账号池体验方面学习 workbuddy 的做法」,因此单列。本轮做了**一次逐项差距审计**(对照 workbuddy 4.6.7 的实际代码),下面只记**已修**与**明确不修**。
212
+
213
+ ### 3.1 已修:继承了上游 issue #70(「快过期先花」是死代码)
214
+
215
+ `src/account-pool.ts` 的 `rankPool` 此前把 `score`(积分总量)排在 `_expiring`(过期时刻)**之前**。总量几乎从不完全相等,所以「临期优先」在数学上不可达。更糟的是单个 `_expiring` 键存的是**时间戳**,`expiringSoon`(**金额**)从未被任何排序读取 —— 「临期量大者优先」根本无法表达。
216
+
217
+ 修法(照 workbuddy `account-pool.ts:434-457`):拆成三个独立键 —— `_atRisk`(有临期)/ `_expiring`(何时到期)/ `_expiringAmount`(临期多少),排序键变为:
218
+
219
+ > 可用性 → 有临期 → 先到期 → 临期量大 → 积分总量 → 账号 id
220
+
221
+ **变异验证**:退回旧排序 → **3 红**(含「196.4 分当天作废压过 1200 分」「1 分临期压过 5 万」)。
222
+
223
+ ### 3.2 已修:`pool.enabled` 对换号**完全无效**
224
+
225
+ `nextFailoverCredential` 只读成员名单、**从不读 `enabled`**。默认 `enabled: false`,所以**每一条全新安装**都在这条路径上:用户以为关掉了自动行为,插件仍会在失败后悄悄换到另一个 PAT 计费。
226
+
227
+ 修法:新增导出的纯函数 `poolAllowsFailover()`,在换号入口设门。
228
+
229
+ ### 3.3 已修:失败记录缺两条守卫
230
+
231
+ `onServingFailure` 此前无条件把失败写进池状态。新增 `shouldRecordPoolFailure()`:
232
+
233
+ - **池关不记** —— 关掉池子意味着插件不再替用户选号,此时记下的失败会在下次开池时变成一堆没参与过任何决策的陈旧事实;
234
+ - **非成员不记** —— 勾选成员就是「我同意让这些号参与」,没勾的号不该因为一次恰好用了它的请求而被判出池。
235
+
236
+ > `invalid-request` 一类不必在这里再挡:shim 的 `isFailoverEligible` 已排除它们(400 换谁都是 400)。
237
+
238
+ **变异验证**:退回无条件通过 → **4 红**。
239
+
240
+ > 两个判据都做成**导出的纯函数**而不是留在接线里,理由与本仓库 `liveRequestProbe` 的既有注释一致:「接线变异掉,测试照样全绿过一次了」。
241
+
242
+ ### 3.4 明确**不修**的项(附理由)
243
+
244
+ | 项 | workbuddy 的做法 | 本仓库为何不跟 |
245
+ |---|---|---|
246
+ | 首发按排序挑号 | `applyPoolSelection`:开池后每请求都发给排名第一 | **产品决策**:本插件「首发射给用户选的号,失败才换」是明确设计(CHANGELOG 有记录)。本次不擅自改变计费落点 |
247
+ | 凭据新鲜度决胜键 | `tokenExpiresAtMs` 更晚过期者优先 | **领域不适用**:PAT 通常不过期,该键无意义(`account-pool.ts` 头部已记录) |
248
+ | `model-busy` 2 分钟专用冷却 | 上游 14003 有独立语义 | **需先有实测报文**:不能照抄数值。已在 §3.5 记为待办 |
249
+ | 换号提示注入回复流 | 「「A」被限流,已改用池中另一个账号回答」 | 本插件的 `shim` **保留**了 `poolServingNotice` 能力,但 host 显式不接(有记录的决定)。是否需要改回属于产品决策,不在本次升级范围 |
250
+ | 每行「测试」按钮跑整批 | 逐账号 `testOne` | **是真实缺陷,但需要新增 host 能力**(`QoderPoolDeps` 无 `testOne`)。见 §3.5 |
251
+ | 静态清理幽灵成员 | 具名提示 + 可移除 chip | **用户明确要求过静默清理**(CHANGELOG 有记录),不回退 |
252
+
253
+ ### 3.5 已记录、本轮**未做**的账号池待办
254
+
255
+ 按用户感知收益排序,供下一轮决策:
256
+
257
+ 1. **每行「测试」按钮实际跑整批** —— 用户只想测一个号,却把全部成员真实探测一遍(每个 ~25k token,有真实成本)。需要 host 新增 `testOne` dep + 路由分支。
258
+ 2. **`probe.modelId` 作用域** —— 现在「可用」是无作用域的宣称:同一账号在模型 A 可用、模型 B 429,表格照样写「可用」。workbuddy 的教训:这个字段**写了必须同时改读侧**,否则每次写入都会把它抹掉。
259
+ 3. **`out-of-credit` 的真实恢复时刻** —— 现在走 30 分钟兜底,而真实恢复可能是次日。
260
+ 4. **`model-busy` 语义** —— 需先用 Qoder 真实报文确认是否存在「模型级拥堵 vs 账号限流」的区分;**没有就不要伪造**。
261
+ 5. **空池/幽灵成员的服务端守卫** —— 卡片层已有,host 层缺 `no-members` / `no-live-members` 两个 409 reason。
262
+ 6. **NDJSON 流式进度** —— 批次跑 10 个号时按钮冻结约 10×(探针耗时+400ms),看起来像卡死。
263
+
264
+ ---
265
+
266
+ ## 四、已核对确认「无需改动」的项
267
+
268
+ - **宿主 API**:本仓库调用的 `dsh-llm` / `dsh-settings` / `dsh-host-webserver` / `dsh-llm-pi-ai` 符号在 0.2.1-rc.1 下签名一致(对照 npm 上的 `@deepseek-ai/*@0.2.1-rc.1` 类型面)。
269
+ - **客户端外壳**:`configForms` / `settingsScope` / `locale` / 槽位名与 `{view, form}` 契约未变。
270
+ - **`off-thinking` 的 §6 缺陷不适用本仓库**:参考文档 §6 记录的 `canDisableThinking !== true` 条件反转,在本仓库**不存在** —— `src/adapter.ts:146` 写的是正确形式 `if (info.canDisableThinking === true) map.off = 'off'`。已核对,未改。
271
+
272
+ ---
273
+
274
+ ## 五、附录:可复现的验证手法
275
+
276
+ ### 5.1 决定性对齐测试(真实宿主栈)
277
+
278
+ 用 npm 上的 `@deepseek-ai/dsh-llm-pi-ai@0.2.1-rc.1` + 真实 pi-ai 1.3.0 + 真实 `openaiCompletionsApi`,挂一个注入的 `fetch` 截住线上 body,只切换适配器分支:
279
+
280
+ ```
281
+ legacy 分支(修复前)→ roles ["user"], system null, tools 0
282
+ modern 分支(修复后)→ roles ["system","user"], prompt 原样, tools 1
283
+ ```
284
+
285
+ ### 5.1b 两份 pi-ai 副本并存 —— 谁跑哪一代(2026-10-17 补记)
286
+
287
+ 追这一条时发现一个**结构事实**,它决定了这个缺陷到底影响谁:
288
+
289
+ `src/adapter.ts` 第 15–17 行是 **静态 import**——
290
+
291
+ ```ts
292
+ import { createProvider } from '@earendil-works/pi-ai'
293
+ import { openAICompletionsApi } from '@earendil-works/pi-ai/api/openai-completions.lazy'
294
+ ```
295
+
296
+ 所以**插件用的永远是「它自己解析到的那份 pi-ai」的 api**,而 `createModels`
297
+ (真正做归一化、也是把 provider 注册进去的那一层)是**宿主那一份**。两份副本
298
+ 在宿主里可以不同代。
299
+
300
+ 实测(真实 1.x 的 `createModels` + 真实 0.85.1 的 `createProvider`/api 混装):
301
+
302
+ | 场景 | 1.x `createModels` 交给插件 api 的 context | 线上 body(**修复前**) | 线上 body(**修复后**) |
303
+ |---|---|---|---|
304
+ | 插件自带 **0.85.1**(本机现状:软链到本仓库,overrides 钉 0.85.1) | `messages[0].role === 'system'`(已归一化) | ✅ 正常(判 `legacy`,逆折回扁平 —— 0.85 读得懂) | ✅ 正常(同左,未变) |
305
+ | 插件也解析到 **1.x**(市场安装,无本地 0.85) | 同上 | ❌ `roles:["user"]`, `system:null`, `tools:0` | ✅ `roles:["system","user"]`, prompt 原样, `tools:1` |
306
+
307
+ **结论**:
308
+ - 本机这台(插件自带 0.85.1,`doctor` 报 `legacy (0.85.1)`)**从来没有坏过** ——
309
+ 它判 legacy 恰好是对的,因为它的 api 就是 0.85。
310
+ - 受害的是**市场安装**:插件自己解析到 1.x 时,修复前必然丢 prompt 与工具。
311
+ - 因此**本机无法用「发一条对话」复现这个 bug**,也无法用它证明修复 —— 本机能
312
+ 验证的只是「修复没有破坏它」。可复现的证据在 §5.1b 的表格里(两份真实副本
313
+ 混装实测),以及 `tests/fixtures/pi-ai-modern/` 的 4 条用例。
314
+ - 顺带解释了为什么 `tests/pi-ai-runtime.spec.ts` 那条「宿主注入 → modern」的
315
+ 默认值是安全的:它针对的是 `resolvedLocally: false` 的市场安装路径。
316
+
317
+ ### 5.2 第一版测试为什么是错的(留档)
318
+
319
+ 我第一版按参考文档写了「2×2 矩阵」(legacy/modern × 原始/已归一化),然后发现两格在 0.85 checkout 上红。第一反应是「测试写错了」,但**红的原因有两种可能**:
320
+
321
+ - (a) 我的折叠代码有 bug;
322
+ - (b) `modern × 已归一化 transcript` 在 0.85 上本来就非法。
323
+
324
+ 实测分清了两者:0.85 的 `transformMessages` 对 transcript 会在 `assistantMsg.content.filter(...)` 处崩(`Cannot read properties of undefined (reading 'length')`),因为 0.85 的 `Message` 联合里**没有 system 变体**。所以 (b) 成立 —— 把「四种任意组合」写成期望通过,等于要求插件去实现一个不存在的形状。
325
+
326
+ 最终拆成两套:
327
+ - `tests/adapter-outgoing-body.spec.ts` —— 只覆盖 **legacy** 世代(本 checkout 能跑真实 0.85 api);
328
+ - `tests/fixtures/pi-ai-modern/` —— 独立装一份 **真实 pi-ai 1.1.0**,覆盖 modern 世代。
329
+
330
+ ### 5.3 fixture 的安装
331
+
332
+ ```bash
333
+ pnpm run fixture:pi-ai-modern # = npm install --prefix tests/fixtures/pi-ai-modern
334
+ ```
335
+
336
+ `node_modules/` 不进版本控制,所以干净的 checkout 里这 4 条用例会**跳过**(并打印原因),而不是静默通过。
337
+
338
+ ---
339
+
340
+ ## 六、证据来源
341
+
342
+ - 宿主版本:`/Applications/DeepSeek Harness.app/Contents/Resources/runtime/primary-runtime/runtime.json` → `desktopVersion: 0.2.1-rc.1`
343
+ - 装机 pi-ai:从 `app.asar` 按原始 offset 提取 `dist/models.js` / `dist/api/openai-completions.js` / `dist/utils/transcript.js` 逐字阅读(asar 内无 `package.json`,版本由 `dsh-llm-pi-ai` 的 `dependencies: {"@earendil-works/pi-ai": "^1.1.0"}` 界定)
344
+ - `dist/api/openai-completions.js` 里 `context.systemPrompt` / `context.tools` 出现次数均为 **0**
345
+ - `dist/models.js` 的 `streamSimple` 第一行是 `const transcript = normalizeContext(context)`
346
+ - 宿主侧归一化调用点:`dsh-llm-pi-ai/lib/index.js:1763`(`models.setProvider(profile.piProvider)`)
347
+ - semver:npm `semver@7.8.5` 实算
348
+ - 账号池对照基准:`dsh-connect-workbuddy` 4.6.7 的 `src/account-pool.ts:434-457`、`src/index.ts:1491,1656-1661`