【修复与优化】修复历史回放空指针崩溃，并支持 OpenAI 兼容端点完整 compat 参数透传

[sprainJinyu]

📌 背景与问题

在使用 @deepseek-ai/dsh-llm-pi-ai 接入第三方 OpenAI 兼容网关（如 Google Gemini 兼容端点、火山引擎豆包、Kimi 等）及复杂多轮会话时，发现了两个较为关键的底层问题：

1. 多轮历史重构时的空指针崩溃（replay.ts）：

   • 当会话发生历史压缩（Context Compression / Summarization），或有插件/系统注入了未携带 source 元数据的辅助 Assistant 消息时，toPiAssistant 和 foreignAssistant 直接访问 message.source.kind 会触发未捕获的 TypeError: Cannot read properties of undefined (reading 'kind')，导致会话直接中断。

2. 自定义 compat 配置被静默丢弃（catalog.ts）：

   • resolveModelCompat() 目前仅提取了思考链相关的参数，将用户在 settings.yaml 中配置的其它兼容性参数（如 supportsDeveloperRole: false、supportsStore: false、maxTokensField）全部丢弃。
   • 这导致在接入对非标准字段有严格校验的端点（如 Google 端点收到 store: false 报 400，火山引擎端点收到 developer 角色报 400）时，用户即便在配置文件中声明了关闭开关也无法生效。

---

🛠️ 解决方案与代码实现

已在个人 Fork 分支中完成修复并完成了实机测试，代码链接如下：
🔗 Commit: sprainJinyu/deepseek-harness@0359397
🔗 Branch: fix/gemini-openai-compat-and-replay

核心修改点：

• packages/llm/llm-pi-ai/src/replay.ts：
  • 在 toPiAssistant 和 foreignAssistant 中加入可选链安全访问（message.source?.kind），在缺失 source 时安全回退至 neutral foreign 模式。
• packages/llm/llm-pi-ai/src/catalog.ts：
  • 为 resolveModelCompat 传入 baseUrl；
  • 完整合并并透传用户在 route.compat 和 entry.compat 中配置的全部兼容性开关；
  • 增加对 googleapis.com 等 Google 官方 OpenAI 兼容端点的自动识别与开箱即用默认值（默认关闭 supportsStore 和 supportsDeveloperRole，maxTokensField 设为 max_tokens）。

---

✅ 验证结果

• 在开启工具调用（glob）与流式输出的多轮复杂会话中进行了实测，多轮交互全程畅通；
• 验证了会话历史压缩（无 source 消息）下的安全性，彻底消除了 TypeError 崩溃；
• 验证了 Google Gemini 3.5/3.7 Flash 官方端点的连通性与参数校验，调用正常。

希望能为社区和官方后续的主线合并提供参考！

[weijiafu14]

两个修复的方向都对，但第 2 条（compat 透传）在 rc.8 上可能已经落地了——建议先核一下再继续投入，我这边有一条比较硬的间接证据。

一、PiAiCompatProfile 上这些字段确实存在，而且能打到线上

我们做 DSH 上的兼容层，需要把 Pi 侧的 compat 声明翻译成 DSH profile 字段。为了防止上游加字段时我们悄悄漏掉，那张映射表钉了一个编译期门：

const DSH_COMPAT_FIELD_PROTOCOLS = {
  supportsStore, supportsDeveloperRole, supportsReasoningEffort,
  supportsUsageInStreaming, maxTokensField, requiresToolResultName,
  requiresAssistantAfterToolResult, requiresThinkingAsText,
  requiresReasoningContentOnAssistantMessages, thinkingFormat,
  chatTemplateKwargs, supportsStrictMode, cacheControlFormat,
  supportsLongCacheRetention, supportsEagerToolInputStreaming,
  supportsCacheControlOnTools, supportsTemperature, forceAdaptiveThinking,
  allowEmptySignature, supportsStrictTools,
} satisfies Record<keyof PiAiCompatProfile, ReadonlySet<string>>

satisfies Record<keyof PiAiCompatProfile, …> 要求这张表穷举 PiAiCompatProfile 的每一个键。它在我们仓库里编译通过（peer 解析到宿主装的那一代），所以你点名的 supportsDeveloperRole / supportsStore / maxTokensField 都在这个类型上。

更进一步，这三个不只是类型上有，是真能打到线上的：我们有一个专门验这件事的 example，用透传录制代理（请求真发给上游、响应真流回、中间只多存一份请求体）录到的 body 里是 "role":"system" 而不是 "developer"，max_tokens 是声明的非默认拼写，store 字段消失——三个 compat 声明全部生效。

二、那为什么另外两位报告的是"只有两个字段"？

#780 和 #2822 都核到 packages/llm/llm-pi-ai/src/config.ts:188 的用户配置 schema 只有 thinkingFormat 和 supportsReasoningEffort 两个字段。

这和上面并不矛盾——类型（PiAiCompatProfile）和用户配置校验 schema（compatProfile）是两回事。而且 rc.8 的发布说明性质的变化是：compat 拿到了真正的 profile 槽位，但只对选定协议开放一个受控子集。

所以最可能的情况是：这个能力在 rc.8 落地了，而上面几份报告（含你这份）核的是 rc.8 之前的 master。

建议你花十分钟核一下，结果决定你的 fork 该怎么处理：

llm-pi-ai:
  providers:
    my-gateway:
      api: openai-completions
      baseURL: https://<你的端点>/v1
      apiKeyEnv: MY_KEY
      models:
        - id: <model>
          compat:
            supportsDeveloperRole: false
            supportsStore: false
            maxTokensField: max_tokens

装 rc.8 起一遍，看这段配置是被接受还是被拒。被接受 = 你的第 2 条已经不需要了，fork 可以只留第 1 条，评审面积小一大截。

（一个坑值得提前说：这个 profile 槽位是按协议 gated 的受控子集，而且一个非法键会让整个 settings 段被拒——不是只忽略那一个键。所以核的时候一次只加一个字段，别一口气全写上，否则你分不清是"不支持"还是"某一个键拼错了"。）

三、你的第 1 条（replay 空指针）是独立的，建议拆开提

message.source?.kind 这个修复和 compat 完全无关：它治的是历史压缩之后、或插件注入了不带 source 的辅助消息时，toPiAssistant / foreignAssistant 直接解引用导致会话中断。

这条我没有对应证据，但它的形状很像这个社区反复出现的一类：会话历史里出现了一条"形状不完全符合预期"的消息，然后整个会话再也用不了了。（同族：#2915 / #1627 的 replay 块数不匹配、#740 的残缺 tool_calls 历史——都是一次异常留下一条不合规的历史，之后每次请求都带上它，会话永久报废。）

建议把它单独开一帖，标题直写后果（例如 "Compaction or a source-less assistant message crashes replay with Cannot read properties of undefined (reading 'kind')"），理由很实际：它现在挂在一个标题是"修复与优化"的帖子里，会跟着第 2 条一起等 compat 的排期，而它其实是一个独立的、便宜的崩溃修复。

四、Google 端点自动识别那半，我建议想清楚再加

增加对 googleapis.com 等 Google 官方 OpenAI 兼容端点的自动识别与开箱即用默认值

开箱即用当然好用，但这条走的是"枚举一方端点"那条路，而 #780 那帖的核心论点正是：

Auto-detection can only enumerate first-party endpoints; third-party gateways with different replay/role conventions cannot be closed over.

名单是有限的，端点是无穷的——今天加 googleapis.com，明天有人用一个反代到 Google 的私有域名，名单又不认了。而且 pi-ai 的 detectSessionAffinityFormat 只认 openrouter 一个特例、其余一律当 openai（#2822 那位踩的正是这个），说明这个模式在上游已经有过前车之鉴。

我的看法是：配置透传（你的第 2 条）是可持续的表面，自动识别是跑步机。 如果要保留，建议把它明确定位成"便利默认值，配置永远优先"，并且在提案里说清它不是解决方案本身——否则评审很容易把注意力放在"该不该内置某个厂商的名单"这个争议点上，反而拖住了真正该合的那半。

边界与利益相关

我们不修 DSH 自家组件——llm-pi-ai 的 replay.ts / catalog.ts 都在 DSH 里。第一节是我们自己的实测与编译期证据；我没有读过你 fork 的 diff，也没有在 Google 端点上试过，第二节的"可能已落地"是一条待你核实的推断，不是结论。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。这条不推销：第二节那段 YAML 是纯 DSH 官方配置，不需要装我们任何东西；我只是因为要翻译这些字段，所以对它们在不在 schema 里格外敏感。