samuelrubiodev/dsh-hyper-tools

dsh-hyper-tools

使 Charm Hyper 模型请求保持在网关严格的 10 MiB 请求体上限之内。

Charm Hyper 的 HTTP 网关（位于 Go 后端前面的 Google Frontend）会拒绝任何超过 10 MiB 的请求体，并返回：

{ "error": { "message": "invalid request body", "type": "invalid_request_error", "code": null } }

长对话会累积图像，而每张图像都以 base64 image_url 部分内联。一旦序列化后的请求体超过上限，整个请求就会在推理之前失败——即使这些图像只是普通附件。本插件为配置的 Charm Hyper 提供商路由注册一个 llm/stream 中间件：

1. 在分发之前，它会投影持久历史，使累积的 base64 图像负载符合 maxRequestImageBytes（默认 6 MiB）。最旧的图像会变成 harness 标准的确定性占位符（[image omitted to fit request image limits; …]），而最新的图像会保留。已经符合要求的请求会原样通过 next() 分发——不会额外尝试提供商。
2. 当网关仍然拒绝请求体时（投影低估了非图像开销），它会吞掉那个终态的 invalid request body 失败，并以图像预算乘以 recoveryBudgetFactor（默认 0.5）重新分发一次，这会替换掉更多最旧的图像。如果更严格的投影无法再移除任何内容，则原样呈现原始失败。

计量和占位符来自 harness 本身（offloadRequestImagesWithPolicy、offloadedImageText）：每个图像出现的 base64 长度——包括嵌套的工具结果图像——以及已发布适配器使用的相同确定性占位符文本。

已验证行为

针对 https://hyper.charm.land/v1（deepseek-v4.1-flash，六张 1024×683 PNG 截图）进行了实时检查：

| 请求 | 序列化请求体 | 结果 |
| --- | ---: | --- |
| 累积图像，未投影 | 16,794,575 字节 | 400 invalid request body |
| 由本插件投影的同一历史 | 5,599,267 字节（替换了 4 张最旧的图像） | 200 OK |

网关上限实测为 10 MiB（10,485,760 字节）：10,400,000 字节的请求体可通过网关，10,490,000 字节的请求体被拒绝。scripts/probe-hyper.py 可复现该探测；tests/live.test.ts 可复现上表。

安装

dsh plugin --profile  add dsh-hyper-tools

从检出目录或 tarball 安装：

dsh plugin --profile  add ./dsh-hyper-tools
or
npm pack && dsh plugin --profile  add ./dsh-hyper-tools-0.1.0.tgz

从 git 安装（构建好的 lib/ 已提交，因此 pnpm 无需构建权限）：

dsh plugin --profile  add github:samuelrubiodev/dsh-hyper-tools#main

bundle 补丁（cordis.patch.yml）会插入一行（hyper-tools）。

配置

每个字段都是可选的；行 config 承载它们。

| 字段 | 默认值 | 含义 |
| --- | --- | --- |
| providers | ['charm-hyper', 'hyper'] | 要防护的 Provider 路由；匹配不区分大小写。 |
| maxRequestImageBytes | 6291456（6 MiB） | 单个请求可携带的 base64 图像负载总量。 |
| maxImagesPerRequest | 无 | 每个请求图像数量的可选上限。 |
| recovery | true | 当网关拒绝请求体时重试一次。 |
| recoveryBudgetFactor | 0.5 | 恢复重试时的图像预算乘数。 |
| byteQuantum | 1 | 字节溢出时按整步移除的量化单位；1 会保留最新的可保留图像。 |
| countQuantum | 1 | 数量溢出时按整步移除的量化单位。 |

- id: hyper-tools
name: 'dsh-hyper-tools'
config:
providers: ['charm-hyper']
maxRequestImageBytes: 6291456

说明与限制

- 预算只计算图像负载——即平台文档中针对请求图像限制所规定的单位。文本、工具 schema 和 JSON 结构不计入其中；默认值在 10 MiB 上限之下留出了数 MiB 的余量，而恢复重试则能覆盖估算偏差。
- 投影会根据持久化的附件元数据（attachment.bytes）估算每次出现；任何 provider 端的重新编码只会让实际负载更小，因此该估算倾向于略微提前替换。
- 只有 providers 中列出的路由会受到影响；其他所有 provider 请求都会原样通过。
- 该插件与适配器无关：它只依据 GenerateOptions.provider 进行判断，因此无论 Charm Hyper 是由 @deepseek-ai/dsh-llm-pi-ai、自定义网关适配器还是其他任何方式提供服务，它都能对其进行防护。

开发

npm ci
npm run typecheck
npm test                 # 针对真实 cordis + @deepseek-ai/dsh-llm 运行时的单元 + 集成测试
npm run build
HYPER_API_KEY=... npx vitest run tests/live.test.ts   # 针对 Charm Hyper 的实时检查

编译后的 lib/ 已提交，因此通过 github: 安装无需构建步骤；npm pack / npm publish 会通过 prepack 刷新它。

兼容性：@deepseek-ai/dsh-llm ^0.1.5-rc.1、@deepseek-ai/cordis ^4.0.1。

许可证

MIT