图片长边限制 mrbeandev/dsh-image-edge-cap

dsh-image-edge-cap

限制发送给你所选服务商或模型的每张图片最长边，在 DeepSeek Harness（DSH）里生效，自带 Settings → Image size 标签页。

- 源码： github.com/mrbeandev/dsh-image-edge-cap
- npm 包： npmjs.com/package/dsh-image-edge-cap

缩放图片时保持宽高比（默认上限 2000 px）。只有模型请求里发送的那份副本会被缩放：存储的附件和会话日志永远不变。你没选中的服务商和模型，收到的请求和以前完全一样。

目录： 支持的 DSH 版本 ·为什么需要这个插件 · 安装 ·设置标签页 · 工作原理 ·兼容性与风险 · 开发

支持的 DSH 版本

支持范围：DSH 0.2.0-rc.1 起，到 0.3.0（不含）为止。 用 dsh --version 查看你的版本。

| DSH 版本 | npm tag（本次发布时） | 状态 |
| 0.2.0-rc.2 | latest、next | ✅ 已测试 |
| 0.2.0-rc.1 | — | ✅ 已测试 |
| 0.2.1-alpha.1 | alpha | ⚠️ 集成测试通过；加载时提示「未测试」警告 |
| 0.2.0-rc.1 起、到 0.3.0（不含）为止的其他版本 | — | ⚠️ 未测试：加载时提示警告 |
| 早于 0.2.0-rc.1（0.1.x） | — | ❌ 不支持：没有按路由选择请求图片的目标 |
| 0.3.0 及更新版本（含预发布版） | — | ❌ 测试通过前拒绝加载（可用 allowUntestedHarness: true 覆盖） |

Node.js： ^22.19.0 或 >=24.0.0。

插件没有运行时依赖，也不需要任何其他社区插件。被拒绝的插件会在启动时记录一条清晰的错误，然后不加载；设置标签页随后会提示宿主插件未运行。它绝不会加载到一半。

为什么需要这个插件

Anthropic 的 Messages API 会拒绝这样的请求：图片超过 20 张，且其中任何一张任意一边超过 2000 px：

400 invalid_request_error: messages.N.content.1.image.source.base64.data:
At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels

每一轮都会重发整个历史记录。一旦会话超过 20 张图片，且其中一张是长截图，之后每一轮都会失败，/compact 也会失败（它发送同样的历史记录）。移动端布局的整页截图是常见诱因。

DSH 自带的 requestImagePixelBudget 限制的是总像素数（宽 × 高），不是边长。又长又细的图片能原样通过：
| 图片 | 像素 | 按 1.15 MP 预算处理后 | Anthropic 多图规则 |
| 2460 × 392（宽条图） | 0.96 MP | 2460 × 392 | ❌ 超过 2000 |
| 390 × 2475（整页移动端截图） | 0.97 MP | 390 × 2475 | ❌ 超过 2000 |
| 2718 × 1346 | 3.7 MP | 1524 × 755 | ✅ |

把这个插件设为 2000 px 后，上面两张图变成 2000 × 319 和 315 × 2000，卡住的会话就能继续跑。同样的限制在 anthropics/claude-code#12351 里也有讨论。

从 npm 安装

dsh plugin --profile web add dsh-image-edge-cap

手头的工作做完后，停掉正在运行的 DSH Web 进程，再重新启动（例如 dsh web --no-open --port 3080），然后刷新页面。打开 Settings → Image size，选择要给哪些服务商或模型加上限制。

如果想从本地检出安装（保留该文件夹，配置档会链接到它）：

dsh plugin --profile web add "/absolute/path/to/dsh-image-edge-cap"

卸载：

dsh plugin --profile web remove dsh-image-edge-cap

另一种做法是把某个服务商设为 Off，它下一次请求就原样发出。

Settings 标签页

插件在 Settings 里加了自己的 Image size 标签页。它会列出所有已注册的模型服务商，你可以给每个服务商选一种模式：

| 模式 | 效果 |
| Off（默认） | 该服务商不做任何改动。 |
| All models | 该服务商的所有模型都限制图片尺寸。 |
| Selected models | 出现该服务商模型的勾选列表；只有勾选的模型限制图片尺寸，同一服务商的其他模型不受影响。 |

然后设置 Max edge（16–16384 px，默认 2000），按 Apply。

- 规则从下一次请求开始生效，包括恢复的会话、子代理和重试。不需要重启。
- 模型勾选列表来自 DSH 的实时模型目录，和模型选择器用的是同一份列表。
- 服务商已不再列出的模型，或者已被移除的服务商，只要还有规则就仍然可见，方便清掉规则。
- 保存失败或冲突时会报错，不会假装成功。如果宿主插件没在运行（比如在不支持的 DSH 上），标签页会说明情况，控件也会禁用。

典型配置：一个路由服务商同时提供 Claude 和 GPT 模型 → 选 Selected models，只勾 Claude 模型，max edge 填 2000。其他模型继续用全尺寸图片。

规则存在配置档补丁（cordis.patch.yml）里本插件的条目中，所以你也可以手动编辑：

- id: dsh-image-edge-cap
name: dsh-image-edge-cap
config:
providers:
my-router:
mode: selected # off | all | selected
models: [cc/claude-a, cc/claude-b]
maxImageEdge: 2000

工作原理

1. llm/stream 监听器读取请求的 provider 和 model。如果没有规则匹配，就原样返回数据流，请求与未装插件时发送的请求逐字节一致。
2. 规则一旦匹配，监听器就在 AsyncLocalStorage 作用域内运行适配器流，该作用域持有上限。流被消费期间，适配器发起的图片读取都能进入这个作用域，即使中间经过其他 llm/stream 监听器（比如限流器）和并发请求也一样。
3. 插件包装 attachments 服务上的 readImageRequest。当 pi-ai 适配器在受限作用域内请求图片目标时，包装层会调低目标尺寸，让长边不超过上限。短边按存储层缩放时的同一方式取整，因此存储层的校验和缓存仍然对得上。
4. 附件存储用自己的代码，按新的变体 id 缩放并缓存图片。插件里没有任何图片处理代码。

每张受限图片在每个进程中记录一次日志，例如： dsh-image-edge-cap: capped a request image 390×2475 → 315×2000 (max edge 2000)。

兼容性与风险

插件包装 DSH 附件存储的一个方法，而且可逆。这不是官方扩展 API。attachments 服务出现时安装，插件被销毁时移除，绝不重复安装。版本闸门会拒绝测试范围之外的 DSH 版本，因此内部 API 一旦变化，插件会拒绝加载，而不是行为异常。

- 适用于任何通过附件存储的 readImageRequest 准备请求图片的适配器。在 DSH 0.2 上，这包括 pi-ai 适配器（自定义 OpenAI 兼容、Anthropic 及其他 pi-ai 服务商），测试覆盖的就是它，也包括原生 DeepSeek 适配器，所以针对 DeepSeek 服务商的规则同样生效。你设为 Off 的服务商不受影响。
- 绝不放大图片，也绝不撤销 DSH 自身的像素或字节预算；它只能让请求图片更小。
- DSH 已从请求中卸载的图片不受影响。

插件配置键（位于 dsh-image-edge-cap 条目上）：

| 键 | 含义 |
| providers | 由 Settings 标签页编辑的按服务商规则。 |
| enabled: false | 加载但不限制任何内容。 |
| harnessEntry | 正在运行的 dsh 命令行入口路径（自动检测）。 |
| allowUntestedHarness: true | 在受支持范围之外的 DSH 上加载。不推荐。 |

开发

插件没有任何 npm 运行时或构建依赖。宿主代码是纯 ESM，无依赖的构建器按 DSH 的 ModuleLoader 格式写出浏览器 bundle，复用 shell 自带的 React。

| 文件 | 作用 |
| index.mjs | 宿主入口：版本闸门、Config、llm/stream 作用域、存储包装。 |
| cap.mjs | 纯规则匹配与目标尺寸计算。 |
| client/index.mjs | Settings 标签页的源码。 |
| lib/client.js | 由 npm run build 生成；绝不手动编辑。 |
| scripts/check-release.mjs | 发布闸门（元数据、过期 bundle、私有数据、打包文件）。 |
| scripts/e2e-gui.mjs | 在运行中的 DSH Web 里对标签页做 Headless-Chrome 冒烟测试。 |

npm run build # generate lib/client.js from client/index.mjs
npm test # unit tests: rules, scoping, wrapper, version gate, Settings tab
DSH_TEST_HARNESS_ENTRY="/absolute/path/to/dsh/lib/bin.js" npm run test:integration
npm run verify # build + tests + release gate
npm run pack:check # inspect the exact published file set

想让集成测试套件跑在另一个 DSH 版本上，就把那个版本装进一个临时目录，再让 DSH_TEST_HARNESS_ENTRY 指向它：

npm install --prefix /tmp/dsh-020rc2 @deepseek-ai/dsh@0.2.0-rc.2 --ignore-scripts
DSH_TEST_HARNESS_ENTRY=/tmp/dsh-020rc2/node_modules/@deepseek-ai/dsh/lib/bin.js npm run test:integration

集成测试套件把插件挂到那个 DSH 自己的 Cordis 里，旁边就是真实的 LocalAttachmentStore、真实的 LLM 运行时和真实的 pi-ai 适配器。它会保存真实的 PNG，并向回环 mock 服务器发送真实请求（假凭据，不调用付费 API）。然后解码 HTTP body 里的图片，检查：

- 选中的模型收到的是压缩后的图片，同一服务商下的另一个模型收到的是原图；
- 重发时用的是缓存里压缩后的版本；
- 实时修改的设置应用到了下一次请求。

UI 测试用的是假的 React 测试框架。0.1.0 版本还在真实的 DSH Web 应用上验证过，环境是 0.2.0-rc.2 和 0.2.0-rc.1：把打包好的 tarball 装进一个隔离的 DSH_HOME，配一个 mock 服务商（见 LOCAL-SETUP.md）。每个版本上都检查了：

- 标签页能渲染出来，所有服务商都是 Off；
- 模型清单来自实时目录；
- 规则保存后能持久化，刷新页面仍在；在 0.2.0-rc.2 上，重启服务器、卸载再重装也仍在；
- 浏览器控制台没有插件报出的错误。

License

MIT。维护者的发布步骤见 RELEASE.md。