dsh-remote-bridge 2.2.2 → 2.2.3

package/docs/api/asyncapi.yaml

@@ -1,8 +1,15 @@
 asyncapi: 3.0.0
 info:
   title: DeepSeek Harness Mobile Events
-  version: 2.2.2
-  description: Live file and authorized DSH chat events. Reconnect clients must refresh REST state; unbounded replay is not provided.
+  version: 2.2.3
+  description: |
+    Live file and authorized DSH chat events. Reconnect clients must refresh
+    REST state; unbounded replay is not provided.
+
+    `chat.turn.failed` carries the terminal failure of a model turn (rate
+    limit, quota exhausted, invalid API key, signed-out stop). Without it a
+    remote client sees an ordinary `chat.turn.end` and keeps waiting on a run
+    that already failed.
 servers:
   local:
     host: 127.0.0.1:3090
@@ -32,7 +39,7 @@ components:
           id: { type: string }
           type:
             type: string
-            examples: [file.changed, file.trashed, chat.message.delta, chat.message.committed, chat.session.status, chat.approval.requested, chat.approval.resolved, connection.ready]
+            examples: [file.changed, file.trashed, chat.message.delta, chat.message.committed, chat.session.status, chat.approval.requested, chat.approval.resolved, chat.turn.failed, connection.ready]
           time: { type: integer }
           data:
             oneOf:
@@ -40,6 +47,7 @@ components:
               - $ref: '#/components/schemas/ChatMessageCommitted'
               - $ref: '#/components/schemas/ChatApprovalRequested'
               - $ref: '#/components/schemas/ChatApprovalResolved'
+              - $ref: '#/components/schemas/ChatTurnFailed'
               - type: object
                 additionalProperties: true
   schemas:
@@ -84,3 +92,30 @@ components:
         sessionId: { type: string }
         approvalId: { type: string }
         outcome: { type: string, enum: [allowed-once, rejected, cancelled, unavailable] }
+    ChatTurnFailed:
+      type: object
+      description: |
+        Terminal failure of a model turn. Emitted instead of a plain
+        `chat.turn.end` when the host reports `reason.kind === 'error'` (rate
+        limit, quota exhausted, invalid key) or an abort caused by signing out
+        of the DeepSeek account. Clients must stop their running indicator and
+        show the message; otherwise a failed run keeps looking like it is in
+        flight.
+      required: [sessionId, eventType, failure]
+      properties:
+        sessionId: { type: string }
+        eventType: { type: string, const: turn/end }
+        seq: { type: integer }
+        failure:
+          type: object
+          description: |
+            `message` is the host's own wording, forwarded verbatim so clients
+            can decide localization. `code` is present only when the host
+            supplies one; an empty string is meaningful and must not be
+            treated as absent. `stopped` marks an account-sign-out stop, which
+            is not a model fault.
+          required: [message]
+          properties:
+            message: { type: string }
+            code: { type: string }
+            stopped: { type: boolean, const: true }

package/docs/api/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: DeepSeek Harness Mobile API
-  version: 2.2.2
+  version: 2.2.3
   description: Versioned file and chat BFF for mobile and third-party DSH clients. HTTP and HTTPS are both supported.
 servers:
   - url: http://127.0.0.1:3090/api/v1

package/lib/index.d.ts

@@ -220,16 +220,37 @@ interface DshApiProxy {
      *
      * `attachmentId` 形如 `sha256:<hex>`（**含冒号**，客户端必须 URL 编码）。
      * 返回 `Uint8Array` 而不是 base64：图片动辄上百 KB，多一次编解码纯属浪费。
+     *
+     * **必须带 `sessionId`**：内核要靠它读会话事件、取出这张图的真实 ref，
+     * 再据此做完整性校验（详见 chat-adapter 的 readAttachment 注释）。
      */
     readAttachment(request: {
       rpcId: string;
       payload: {
+        sessionId: string;
         attachmentId: string;
       };
     }): Promise<RpcResponse<{
       bytes: Uint8Array;
       mediaType: string;
     }>>;
+    /**
+     * 取回一张**交接图片**的字节（纯文本模型发图时，图片被落成工作区文件）。
+     *
+     * 与 [readAttachment] 的区别：那一个取内核附件存储里的图（走
+     * `sessionController.attachment`），这一个取插件自己写进 `.dsh-images/`
+     * 的交接件。手机端用它把图片**显示**给人看；消息里的路径文本照旧留给模型。
+     */
+    readHandoffImage(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        name: string;
+      };
+    }): Promise<RpcResponse<{
+      bytes: Uint8Array;
+      mediaType: string;
+    }>>;
     cancel(request: {
       rpcId: string;
       payload: {
@@ -622,12 +643,28 @@ declare class DshChatAdapter {
   /**
    * 取回会话历史里某个图片附件的字节。
    *
-   * 这里不做会话归属校验：附件 id 是内容哈希，拿到 id 就等于拿到内容，
-   * 而且调用方必须已经通过 `files.read` 鉴权并主动持有该 id（它只出现在其有权读取的
-   * 会话事件里）。多一层会话校验并不能提升安全性，却会让「在别的会话里引用同一张图」
-   * 这种正常情况莫名失败。
+   * **为什么会走内核的 `sessionController.attachment()`，而不自己调
+   * `ctx.attachments.readImage()`**：
+   * 1. 实测本机 profile 里 `ctx.attachments` 是 **MISSING**（拿不到注入属性）——
+   *    自己拼 ref 那条路根本走不通；
+   * 2. 内核那个方法内部一次做完三件事：校验该会话确实引用了这张图、
+   *    读出字节、用**会话事件里那条真实 ref** 做完整性校验
+   *    （`mediaType` / `bytes` / `width` / `height` 四项逐项比对）。
+   *    绕开它就得把这三件事全复刻 —— 先前正是漏了第三件，于是每张图
+   *    `ATTACHMENT_CORRUPT`：「字节读到了，却被校验拒之门外」。
+   *
+   * 因此 **sessionId 是必需参数**（内核要拿它读会话事件、找到那张图的真实 ref）；
+   * 早先设计的「客户端把四项元数据带上来」是多余的 —— 内核手里本来就有。
+   */
+  readAttachment(principal: Principal, sessionId: string, attachmentId: string): Promise<{
+    bytes: Uint8Array;
+    mediaType: string;
+  }>;
+  /**
+   * 取回一张**交接图片**（纯文本模型发图时落在工作区 `.dsh-images/` 的那份）。
+   * 与 [readAttachment] 同样要求会话归属；文件名在桥里还有一道白名单校验。
    */
-  readAttachment(principal: Principal, attachmentId: string): Promise<{
+  readHandoffImage(principal: Principal, sessionId: string, name: string): Promise<{
     bytes: Uint8Array;
     mediaType: string;
   }>;
@@ -902,8 +939,21 @@ interface FileUploadsLike {
  * 否则历史里的图片一律显示不出来。
  */
 interface AttachmentStoreLike {
-  readImage(ref: {
+  readImage(
+  /**
+   * 附件引用。
+   *
+   * `attachmentId` 是唯一的**定位**字段（内核用 `ID_PATTERN.exec()` 取出 sha256
+   * 再拼 `objects/<前两位>/<sha>`）；而 `mediaType` / `bytes` / `width` / `height`
+   * 参与读后**完整性校验** —— 缺任何一项都会抛 `ATTACHMENT_CORRUPT`，
+   * 哪怕字节已经正确读出来了。
+   */
+  ref: {
     attachmentId: string;
+    mediaType?: string;
+    bytes?: number;
+    width?: number;
+    height?: number;
   }, signal?: AbortSignal): Promise<{
     ref: {
       mediaType: string;
@@ -978,6 +1028,33 @@ interface SessionControllerLike {
   }): Promise<{
     sessionId: string;
   }>;
+  /**
+   * 取一张**被这个会话引用过**的图片字节（内核主机端方法，名字就叫 `attachment`）。
+   *
+   * 这是取历史图片的**正路**，它内部一次做完三件事：校验会话确实引用了这张图、
+   * 调 `ctx.attachments.readImage`、用**会话事件里那条真实 ref**做完整性校验
+   *（`mediaType` / `bytes` / `width` / `height` 四项逐项比对）。
+   *
+   * 为什么必须走它、不能自己调 `ctx.attachments`：实测本机这条 profile 里
+   * `ctx.attachments` 是 **MISSING**（诊断日志
+   * `ctx.attachments MISSING（所以改走内核 sessionController.readAttachment）`），
+   * 自己拼 ref 那条路根本走不通；而且绕开内核就得把它内部三件事全复刻一遍，
+   * 早先正是只传了 id、缺四项元数据，导致 `ATTACHMENT_CORRUPT`。
+   *
+   * 注意方法名：**主机端叫 `attachment`**，客户端契约里才叫 `readAttachment`
+   *（`dsh-api-session-controller/lib/types/client/contract/session.d.ts`）。
+   * `data` 是 **base64 字符串**（主机端实现里 `Buffer.from(stored.data).toString("base64")`），
+   * 不是 Uint8Array —— 调用方要自己解码。
+   */
+  attachment(request: {
+    sessionId: string;
+    attachmentId: string;
+  }): Promise<{
+    attachment: {
+      mediaType: string;
+    };
+    data: string;
+  }>;
   selectModel(request: {
     sessionId: string;
     provider: string;
@@ -1085,6 +1162,17 @@ interface LlmLike {
     error?: string;
   }[];
   discoverModels(settingsNs: string, request: unknown, signal?: AbortSignal): Promise<readonly unknown[]>;
+  /**
+   * 一个路由 + 模型 id 的**真实元数据**。
+   *
+   * 为什么必须用它、而不是自己猜模型能不能看图：内核拒绝「给纯文本模型发图片」时
+   * 用的就是**这个方法**（`SessionController` 的 prompt 准入里
+   * `this.ctx.llm.resolveModelInfo(...)` 再查 `inputModalities`）。入口要与内核
+   * 得出同一个结论，只能查同一份元数据 —— 名字、前缀、家族表都是启发式，会漂。
+   */
+  resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<{
+    inputModalities?: readonly string[];
+  } | undefined>;
 }
 /** Host services the bridge consumes; assembled by `src/index.ts` from `ctx`. */
 interface Dsh02HostServices {

package/lib/index.js

@@ -1,11 +1,11 @@
-import path from "node:path";
+import path, { join } from "node:path";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { chmod, copyFile, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
-import { createReadStream, mkdirSync } from "node:fs";
+import { createReadStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
+import os, { homedir, hostname, networkInterfaces } from "node:os";
 import { pipeline } from "node:stream/promises";
 import { isIP } from "node:net";
-import os, { hostname, networkInterfaces } from "node:os";
 import { createServer } from "node:http";
 import { WebSocket, WebSocketServer } from "ws";
 //#region src/shared/contracts.ts
@@ -424,16 +424,45 @@ var DshChatAdapter = class {
 	/**
 	* 取回会话历史里某个图片附件的字节。
 	*
-	* 这里不做会话归属校验：附件 id 是内容哈希，拿到 id 就等于拿到内容，
-	* 而且调用方必须已经通过 `files.read` 鉴权并主动持有该 id（它只出现在其有权读取的
-	* 会话事件里）。多一层会话校验并不能提升安全性，却会让「在别的会话里引用同一张图」
-	* 这种正常情况莫名失败。
+	* **为什么会走内核的 `sessionController.attachment()`，而不自己调
+	* `ctx.attachments.readImage()`**：
+	* 1. 实测本机 profile 里 `ctx.attachments` 是 **MISSING**（拿不到注入属性）——
+	*    自己拼 ref 那条路根本走不通；
+	* 2. 内核那个方法内部一次做完三件事：校验该会话确实引用了这张图、
+	*    读出字节、用**会话事件里那条真实 ref** 做完整性校验
+	*    （`mediaType` / `bytes` / `width` / `height` 四项逐项比对）。
+	*    绕开它就得把这三件事全复刻 —— 先前正是漏了第三件，于是每张图
+	*    `ATTACHMENT_CORRUPT`：「字节读到了，却被校验拒之门外」。
+	*
+	* 因此 **sessionId 是必需参数**（内核要拿它读会话事件、找到那张图的真实 ref）；
+	* 早先设计的「客户端把四项元数据带上来」是多余的 —— 内核手里本来就有。
 	*/
-	async readAttachment(principal, attachmentId) {
+	async readAttachment(principal, sessionId, attachmentId) {
 		if (attachmentId.trim() === "") throw new ApiError(400, "BODY_INVALID", "attachmentId is required.");
+		if (sessionId.trim() === "") throw new ApiError(400, "BODY_INVALID", "sessionId is required.");
+		await this.requireSession(principal, sessionId);
 		return unwrapDsh(await this.api.sessions.readAttachment({
 			rpcId: randomUUID(),
-			payload: { attachmentId }
+			payload: {
+				sessionId,
+				attachmentId
+			}
+		}));
+	}
+	/**
+	* 取回一张**交接图片**（纯文本模型发图时落在工作区 `.dsh-images/` 的那份）。
+	* 与 [readAttachment] 同样要求会话归属；文件名在桥里还有一道白名单校验。
+	*/
+	async readHandoffImage(principal, sessionId, name) {
+		if (name.trim() === "") throw new ApiError(400, "BODY_INVALID", "name is required.");
+		if (sessionId.trim() === "") throw new ApiError(400, "BODY_INVALID", "sessionId is required.");
+		await this.requireSession(principal, sessionId);
+		return unwrapDsh(await this.api.sessions.readHandoffImage({
+			rpcId: randomUUID(),
+			payload: {
+				sessionId,
+				name
+			}
 		}));
 	}
 	async cancel(principal, sessionId) {
@@ -807,12 +836,30 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 				}
 			};
 		}
-		if (eventType === "turn/start" || eventType === "turn/end") return {
-			id: frame.rpcId,
-			type: eventType === "turn/start" ? "chat.turn.start" : "chat.turn.end",
-			time,
-			data: base
-		};
+		if (eventType === "turn/start" || eventType === "turn/end") {
+			if (eventType === "turn/end") {
+				const failure = turnFailureOf(event);
+				if (failure !== void 0) {
+					const data = {
+						...base,
+						failure
+					};
+					if (failure.stopped === true) data.stopped = true;
+					return {
+						id: `${frame.rpcId}:failed`,
+						type: "chat.turn.failed",
+						time,
+						data
+					};
+				}
+			}
+			return {
+				id: frame.rpcId,
+				type: eventType === "turn/start" ? "chat.turn.start" : "chat.turn.end",
+				time,
+				data: base
+			};
+		}
 		return {
 			id: frame.rpcId,
 			type: "chat.session.event",
@@ -848,6 +895,39 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 		data: payload
 	};
 }
+/**
+* `turn/end` 里的终局失败摘要，取不到就返回 undefined（这轮是正常结束的）。
+*
+* 内核 `turn-error.js` 的 match 判据只认两种：`reason.kind === 'error'`，
+* 以及 `aborted` 且取消原因是「退出 DeepSeek 登录」这个钩子。这里**同一判据**，
+* 不多不少 ——
+* - 不能少：漏掉任一形态，客户端就又回到「傻等」状态；
+* - 不能多：`max-tokens` 是「回答被截断，已有输出保留」，官方单独渲染成黄色警示，
+*   不是失败（客户端按普通 turn/end 收尾即可）；普通取消（用户点了停止）更不是。
+*
+* `code === 'AUTH'` 时内核把 message 抹成空串（`displayFailure`），客户端那边
+* 用本地化文案「API 密钥无效」顶上。这里保持原样转发，不替客户端猜。
+*/
+function turnFailureOf(event) {
+	const reason = isRecord$1(event.data) ? event.data.reason : void 0;
+	if (!isRecord$1(reason)) return void 0;
+	const kind = reason.kind;
+	if (kind === "error") {
+		const error = reason.error;
+		if (!isRecord$1(error)) return { message: String(error ?? "本轮运行失败") };
+		const code = typeof error.code === "string" ? error.code : void 0;
+		const message = typeof error.message === "string" ? error.message : JSON.stringify(error);
+		return code === void 0 ? { message } : {
+			message,
+			code
+		};
+	}
+	if (kind === "aborted" && isRecord$1(reason.reason) && reason.reason.kind === "hook" && reason.reason.reason === "deepseek-account/signed-out") return {
+		message: "Stopped because you signed out of DeepSeek.",
+		code: "ACCOUNT_SIGNED_OUT",
+		stopped: true
+	};
+}
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1732,6 +1812,183 @@ function sessionIdOf(summary) {
 	return typeof id === "string" ? id : void 0;
 }
 /**
+* 内核在 prompt 准入里会因为「模型看不到图」拒收整条消息
+* （`MODEL_DOES_NOT_SUPPORT_IMAGES`）。手机端拿不到桌面 WebUI 那套
+* 「粘贴即落成临时文件、路径进输入框」的浏览器半边，所以图片在手机上
+* **直接发不出去** —— 而用户明明装了识图插件。
+*
+* 这里补上手机端缺的那一步，但**刻意不引用任何插件的 API**：
+* 判定用内核自己的 `llm.resolveModelInfo()`（与内核拒收时查的是同一份元数据），
+* 动作只是「图片落成文件 + 消息里给路径」—— 任何「按路径读图」的工具都能接手。
+* 哪天换插件、甚至不用插件，这段代码都不需要改。
+*
+* 三条保守原则（宁可退回原样、也不要自作聪明）：
+* 1. 元数据拿不到 / 解析不出模型 → **不动**（内核这时也不会拒，交给它）；
+* 2. 模型声明了 image → **不动**（原生图片能显示缩略图，别抢它的活）；
+* 3. 落盘失败 → **不动**（退回内核自己的报错，至少用户能看懂发生了什么）。
+*
+* 两个落点（按优先级）：
+* - **会话工作目录下的 `.dsh-images/`**（首选）：文件在用户的项目里，
+*   人和 agent 都找得到，也符合「产物放工作目录、别塞进 DSH 私有目录」；
+* - 解析不出工作目录时退回 DSH 目录（[DEFAULT_IMAGE_HANDOFF_DIR]）——
+*   宁可落到私有目录也不能让「发消息」本身失败。
+*/
+const HANDOFF_SUBDIR = ".dsh-images";
+const DEFAULT_IMAGE_HANDOFF_DIR = join(homedir(), ".dsh", "image-handoff");
+const IMAGE_EXTENSIONS = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/webp": "webp",
+	"image/gif": "gif",
+	"image/heic": "heic",
+	"image/heif": "heif",
+	"image/bmp": "bmp",
+	"image/avif": "avif"
+};
+/** 扩展名优先按声明的 mediaType，认不出再从魔数嗅，最后 .bin。 */
+function handoffExtension(mediaType, bytes) {
+	const declared = IMAGE_EXTENSIONS[mediaType.trim().toLowerCase()];
+	if (declared !== void 0) return declared;
+	if (bytes.length >= 8 && bytes[0] === 137 && bytes[1] === 80) return "png";
+	if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216) return "jpg";
+	if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") return "webp";
+	if (bytes.length >= 6 && bytes.toString("ascii", 0, 3) === "GIF") return "gif";
+	return "bin";
+}
+/**
+* 把一张内联图片写成文件，返回 `{ absolute, relative }`。
+*
+* 文件名用**内容哈希**：同一张图重复发不会堆副本（与内核附件存储同一思路），
+* 也让「同一路径 → 同一内容」对下游工具成立（可安全缓存）。
+* `relative` 是相对会话工作目录的短路径，给人看；`absolute` 给读图工具用。
+* 目录 0700、文件 0600：这些字节可能包含用户隐私。
+*/
+function writeHandoffFile(dir, workspace, mediaType, data) {
+	const bytes = Buffer.from(data, "base64");
+	if (bytes.length === 0) throw new Error("EMPTY_IMAGE");
+	mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const fileName = `${createHash("sha256").update(bytes).digest("hex")}.${handoffExtension(mediaType, bytes)}`;
+	const absolute = join(dir, fileName);
+	if (!existsSync(absolute)) writeFileSync(absolute, bytes, { mode: 384 });
+	return {
+		absolute,
+		relative: workspace !== void 0 && absolute.startsWith(workspace + "/") ? absolute.slice(workspace.length + 1) : fileName
+	};
+}
+/** 交接文件名只允许「内容哈希 + 图片扩展名」：挡住一切路径穿越。 */
+const HANDOFF_NAME = /^[0-9a-f]{64}\.(png|jpe?g|webp|gif|heic|heif|bmp|avif)$/i;
+const HANDOFF_MEDIA_TYPES = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	webp: "image/webp",
+	gif: "image/gif",
+	heic: "image/heic",
+	heif: "image/heif",
+	bmp: "image/bmp",
+	avif: "image/avif"
+};
+/**
+* 读出一张交接图片的字节（供手机端把它**显示**出来）。
+*
+* 只接受裸文件名，目录永远由「会话工作目录 + `.dsh-images`」（或兜底目录）推出，
+* 客户端给绝对路径也不认 —— 否则这条读文件的口子会变成任意文件读取。
+* 工作目录与 [writeHandoffFile] 用的是同一套解析，保证「写在哪、从哪读」。
+*/
+async function readHandoffImageFile(host, roots, fallbackDir, sessionId, name) {
+	const fileName = name.split(/[/\\]/).pop() ?? name;
+	const match = HANDOFF_NAME.exec(fileName);
+	if (match === null) throw new Error("BAD_HANDOFF_NAME");
+	const ext = (match[1] ?? "").toLowerCase();
+	const mediaType = HANDOFF_MEDIA_TYPES[ext] ?? "application/octet-stream";
+	const workspace = await sessionWorkspaceDir(host, roots, sessionId);
+	const target = [...workspace !== void 0 ? [join(workspace, HANDOFF_SUBDIR, fileName)] : [], join(fallbackDir, fileName)].find((candidate) => existsSync(candidate));
+	if (target === void 0) throw new Error("HANDOFF_IMAGE_NOT_FOUND");
+	return {
+		bytes: new Uint8Array(readFileSync(target)),
+		mediaType
+	};
+}
+/**
+* 解析会话当前的工作目录（绝对路径），冷会话也能用。
+*
+* 不走 live agent（冷会话没有 agent）：直接用 `sessionController.list()`
+* 里那条会话的 `cwd`（相对授权根的 wire 路径），再与数据库里的根拼出真实路径。
+* 解析不出来（没有授权根 / cwd 不在任何根下）就返回 undefined —— 交给上层兜底。
+*/
+async function sessionWorkspaceDir(host, roots, sessionId) {
+	if (roots.length === 0) return void 0;
+	const item = (await host.sessionController.list({}, new AbortController().signal)).items?.find((entry) => entry.sessionId === sessionId);
+	const cwd = typeof item?.cwd === "string" ? item.cwd : void 0;
+	if (cwd === void 0) return void 0;
+	for (const root of roots) {
+		const relative = wireRelative(root.realPath, cwd);
+		if (relative !== void 0) return join(root.realPath, relative);
+	}
+}
+/** 会话当前生效的模型（pending > lastUsed > 目录默认），取不到返回 undefined。 */
+async function currentModelSelection(host, sessionId) {
+	const selection = (await host.sessionController.projections({ sessionId }, new AbortController().signal))?.values?.["modelSelection"];
+	const catalog = await host.sessionController.modelCatalog();
+	const current = selection?.next ?? selection?.lastUsed ?? catalog.default;
+	const provider = current?.provider;
+	const model = current?.model;
+	if (typeof provider !== "string" || typeof model !== "string") return void 0;
+	return {
+		provider,
+		model
+	};
+}
+/**
+* 内核会不会因为「这个模型看不到图」拒收？判据与内核**逐字一致**：
+* `inputModalities` 已声明且不含 `image`。
+*
+* 元数据缺失（`undefined`）**不算**「确认看不到图」—— 内核在那种情况下也不拒，
+* 我们跟着不插手（拿不准就走原路）。
+*/
+async function modelIsConfirmedTextOnly(host, sessionId) {
+	const selection = await currentModelSelection(host, sessionId);
+	if (selection === void 0) return false;
+	const modalities = (await host.llm.resolveModelInfo(selection.provider, selection.model))?.inputModalities;
+	if (!Array.isArray(modalities)) return false;
+	return !modalities.includes("image");
+}
+/**
+* 需要交接时，把每个 `image` 部件换成**两行文本**；否则原样返回。
+*
+* 同一行路径要同时伺候两类读者：
+* - **给人看**（第一行）：图片序号、原始文件名、工作目录里的短路径；
+* - **给机器看**（第二行 `[Image: source: <绝对路径>]`）：这是读图技能明确
+*   识别的占位形状之一（带图片扩展名的绝对路径同样触发），任何按路径读图的
+*   工具都能接手，不出现任何具体插件名。
+*
+* 任何一步抛错都退回原内容：这个功能的失败**不该**把「发消息」本身弄坏。
+*/
+async function handoffImagesForTextOnlyModel(host, roots, fallbackDir, sessionId, content) {
+	if (!content.some((part) => part.type === "image")) return content;
+	try {
+		if (!await modelIsConfirmedTextOnly(host, sessionId)) return content;
+		const workspace = await sessionWorkspaceDir(host, roots, sessionId);
+		const dir = workspace !== void 0 ? join(workspace, HANDOFF_SUBDIR) : fallbackDir;
+		let index = 0;
+		return content.map((part) => {
+			if (part.type !== "image") return part;
+			index += 1;
+			const { absolute, relative } = writeHandoffFile(dir, workspace, part.mediaType, part.data);
+			const name = typeof part.name === "string" && part.name.trim() !== "" ? part.name.trim() : `图片 ${index}`;
+			return {
+				type: "text",
+				text: [`🖼️ 图片 ${index}「${name}」（当前模型不支持图片输入，已保存到工作目录 ${relative}；请先用读图工具打开下面那行的绝对路径，看清内容再回答）`, `[Image: source: ${absolute}]`].join("\n")
+			};
+		});
+	} catch {
+		return content;
+	}
+}
+/**
 * Build the `apiProxy` replacement out of 0.2.x host services.
 *
 * Every method keeps the old `{ rpcId, payload }` request shape and the old
@@ -1739,12 +1996,15 @@ function sessionIdOf(summary) {
 * `chat-adapter.ts` and `settings-adapter.ts` are written against.
 *
 * @param host - host services resolved from the plugin context.
+* @param host - host services resolved from the plugin context.
 * @returns a `SettingsApiProxy` (i.e. `DshApiProxy` plus the settings surfaces).
 */
-function createDsh02ApiProxy(host) {
+function createDsh02ApiProxy(host, options = {}) {
 	const mux = new FrameHub();
 	const hostFrames = new FrameHub();
-	const attachmentStore = optionalService(host, "attachments");
+	const imageHandoff = options.imageHandoff !== false;
+	const handoffRoots = options.handoffRoots ?? [];
+	const imageHandoffDir = options.imageHandoffDir ?? DEFAULT_IMAGE_HANDOFF_DIR;
 	const fileUploadService = optionalService(host, "fileUploads");
 	const approvals = new ApprovalBridge(host, mux);
 	approvals.attach();
@@ -1847,13 +2107,15 @@ function createDsh02ApiProxy(host) {
 			prompt: (request) => call(async () => {
 				const requestId = randomUUID();
 				const receiptIds = request.payload.content.filter((part) => part.type === "file").map((part) => part.receiptId);
+				const content = imageHandoff ? await handoffImagesForTextOnlyModel(host, handoffRoots, imageHandoffDir, request.payload.sessionId, request.payload.content) : request.payload.content;
 				const binding = receiptIds.length === 0 ? void 0 : await (async () => {
 					if (fileUploadService == null) throw new Error("FILE_UPLOADS_UNAVAILABLE: this DSH build provides no ctx.fileUploads service, so file attachments cannot be sent");
 					return fileUploadService.bindPrompt(await agentFor(request.payload.sessionId), receiptIds, requestId);
 				})();
 				await host.sessionController.prompt({
 					requestId,
-					...request.payload
+					...request.payload,
+					content
 				}, new AbortController().signal);
 				binding?.commit();
 				return { accepted: true };
@@ -1870,13 +2132,20 @@ function createDsh02ApiProxy(host) {
 				};
 			}),
 			readAttachment: (request) => call(async () => {
-				if (attachmentStore == null) throw new Error("ATTACHMENT_STORE_UNAVAILABLE: this DSH build provides no ctx.attachments service, so stored image bytes cannot be read");
-				const stored = await attachmentStore.readImage({ attachmentId: request.payload.attachmentId }, new AbortController().signal);
+				const { sessionId, attachmentId } = request.payload;
+				const value = await host.sessionController.attachment({
+					sessionId,
+					attachmentId
+				});
 				return {
-					bytes: stored.data,
-					mediaType: stored.ref.mediaType
+					bytes: new Uint8Array(Buffer.from(value.data, "base64")),
+					mediaType: value.attachment.mediaType
 				};
 			}),
+			readHandoffImage: (request) => call(async () => {
+				const { sessionId, name } = request.payload;
+				return readHandoffImageFile(host, handoffRoots, imageHandoffDir, sessionId, name);
+			}),
 			cancel: (request) => call(() => host.sessionController.cancel(request.payload)),
 			rename: (request) => call(() => host.sessionController.rename(request.payload)),
 			fork: (request) => call(() => host.sessionController.fork(request.payload)),
@@ -1888,7 +2157,7 @@ function createDsh02ApiProxy(host) {
 				const catalog = await host.sessionController.modelCatalog();
 				const selection = (await host.sessionController.projections({ sessionId }, new AbortController().signal))?.values?.["modelSelection"];
 				return {
-					current: selection?.pending ?? selection?.lastUsed ?? catalog.default,
+					current: selection?.next ?? selection?.lastUsed ?? catalog.default,
 					routable: Array.isArray(catalog.routableProviders) && catalog.routableProviders.length > 0,
 					groups: Array.isArray(catalog.groups) ? catalog.groups : [],
 					failures: Array.isArray(catalog.failures) ? catalog.failures.map((entry) => ({
@@ -3101,7 +3370,9 @@ var ApiRouter = class {
 		if (attachmentRoute !== null && method === "GET") {
 			this.options.auth.requireScope(principal, "files.read");
 			const attachmentId = decodeURIComponent(attachmentRoute[1]);
-			const { bytes, mediaType } = await this.options.chat.readAttachment(principal, attachmentId);
+			const sessionId = url.searchParams.get("sessionId")?.trim();
+			if (!sessionId) throw new ApiError(400, "BODY_INVALID", "sessionId query parameter is required.");
+			const { bytes, mediaType } = await this.options.chat.readAttachment(principal, sessionId, attachmentId);
 			res.statusCode = 200;
 			res.setHeader("Content-Type", mediaType);
 			res.setHeader("Content-Length", String(bytes.byteLength));
@@ -3109,6 +3380,19 @@ var ApiRouter = class {
 			res.end(Buffer.from(bytes));
 			return;
 		}
+		if (pathname === "/api/v1/image-handoff" && method === "GET") {
+			this.options.auth.requireScope(principal, "files.read");
+			const name = url.searchParams.get("name")?.trim();
+			const sessionId = url.searchParams.get("sessionId")?.trim();
+			if (!name || !sessionId) throw new ApiError(400, "BODY_INVALID", "name and sessionId query parameters are required.");
+			const { bytes, mediaType } = await this.options.chat.readHandoffImage(principal, sessionId, name);
+			res.statusCode = 200;
+			res.setHeader("Content-Type", mediaType);
+			res.setHeader("Content-Length", String(bytes.byteLength));
+			res.setHeader("Cache-Control", "private, max-age=3600");
+			res.end(Buffer.from(bytes));
+			return;
+		}
 		const attachmentsRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/attachments$/);
 		if (attachmentsRoute !== null && method === "POST") {
 			this.options.auth.requireScope(principal, "chat.write");
@@ -4365,7 +4649,13 @@ async function apply(ctx, config = {}) {
 	const events = new WorkspaceEventBus();
 	const auth = new AuthService(database);
 	const files = new FileService(database, (event) => events.emit(event));
-	const apiProxy = createDsh02ApiProxy(ctx);
+	const apiProxy = createDsh02ApiProxy(ctx, {
+		handoffRoots: database.listRoots().map((root) => ({
+			id: root.id,
+			realPath: root.realPath
+		})),
+		imageHandoffDir: path.join(dataDir, "image-handoff")
+	});
 	const chat = new DshChatAdapter(apiProxy, database, {
 		agents: ctx.agents,
 		commands: ctx.commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-bridge",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "Versioned REST bridge for DeepSeek Harness: remote access for trusted clients (chat, files, devices) plus a Phone-settings panel inside the DSH WebUI.",
   "type": "module",
   "packageManager": "pnpm@11.19.0",