dsh-cmtoken-oauth 1.0.3 → 1.4.0

package/README.md

@@ -7,8 +7,14 @@ DeepSeek Harness（DSH）插件：在 **DSH 设置页**内一键认证广东移
 - **一键认证**：基于 OAuth 2.0 Device Authorization Grant（RFC 8628）+ PKCE (S256)，扫码或输入用户码即可完成，无需配置脚本。
 - **内联二维码**：认证流程内置 QR 生成（零依赖），无需额外安装二维码工具。
 - **自动发现模型**：认证成功后自动拉取可用模型列表，写入 `llm-pi-ai` 的 `providers.cmtoken` 配置（merge，不影响其他 provider）。
+- **原生视觉**：视觉模型（Qwen3.8 27B / Qwen3.x / Kimi K2.x 非 code / MiniMax M3）写入配置时自动声明 `input: ["text","image"]` 模态，DSH 直接放行图片输入（经持久附件服务直达模型），粘贴/拖入图片即可用。
+- **粘贴/拖图转路径（普通模型直接收图）**：纯文本模型（如 deepseekv4-flash）贴图/拖图时，client 端拦截并把图片存到 `~/.dsh/cmtoken-pastes/`，`[Image: <路径>]` 直接进入输入框——不再弹「当前模型不支持图片」。识图延迟到模型按需调用 `cmtoken_read_image` 工具时完成，不看图不花识图调用；同一图片按内容哈希缓存路径。视觉模型不接管，保留原生缩略图体验。
+- **视觉回退工具**：注册 `cmtoken_read_image` 工具——任何模型把图片路径（本地路径或 http(s) URL）交给工具，host 侧自动选用优先级最高的视觉模型识图，返回结构化取证（概述 / 全文转写 / 版面 / 语义 / 不确定项）。无需外部识图服务，凭据与配额都在 cmtoken 体系内。
+- **可选包装路由（默认关闭）**：profile 插件 config 设 `visionRoute: true` 可注册 `cmtoken-vision` 分组——把纯文本模型镜像成声明图片输入的条目，贴图以真实图片气泡进入会话、请求时自动转证据文本。需要图片气泡原样展示的会话可开启。
+- **自动配置上下文**：按模型名称关键词自动匹配各模型的上下文与最大输出长度（DeepSeek V4 / MiniMax M3 / Qwen / GLM / Kimi / MiniMax 2.x / hy 等），无需手动填写。
 - **安全存储**：token 存入 DSH 凭据服务（OS keyring / env），不落盘明文。
 - **自动续期 / 注销**：令牌临近过期自动 refresh；可随时注销清空凭据。
+- **订购算力豆套餐**：设置页内一键跳转广东移动 H5 订购页，直达算力豆套餐购买。
 
 零第三方运行时依赖（仅使用 Node 内置模块）。
 
@@ -33,8 +39,10 @@ dsh plugin --profile web add github:your-username/dsh-cmtoken-oauth
 
 1. 打开 DSH Web → 设置（左下角齿轮）→ 左侧导航选择「**cmtoken 认证**」。
 2. 点击「开始一键认证」→ 用手机扫描二维码（或打开链接输入用户码），在广东移动 IDaaS 页面确认授权。
-3. 插件自动完成：发现模型 → 写入 `llm-pi-ai.providers.cmtoken` → 保存凭据。
-4. 在 DSH 的模型选择器中选择 cmtoken 模型即可使用。
+3. 插件自动完成：发现模型 → 按名称配置各模型上下文 → 写入 `llm-pi-ai.providers.cmtoken` → 保存凭据。
+4. 套餐不足时，点设置页里的「**订购算力豆套餐**」跳转到广东移动 H5 订购页购买。
+5. 在 DSH 的模型选择器中选择 cmtoken 模型即可使用。
+6. 视觉，日常零配置：**任何 cmtoken 模型直接粘贴图片**——视觉模型（Qwen3.8 / Qwen3.x / Kimi K2.x / MiniMax M3）原生收图；纯文本模型贴图时自动经视觉模型识读为文字证据进入输入框（首次粘贴前聚焦一次输入框可预热判定）。也可在任何模型下把图片路径给助手调用 `cmtoken_read_image` 工具。
 
 ## 数据与配置
 
@@ -45,12 +53,17 @@ dsh plugin --profile web add github:your-username/dsh-cmtoken-oauth
 | 模型发现端点 | `GET https://maas.gd.chinamobile.com:36007/ai/uifm/open/v1/models` |
 | 凭据引用 | `CMTOKEN_API_KEY` / `CMTOKEN_REFRESH_TOKEN` / `CMTOKEN_EXPIRES` |
 | 写配置 | `llm-pi-ai` 设置 namespace 的 `providers.cmtoken`（merge，不覆盖其他 provider） |
+| 视觉模态 | 模型写入时声明 `input`：qwen38 / qwen3.x / kimi k2.x（非 code）/ minimax-m3 → `["text","image"]`，其余 `["text"]` |
+| 粘贴转路径 | `GET/POST /cmtoken-oauth/paste`（client 拦截纯文本模型贴图/拖图，host 落盘 `~/.dsh/cmtoken-pastes/` 返回路径；7 天自动清理） |
+| 视觉优先级 | qwen38 > qwen3.x > kimi k2.x（非 code）> minimax-m3；识图走 `{baseURL}/chat/completions` |
+| 视觉回退工具 | `cmtoken_read_image` 工具；输入本地路径或 http(s) URL |
+| 包装路由（可选） | config `visionRoute: true` 启用 `cmtoken-vision` 分组（默认关闭） |
 
 ## 开发
 
 ```text
-lib/index.js    host：OAuth 核心（PKCE / 设备码 / 轮询 / 刷新 / 模型发现）+ RPC
-lib/client.js   web：设置页「cmtoken 认证」向导（二维码 + 轮询 + 完成）
+lib/index.js    host：OAuth 核心（PKCE / 设备码 / 轮询 / 刷新 / 模型发现）+ RPC + 粘贴识图路由 + cmtoken_read_image 工具 + 可选 cmtoken-vision 包装路由
+lib/client.js   web：设置页「cmtoken 认证」向导（视觉模型标 👁）+ 粘贴识图拦截
 lib/qr-core.cjs 内联 QR 编码器（输出 SVG）
 ```
 

package/lib/client.js

@@ -12,6 +12,7 @@ window.__ModuleLoader__.load({
 
 		// ==================== 工具 ====================
 		const CHANNEL = "/cmtoken-oauth";
+		const ORDER_URL = "https://wap.gd.10086.cn/ech/h5/token-prduct/index.html";
 		function unwrap(r) { if (r && r.ok) return r.value; throw new Error(r && r.error ? r.error.message : "未知错误"); }
 
 		// ==================== 样式 ====================
@@ -142,10 +143,13 @@ window.__ModuleLoader__.load({
 					statusCard,
 					react.createElement("div", { className: "co-ok" }, "✅ 认证成功！已发现 " + models.length + " 个模型并写入配置。"),
 					models.length ? react.createElement("div", null,
-						react.createElement("div", { className: "co-hint", style: { marginBottom: 6 } }, "可用模型："),
-						react.createElement("div", { className: "co-models" }, models.map((m, i) => react.createElement(Pill, { key: i }, m.name || m.id)))
+						react.createElement("div", { className: "co-hint", style: { marginBottom: 6 } }, "可用模型（👁 支持视觉，可直接收图）："),
+						react.createElement("div", { className: "co-models" }, models.map((m, i) => {
+							const vision = Array.isArray(m.input) && m.input.indexOf("image") !== -1;
+							return react.createElement(Pill, { key: i }, (m.name || m.id) + (vision ? " 👁" : ""));
+						}))
 					) : null,
-					react.createElement("p", null, "现在可以在 DSH 的模型选择器里选用 cmtoken 模型了。")
+					react.createElement("p", null, "现在可以在 DSH 的模型选择器里选用 cmtoken 模型了；非视觉模型可通过 cmtoken_read_image 工具读图。")
 				);
 			}
 
@@ -166,12 +170,186 @@ window.__ModuleLoader__.load({
 					: react.createElement("p", null, "一键认证：点击下方按钮，用手机扫描二维码即可完成广东移动 MaaS 授权（无需手动填写 API Key）。"),
 				react.createElement("div", { className: "co-row" },
 					react.createElement(Button, { variant: "primary", size: "md", onClick: begin }, "开始一键认证"),
+					react.createElement(Button, { variant: "outline", size: "md", onClick: () => window.open(ORDER_URL, "_blank", "noopener,noreferrer") }, "订购算力豆套餐"),
 					status && status.hasRefresh && status.expired ? react.createElement(Button, { variant: "outline", size: "md", onClick: doRefresh }, "刷新令牌") : null
 				),
 				error ? react.createElement("div", { className: "co-err" }, error) : null
 			);
 		}
 
+		// ==================== 粘贴识图（纯文本模型贴图即用） ====================
+		// 捕获阶段 paste 监听先于 composer 自身处理：剪贴板带图片且当前模型是
+		// 纯文本 cmtoken 模型（host 判定）时，抑制默认 intake（否则入口即被
+		// 「模型不支持图片」拒绝），把字节 POST 给 host 的识图路由，返回的
+		// 证据文本直接插入输入框。视觉模型不接管，保留原生缩略图体验。
+		function imageFilesOf(event) {
+			const items = event.clipboardData && event.clipboardData.items;
+			if (!items) return [];
+			const files = [];
+			for (let i = 0; i < items.length; i++) {
+				const item = items[i];
+				if (item.kind !== "file") continue;
+				const file = item.getAsFile();
+				if (file && /^image\//.test(file.type)) files.push(file);
+			}
+			return files;
+		}
+
+		function insertText(target, text) {
+			let el = target && (target.tagName === "TEXTAREA" || target.tagName === "INPUT") ? target : document.activeElement;
+			if (!el || (el.tagName !== "TEXTAREA" && el.tagName !== "INPUT")) return;
+			el.focus();
+			let inserted = false;
+			try { inserted = document.execCommand("insertText", false, text); } catch { inserted = false; }
+			if (!inserted) {
+				const proto = el.tagName === "TEXTAREA" ? window.HTMLTextAreaElement.prototype : window.HTMLInputElement.prototype;
+				const setter = Object.getOwnPropertyDescriptor(proto, "value").set;
+				setter.call(el, el.value + text);
+				el.dispatchEvent(new Event("input", { bubbles: true }));
+			}
+		}
+
+		function currentModelLabel() {
+			// aria-label 只是静态「选择模型」，不含当前模型名；模型名在按钮内部文本里，
+			// 拼成「选择模型，<模型名>」交给 host 解析（host 端按逗号取尾 + 剥「当前」）
+			const buttons = document.querySelectorAll("button");
+			for (let i = 0; i < buttons.length; i++) {
+				const label = buttons[i].getAttribute("aria-label") || "";
+				if (!/选择模型|select model|current model/i.test(label)) continue;
+				const text = (buttons[i].textContent || "").trim();
+				return text ? label + "，" + text : label;
+			}
+			return "";
+		}
+
+		function findComposer() {
+			const el = document.activeElement;
+			if (el && (el.tagName === "TEXTAREA" || el.tagName === "INPUT")) return el;
+			return document.querySelector("textarea") || el;
+		}
+
+		// 接管判定缓存：同一标签 60 秒内不重复询问；host 404（路由未注册）则彻底停用。
+		// 决策策略「零报错」：粘贴带图先同步拦截（纯文本模型吃到默认拒绝就是这次要
+		// 消灭的体验），异步拿到判定后——纯文本模型转证据文本；视觉模型把带原图
+		// 的粘贴事件重派给默认流程（标记 __cmtokenRevived 防循环），保留原生缩略图。
+		let pasteRouteAlive = true;
+		let pasteBusy = false;
+		const pasteVerdicts = {};
+		const PASTE_VERDICT_TTL_MS = 60000;
+
+		function verdictPromise(label) {
+			if (!label) return Promise.resolve(false);
+			const hit = pasteVerdicts[label];
+			if (hit && Date.now() - hit.at < PASTE_VERDICT_TTL_MS) return Promise.resolve(hit.takeover);
+			return fetch("/cmtoken-oauth/paste?model=" + encodeURIComponent(label))
+				.then((res) => {
+					if (res.status === 404) { pasteRouteAlive = false; return false; }
+					if (!res.ok) return false;
+					return res.json().then((body) => {
+						pasteVerdicts[label] = { at: Date.now(), takeover: !!body.takeover };
+						return !!body.takeover;
+					});
+				})
+				.catch(() => false);
+		}
+
+		function savePaste(file) {
+			return file.arrayBuffer()
+				.then((buffer) => fetch("/cmtoken-oauth/paste", { method: "POST", body: buffer }))
+				.then((res) => res.json().then((body) => {
+					if (!res.ok) throw new Error(body.error || ("保存图片失败 (" + res.status + ")"));
+					return body.path;
+				}));
+		}
+
+		// 图片插入输入框的形态：路径行。模型看到路径会用 cmtoken_read_image 工具按需识读。
+		function imageLine(path) {
+			return "[Image: " + path + "]\n";
+		}
+
+		function onPaste(event) {
+			if (!pasteRouteAlive || pasteBusy || event.__cmtokenRevived || !event.clipboardData) return;
+			const files = imageFilesOf(event);
+			if (files.length === 0) return;
+			const label = currentModelLabel();
+			if (!label) return;
+			// 同步拦截默认 intake（取消默认行为 + 阻断其他监听）
+			event.preventDefault();
+			event.stopImmediatePropagation();
+			pasteBusy = true;
+			const el = findComposer();
+			verdictPromise(label).then((takeover) => {
+				if (!takeover) {
+					// 视觉模型/未知模型：原样重派，走原生图片附件流程
+					const dt = new DataTransfer();
+					for (const file of files) dt.items.add(file);
+					const revived = new ClipboardEvent("paste", { clipboardData: dt, bubbles: true, cancelable: true });
+					revived.__cmtokenRevived = true;
+					(event.target && event.target.dispatchEvent ? event.target : document).dispatchEvent(revived);
+					return;
+				}
+				// 纯文本模型：存文件 → 路径插入输入框（识图交给 cmtoken_read_image 工具按需完成）
+				let chain = Promise.resolve();
+				for (const file of files) {
+					chain = chain.then(() => savePaste(file).then((path) => {
+						insertText(el, imageLine(path));
+					}).catch((e) => {
+						insertText(el, "[图片保存失败：" + String(e && e.message ? e.message : e) + "]\n");
+					}));
+				}
+				return chain;
+			}).finally(() => { pasteBusy = false; });
+		}
+
+		// 拖拽放图同样接管：附件栏的 drop 监听在 document 冒泡阶段，
+		// 我们的 capture 拦截先到；不接管时重派原事件走原生流程。
+		function onDrop(event) {
+			if (!pasteRouteAlive || pasteBusy || event.__cmtokenRevived || !event.dataTransfer) return;
+			let dtFiles = [];
+			try { dtFiles = Array.from(event.dataTransfer.files || []).filter((f) => /^image\//.test(f.type)); } catch (e) { dtFiles = []; }
+			if (dtFiles.length === 0) return;
+			const label = currentModelLabel();
+			if (!label) return;
+			event.preventDefault();
+			event.stopImmediatePropagation();
+			// 附件栏的 drop 监听被阻断后，其拖拽状态机收不到 reset；它在 window 上
+			// 还挂了 dragend → reset，手动派发一个让「拖动图片到此处」叠加层立即收起
+			try { window.dispatchEvent(new Event("dragend")); } catch (e) { /* 忽略 */ }
+			pasteBusy = true;
+			const el = findComposer();
+			verdictPromise(label).then((takeover) => {
+				if (!takeover) {
+					const dt = new DataTransfer();
+					for (const f of dtFiles) dt.items.add(f);
+					const revived = new DragEvent("drop", { dataTransfer: dt, bubbles: true, cancelable: true });
+					revived.__cmtokenRevived = true;
+					(event.target && event.target.dispatchEvent ? event.target : document).dispatchEvent(revived);
+					return;
+				}
+				let chain = Promise.resolve();
+				for (const file of dtFiles) {
+					chain = chain.then(() => savePaste(file).then((path) => {
+						insertText(el, imageLine(path));
+					}).catch((e) => {
+						insertText(el, "[图片保存失败：" + String(e && e.message ? e.message : e) + "]\n");
+					}));
+				}
+				return chain;
+			}).finally(() => { pasteBusy = false; });
+		}
+
+		// composer 聚焦时预取判定，粘贴时少等一次网络往返
+		function onFocusIn() {
+			if (pasteRouteAlive) verdictPromise(currentModelLabel());
+		}
+
+		if (typeof document !== "undefined" && !window.__cmtokenPasteHook) {
+			window.__cmtokenPasteHook = true;
+			document.addEventListener("paste", onPaste, true);
+			document.addEventListener("drop", onDrop, true);
+			document.addEventListener("focusin", onFocusIn, true);
+		}
+
 		// ==================== 插件主体 ====================
 		const NS = "cmtoken-oauth";
 		const zh = { "nav": "cmtoken 认证" };

package/lib/index.js

@@ -5,6 +5,8 @@
 // 写入 llm-pi-ai provider 配置 + 凭据（OS keyring / env）。
 // ============================================================
 import { randomBytes, randomUUID, createHash } from 'node:crypto';
+import { readFile, writeFile, mkdir, readdir, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
 import os from 'node:os';
 import { createRequire } from 'node:module';
 import z from '@deepseek-ai/schemastery';
@@ -15,7 +17,7 @@ const require2 = createRequire(import.meta.url);
 const { qrSvg } = require2('./qr-core.cjs');
 
 export const name = 'dsh-cmtoken-oauth';
-export const inject = ['connection', 'settings', 'credentials'];
+export const inject = ['connection', 'settings', 'credentials', 'tools', 'llm', 'attachments'];
 
 export const Config = z.object({});
 
@@ -129,6 +131,61 @@ async function refreshToken(refresh) {
   };
 }
 
+// 根据模型名称关键词匹配「输入（上下文）/ 输出（最大生成）」规格。
+// 规格优先级：已知关键词匹配 > 发现接口自带值 > 通用默认值。
+const MODEL_SPECS = [
+  // DeepSeek V4 系列：deepseek-v4-pro / deepseek-v4-flash
+  { match: (n) => n.includes('deepseek') && n.includes('v4'), contextWindow: 1_048_576, maxTokens: 393_216 },
+  // MiniMax-M3（支持图片）
+  { match: (n) => n.includes('minimax') && /m3/.test(n), contextWindow: 1_048_576, maxTokens: 131_072 },
+  // Qwen 开源系列：qwen36-35b / qwen38-27b（支持图片）
+  { match: (n) => n.includes('qwen36') || n.includes('qwen38'), contextWindow: 262_144, maxTokens: 65_536 },
+  // Qwen 闭源系列：Qwen3.x-flash / plus / max（支持图片）
+  { match: (n) => n.includes('qwen'), contextWindow: 1_048_576, maxTokens: 65_536 },
+  // 智谱 GLM：glm-5.2 / glm-5.3
+  { match: (n) => n.includes('glm'), contextWindow: 1_048_576, maxTokens: 131_072 },
+  // MiniMax 2.x 系列：M2.7-highspeed / MiniMax M2.5
+  { match: (n) => n.startsWith('m2') || (n.includes('minimax') && /m2/.test(n)), contextWindow: 204_800, maxTokens: 65_536 },
+  // hy3 / hy3-preview 等
+  { match: (n) => /hy/.test(n), contextWindow: 262_144, maxTokens: 65_536 },
+];
+
+const DEFAULT_MODEL_SPEC = { contextWindow: 262_144, maxTokens: 65_536 };
+
+function modelSpecFor(id) {
+  const n = String(id).toLowerCase().replace(/[-_\s.]+/g, '');
+  for (const spec of MODEL_SPECS) {
+    if (spec.match(n)) return spec;
+  }
+  return DEFAULT_MODEL_SPEC;
+}
+
+// ---------------- 视觉（图片）能力判定与回退优先级 ----------------
+// 视觉模型优先级（值越小越优先，0 表示不支持图片）：
+//   1) Qwen3.8 27B（qwen38-27b 等）—— 最优先
+//   2) Qwen3.x 系列（qwen3.6、qwen3-plus/flash/max 等）
+//   3) Kimi K2.x 非 code 系列（kimi-k2.5 / kimi-k2.6，原生多模态）
+//   4) MiniMax M3（minimax-m3 等）
+function visionRank(id) {
+  const n = String(id).toLowerCase().replace(/[-_\s.]+/g, '');
+  if (n.includes('qwen38')) return 1; // Qwen3.8 27B
+  if (n.includes('qwen3')) return 2; // Qwen3.6 / Qwen3.x 系列
+  if (n.includes('kimik2') && !n.includes('code')) return 3; // kimi-k2.5 / k2.x（非 code，原生多模态）
+  if (n.includes('minimax') && /m3/.test(n)) return 4; // MiniMax M3
+  return 0;
+}
+
+function supportsVision(id) {
+  return visionRank(id) > 0;
+}
+
+// 模型在 llm-pi-ai 配置里的 input 模态；视觉模型声明 ['text','image']，纯文本声明 ['text']。
+// DSH（dsh-llm-pi-ai）按该声明决定图片准入：缺失按目录默认（通常纯文本），图片请求会被
+// 以 UNSUPPORTED_CONTENT 拒绝，故必须显式声明而非省略。
+function modelInputModalities(id) {
+  return supportsVision(id) ? ['text', 'image'] : ['text'];
+}
+
 async function fetchModels(access, discoveryUrl) {
   const res = await fetch(discoveryUrl || DISCOVERY_URL, {
     signal: AbortSignal.timeout(15_000),
@@ -143,12 +200,16 @@ async function fetchModels(access, discoveryUrl) {
   }
   const json = await res.json();
   const list = Array.isArray(json.models) ? json.models : Array.isArray(json.data) ? json.data : [];
-  return list.map((m) => ({
-    id: m.id,
-    name: m.name ?? m.id,
-    contextWindow: m.contextWindow ?? 192_000,
-    maxTokens: m.maxTokens ?? 8192,
-  }));
+  return list.map((m) => {
+    // 已知模型按名称关键词配置最大上下文；其余回退到发现接口值或通用默认
+    const spec = modelSpecFor(m.id);
+    return {
+      id: m.id,
+      name: m.name ?? m.id,
+      contextWindow: spec.contextWindow,
+      maxTokens: spec.maxTokens,
+    };
+  });
 }
 
 function errorResult(e) {
@@ -207,7 +268,15 @@ function registerRpc(ctx) {
             models = [{ id: 'deepseekv4-flash', name: 'deepseekv4-flash', contextWindow: 192000, maxTokens: 8192 }];
           }
           await writeConfigAndCreds(ctx, token, models);
-          return { ok: true, value: { status: 'ok', models, baseURL: token.resourceUrl || DEFAULT_API_BASE } };
+          return {
+            ok: true,
+            value: {
+              status: 'ok',
+              // input 模态一并返回，client 用它给视觉模型打标
+              models: models.map((m) => ({ ...m, input: m.input ?? modelInputModalities(m.id) })),
+              baseURL: token.resourceUrl || DEFAULT_API_BASE,
+            },
+          };
         }
 
         // ---- 认证状态 ----
@@ -273,7 +342,15 @@ async function writeConfigAndCreds(ctx, token, models) {
         apiKeyEnv: API_KEY_ENV,
         api: 'openai-completions',
         baseURL: token.resourceUrl || DEFAULT_API_BASE,
-        models: models.map((m) => ({ id: m.id, name: m.name, contextWindow: m.contextWindow, maxTokens: m.maxTokens })),
+        models: models.map((m) => ({
+          id: m.id,
+          name: m.name,
+          contextWindow: m.contextWindow,
+          maxTokens: m.maxTokens,
+          // input 模态显式声明：视觉模型 ['text','image']，纯文本 ['text']。
+          // 声明后 DSH 原生放行图片（经持久附件服务直达模型），缺失则一律拒绝。
+          input: m.input ?? modelInputModalities(m.id),
+        })),
       },
     },
   };
@@ -333,18 +410,594 @@ function startAutoRefresh(ctx) {
   return () => clearInterval(timer);
 }
 
+// ---------------- 视觉回退：cmtoken_read_image 工具 ----------------
+// DSH 的图片准入以模型声明的 input 模态为准：文本模型收图直接报 UNSUPPORTED_CONTENT，
+// rc8 没有原生的"改投视觉模型"路由。本工具补上这条通路：任何在用模型把图片路径交给
+// 工具，host 侧按优先级（qwen38 > qwen3.x > minimax-m3）选 cmtoken 视觉模型完成识读，
+// 返回结构化取证结果——纯文本模型由此获得视觉。与 modlens 的外置识图引擎不同，
+// 引擎就是 cmtoken 自己的模型，凭据/配额都在本插件体系内，零外部依赖。
+
+const VISION_TOOL_NAME = 'cmtoken_read_image';
+const VISION_TOOL_TIMEOUT_MS = 180_000;
+const VISION_MAX_IMAGE_BYTES = 15 * 1024 * 1024;
+
+// 魔数签名：只放行 MaaS 通道常见的四种光栅格式，其余（heic/bmp 等）明确报错而非让服务端猜
+const MEDIA_SIGNATURES = [
+  { type: 'image/png', match: (b) => b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 },
+  { type: 'image/jpeg', match: (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
+  { type: 'image/gif', match: (b) => b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38 },
+  { type: 'image/webp', match: (b) => b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 && b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50 },
+];
+
+function detectMediaType(bytes) {
+  for (const sig of MEDIA_SIGNATURES) {
+    if (bytes.length >= 12 && sig.match(bytes)) return sig.type;
+  }
+  return undefined;
+}
+
+const EVIDENCE_PROMPT = [
+  '你是图像取证助手。请仔细阅读这张图片，输出严格的 JSON（不要 markdown 代码块、不要任何多余文字），字段如下：',
+  '{"summary":"一两句话概述图片内容","ocr_full_text":"图中所有可读文字的完整转写，保持阅读顺序，没有文字则为空字符串","layout":[{"type":"区域类型，如 title/paragraph/list/table/chart/form/code/button","reading_order":1,"text":"该区域文字或内容摘要"}],"semantics":{"scene":"场景描述","entities":[{"name":"实体名","type":"类型"}]},"uncertainty":["看不清或不确定的地方，没有则为空数组"]}',
+  '只输出 JSON 本身。',
+].join('\n');
+
+// 工具输出 schema：rc8 的 tools.register 强制要求 output { schema, render }，
+// 缺 output 会在注册时抛 TypeError（工具静默不生效）。形状对齐 EVIDENCE_PROMPT 的字段，
+// 外层多一个 model（实际识图的模型 id）。
+const VISION_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    model: { type: 'string', description: '实际完成识图的 cmtoken 视觉模型 id' },
+    summary: { type: 'string' },
+    ocr_full_text: { type: 'string' },
+    layout: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          type: { type: 'string' },
+          reading_order: { type: 'number' },
+          text: { type: 'string' },
+        },
+        required: ['type', 'reading_order', 'text'],
+      },
+    },
+    semantics: {
+      type: 'object',
+      properties: {
+        scene: { type: 'string' },
+        entities: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: { name: { type: 'string' }, type: { type: 'string' } },
+            required: ['name', 'type'],
+          },
+        },
+      },
+      required: ['scene'],
+    },
+    uncertainty: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['model', 'summary'],
+};
+
+/** 取证结果 → 可读多行文本（工具 render 与视觉回退 provider 共用）。 */
+function evidenceTextLines(value) {
+  const v = value ?? {};
+  const lines = [];
+  lines.push(`识图模型：${v.model ?? '(unknown)'}`);
+  lines.push(`概述：${v.summary ?? ''}`);
+  if (typeof v.ocr_full_text === 'string' && v.ocr_full_text !== '') {
+    lines.push(`全文转写：\n${v.ocr_full_text}`);
+  }
+  if (Array.isArray(v.layout) && v.layout.length > 0) {
+    lines.push('版面：');
+    for (const r of [...v.layout].sort((a, b) => (a?.reading_order ?? 0) - (b?.reading_order ?? 0))) {
+      lines.push(`  [${r?.type ?? '?'}] ${r?.text ?? ''}`);
+    }
+  }
+  const scene = v.semantics?.scene;
+  if (typeof scene === 'string' && scene !== '') lines.push(`场景：${scene}`);
+  const entities = v.semantics?.entities;
+  if (Array.isArray(entities) && entities.length > 0) {
+    lines.push(`实体：${entities.map((e) => `${e?.name ?? '?'}(${e?.type ?? '?'})`).join('、')}`);
+  }
+  if (Array.isArray(v.uncertainty) && v.uncertainty.length > 0) {
+    lines.push(`不确定：${v.uncertainty.join('；')}`);
+  }
+  return lines.join('\n');
+}
+
+/** 工具结果 → 会话里的可读文本块（对齐 rc8 render 契约：返回 content 块数组）。 */
+function renderEvidence(_args, value) {
+  return [{ type: 'text', text: evidenceTextLines(value) }];
+}
+
+/** 从已认证写入的 llm-pi-ai 配置里选出优先级最高的视觉模型；未认证返回 undefined。 */
+function resolveVisionModel(ctx) {
+  const section = ctx.settings?.get?.(settingsNamespace('llm-pi-ai'));
+  const models = section?.providers?.cmtoken?.models ?? [];
+  let best;
+  for (const m of models) {
+    const rank = visionRank(m.id);
+    if (rank > 0 && (!best || rank < best.rank)) best = { rank, id: m.id };
+  }
+  return best?.id;
+}
+
+/** 读取图片字节：http(s) URL 或本地路径。 */
+async function loadImageBytes(source, signal) {
+  if (/^https?:\/\//i.test(source)) {
+    const res = await fetch(source, { signal, headers: { Accept: 'image/*' } });
+    if (!res.ok) throw new Error(`下载图片失败 HTTP ${res.status}`);
+    return new Uint8Array(await res.arrayBuffer());
+  }
+  try {
+    return new Uint8Array(await readFile(source));
+  } catch (e) {
+    throw new Error(`读取图片文件失败: ${e?.code ?? e?.message ?? e}`);
+  }
+}
+
+/** 视觉模型输出 → 结构化取证；JSON 解析失败时整段文本降级为 summary。 */
+function parseEvidence(content) {
+  const raw = String(content ?? '').trim();
+  const fenced = raw.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/);
+  const candidate = fenced ? fenced[1] : raw;
+  const start = candidate.indexOf('{');
+  const end = candidate.lastIndexOf('}');
+  if (start >= 0 && end > start) {
+    try {
+      const parsed = JSON.parse(candidate.slice(start, end + 1));
+      if (parsed && typeof parsed === 'object') return parsed;
+    } catch { /* 降级为纯文本 */ }
+  }
+  return { summary: raw };
+}
+
+/** 调用 cmtoken 视觉模型识图（OpenAI 兼容 chat completions + data URI）。 */
+async function describeImage({ baseURL, apiKey, model, dataUri, focus, signal }) {
+  let res;
+  try {
+    res = await fetch(`${baseURL.replace(/\/+$/, '')}/chat/completions`, {
+      method: 'POST',
+      signal,
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', Authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify({
+        model,
+        messages: [{
+          role: 'user',
+          content: [
+            { type: 'text', text: focus ? `${EVIDENCE_PROMPT}\n重点关注：${focus}` : EVIDENCE_PROMPT },
+            { type: 'image_url', image_url: { url: dataUri } },
+          ],
+        }],
+        max_tokens: 4096,
+      }),
+    });
+  } catch (e) {
+    if (e?.name === 'TimeoutError' || e?.name === 'AbortError') throw new Error('视觉模型识图超时/已取消');
+    throw new Error(`视觉模型请求失败: ${e?.message ?? e}`);
+  }
+  if (!res.ok) {
+    const text = (await res.text().catch(() => '')).slice(0, 300);
+    if (res.status === 401) throw new Error('cmtoken 访问令牌无效，请在设置 → cmtoken 认证里重新认证');
+    if (res.status === 403 && /订阅套餐|订阅已过期|余额不足/.test(text)) throw new Error('订阅错误：' + text);
+    throw new Error(`视觉模型识图失败 ${res.status}: ${text}`);
+  }
+  const json = await res.json().catch(() => undefined);
+  const content = json?.choices?.[0]?.message?.content;
+  if (typeof content !== 'string' || content.trim() === '') {
+    throw new Error('视觉模型未返回识图内容' + (json?.error ? `: ${JSON.stringify(json.error).slice(0, 200)}` : ''));
+  }
+  return parseEvidence(content);
+}
+
+function registerVisionTool(ctx) {
+  const tool = {
+    name: VISION_TOOL_NAME,
+    description:
+      '通过 cmtoken 视觉模型读取图片。当对话中出现当前模型无法查看的图片时使用，典型形态是 [Image: <本地路径>] 行（粘贴/拖入的图片由插件自动落盘）或裸的本地绝对路径、http(s) URL：截图、照片、图表、扫描件等。返回结构化取证结果（summary、ocr_full_text、layout、semantics、uncertainty），请引用证据而不是猜测。需要已完成 cmtoken 一键认证。',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '图片的本地绝对路径或 http(s) URL' },
+        prompt: { type: 'string', description: '可选的额外关注点（如"重点看坐标轴标签"）' },
+      },
+      required: ['path'],
+    },
+    timeoutMs: VISION_TOOL_TIMEOUT_MS,
+    isConcurrencySafe: () => true,
+    output: {
+      schema: VISION_OUTPUT_SCHEMA,
+      render: renderEvidence,
+    },
+    async execute(args, exec) {
+      const source = typeof args?.path === 'string' ? args.path.trim() : '';
+      if (!source) throw new Error(`${VISION_TOOL_NAME} 需要非空字符串 "path"（本地路径或 http(s) URL）`);
+
+      const model = resolveVisionModel(ctx);
+      if (!model) throw new Error('cmtoken 未配置视觉模型：请先在 DSH 设置 → cmtoken 认证完成一键认证');
+
+      // 识图前先按需刷新令牌（复用自动续期逻辑），避免用过期 access 调用
+      await autoRefresh(ctx).catch(() => {});
+      const key = await ctx.credentials?.resolve(credentialRef(API_KEY_ENV));
+      if (!key) throw new Error('cmtoken 访问令牌不可用：请先在 DSH 设置 → cmtoken 认证完成一键认证');
+
+      const bytes = await loadImageBytes(source, exec?.signal);
+      if (bytes.length === 0) throw new Error('图片内容为空');
+      if (bytes.length > VISION_MAX_IMAGE_BYTES) {
+        throw new Error(`图片过大（${(bytes.length / 1048576).toFixed(1)}MB），上限 ${VISION_MAX_IMAGE_BYTES / 1048576}MB`);
+      }
+      const mediaType = detectMediaType(bytes);
+      if (!mediaType) throw new Error('不支持的图片格式（支持 PNG / JPEG / GIF / WebP）');
+
+      const signals = [AbortSignal.timeout(VISION_TOOL_TIMEOUT_MS)];
+      if (exec?.signal) signals.push(exec.signal);
+      const baseURL = ctx.settings?.get?.(settingsNamespace('llm-pi-ai'))?.providers?.cmtoken?.baseURL || DEFAULT_API_BASE;
+      const evidence = await describeImage({
+        baseURL,
+        apiKey: key.value,
+        model,
+        dataUri: `data:${mediaType};base64,${Buffer.from(bytes).toString('base64')}`,
+        focus: typeof args.prompt === 'string' && args.prompt.trim() ? args.prompt.trim() : undefined,
+        signal: AbortSignal.any(signals),
+      });
+      // 标注实际使用的模型，便于调用方区分证据来源与核算配额
+      return { model, ...evidence };
+    },
+  };
+  try {
+    ctx.tools.register(tool);
+    ctx.logger?.info?.(`[cmtoken-oauth] 视觉回退工具 ${VISION_TOOL_NAME} 已注册`);
+  } catch (e) {
+    // 注册失败（服务面变化/重名）只降级报错，不影响认证主功能
+    ctx.logger?.error?.(`[cmtoken-oauth] ${VISION_TOOL_NAME} 注册失败: ${String(e?.message ?? e)}`);
+  }
+}
+
+// ---------------- 视觉回退 provider（cmtoken-vision 包装路由） ----------------
+// DSH 的图片准入以所选模型的 input 模态为准：纯文本模型在入口即被拒，
+// 贴图永远到不了任何工具。本包装注册一个新 provider 路由 cmtoken-vision，
+// 把 cmtoken 的纯文本模型镜像成声明图片输入的条目（名称带「(视觉回退)」）；
+// 请求时把消息里的图片块交给自家视觉模型识读（qwen38 > qwen3.x > minimax-m3），
+// 以文本证据块替换后再委托上游文本模型——会话日志保留真实图片块（UI 原样显示），
+// 仅出网请求携带证据文本。原生视觉模型不包装（自己能收图，回退反而降级）。
+
+const VISION_PROVIDER_ID = 'cmtoken-vision';
+const VISION_PROVIDER_NAME = 'cmtoken (视觉回退)';
+const UPSTREAM_PROVIDER = 'cmtoken';
+const EVIDENCE_CACHE_MAX = 32;
+const EVIDENCE_FAILURE_COOLDOWN_MS = 60_000;
+
+function contentHasImage(blocks) {
+  return (
+    Array.isArray(blocks) &&
+    blocks.some((b) => b?.type === 'image' || (b?.type === 'tool-result' && contentHasImage(b.content)))
+  );
+}
+
+async function convertBlocks(blocks, convertOne) {
+  const out = [];
+  for (const block of blocks) {
+    if (block?.type === 'image') {
+      out.push(await convertOne(block));
+    } else if (block?.type === 'tool-result' && contentHasImage(block.content)) {
+      out.push({ ...block, content: await convertBlocks(block.content, convertOne) });
+    } else {
+      out.push(block);
+    }
+  }
+  return out;
+}
+
+/** 跨回放稳定的缓存键：同一附件以不同键序序列化后仍命中同一证据。 */
+function evidenceKey(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(evidenceKey).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${evidenceKey(value[k])}`).join(',')}}`;
+}
+
+/**
+ * 图片块 → 证据文本块。不抛错：失败降级为说明性文本块。
+ * 同一附件的证据带缓存（同一历史每步都会重发，不缓存则每步重复识图）；
+ * 失败按单调时钟冷却缓存，避免引擎故障时每步烧配额。
+ */
+async function evidenceForBlock(ctx, block, signal, cache) {
+  const key = evidenceKey(block.attachment ?? block);
+  const hit = cache.get(key);
+  if (hit !== undefined) {
+    cache.delete(key);
+    cache.set(key, hit); // 刷新新近度（Map 按插入序淘汰）
+    if (hit.ok || performance.now() < hit.retryAfter) return hit.block;
+    cache.delete(key);
+  }
+  try {
+    const stored = await ctx.attachments.readImage(block.attachment, signal);
+    if (!stored?.data) throw new Error('附件服务未返回图片数据');
+    const mediaType = stored.ref?.mediaType ?? block.attachment?.mediaType;
+    if (typeof mediaType !== 'string' || !mediaType.startsWith('image/')) {
+      throw new Error(`不支持的附件媒体类型 ${mediaType ?? '(未声明)'}`);
+    }
+    const model = resolveVisionModel(ctx);
+    if (!model) throw new Error('cmtoken 未配置视觉模型，请先完成一键认证');
+    await autoRefresh(ctx).catch(() => {});
+    const keyRes = await ctx.credentials?.resolve(credentialRef(API_KEY_ENV));
+    if (!keyRes) throw new Error('cmtoken 访问令牌不可用，请重新认证');
+    const baseURL = ctx.settings?.get?.(settingsNamespace('llm-pi-ai'))?.providers?.cmtoken?.baseURL || DEFAULT_API_BASE;
+    const signals = [AbortSignal.timeout(VISION_TOOL_TIMEOUT_MS)];
+    if (signal) signals.push(signal);
+    const evidence = await describeImage({
+      baseURL,
+      apiKey: keyRes.value,
+      model,
+      dataUri: `data:${mediaType};base64,${Buffer.from(stored.data).toString('base64')}`,
+      signal: AbortSignal.any(signals),
+    });
+    const textBlock = Object.freeze({
+      type: 'text',
+      text: `[粘贴/上传的图片，由 cmtoken 视觉模型 ${model} 识读]\n${evidenceTextLines({ model, ...evidence })}`,
+    });
+    cache.set(key, { ok: true, block: textBlock });
+    trimEvidenceCache(cache);
+    return textBlock;
+  } catch (e) {
+    const detail = String(e?.message ?? e).slice(0, 300);
+    ctx.logger?.warn?.('[cmtoken-oauth] 图片证据生成失败: ' + detail);
+    cache.set(key, { ok: false, retryAfter: performance.now() + EVIDENCE_FAILURE_COOLDOWN_MS, block: { type: 'text', text: `[图片识读失败：${detail}。请把失败告知用户，并建议在 DSH 设置 → cmtoken 认证里检查认证状态。]` } });
+    trimEvidenceCache(cache);
+    return cache.get(key).block;
+  }
+}
+
+function trimEvidenceCache(cache) {
+  while (cache.size > EVIDENCE_CACHE_MAX) cache.delete(cache.keys().next().value);
+}
+
+/** 出网前把包装路由产生的 assistant 轮次按上游重标：回放状态是 adapter 私有的。 */
+function relabelUpstreamSource(messages) {
+  return messages.map((m) => (
+    m?.role === 'assistant' && m?.source?.kind === 'model' && m?.source?.provider === VISION_PROVIDER_ID
+      ? { ...m, source: { ...m.source, provider: UPSTREAM_PROVIDER } }
+      : m
+  ));
+}
+
+// ---------------- 粘贴/拖图转路径（普通模型直接收图） ----------------
+// 普通分组里的纯文本模型贴图会在入口被拒（准入按模型模态声明）。此路由配合
+// client 端捕获阶段拦截：client 拿当前模型标签问 host 是否接管（GET）；纯文本
+// 模型则把图片字节 POST 过来，host 存成文件并把路径返回，client 把
+// `[Image: <路径>]` 插入输入框。识图延迟到模型按需调用 cmtoken_read_image
+// 工具时完成——不需要看图就不花识图调用，需要看图时上下文更充分。
+// 视觉模型（Qwen3.8 / Qwen3.x / kimi k2.x 非 code / MiniMax M3）不接管，
+// 走原生缩略图 + 原生视觉。
+
+const PASTE_ROUTE_PATH = '/cmtoken-oauth/paste';
+const PASTE_CACHE_MAX = 32;
+const PASTE_EXT = { 'image/png': '.png', 'image/jpeg': '.jpg', 'image/gif': '.gif', 'image/webp': '.webp' };
+const PASTE_MAX_AGE_MS = 7 * 24 * 3600_000;
+
+async function openPasteRoot() {
+  const root = join(os.homedir(), '.dsh', 'cmtoken-pastes');
+  await mkdir(root, { recursive: true }).catch(() => {});
+  return root;
+}
+
+/** 清理超过 7 天的粘贴文件；随粘贴顺带触发，失败静默。 */
+function sweepExpiredPastes(root) {
+  return (async () => {
+    const entries = await readdir(root).catch(() => []);
+    const now = Date.now();
+    for (const name of entries) {
+      const file = join(root, name);
+      const info = await stat(file).catch(() => undefined);
+      if (info?.isFile() && now - info.mtimeMs > PASTE_MAX_AGE_MS) {
+        await unlink(file).catch(() => {});
+      }
+    }
+  })().catch(() => {});
+}
+
+/** 从模型选择器标签（如「选择模型，当前 deepseekv4-flash」）提取模型名。 */
+function modelLabelToName(label) {
+  let s = String(label ?? '');
+  const idx = s.includes('，') ? s.lastIndexOf('，') : s.lastIndexOf(',');
+  if (idx >= 0) s = s.slice(idx + 1);
+  // 逗号后可能还有「当前 / current (:)」前缀，按 locale 变体剥掉
+  s = s.replace(/^\s*(当前|current)\s*:?\s*/i, '');
+  return s.replace(/\s*\(视觉回退\)\s*$/i, '').trim();
+}
+
+/** 在已认证模型列表里查找（id 或显示名，忽略大小写；兜底子串匹配）；找不到返回 undefined。 */
+function findConfiguredModel(ctx, name) {
+  if (!name) return undefined;
+  const models = ctx.settings?.get?.(settingsNamespace('llm-pi-ai'))?.providers?.cmtoken?.models ?? [];
+  const lower = String(name).toLowerCase();
+  return models.find((m) => String(m.id).toLowerCase() === lower || String(m.name ?? '').toLowerCase() === lower)
+    ?? models.find((m) => lower.includes(String(m.id).toLowerCase()) || lower.includes(String(m.name ?? '').toLowerCase()));
+}
+
+function registerPasteRoute(ctx) {
+  if (typeof ctx.inject !== 'function') return;
+  ctx.inject(['webServer'], (scope) => {
+    const cache = new Map(); // sha256(图片字节) → 文件路径
+    try {
+      scope.webServer.register({
+        name: 'cmtoken-oauth-paste',
+        kind: 'exact',
+        path: PASTE_ROUTE_PATH,
+        handler: async (req, res) => {
+          try {
+            if (req.method === 'GET') {
+              const label = new URL(req.url, 'http://localhost').searchParams.get('model') ?? '';
+              const model = findConfiguredModel(ctx, modelLabelToName(label));
+              res.writeHead(200, { 'content-type': 'application/json' });
+              res.end(JSON.stringify({ takeover: !!model && !supportsVision(model.id) }));
+              return;
+            }
+            if (req.method === 'POST') {
+              const chunks = [];
+              for await (const chunk of req) chunks.push(chunk);
+              const bytes = new Uint8Array(Buffer.concat(chunks));
+              if (bytes.length === 0) throw new Error('空请求体');
+              if (bytes.length > VISION_MAX_IMAGE_BYTES) {
+                throw new Error(`图片过大（${(bytes.length / 1048576).toFixed(1)}MB），上限 ${VISION_MAX_IMAGE_BYTES / 1048576}MB`);
+              }
+              const mediaType = detectMediaType(bytes);
+              if (!mediaType) throw new Error('不支持的图片格式（支持 PNG / JPEG / GIF / WebP）');
+              const hash = createHash('sha256').update(bytes).digest('hex');
+              const hit = cache.get(hash);
+              if (hit !== undefined) {
+                cache.delete(hash);
+                cache.set(hash, hit); // 刷新新近度
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ path: hit }));
+                return;
+              }
+              const root = await openPasteRoot();
+              void sweepExpiredPastes(root); // 顺带清理过期文件，不阻塞响应
+              const file = join(root, `paste-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}${PASTE_EXT[mediaType]}`);
+              await writeFile(file, bytes, { mode: 0o600 });
+              cache.set(hash, file);
+              while (cache.size > PASTE_CACHE_MAX) cache.delete(cache.keys().next().value);
+              res.writeHead(200, { 'content-type': 'application/json' });
+              res.end(JSON.stringify({ path: file }));
+              return;
+            }
+            res.writeHead(405, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'method not allowed' }));
+          } catch (e) {
+            res.writeHead(400, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: String(e?.message ?? e).slice(0, 300) }));
+          }
+        },
+      });
+      ctx.logger?.info?.('[cmtoken-oauth] 粘贴转路径路由已注册 ' + PASTE_ROUTE_PATH);
+    } catch (e) {
+      ctx.logger?.warn?.('[cmtoken-oauth] 粘贴转路径路由注册失败: ' + String(e?.message ?? e));
+    }
+  });
+}
+
+function registerVisionAdapter(ctx) {
+  // 宿主无该服务面（旧版 dsh）时只降级为「工具型」插件，不影响认证主功能
+  if (typeof ctx.llm?.registerAdapter !== 'function' || typeof ctx.llm?.stream !== 'function') {
+    ctx.logger?.warn?.('[cmtoken-oauth] 当前宿主无 llm.registerAdapter，视觉回退 provider 未注册（工具仍可用）');
+    return () => {};
+  }
+  const cache = new Map();
+  // llm-pi-ai 在 settings 加载后才挂载 cmtoken 路由，而本插件加载更早：
+  // providerRetryPolicy 会在 registerAdapter 内同步查询上游，上游未就绪即抛
+  // "no adapter registered"。故先探测、未就绪则监听 llm/adapters-updated 补注册。
+  const upstreamReady = () => {
+    try {
+      return typeof ctx.llm.listProviders === 'function'
+        && ctx.llm.listProviders().some((p) => (typeof p === 'string' ? p : p?.id) === UPSTREAM_PROVIDER);
+    } catch {
+      return false;
+    }
+  };
+  let disposeRegistration = () => {};
+  let done = false;
+  const tryRegister = () => {
+    if (done || !upstreamReady()) return;
+    try {
+      const registration = ctx.llm.registerAdapter([VISION_PROVIDER_ID], {
+        providerInfo(provider) {
+          return { id: provider, name: VISION_PROVIDER_NAME };
+        },
+        providerRetryPolicy() {
+          try {
+            return typeof ctx.llm.providerRetryPolicy === 'function'
+              ? ctx.llm.providerRetryPolicy(UPSTREAM_PROVIDER)
+              : undefined;
+          } catch {
+            return undefined; // 上游恰在此刻被卸载（热重载）：按默认重试策略注册
+          }
+        },
+        async listModels(_provider, signal) {
+          const models = await ctx.llm.listModels(UPSTREAM_PROVIDER, signal);
+          // 镜像纯文本模型；原生视觉模型（声明 image）不包装
+          return models
+            .filter((m) => !(Array.isArray(m?.inputModalities) && m.inputModalities.includes('image')))
+            .map((m) => ({
+              ...m,
+              provider: VISION_PROVIDER_ID,
+              inputModalities: ['text', 'image'],
+              name: `${m.name ?? m.id} (视觉回退)`,
+            }));
+        },
+        async resolveModel(provider, model, signal) {
+          const info = await ctx.llm.resolveModelInfo(UPSTREAM_PROVIDER, model, signal);
+          if (Array.isArray(info?.inputModalities) && info.inputModalities.includes('image')) {
+            throw new Error(`模型 "${model}" 原生支持图片输入，无需视觉回退；请在模型选择器选 cmtoken 分组下的同名模型。`);
+          }
+          // 校验要求 provider/id 与本路由一致，展开上游 info 后必须显式覆写
+          return { ...info, provider, id: model, inputModalities: ['text', 'image'] };
+        },
+        stream(options) {
+          return (async function* () {
+            const messages = [];
+            for (const message of options.messages) {
+              if (!contentHasImage(message.content)) {
+                messages.push(message);
+                continue;
+              }
+              const content = await convertBlocks(message.content, (block) =>
+                evidenceForBlock(ctx, block, options.signal, cache));
+              messages.push({ ...message, content });
+            }
+            yield* ctx.llm.stream({ ...options, provider: UPSTREAM_PROVIDER, messages: relabelUpstreamSource(messages) });
+          })();
+        },
+      });
+      disposeRegistration = () => {
+        try { registration?.(); } catch { /* 已卸载 */ }
+      };
+      done = true;
+      ctx.logger?.info?.(`[cmtoken-oauth] 视觉回退 provider ${VISION_PROVIDER_ID} 已注册`);
+    } catch (e) {
+      const duplicate = e?.code === 'DUPLICATE_ADAPTER' || /already registered|duplicate (adapter|provider)/i.test(String(e?.message ?? e));
+      if (duplicate) {
+        done = true; // 已有同名注册（如热重载残留），视为成功
+        return;
+      }
+      ctx.logger?.error?.(`[cmtoken-oauth] 视觉回退 provider 注册失败: ${String(e?.message ?? e)}`);
+    }
+  };
+  tryRegister(); // 上游已就绪（插件热重载/晚加载）则立即注册
+  let off = () => {};
+  if (typeof ctx.on === 'function') {
+    off = ctx.on('llm/adapters-updated', () => tryRegister());
+  }
+  return () => {
+    off();
+    disposeRegistration();
+  };
+}
+
 export function apply(ctx, cfg = {}) {
   let removeRpc = () => {};
   let stopTimer = () => {};
+  let disposeVisionAdapter = () => {};
   ctx.effect(() => {
     removeRpc = registerRpc(ctx);
     stopTimer = startAutoRefresh(ctx);
+    registerVisionTool(ctx);
+    registerPasteRoute(ctx);
+    // 视觉回退包装分组（cmtoken-vision）默认关闭：粘贴识图已覆盖纯文本模型，
+    // 需要真实图片气泡的会话可在 profile 的插件 config 里设 visionRoute: true。
+    if (cfg.visionRoute === true) disposeVisionAdapter = registerVisionAdapter(ctx);
     // 启动时立即补刷一次：若停机期间 access 过期、但 refresh 仍有效，马上恢复，
     // 不必等 60 秒定时器；失败只记日志，不影响启动。
     void autoRefresh(ctx).catch((e) => ctx.logger?.warn?.('[cmtoken-oauth] 启动补刷失败: ' + String(e?.message || e)));
     return () => {
       removeRpc();
       stopTimer();
+      disposeVisionAdapter();
     };
   }, 'cmtoken-oauth: host service');
   ctx.logger?.info?.('[cmtoken-oauth] host 服务已启动（自动刷新已开启：启动即补刷 + 每 1 分钟检查 + status 查询按需触发，剩余 <1 小时或已过期即刷新）');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-cmtoken-oauth",
-  "version": "1.0.3",
-  "description": "DeepSeek Harness 插件：在 DSH 设置页一键完成广东移动 MaaS（cmtoken）的 OAuth 2.0 Device Grant + PKCE 认证，自动发现模型并写入 llm-pi-ai provider 配置，凭据安全保存并自动续期。零第三方运行时依赖。",
+  "version": "1.4.0",
+  "description": "DeepSeek Harness 插件：在 DSH 设置页一键完成广东移动 MaaS（cmtoken）的 OAuth 2.0 Device Grant + PKCE 认证，自动发现模型并写入 llm-pi-ai provider 配置（视觉模型自动声明图片输入模态）；粘贴识图让纯文本模型直接收图（Qwen3.8 / Qwen3.x / Kimi K2.x / MiniMax M3 自动识读），另有 cmtoken_read_image 工具与可选的 cmtoken-vision 包装路由；凭据安全保存并自动续期。零第三方运行时依赖。",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/types/index.d.ts",