dsh-neartoken 0.15.4 → 0.16.0

package/README.md

@@ -68,6 +68,8 @@
 | `defaultContextWindow` | `200000` | 没有任何来源能说明某模型上下文窗口时上报的值 |
 | `modelOverrides` | `{}` | 按裸模型名逐条修正容量与推理等级，见下 |
 | `enabledModels` | `[]` | 模型白名单（裸模型名）；空数组 = 全部显示。volatile，设置页直接写它 |
+| `imageMaxEdge` | `2048` | 发送到上游前图片的长边上限（像素）；更大的图按长边缩到它，见下「图片压缩」 |
+| `imageMaxBytes` | `2097152` | 单张请求图的编码字节上限；超出走编码质量阶梯，必要时把 PNG 转成 JPEG / WebP |
 | `imageTimeoutMs` | `300000` | 单次生图的预算（毫秒）；工具调用截止时间 = 它 + 30 秒，见下文「超时」 |
 | `imageGeneration` | `{ enabled: false, models: {} }` | 生图开关与「模型 → 分组」映射；volatile，设置页写 |
 
@@ -83,6 +85,17 @@
         reasoning: [low, medium, high, max]
 ```
 
+### 图片压缩
+
+**图片在离开本机前先被重编码**，不是原图直传：请求前把每张图交给 harness 的附件服务（`attachments.readImageRequest`）按 `imageMaxEdge` / `imageMaxBytes` 生成一份请求版，sharp 缩放 + 质量阶梯重编码（有 alpha 走 WebP、无 alpha 走 JPEG），结果按「附件 + 目标尺寸 + 字节预算」缓存，同一张图重复发不重复编码。已经被上游视觉网格丢掉的分辨率不再上传，也就不再计费。
+
+实测（`ds-harness-remote/docs/images/remote.png`，2559×1639 PNG 951 KB）：默认策略下变成 2048 长边 JPEG 219 KB，base64 后 292 KB，约为原图的 23%；把 `imageMaxEdge` 调到 768 且 `imageMaxBytes` 调到 300 KB 时降到 52 KB。
+
+两条边界：
+
+- **原图已经在两个上限内时不重编码**（附件服务直接返回原字节），所以小图不会被无谓地转成 JPEG。
+- **附件服务不支持请求版**（`ATTACHMENT_PROJECTION_UNSUPPORTED`，非本地存储后端的默认行为）时**退回原图发送**，请求不会因此失败；其它错误照旧让请求失败，不会静默降级。
+
 ## 模型可见性
 
 站点 `/api/pricing` 会列出它知道的所有模型，插件只提供会响应聊天请求的那部分：
@@ -190,7 +203,7 @@ Gemini 系走原生 surface 而不是 openai 兼容层：同模型同提示词
 
 ## 已知限制
 
-- 四套 wire（chat / anthropic / genai / responses）各自解析 SSE；**图片按各协议原样发送** —— chat 用 `image_url` part、anthropic 用 `source.base64`、genai 用 `inlineData`、responses 用 `input_image`。**工具结果里的图片也发**（`read_image` 的结果就是一段文本信封 + 一张图）：anthropic 把图塞回同一个 `tool_result` 的 content 块数组；genai 在同一 user turn 的 parts 里补 `inlineData`；chat 的 tool 消息只能放字符串、responses 的 `function_call_output` 同理，所以图跟在**整段连续工具结果之后**的一条 user 消息 / 条目里（并行调用时不会把 tool 消息切断）。字节由 `attachments.readImage` 在请求前内联；没有 attachments 服务或读不出来会**让请求失败**，不再静默降级成纯文本（曾经就是这样：贴的截图模型根本收不到）。会话里被 image-offload 标记的图片（`offloaded: true`）不发字节；插件也不替它生成占位文本，所以那一次图片对模型完全不可见。文件块（非图片附件）仍不发；`/model` 弹窗仍是内置平铺列表；箭头键盘导航未接。
+- 四套 wire（chat / anthropic / genai / responses）各自解析 SSE；**图片按各协议发送** —— chat 用 `image_url` part、anthropic 用 `source.base64`、genai 用 `inlineData`、responses 用 `input_image`。发送前先按 `imageMaxEdge` / `imageMaxBytes` 重编码（见「图片压缩」），所以线上字节与媒体类型未必等于附件里的原图。**工具结果里的图片也发**（`read_image` 的结果就是一段文本信封 + 一张图）：anthropic 把图塞回同一个 `tool_result` 的 content 块数组；genai 在同一 user turn 的 parts 里补 `inlineData`；chat 的 tool 消息只能放字符串、responses 的 `function_call_output` 同理，所以图跟在**整段连续工具结果之后**的一条 user 消息 / 条目里（并行调用时不会把 tool 消息切断）。字节由 `attachments.readImage` 在请求前内联；没有 attachments 服务或读不出来会**让请求失败**，不再静默降级成纯文本（曾经就是这样：贴的截图模型根本收不到）。会话里被 image-offload 标记的图片（`offloaded: true`）不发字节；插件也不替它生成占位文本，所以那一次图片对模型完全不可见。文件块（非图片附件）仍不发；`/model` 弹窗仍是内置平铺列表；箭头键盘导航未接。
 - 四套 wire 的 SSE 解析都有「帧样本 → 期望 chunk 序列」回归测试（`src/host/wire-parse.spec.ts`），帧样本取自生产网关的真实响应。网关在内容帧上发 `"usage": null`，只有末帧带真值：任何一处把 `usage` 当对象直接读都会让整条流中途崩掉（曾导致 claude 模型全不可用）。
 - **每个请求都带会话亲和键**：chat 与 responses 发 `prompt_cache_key`，anthropic 发 `metadata.user_id`，取值都是 DSH 的 `GenerateOptions.sessionId`。站点就是靠这个值挑上游渠道的（New API 的「codex cli trace」规则：`^gpt-.*$` + `/v1/responses`，键取自 body 的 `prompt_cache_key`，取不到就把整条规则跳过），而提示词缓存按**上游账号**存 —— 不带键时每个请求随机换账号，缓存永远不中。实测同一 6k 前缀：不带键连发 4 次 `cached_tokens` 全 0；带键后第 2 次起 5888/6011 ≈ 98%。`/v1/chat/completions` 上目前没有对应规则，chat 线即使带键也只是偶发命中，要彻底解决需要站点加一条匹配该路径的亲和规则；anthropic 线的 `metadata.user_id` 同理（规则只作用于 `/v1/messages`，这一条已经匹配）。
 - **anthropic 线显式打缓存断点**：Anthropic 只在 `cache_control` 断点处写缓存，没有断点就整段 prompt 按新输入计价（亲和键只保证落在同一上游账号，不产生缓存）。每个请求打 4 个断点：`tools` 末项、`system` 末块、最后两条消息各自末块 —— harness 每轮全量重放历史，尾部双断点保证下一轮几乎全命中，每轮只写新增片段。实测（Claude Max 超惠分组，~6.3k token 前缀）：无断点连发两次 `cache_read` 全 0；打点后第 2 次起 `in=4, cr=6316`，三轮增长历史 `cr` 累积到 10811、`in` 恒为个位数。断点也覆盖 `tool_result` 结尾的轮次（DSH 会话的常态形态）。

package/lib/index.js

@@ -2136,6 +2136,18 @@ function sessionKeyOf(options) {
 * @module
 */
 /**
+* Default request-image bounds.
+*
+* A model reads a picture through a fixed visual grid, so bytes past roughly
+* 2048 pixels on the long edge buy no detail while still costing upload time and
+* base64 in the prompt. 2 MiB is the ceiling the harness's own DeepSeek routes
+* use for one encoded request image.
+*/
+const DEFAULT_IMAGE_REQUEST_POLICY = {
+	maxEdge: 2048,
+	maxBytes: 2097152
+};
+/**
 * The images one block list carries, in message order.
 *
 * Message content is flat: a tool result keeps the blocks its tool rendered (a
@@ -2154,14 +2166,80 @@ function imagesIn(content, images) {
 	return found;
 }
 /**
+* The request dimensions one stored image is projected onto.
+*
+* The long edge is what a visual encoder resamples by, so the short edge follows
+* it. An image already inside the bound keeps its own dimensions and the store
+* then decides from the byte ceiling whether it has to encode anything at all.
+* @param reference - the stored image's intrinsic dimensions.
+* @param policy - the configured bounds.
+* @returns integer dimensions no larger than the source, plus the byte ceiling.
+*/
+function requestTargetOf(reference, policy) {
+	const longEdge = Math.max(reference.width, reference.height);
+	if (longEdge <= policy.maxEdge) return {
+		width: reference.width,
+		height: reference.height,
+		maxBytes: policy.maxBytes
+	};
+	const scale = policy.maxEdge / longEdge;
+	return {
+		width: Math.max(1, Math.floor(reference.width * scale)),
+		height: Math.max(1, Math.floor(reference.height * scale)),
+		maxBytes: policy.maxBytes
+	};
+}
+/**
+* Whether a store refused request-image projection itself.
+* @param error - value caught from `readImageRequest`.
+* @returns true for the attachment service's documented unsupported code.
+*/
+function isProjectionUnsupported(error) {
+	return typeof error === "object" && error !== null && error.code === "ATTACHMENT_PROJECTION_UNSUPPORTED";
+}
+/**
+* Read one image as the bytes this request should carry.
+*
+* The request version is preferred: the store downscales and re-encodes it
+* within the target, so a 4K screenshot does not travel as 8 MiB of base64. A
+* store without projection still has the normalized original, which is sent
+* unchanged rather than failing the request.
+* @param source - the attachment service.
+* @param reference - the durable reference carried by the message.
+* @param policy - the configured bounds.
+* @param signal - the request's cancellation.
+* @returns the bytes to inline and the media type they are.
+* @throws {LlmError} when the bytes cannot be read at all.
+*/
+async function requestBytes(source, reference, policy, signal) {
+	try {
+		if (source.readImageRequest !== void 0) try {
+			const version = await source.readImageRequest(reference, requestTargetOf(reference, policy), signal);
+			return {
+				data: version.data,
+				mediaType: version.mediaType
+			};
+		} catch (error) {
+			if (!isProjectionUnsupported(error)) throw error;
+		}
+		return {
+			data: (await source.readImage(reference, signal)).data,
+			mediaType: reference.mediaType
+		};
+	} catch (error) {
+		throw new LlmError(`cannot read attachment "${reference.attachmentId}" for this request: ${error instanceof Error ? error.message : String(error)}`, "ATTACHMENT_UNREADABLE");
+	}
+}
+/**
 * Collect every image a request's messages carry, inlined for the wires.
 * @param attachments - the attachment service, when the composition has one.
 * @param messages - the request's conversation messages.
 * @param signal - the request's cancellation.
+* @param policy - the request-image bounds every picture is encoded to.
 * @returns attachment id to base64 image; empty when the request carries none.
 * @throws {LlmError} when a message carries an image that cannot be inlined.
 */
-async function inlineImages(attachments, messages, signal) {
+async function inlineImages(attachments, messages, signal, policy = DEFAULT_IMAGE_REQUEST_POLICY) {
 	const references = [];
 	for (const message of messages) for (const block of message.content) {
 		if (typeof block !== "object" || block === null) continue;
@@ -2176,15 +2254,10 @@ async function inlineImages(attachments, messages, signal) {
 	for (const reference of references) {
 		const id = String(reference.attachmentId);
 		if (images.has(id)) continue;
-		let data;
-		try {
-			data = (await attachments.readImage(reference, signal)).data;
-		} catch (error) {
-			throw new LlmError(`cannot read attachment "${id}" for this request: ${error instanceof Error ? error.message : String(error)}`, "ATTACHMENT_UNREADABLE");
-		}
+		const bytes = await requestBytes(attachments, reference, policy, signal);
 		images.set(id, {
-			mediaType: reference.mediaType,
-			data: Buffer.from(data).toString("base64")
+			mediaType: bytes.mediaType,
+			data: Buffer.from(bytes.data).toString("base64")
 		});
 	}
 	return images;
@@ -4141,7 +4214,7 @@ var NearTokenAdapter = class extends LlmAdapter {
 		const { model } = decodeRoute(options.model);
 		const groupRef = (await this.deps.routes()).find((entry) => entry.id === options.model)?.groupRef;
 		const wire = wireFor(model);
-		const images = await inlineImages(this.deps.attachments(), options.messages, options.signal);
+		const images = await inlineImages(this.deps.attachments(), options.messages, options.signal, this.deps.imagePolicy());
 		let response;
 		try {
 			response = await fetch(wire.url(this.deps.baseURL(), model), {
@@ -4402,7 +4475,8 @@ var NearTokenProvider = class {
 			baseURL: this.deps.baseURL,
 			defaultContextWindow: this.deps.defaultContextWindow,
 			modelOverride: this.deps.modelOverride,
-			attachments: this.deps.attachments
+			attachments: this.deps.attachments,
+			imagePolicy: this.deps.imagePolicy
 		});
 		this.routes = this.ctx.llm.registerAdapter([this.deps.provider], adapter);
 		this.directory = this.ctx.llm.registerConfigurableProviders([{
@@ -4909,6 +4983,20 @@ const Config = z.object({
 		input: z.array(z.union([z.const("text"), z.const("image")]))
 	})).default({}).volatile(),
 	/**
+	* Longest edge, in pixels, of one image on the wire. A model reads a picture
+	* through a fixed visual grid, so detail past roughly 2048 pixels on the long
+	* edge is billed and uploaded without being seen; a larger image is scaled down
+	* to this bound before it is sent.
+	*/
+	imageMaxEdge: z.number().step(1).min(1).default(2048),
+	/**
+	* Encoded-byte ceiling for one request image. An image already inside both
+	* bounds travels unchanged; one that is not is re-encoded down through the
+	* encoder's quality ladder until it fits, converting a screenshot PNG to JPEG
+	* or WebP on the way.
+	*/
+	imageMaxBytes: z.number().step(1).min(1024).default(2097152),
+	/**
 	* How long one picture may take. The site's image models routinely need
 	* 25-60 seconds, and a discounted group measured 114 seconds on a good day, so
 	* the default leaves room for that rather than sitting just above the median.
@@ -4961,7 +5049,11 @@ function apply(ctx, config) {
 				...page
 			};
 		},
-		attachments: () => ctx.get("attachments")
+		attachments: () => ctx.get("attachments"),
+		imagePolicy: () => ({
+			maxEdge: config.imageMaxEdge,
+			maxBytes: config.imageMaxBytes
+		})
 	});
 	const whitelist = new NearTokenWhitelist({
 		enabled: () => config.enabledModels.get(),

package/lib/types/host/adapter.d.ts

@@ -1,6 +1,7 @@
 import { LlmAdapter } from '@deepseek-ai/dsh-llm';
 import type { GenerateOptions, LlmModelInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
 import type { NearTokenRoute } from './pricing.ts';
+import type { ImageRequestPolicy } from './wire-images.ts';
 import type { ImageSource } from './wire-images.ts';
 /** Display name of the single provider route this adapter owns. */
 export declare const NEARTOKEN_PROVIDER_NAME = "NearToken";
@@ -38,6 +39,8 @@ export interface NearTokenDeps {
     modelOverride: (model: string) => NearTokenModelOverride | undefined;
     /** The attachment service, which owns the bytes behind a message's images. */
     attachments: () => ImageSource | undefined;
+    /** The bounds every request image is re-encoded to before it is sent. */
+    imagePolicy: () => ImageRequestPolicy;
 }
 /**
  * Decode one catalog model id into its routing parts.

package/lib/types/host/provider-mount.d.ts

@@ -10,7 +10,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { NearTokenModelOverride } from './adapter.ts';
-import type { ImageSource } from './wire-images.ts';
+import type { ImageRequestPolicy, ImageSource } from './wire-images.ts';
 import type { NearTokenRoute } from './pricing.ts';
 /** External facts the route is built from. */
 export interface NearTokenProviderDeps {
@@ -34,6 +34,8 @@ export interface NearTokenProviderDeps {
     modelOverride: (model: string) => NearTokenModelOverride | undefined;
     /** The attachment service, when the composition provides one. */
     attachments: () => ImageSource | undefined;
+    /** The bounds every request image is re-encoded to before it is sent. */
+    imagePolicy: () => ImageRequestPolicy;
 }
 /** The NearToken provider route, mounted at most once per process. */
 export declare class NearTokenProvider {

package/lib/types/host/wire-images.d.ts

@@ -8,6 +8,30 @@ export interface WireImage {
 }
 /** Attachment id to the inlined image, for one request. */
 export type WireImages = ReadonlyMap<string, WireImage>;
+/** One durable image reference, as a message block carries it. */
+export interface ImageReference {
+    readonly attachmentId: string;
+    readonly mediaType: string;
+    readonly bytes: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** Bounds one request image is encoded to before any wire carries it. */
+export interface ImageRequestPolicy {
+    /** Longest edge in pixels; a larger image is scaled down to it and never up. */
+    readonly maxEdge: number;
+    /** Encoded-byte ceiling for one image; the encoder keeps the smallest quality that fits. */
+    readonly maxBytes: number;
+}
+/**
+ * Default request-image bounds.
+ *
+ * A model reads a picture through a fixed visual grid, so bytes past roughly
+ * 2048 pixels on the long edge buy no detail while still costing upload time and
+ * base64 in the prompt. 2 MiB is the ceiling the harness's own DeepSeek routes
+ * use for one encoded request image.
+ */
+export declare const DEFAULT_IMAGE_REQUEST_POLICY: ImageRequestPolicy;
 /** The slice of the attachment service this module reads. */
 export interface ImageSource {
     /**
@@ -16,14 +40,26 @@ export interface ImageSource {
      * @param signal - the request's cancellation.
      * @returns the stored bytes beside their reference.
      */
-    readImage(attachment: {
-        attachmentId: string;
-        mediaType: string;
-        bytes: number;
+    readImage(attachment: ImageReference, signal?: AbortSignal): Promise<{
+        data: Uint8Array;
+    }>;
+    /**
+     * Derive the request version of one stored image: scaled within the target and
+     * re-encoded under its byte ceiling. A store that cannot derive one rejects
+     * with code `ATTACHMENT_PROJECTION_UNSUPPORTED`, and the caller sends the
+     * normalized original instead.
+     * @param attachment - the durable reference carried by the message.
+     * @param target - integer dimensions and encoded-byte ceiling for this request.
+     * @param signal - the request's cancellation.
+     * @returns the request bytes and the media type they were encoded as.
+     */
+    readImageRequest?(attachment: ImageReference, target: {
         width: number;
         height: number;
+        maxBytes: number;
     }, signal?: AbortSignal): Promise<{
         data: Uint8Array;
+        mediaType: string;
     }>;
 }
 /**
@@ -42,10 +78,11 @@ export declare function imagesIn(content: readonly unknown[], images: WireImages
  * @param attachments - the attachment service, when the composition has one.
  * @param messages - the request's conversation messages.
  * @param signal - the request's cancellation.
+ * @param policy - the request-image bounds every picture is encoded to.
  * @returns attachment id to base64 image; empty when the request carries none.
  * @throws {LlmError} when a message carries an image that cannot be inlined.
  */
-export declare function inlineImages(attachments: ImageSource | undefined, messages: readonly RequestMessage[], signal?: AbortSignal): Promise<WireImages>;
+export declare function inlineImages(attachments: ImageSource | undefined, messages: readonly RequestMessage[], signal?: AbortSignal, policy?: ImageRequestPolicy): Promise<WireImages>;
 /**
  * Find the inlined bytes behind one message block.
  * @param block - one content block, of any type.

package/lib/types/index.d.ts

@@ -25,6 +25,10 @@ export interface Options {
     enabledModels: Volatile<string[]>;
     /** Per-model meta overrides the settings page edits beside the whitelist. */
     modelMeta: Volatile<Record<string, NearTokenModelMeta>>;
+    /** Longest edge, in pixels, one request image keeps. */
+    imageMaxEdge: number;
+    /** Encoded-byte ceiling for one request image. */
+    imageMaxBytes: number;
     /** How long one image generation may take, in milliseconds. */
     imageTimeoutMs: number;
     /** The image-generation setting: the tool's switch and one group per enabled model. */
@@ -89,6 +93,20 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         maxTokens: z<number, number, "plain">;
         input: z<("text" | "image")[], ("text" | "image")[], "plain">;
     }>>, string>>, "volatile-defined">;
+    /**
+     * Longest edge, in pixels, of one image on the wire. A model reads a picture
+     * through a fixed visual grid, so detail past roughly 2048 pixels on the long
+     * edge is billed and uploaded without being seen; a larger image is scaled down
+     * to this bound before it is sent.
+     */
+    imageMaxEdge: z<number, number, "defined">;
+    /**
+     * Encoded-byte ceiling for one request image. An image already inside both
+     * bounds travels unchanged; one that is not is re-encoded down through the
+     * encoder's quality ladder until it fits, converting a screenshot PNG to JPEG
+     * or WebP on the way.
+     */
+    imageMaxBytes: z<number, number, "defined">;
     /**
      * How long one picture may take. The site's image models routinely need
      * 25-60 seconds, and a discounted group measured 114 seconds on a good day, so
@@ -168,6 +186,20 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         maxTokens: z<number, number, "plain">;
         input: z<("text" | "image")[], ("text" | "image")[], "plain">;
     }>>, string>>, "volatile-defined">;
+    /**
+     * Longest edge, in pixels, of one image on the wire. A model reads a picture
+     * through a fixed visual grid, so detail past roughly 2048 pixels on the long
+     * edge is billed and uploaded without being seen; a larger image is scaled down
+     * to this bound before it is sent.
+     */
+    imageMaxEdge: z<number, number, "defined">;
+    /**
+     * Encoded-byte ceiling for one request image. An image already inside both
+     * bounds travels unchanged; one that is not is re-encoded down through the
+     * encoder's quality ladder until it fits, converting a screenshot PNG to JPEG
+     * or WebP on the way.
+     */
+    imageMaxBytes: z<number, number, "defined">;
     /**
      * How long one picture may take. The site's image models routinely need
      * 25-60 seconds, and a discounted group measured 114 seconds on a good day, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-neartoken",
-  "version": "0.15.4",
+  "version": "0.16.0",
   "publishConfig": {
     "access": "public"
   },