（ pi-ai-llm版本无法兼容新的模型 ） 建立 pi-ai 版本兼容边界并完成 0.82.1 → 0.84.2 迁移

[yifanxuaaa]

[llm-pi-ai] 建立 pi-ai 版本兼容边界并完成 0.82.1 → 0.84.2 迁移

背景

@deepseek-ai/dsh-llm-pi-ai@0.1.0-rc.8 当前依赖：

{
  "@earendil-works/pi-ai": "^0.82.1"
}

由于 pi-ai 仍处于 0.x 版本，^0.82.1 的有效范围是：

>= 0.82.1 < 0.83.0

因此当前依赖范围实际上不包含 0.84.2。当前 lockfile 也解析到 0.82.1。

这在旧模型时代问题不明显，但新模型发布后，模型 catalog、thinking capability、请求字段、stream stop reason、abort 和 replay 行为都可能发生变化。仅修改版本号不能完成升级。

目前 Grok 4.6 在旧版 pi-ai@0.82.1 的原生 xAI catalog 中不存在。我们通过 DSH 的显式 provider route 增加了：

xai-grok-4-6 → grok-4.6

该 route 已经通过真实 DSH smoke test，并能暴露 low、medium、high thinking effort。

但是，这只是模型 metadata 和 provider route 的兼容方案，不是完整解决 pi-ai host adapter 版本迁移问题。后续每次新模型发布，都可能重复出现同样的手工适配成本。

问题

将 DSH host 的 pi-ai 临时从 0.82.1 升级到 0.84.2 时，发现这不是普通的依赖升级，而是一次 adapter compatibility migration。

1. Catalog 类型发生 drift

DSH 当前 catalog.ts 对 pi-ai 的 catalog capability 使用显式 drift gate，确保上游新增字段不会被静默忽略。

pi-ai@0.84.2 相比 0.82.1 新增或扩展了多个字段，例如：

OpenAICompletionsCompat:
  supportsFinishReason
  chatTemplateArgs
  supportsThinkingTokenBudget

OpenAIResponsesCompat:
  supportsAdditionalTools

同时 reasoning format 增加了：

baseten

因此现有 catalog gate 在升级后需要重新分类每一个新字段：

• 是否暴露给 DSH 配置；
• 是否允许 route-level 配置；
• 是否允许 model-level 配置；
• 是否只继承 pi-ai catalog；
• 是否暂时明确拒绝。

如果只是修改类型使其编译通过，可能会静默丢失新的 provider capability。

2. StopReason 增加了新的生命周期状态

pi-ai@0.82.1 的 StopReason：

type StopReason =
  | "stop"
  | "length"
  | "toolUse"
  | "error"
  | "aborted"

pi-ai@0.84.2 增加：

type StopReason =
  | "pending"
  | "stop"
  | "length"
  | "toolUse"
  | "error"
  | "aborted"
  | "deferred"

其中：

• pending 表示当前 assistant message 仍处于部分流或中间状态；
• deferred 表示 provider 请求被延迟，需要后续 poll、resolve 或 cancel。

这两个状态不能简单映射成 DSH 的成功、失败或 aborted。

当前 DSH 的 stream.ts 主要假设一个请求最终以以下状态之一结束：

stop / length / toolUse / error / aborted

升级后需要明确：

• pending 是否只能存在于 pi-ai 内部，还是需要暴露到 DSH stream；
• deferred 是否需要成为 DSH durable operation；
• deferred handle 是否进入 session/replay；
• 进程重启后是否可以恢复 deferred request；
• timeout、abort、cancel 如何映射；
• provider 完成后如何重新进入当前 agent turn。

3. AssistantMessage 增加了新的持久化语义

pi-ai@0.84.2 的 AssistantMessage 增加了：

deferred?: DeferredHandle
rawStopReason?: string
endTurn?: boolean

这些字段分别关系到：

• 延迟请求的恢复和取消；
• provider 原始结束原因的诊断；
• OpenAI Codex Responses 的原生 end_turn 语义。

当前 DSH replay envelope 没有完整保存这些信息。若只升级 TypeScript 类型而不升级 replay schema，会出现以下风险：

• pi-ai 已经产生新状态，但 DSH replay 拒绝它；
• replay 丢失 provider-specific stop reason；
• Codex Responses 的 end_turn 语义在历史消息重建时丢失；
• deferred request 不能在重启后恢复；
• 新版本生成的历史无法被旧版本读取。

当前 replay.ts 的 stop reason 校验仍然只接受：

["stop", "length", "toolUse", "error", "aborted"]

4. Thinking effort 不是 provider-neutral 的简单字段

DSH UI 使用 provider-neutral 的 thinking effort，例如：

off
minimal
low
medium
high
xhigh
max

但不同 provider 的实际 wire format 可能不同：

{
  "reasoning_effort": "high"
}

{
  "thinking": {
    "type": "enabled"
  }
}

{
  "chat_template_args": {
    "thinking": true
  }
}

{
  "thinking_token_budget": 2048
}

pi-ai@0.84.2 原生的 xai/grok-4.6 catalog 虽然声明：

{
  "reasoning": true,
  "compat": {
    "supportsReasoningEffort": false
  }
}

但没有提供当前显式 route 使用的 thinkingLevelMap。

因此：

升级到 pi-ai@0.84.2
≠
Grok 4.6 自动获得 DSH UI 的 low / medium / high 选择

DSH 需要明确区分：

• 模型是否支持 reasoning；
• provider 是否接受 reasoning_effort；
• DSH UI 是否应该显示 effort selector；
• DSH effort id 如何映射为 provider wire value；
• 未声明映射时是否隐藏 effort，而不是猜测。

5. 请求 body 可能发生变化

pi-ai 会根据 provider/model catalog 和 compat 字段决定请求字段，例如：

max_tokens
max_completion_tokens
reasoning_effort
thinking
chat_template_args
thinking_token_budget
sampling parameters

同一份 DSH request，在 0.82.1 与 0.84.2 下可能产生不同的 provider request body。

因此升级必须覆盖：

• max_tokens 与 max_completion_tokens 的选择；
• Grok 4.6 的 output token cap；
• reasoning effort 的发送条件；
• provider 不支持 reasoning effort 时的行为；
• streamed finish reason 缺失时的推断；
• tool result 和 assistant-after-tool-result 的格式；
• Codex Responses 的 additional tools；
• provider API 错误、stream close 和 retry 行为。

实际影响

当前实现会带来以下维护问题：

1. 新模型无法稳定依赖旧版 pi-ai 的原生 catalog；
2. 每个新模型都可能需要增加 DSH 显式 route；
3. provider metadata、model offering、thinking effort 可能在多个地方重复维护；
4. 模型能否显示在 UI 中，取决于 pi-ai catalog 与 DSH route 的组合；
5. 新 pi-ai 版本的字段变化会同时影响编译、stream、replay、request body 和测试；
6. DSH 没有明确的 pi-ai compatibility contract，升级风险只能在临时实验中发现；
7. 旧版本为了稳定而固定后，后续模型支持会继续积累临时兼容代码。

建议方案

阶段一：明确当前稳定基线

在 DSH 文档和 package metadata 中明确记录：

DSH llm-pi-ai stable baseline:
@earendil-works/pi-ai@0.82.1

建议稳定发布版本使用精确版本或受控 lockfile，避免未经测试的 pi-ai 变化进入 release。

同时保留：

xai-grok-4-6 → grok-4.6

作为当前 DSH 0.82.1 运行时上的显式 fallback route。

该 route 不应被视为第二个 LLM engine，也不应引入第二个 pi-ai runtime。它只是为旧 catalog 补充缺失的 provider/model metadata。

阶段二：建立 adapter compatibility boundary

将 pi-ai 变化集中在 llm-pi-ai adapter 内处理，避免 pi-ai 类型和 provider-specific 行为向 DSH 其他模块泄漏。

需要明确以下归一化边界：

pi-ai AssistantMessage
        ↓
DSH provider-neutral StreamChunk
        ↓
DSH FinishReason / ReplayEnvelope

重点包括：

• pi-ai stop reason 到 DSH finish reason 的映射；
• pending/deferred 的生命周期；
• provider raw stop reason 的保留策略；
• endTurn 的保存和恢复策略；
• usage 和 max-token 的统一行为；
• abort、retry、stream termination 的统一行为；
• provider thinking effort 到 DSH effort id 的映射。

新增 pi-ai 字段时，应当由 adapter 明确选择：

支持并归一化
或
显式拒绝并给出可诊断错误

不能通过 as、字符串兜底或默认成功状态静默吞掉新语义。

阶段三：单独完成 0.82.1 → 0.84.2 迁移

将 0.84.2 作为一次独立的 DSH host adapter migration，而不是为了支持单个新模型直接修改版本号。

迁移至少需要覆盖：

• catalog compat drift gates；
• baseten thinking format；
• supportsFinishReason；
• chatTemplateArgs；
• supportsThinkingTokenBudget；
• supportsAdditionalTools；
• pending 和 deferred stop reason；
• AssistantMessage.deferred；
• rawStopReason；
• endTurn；
• replay envelope 版本；
• max_tokens 和 max_completion_tokens；
• reasoning effort request mapping；
• abort、retry 和 stream close；
• Codex Responses tool call、additional tools 和 replay；
• Grok 4.6 completions、thinking 和 finish reason；
• OAuth refresh 和 catalog refresh。

阶段四：增加模型兼容性测试矩阵

至少建立以下测试矩阵：

场景	pi-ai 0.82.1	pi-ai 0.84.2
普通文本请求	stable	candidate
thinking off	stable	candidate
thinking low/medium/high	stable	candidate
tool call	stable	candidate
max tokens	stable	candidate
provider error	stable	candidate
abort	stable	candidate
stream premature close	stable	candidate
replay round-trip	stable	candidate
Codex Responses	stable	candidate
Grok 4.6 completions	explicit route	native catalog/route
OAuth refresh	stable	candidate

测试不需要让生产运行时同时加载两个 pi-ai 版本。可以使用两个独立的 dependency fixture 或 CI job，重点是防止升级时只能依赖手工 smoke test。

验收标准

• 明确记录 DSH llm-pi-ai 支持的 pi-ai 版本策略；
• @earendil-works/pi-ai@0.84.2 可以完成 DSH adapter 的 typecheck；
• catalog 中所有新增字段都有明确的 offer、withhold 或 reject 决策；
• pending 和 deferred 不会被静默当成 stop、error 或 aborted；
• replay schema 能正确处理新 stop reason 和新增 assistant metadata；
• provider raw stop reason 的保留策略有测试；
• endTurn 的 Codex Responses 行为有测试；
• supportsAdditionalTools 的 Codex tool loading 行为有测试；
• max_tokens、max_completion_tokens 和 thinking 参数有 request body 断言；
• Grok 4.6 的请求、thinking、tool call、finish reason 和 abort 有真实或录制的测试；
• OAuth refresh、catalog refresh 和 retry 行为无回归；
• 现有 llm-pi-ai 测试全部通过；
• DSH UI 可以显示并选择受支持的 model 与 thinking effort；
• 0.82.1 stable route 在迁移完成前继续可用；
• 只有迁移测试和真实 smoke test 全部通过后，才移除或合并 xai-grok-4-6 fallback route。

非目标

本 Issue 不要求：

• 为 Codex 和 Grok 各维护一套独立的 pi-ai runtime；
• 为每个 provider 复制一份 llm-pi-ai adapter；
• 绕过 llm-pi-ai 直接实现第二套 streaming engine；
• 为每个新模型永久增加临时兼容层；
• 在没有定义 deferred/replay 语义的情况下强行把 0.84.2 标记为兼容；
• 为了自动出现一个模型而牺牲 DSH 当前 stream、abort 和 replay 契约。

相关代码

• [packages/llm/llm-pi-ai/package.json](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/package.json)
• [packages/llm/llm-pi-ai/src/catalog.ts](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/src/catalog.ts)
• [packages/llm/llm-pi-ai/src/stream.ts](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/src/stream.ts)
• [packages/llm/llm-pi-ai/src/replay.ts](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/src/replay.ts)
• [packages/llm/llm-pi-ai/src/adapter.ts](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/src/adapter.ts)
• [pi-ai CHANGELOG](https://raw.githubusercontent.com/earendil-works/pi/refs/heads/main/packages/ai/CHANGELOG.md)
• [pi-ai 0.84.2 release](https://github.com/earendil-works/pi/releases/tag/v0.84.2)
• [详细兼容性研究](https://github.com/Ephemeral-AI-Lab/deepseek-harness-docs/blob/main/how-to/pi-ai-0.82.1-to-0.84.2-compatibility-study.md)

[weijiafu14]

这个提案的方向我们用几个月的实测数据背书——我们维护 pi2dsh（让 Pi 插件跑在 DSH 上的兼容层），兼容面钉死单一 pi-ai 版本、升级走显式迁移，正是你说的"版本兼容边界"姿势，而且积累了跨版本 A/B 的实测差异数据，供这个迁移提案参考：

• 累加器（0.82.1 vs 0.84.1/0.84.4 注入 A/B）：空串 id/name 续块、无 id 并行、乱序 index 这些畸形流两代都能正确组装；markdown 围栏包 arguments 两代都静默丢成 {}（已报上游 earendil-works/pi#8858）。逐案判决。
• 历史回放 transform（0.82.1 vs 0.84.1）：thinking 块内联进 content 的行为两代一致、不产 reasoning_content 字段。判决。
• 传输重试：Retry-After 尊重、连接级错误可重试，0.84.1 实测。判决。

经验教训一条：^0.82.1 这种 0.x 范围锁死在 minor 内是对的方向，但升级必须配行为级回归，不能只看类型对齐——上面这些行为差异（和不变量）没有一个能从 changelog 读出来，全是打真代码打出来的。装置都是自包含的（REPO=… PI_AI=<pi-ai 目录> node <experiment>.mjs），迁移到 0.84.x 时拿去当回归夹具随便用。