llm-pi-ai 缺少图片张数闸门：上游按张数限流时会话永久卡死（附源码级根因、完整改动与实测）

[Kernlix]

补充一份源码级的根因分析 + 完整改动清单，把这条线索钉死，也给官方一个最小改动的修法。

缘起与致谢：本文的思路来自 讨论 #6432 中 PerryLink 给出的根因分析——"600 是 DSH 自己的上限、30 才是上游的，两边上限不一致导致 DSH 的图片卸载机制永远不会触发"，这个方向是他先提出来的。我在此基础上补充了 llm-pi-ai 路线的源码级对照、本机实测数据与改动清单。

一、结论

llm-pi-ai 的图片卸载调用只传了「字节」维度，完全没传「张数」维度；llm-deepseek 两者都传。所以上游按张数限流时，llm-pi-ai 路线上卸载逻辑永远不会触发。

二、源码对照（0.1.5-rc.2 实测）

A. dsh-llm-pi-ai —— 卸载调用只带字节

node_modules/@deepseek-ai/dsh-llm-pi-ai/lib/index.js:1286-1300：

const requestMessages = offloadRequestImagesWithPolicy(split.messages, {
  representation: "base64",
  ...maxRequestImageBytes === void 0 ? {} : { maxBytes: maxRequestImageBytes },
  byteQuantum: 1,
  byteLength: (ref) => Math.min(ref.bytes, requestImagePolicy.maxBytes),
  placeholder: (ref) => offloadedImageText(ref, resolveImageAccess(ref))
});

配置 schema 也只有三项（lib/index.js:1011-1013）：

maxRequestImageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_REQUEST_IMAGE_BYTES),
requestImagePixelBudget: z.number().step(1).min(1).default(DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET),
requestImageMaxBytes: z.number().step(1).min(1).default(DEFAULT_REQUEST_IMAGE_MAX_BYTES),

全文件检索（lib/index.js，2688 行）：maxImagesPerRequest 0 次、imageOffloadCountQuantum 0 次、imageOffloadByteQuantum 0 次。

B. dsh-llm-deepseek —— 卸载调用带张数

node_modules/@deepseek-ai/dsh-llm-deepseek/lib/index.js:1677-1685：

const requestMessages = policy === void 0 ? options.messages : offloadRequestImagesWithPolicy(options.messages, {
  representation: "raw",
  maxBytes: connection.maxRequestFilesBytes,
  maxImages: connection.maxImagesPerRequest,          // ← 张数闸门
  byteQuantum: connection.imageOffloadByteQuantum,
  countQuantum: connection.imageOffloadCountQuantum,  // ← 张数步进
  byteLength: (ref) => Math.min(ref.bytes, policy.maxBytes),
  placeholder: (ref) => offloadedImageText(ref, resolveImageAccess?.(ref))
});

base64 分支同样带（1697-1705：maxImagesPerRequest / byteQuantum / countQuantum）。默认值与交叉校验（1970-1982）：

const maxImagesPerRequest = config.maxImagesPerRequest ?? 600;
const imageOffloadByteQuantum = config.imageOffloadByteQuantum ?? 67108864;             // 64MiB
const inlineImageOffloadByteQuantum = config.inlineImageOffloadByteQuantum ?? 10485760; // 10MiB
const imageOffloadCountQuantum = config.imageOffloadCountQuantum ?? 20;
if (imageOffloadCountQuantum > maxImagesPerRequest) throw new Error("llm-deepseek: imageOffloadCountQuantum must not exceed maxImagesPerRequest");

差异一目了然：同一个 offloadRequestImagesWithPolicy，llm-deepseek 传 maxImages + countQuantum，llm-pi-ai 一个都没传。

C. 为什么默认值必然漏

llm-pi-ai 的 maxRequestImageBytes 默认 20MiB；而 byteLength 把单图按 min(ref.bytes, 1MiB) 计（1280-1283：requestImagePolicy 默认 { maxPixels: 4194304, maxBytes: 1048576 }）。31 张图若平均 < 0.68MiB，合计就不到 20MiB ⇒ 字节闸门不触发 ⇒ 31 张原样发出 ⇒ 上游 400。

这就是「上游按张数、适配器按字节」的口径错位。

三、故障复现（本人环境）

环境：DSH 桌面端 0.2.0-rc.2 ｜ @deepseek-ai/dsh-llm-pi-ai 0.1.5-rc.2 ｜ provider = opencode-go（上游报错来自 "Console Go"）

时间	事件	结果
10-04 22:47:27	turn 37	400 ... Too many images in request: 31 > 30（INVALID_REQUEST）
10-04 22:48:41	turn 38	同一条 400
10-04 22:51:42	turn 39	同一条 400
10-04 22:54:50	/compact	compaction/end 的 error 字段仍是同一条 400

/compact 救不了的原因：compaction 压的是文本，图片作为历史内容原样留在请求里，压完还是 31 张。

四、我改了什么（完整 diff）

~/.dsh/profiles/desktop/cordis.patch.yml：

 - id: llm-pi-ai
   name: "@deepseek-ai/dsh-llm-pi-ai"
   config:
     providers:
       opencode-go:
         apiKeyEnv: OPENCODE_GO_API_KEY
+        # 上游（Console Go）单请求限 30 张图，默认 20MiB 字节闸门不会触发
+        # → 31>30 永久卡死会话。调小到 2MiB 强制「最老优先」逐张卸载为文字占位。
+        maxRequestImageBytes: 2097152   # 2MiB

（改动前已备份 cordis.patch.yml.bak-20261004-imgcap，可一键回滚。）

五、效果与验证

项	结果
最后一批真实 400	10-04 22:47~22:54（turn 37/38/39 + 一次 /compact）
此后	至 10-12 零复发（约 7 天）
验证方法	扫描 ~/.dsh/sessions/**/session.v4.jsonl.zstd（38 个会话），按事件类型过滤后确认 assistant/attempt / turn/end / compaction/end 中再无该 400

代价与调参建议（重要）：卸载是「最老优先，直到总量 ≤ maxRequestImageBytes」。设 2MiB 时，若单图平均 0.6MiB，只剩约 3 张图留在上下文里——能用，但很激进。更精细的取值应接近 (上游张数上限 − 1) × 单图平均字节（例：29 × 0.6MiB ≈ 17MiB）。

但字节口径本质上无法精确控制张数——这正是下面建议的由来。

六、上游修复状态（截至 2026-10-12）

核对 npm 上最新发布版 @deepseek-ai/dsh-llm-pi-ai@0.2.0-rc.2：maxImagesPerRequest / imageOffloadCountQuantum 出现 0 次，maxRequestImageBytes 9 次。

→ 仍未落地。

七、建议的上游改法（最小改动）

1. PiAiProviderProfile 增加 maxImagesPerRequest?: number 与 imageOffloadCountQuantum?: number（语义对齐 llm-deepseek）
2. toPiContextWithImages 的两处 offloadRequestImagesWithPolicy 调用补上：

   maxImages: maxImagesPerRequest,
   countQuantum: imageOffloadCountQuantum ?? 1,

3. 校验与 llm-deepseek 对齐：imageOffloadCountQuantum ≤ maxImagesPerRequest
4. （更根本）按路由 / 上游声明的图片数上限判断，而不是只按字节——对这类上游，字节口径永远防不住张数超限

诊断入口（供后来者）：失败原文写在会话存档最后一条 compaction/end 事件的 error 字段里，解压 ~/.dsh/sessions/**/session.v4.jsonl.zstd 可直接读到。

---

按路线对号入座（给遇到同样问题的人）

• 走 llm-deepseek（DeepSeek 官方路由）：用 PerryLink 在讨论 请求图片超过上限后无法继续、无法压缩上下文，导致会话无法继续 #6432 里的方案

  llm-deepseek:
    maxImagesPerRequest: 20        # 低于上游的 30
    imageOffloadCountQuantum: 5    # 必须 ≤ maxImagesPerRequest

• 走 llm-pi-ai 或其它网关路由（opencode-go、各类 OpenAI 兼容中转）：没有张数字段，只能调小字节闸门 maxRequestImageBytes（2MiB 起步）
• 应急（两条路都适用）：从第 31 张图之前 fork 新会话，或直接开新会话