dsh-vision-fallback 0.6.0 → 0.9.0

package/README.md

@@ -106,6 +106,37 @@ The API key is resolved through the DSH **credentials** system (`~/.dsh/.credent
 - Observations are delivered as model-only surface replacements; your original image is never altered in the UI.
 - Image reads go through the DSH attachment service (sandbox/observation-policy aware); the vision request carries the official `attributionHeaders()`.
 
+## Usage records (usage.jsonl)
+
+With `recordUsage` enabled, every real vision call (success or failure) appends one JSON line to
+`<dshHome>/vision-fallback/usage.jsonl` (override via `usageLogPath` in the settings page), consumed by usage-dashboard.
+Fields:
+
+| Field | Meaning |
+| --- | --- |
+| `ts` | Call start time (epoch ms) |
+| `durationMs` | Response latency of this call (ms) |
+| `kind` | Always `"vision"` |
+| `status` | `"ok"` success / `"error"` failure |
+| `model` | Vision model name |
+| `inputTokens` / `outputTokens` | Input / output tokens |
+| `cacheReadTokens` | Cached input tokens served |
+| `error` | Error message (failure entries only) |
+| `imageName` / `mediaType` / `imageBytes` | Image filename / media type / byte size |
+| `imageIndex` / `imageTotal` | This image's position / total images in the request |
+
+Reusing a remembered observation (observations.json) does **not** append a line — this file counts real external vision calls only.
+
+### Observation cache semantics
+
+Observations are keyed by **the image's occurrence in a session** (session id + message id):
+
+- The same image at the **same message position** processed again (restart recovery, replay, compaction) → reused, no re-recognition;
+- The same image at a **new position in the session** (new turn, main model asking to "look again") → **re-recognized** with fresh context;
+- Observations are **not** shared across sessions.
+
+The cache is capped at 256 entries (LRU eviction); failed results are never cached.
+
 ## Default vision route
 
 - Model: `mimo-v2.5` · Endpoint: `https://opencode.ai/zen/go/v1/chat/completions` · Credential: `OPENCODE_GO_API_KEY`

package/README.zh.md

@@ -106,6 +106,37 @@ API key 通过 DSH **凭证系统**（`~/.dsh/.credentials.yaml`）解析，`pro
 - 观察结果以 model-only surface replacement 交付，界面中的原始图片永不被改写。
 - 图片读取走 DSH 附件服务（遵守沙箱与观察策略）；视觉请求携带官方 `attributionHeaders()`。
 
+## 用量记录（usage.jsonl）
+
+开启 `recordUsage` 后，每次真实视觉调用（成功或失败）追加一行 JSON 到
+`<dshHome>/vision-fallback/usage.jsonl`（可在设置页改 `usageLogPath`），供 usage-dashboard 统计。
+字段：
+
+| 字段 | 含义 |
+| --- | --- |
+| `ts` | 调用发起时刻（毫秒时间戳） |
+| `durationMs` | 本次调用响应耗时（毫秒） |
+| `kind` | 固定 `"vision"` |
+| `status` | `"ok"` 成功 / `"error"` 失败 |
+| `model` | 视觉模型名 |
+| `inputTokens` / `outputTokens` | 输入 / 输出 token 数 |
+| `cacheReadTokens` | 命中缓存读取的 token 数 |
+| `error` | 失败时的错误信息（仅失败条目） |
+| `imageName` / `mediaType` / `imageBytes` | 图片文件名 / 媒体类型 / 字节数 |
+| `imageIndex` / `imageTotal` | 该图在本次请求中的第几张 / 总张数 |
+
+复用已记忆的观察结果（observations.json）不会产生新条目——该文件统计的是真实外部视觉调用次数。
+
+### 观察缓存语义
+
+观察结果按**图片在某次会话中的出现位置**（会话 id + 消息 id）记录：
+
+- 同一图片在**同一消息位置**被重复处理（重启恢复、重放、压缩）→ 直接复用，不重新识别；
+- 同一图片在**会话的新位置**再次出现（新轮次、主模型"再仔细看看"）→ **重新识别**，生成贴合当前上下文的新观察；
+- 不同会话之间不共享观察结果。
+
+缓存上限 256 条（LRU 淘汰），失败结果不入缓存。
+
 ## 默认视觉路由
 
 - 模型：`mimo-v2.5` · 端点：`https://opencode.ai/zen/go/v1/chat/completions` · 凭据：`OPENCODE_GO_API_KEY`

package/lib/index.js

@@ -8,7 +8,7 @@
  * @module dsh-vision-fallback
  */
 import { createHash } from "node:crypto";
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { attributionHeaders } from "@deepseek-ai/dsh-llm";
@@ -30,6 +30,13 @@ const DEFAULT_PROMPT = [
 
 const Config = z.object({
   enabled: z.boolean().default(true),
+  /**
+   * auto：仅当主模型不支持图片输入时才接管（默认）。主模型自带视觉
+   * （如 kimi-k3、mimo-v2.5）时图片原样交给它，不再转文字。
+   * always：无论主模型是否支持图片都转成文字（旧行为）。
+   * never：完全不接管（等于停用视觉桥；纯文本模型收图会照常报"模型不支持"）。
+   */
+  mode: z.union(["auto", "always", "never"]).default("auto"),
   model: z.string().default("mimo-v2.5"),
   baseURL: z.string().default("https://opencode.ai/zen/go/v1"),
   apiKeyRef: z.string().role("credential-ref").default("OPENCODE_GO_API_KEY"),
@@ -154,6 +161,66 @@ function latestUserText(messages) {
   return "（用户本轮只提供了图片，没有附加文字问题）";
 }
 
+/**
+ * 观察缓存的 key：图片在某次会话中的一次出现。
+ * 同一图片在同一会话的不同位置（不同消息）视为不同出现，需要重新识别；
+ * 同一位置被重复处理（重启恢复、重放、压缩）时才能复用。
+ * @param {object} attachmentRef 图片附件引用
+ * @param {object} cfg 插件配置
+ * @param {{sessionId?: string, messageId?: string}} [scope] 图片出现的会话位置
+ */
+function observationKey(attachmentRef, cfg, scope) {
+  const attachmentId = attachmentRef?.attachmentId ?? JSON.stringify(attachmentRef);
+  return `${attachmentId}\0${scope?.sessionId ?? ""}\0${scope?.messageId ?? ""}\0${cfg.baseURL}\0${cfg.model}`;
+}
+
+const MAX_OBSERVATIONS = 256;
+
+function rememberObservation(store, key, text) {
+  if (text.startsWith("【图片转换失败：")) return;
+  store.set(key, text);
+  if (store.size > MAX_OBSERVATIONS) store.delete(store.keys().next().value);
+}
+
+function observationStorePath(cfg) {
+  if (typeof cfg.usageLogPath === "string" && cfg.usageLogPath !== "") {
+    return join(dirname(cfg.usageLogPath), "observations.json");
+  }
+  if (cfg.recordUsage === true) {
+    return join(resolveDshHome(), "vision-fallback", "observations.json");
+  }
+  return undefined;
+}
+
+function loadObservations(cfg) {
+  const store = new Map();
+  const path = observationStorePath(cfg);
+  if (path === undefined) return store;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return store;
+    for (const [key, text] of Object.entries(raw)) {
+      if (typeof text === "string" && text !== "" && !text.startsWith("【图片转换失败：")) {
+        store.set(key, text);
+      }
+    }
+  } catch {
+    // 缓存文件不存在或损坏时按空缓存继续。
+  }
+  return store;
+}
+
+function persistObservations(cfg, store) {
+  const path = observationStorePath(cfg);
+  if (path === undefined) return;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(Object.fromEntries(store))}\n`, "utf8");
+  } catch (error) {
+    console.warn(`vision-fallback: 保存视觉观察缓存失败：${errorText(error)}`);
+  }
+}
+
 function recentConversation(messages, cfg) {
   if (!cfg.includeRecentContext || cfg.contextMessages === 0 || cfg.contextMaxChars === 0) return "";
   const rows = [];
@@ -198,9 +265,20 @@ function errorText(error) {
 
 /**
  * 记录一次视觉调用用量（追加 JSONL），供 usage-dashboard 统计。
- * 失败仅告警，不影响主流程。
+ * 成功与失败都会记录；失败仅告警，不影响主流程。
+ * @param {object} cfg 插件配置
+ * @param {object} record 记录内容
+ * @param {number} [record.startedAt] 调用发起时刻（毫秒时间戳），作为 ts
+ * @param {object} [record.usage] OpenAI 风格用量对象（prompt_tokens 等）
+ * @param {"ok"|"error"} [record.status] 调用结果状态
+ * @param {string} [record.error] 失败时的错误信息（截断 500 字符）
+ * @param {string} [record.imageName] 图片文件名
+ * @param {string} [record.mediaType] 图片媒体类型（如 image/png）
+ * @param {number} [record.imageBytes] 图片字节数
+ * @param {number} [record.imageIndex] 本次请求中第几张图（从 1 开始）
+ * @param {number} [record.imageTotal] 本次请求图片总数
  */
-function recordVisionUsage(cfg, usage, startedAt) {
+function recordVisionUsage(cfg, { startedAt, usage, status = "ok", error, imageName, mediaType, imageBytes, imageIndex, imageTotal }) {
   if (!cfg.recordUsage) return;
   try {
     const logPath = cfg.usageLogPath !== ""
@@ -209,12 +287,21 @@ function recordVisionUsage(cfg, usage, startedAt) {
     const u = usage ?? {};
     const entry = {
       ts: startedAt ?? Date.now(),
+      durationMs: Math.max(0, Date.now() - (startedAt ?? Date.now())),
+      kind: "vision",
+      status,
       model: cfg.model,
       inputTokens: u.prompt_tokens ?? 0,
       outputTokens: u.completion_tokens ?? 0,
       cacheReadTokens: u.prompt_tokens_details?.cached_tokens ?? 0,
       cacheWriteTokens: 0
     };
+    if (error !== undefined) entry.error = String(error).slice(0, 500);
+    if (imageName !== undefined) entry.imageName = imageName;
+    if (mediaType !== undefined) entry.mediaType = mediaType;
+    if (imageBytes !== undefined) entry.imageBytes = imageBytes;
+    if (imageIndex !== undefined) entry.imageIndex = imageIndex;
+    if (imageTotal !== undefined) entry.imageTotal = imageTotal;
     mkdirSync(dirname(logPath), { recursive: true });
     appendFileSync(logPath, `${JSON.stringify(entry)}\n`, "utf8");
   } catch (error) {
@@ -229,7 +316,7 @@ function assertVisionConfig(cfg) {
 }
 
 function withImageCapability(info, cfg) {
-  if (!cfg.enabled) return info;
+  if (!cfg.enabled || cfg.mode === "never") return info;
   const inputModalities = Array.isArray(info?.inputModalities) ? info.inputModalities : ["text"];
   if (inputModalities.includes("image")) return info;
   return { ...info, inputModalities: [...new Set([...inputModalities, "text", "image"])] };
@@ -250,7 +337,35 @@ async function resolveApiKey(credentials, ref) {
   throw new Error(`未找到 API Key：请在 DSH 凭证中配置 ${ref}`);
 }
 
-async function describeImage(ctx, apiKey, cfg, attachmentRef, prompt, signal) {
+async function describeImage(ctx, apiKey, cfg, attachmentRef, prompt, signal, meta) {
+  const startedAt = Date.now();
+  const metaInfo = {
+    imageName: attachmentRef?.name,
+    imageIndex: meta?.imageIndex,
+    imageTotal: meta?.imageTotal
+  };
+  try {
+    const result = await performDescribeImage(ctx, apiKey, cfg, attachmentRef, prompt, signal);
+    recordVisionUsage(cfg, {
+      startedAt,
+      ...metaInfo,
+      mediaType: result.mediaType,
+      imageBytes: result.imageBytes,
+      usage: result.usage
+    });
+    return result.text;
+  } catch (error) {
+    recordVisionUsage(cfg, {
+      startedAt,
+      ...metaInfo,
+      status: "error",
+      error: errorText(error)
+    });
+    throw error;
+  }
+}
+
+async function performDescribeImage(ctx, apiKey, cfg, attachmentRef, prompt, signal) {
   const attachments = ctx.get("attachments");
   if (attachments === undefined || typeof attachments.readImage !== "function") {
     throw new Error("attachments 服务不可用，无法读取聊天图片");
@@ -316,29 +431,33 @@ async function describeImage(ctx, apiKey, cfg, attachmentRef, prompt, signal) {
     throw new Error(`视觉 API 返回 ${response.status} ${response.statusText}：${snippet}`);
   }
   const data = await response.json();
-  recordVisionUsage(cfg, data?.usage, Date.now());
   const content = data?.choices?.[0]?.message?.content;
   const text = Array.isArray(content)
     ? content.map((part) => typeof part?.text === "string" ? part.text : "").join("")
     : typeof content === "string" ? content : "";
   if (text.trim() === "") throw new Error("视觉 API 返回空文本");
-  return cfg.tagResult
-    ? `【视觉观察：${cfg.model}${attachmentRef?.name ? ` · ${attachmentRef.name}` : ""}】\n${text.trim()}`
-    : text.trim();
+  return {
+    text: cfg.tagResult
+      ? `【视觉观察：${cfg.model}${attachmentRef?.name ? ` · ${attachmentRef.name}` : ""}】\n${text.trim()}`
+      : text.trim(),
+    usage: data?.usage,
+    mediaType: stored.ref.mediaType,
+    imageBytes: bytes.length
+  };
 }
 
-async function rewriteContent(content, describe, counter) {
+async function rewriteContent(content, describe, counter, messageId) {
   const rewritten = [];
   for (const block of content) {
     if (block?.type === "image") {
       counter.index += 1;
-      rewritten.push({ type: "text", text: await describe(block.attachment, counter.index) });
+      rewritten.push({ type: "text", text: await describe(block.attachment, counter.index, messageId) });
       continue;
     }
     if (block?.type === "tool-result" && contentHasImage(block.content ?? [])) {
       rewritten.push({
         ...block,
-        content: await rewriteContent(block.content ?? [], describe, counter)
+        content: await rewriteContent(block.content ?? [], describe, counter, messageId)
       });
       continue;
     }
@@ -360,8 +479,9 @@ async function rewriteMessages(messages, describe) {
       ...message,
       content: await rewriteContent(
         message.content ?? [],
-        (attachmentRef, imageIndex) => describe(attachmentRef, imageIndex, imageTotal),
-        counter
+        (attachmentRef, imageIndex, messageId) => describe(attachmentRef, imageIndex, imageTotal, messageId),
+        counter,
+        message.id
       )
     });
   }
@@ -386,31 +506,54 @@ class VisionFallbackController {
     this.ctx = ctx;
     this.current = current;
     this.cache = new Map();
+    this.observations = loadObservations(current());
   }
 
   modelInfo(info) {
     return withImageCapability(info, this.current());
   }
 
-  async preprocess(messages, contextMessages, signal) {
+  hydrateObservations() {
+    for (const [key, text] of loadObservations(this.current())) {
+      if (!this.observations.has(key)) this.observations.set(key, text);
+    }
+    return this.observations;
+  }
+
+  recallObservation(attachmentRef, scope) {
+    return this.hydrateObservations().get(observationKey(attachmentRef, this.current(), scope));
+  }
+
+  rememberObservation(attachmentRef, text, scope) {
+    const cfg = this.current();
+    rememberObservation(this.observations, observationKey(attachmentRef, cfg, scope), text);
+    persistObservations(cfg, this.observations);
+  }
+
+  async preprocess(messages, contextMessages, signal, sessionId) {
     const cfg = this.current();
     assertVisionConfig(cfg);
     if (!cfg.enabled || !messages.some((message) => contentHasImage(message.content ?? []))) return messages;
 
     try {
       const apiKey = await resolveApiKey(this.ctx.get("credentials"), cfg.apiKeyRef);
-      return await rewriteMessages(messages, async (attachmentRef, imageIndex, imageTotal) => {
+      return await rewriteMessages(messages, async (attachmentRef, imageIndex, imageTotal, messageId) => {
         const prompt = buildVisionPrompt(contextMessages, attachmentRef, imageIndex, imageTotal, cfg);
         const attachmentId = attachmentRef?.attachmentId ?? JSON.stringify(attachmentRef);
-        const cacheKey = createHash("sha256").update(`${attachmentId}\0${prompt}\0${cfg.baseURL}\0${cfg.model}`).digest("hex");
+        const scope = { sessionId, messageId };
+        const remembered = this.recallObservation(attachmentRef, scope);
+        if (remembered !== undefined) return remembered;
+        const cacheKey = createHash("sha256").update(`${attachmentId}\0${scope.sessionId ?? ""}\0${scope.messageId ?? ""}\0${prompt}\0${cfg.baseURL}\0${cfg.model}`).digest("hex");
         let pending = this.cache.get(cacheKey);
         if (pending === undefined) {
-          pending = describeImage(this.ctx, apiKey, cfg, attachmentRef, prompt, signal);
+          pending = describeImage(this.ctx, apiKey, cfg, attachmentRef, prompt, signal, { imageIndex, imageTotal });
           this.cache.set(cacheKey, pending);
           if (this.cache.size > 64) this.cache.delete(this.cache.keys().next().value);
         }
         try {
-          return await pending;
+          const text = await pending;
+          this.rememberObservation(attachmentRef, text, scope);
+          return text;
         } catch (error) {
           this.cache.delete(cacheKey);
           return `【图片转换失败：${errorText(error)}】`;
@@ -461,6 +604,59 @@ class ReplacementCoordinator {
     }
   }
 
+  replacementFor(session, messageId) {
+    if (session === undefined || messageId === undefined) return undefined;
+    return this.pending.get(session)?.get(messageId);
+  }
+
+  flush(session) {
+    const replacements = this.pending.get(session);
+    if (replacements === undefined || replacements.size === 0) return;
+    const events = session.events;
+    const nodes = session.surface?.nodes;
+    if (!Array.isArray(events) && (events === undefined || typeof events !== "object")) return;
+    if (!Array.isArray(nodes)) return;
+    for (const seq of [...nodes]) {
+      const event = events[seq];
+      if (event === undefined) continue;
+      const message = typeof session.deriveEventMessage === "function"
+        ? session.deriveEventMessage(event)
+        : event.type === "user/message"
+          ? event.data
+          : event.type === "tool/result"
+            ? event.data?.message
+            : undefined;
+      if (message === undefined || message === null) continue;
+      const replacement = replacements.get(message.id);
+      if (replacement === undefined || !contentHasImage(message.content ?? [])) continue;
+      try {
+        if (event.type === "user/message") {
+          session.append("user/message", replacement, {
+            surfaceOp: { op: "replace", start: seq, end: seq },
+            sourceEventSeqs: [seq]
+          });
+        } else if (event.type === "tool/result") {
+          session.append("tool/result", {
+            ...event.data,
+            message: {
+              ...event.data.message,
+              content: replacement.content
+            }
+          }, {
+            surfaceOp: { op: "replace", start: seq, end: seq },
+            sourceEventSeqs: [seq]
+          });
+        } else {
+          continue;
+        }
+        replacements.delete(message.id);
+      } catch (error) {
+        this.logger.error("vision-fallback: 固化视觉观察失败");
+        this.logger.error(error);
+      }
+    }
+  }
+
   onSessionEvent(session, event) {
     if (event.type !== "user/message" || event.surfaceOp !== "append") return;
     const replacements = this.pending.get(session);
@@ -488,7 +684,11 @@ class ReplacementCoordinator {
   }
 }
 
+/** 原始的 resolveModelInfo 实现（绑定原持有者，未被能力覆盖污染）。 */
+let rawResolveModelInfo = null;
+
 function installCapabilityOverride(ctx, current) {
+  rawResolveModelInfo = ctx.llm.resolveModelInfo.bind(ctx.llm);
   const previous = ctx.llm.resolveModelInfo;
   const overridden = async function (provider, model, signal) {
     const info = await previous.call(this, provider, model, signal);
@@ -497,9 +697,60 @@ function installCapabilityOverride(ctx, current) {
   ctx.llm.resolveModelInfo = overridden;
   return () => {
     if (ctx.llm.resolveModelInfo === overridden) ctx.llm.resolveModelInfo = previous;
+    rawResolveModelInfo = null;
   };
 }
 
+/**
+ * 用未被覆盖的 resolveModelInfo 查询主模型的真实图片能力。
+ * 解析失败保守返回 false（沿用接管路径，至少不会让请求挂掉）。
+ */
+async function modelActuallySupportsImage(provider, model, signal) {
+  if (typeof provider !== "string" || typeof model !== "string" || provider === "" || model === "") return false;
+  if (typeof rawResolveModelInfo !== "function") return false;
+  try {
+    const info = await rawResolveModelInfo(provider, model, signal);
+    return Array.isArray(info?.inputModalities) && info.inputModalities.includes("image");
+  } catch {
+    return false;
+  }
+}
+
+function resolveSession(ctx, sessionId) {
+  if (sessionId === undefined) return undefined;
+  return (ctx.sessions ?? ctx.get?.("sessions"))?.get(sessionId);
+}
+
+function reuseExistingVisionMessages(messages, session, coordinator) {
+  const liveById = new Map();
+  if (session !== undefined && typeof session.deriveMessages === "function") {
+    for (const message of session.deriveMessages()) {
+      if (typeof message?.id === "string") liveById.set(message.id, message);
+    }
+  }
+  return messages.map((message) => {
+    const live = typeof message?.id === "string" ? liveById.get(message.id) : undefined;
+    if (live !== undefined && contentHasImage(message.content ?? []) && !contentHasImage(live.content ?? [])) {
+      return live;
+    }
+    return coordinator.replacementFor(session, message.id) ?? message;
+  });
+}
+
+function compactionImagePlaceholder(attachmentRef) {
+  const name = attachmentRef?.name ? attachmentRef.name : "未命名图片";
+  return `【图片：${name}。主模型已直接查看原图，压缩时不再重新识别，请依据后续对话中的结论。】`;
+}
+
+function replaceLeftoverCompactionImages(messages, controller, sessionId) {
+  const cfg = controller.current();
+  controller.hydrateObservations();
+  return rewriteMessages(messages, async (attachmentRef, imageIndex, imageTotal, messageId) => (
+    controller.observations.get(observationKey(attachmentRef, cfg, { sessionId, messageId }))
+      ?? compactionImagePlaceholder(attachmentRef)
+  ));
+}
+
 function apply(ctx, config) {
   let current = () => config;
   let settingsService;
@@ -515,12 +766,51 @@ function apply(ctx, config) {
   ctx.on("agent/pre-step", async ({ agent, signal }, next) => {
     const decision = await next();
     if (decision.kind === "reject" || signal.aborted) return decision;
+    const cfg = current();
+    if (!cfg.enabled || cfg.mode === "never") return decision;
+    // auto 模式：主模型自带视觉能力时让它直接看原图，不接管。
+    if (cfg.mode === "auto") {
+      const header = typeof agent?.session?.requestHeader === "function" ? agent.session.requestHeader() : undefined;
+      const provider = header?.config?.provider ?? agent?.options?.provider;
+      const model = header?.config?.model ?? agent?.options?.model;
+      if (await modelActuallySupportsImage(provider, model, signal)) return decision;
+    }
     const modelMessages = [...agent.session.deriveMessages(), ...decision.messages];
-    const rewritten = await controller.preprocess(modelMessages, modelMessages, signal);
+    const rewritten = await controller.preprocess(modelMessages, modelMessages, signal, agent.session.id);
     replacements.stage(agent.session, modelMessages, rewritten);
+    replacements.flush(agent.session);
     return decision;
   });
 
+  ctx.on("llm/stream", (options, next) => (async function* () {
+    if (options.purpose !== "compaction") {
+      yield* next();
+      return;
+    }
+    const cfg = current();
+    if (!cfg.enabled || cfg.mode === "never") {
+      yield* next();
+      return;
+    }
+    if (!Array.isArray(options.messages) || !options.messages.some((message) => contentHasImage(message.content ?? []))) {
+      yield* next();
+      return;
+    }
+    if (cfg.mode === "auto" && await modelActuallySupportsImage(options.provider, options.model, options.signal)) {
+      yield* next();
+      return;
+    }
+    const projected = reuseExistingVisionMessages(
+      options.messages,
+      resolveSession(ctx, options.sessionId),
+      replacements
+    );
+    options.messages = projected.some((message) => contentHasImage(message.content ?? []))
+      ? await replaceLeftoverCompactionImages(projected, controller, options.sessionId)
+      : projected;
+    yield* next();
+  })(), { global: true, prepend: true });
+
   ctx.inject(["settings"], (sctx) => {
     settingsService = sctx.settings;
     sctx.effect(() => () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vision-fallback",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "DSH 静默视觉增强：主模型照常选择，图片自动交给固定视觉模型后以隐藏上下文返回主模型。",
   "type": "module",
   "main": "lib/index.js",

package/test/vision-fallback.test.mjs

@@ -1,5 +1,7 @@
 import assert from "node:assert/strict";
-import { readFile } from "node:fs/promises";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import test from "node:test";
 import {
   CONFIG_ROUTE,
@@ -49,6 +51,12 @@ function assistantMessage(id, text) {
   };
 }
 
+async function consumeStream(stream) {
+  for await (const _chunk of stream) {}
+}
+
+async function* emptyStream() {}
+
 function createServiceContext() {
   return {
     get(service) {
@@ -325,6 +333,7 @@ test("插件注册静默预处理钩子而不注册新模型 adapter", () => {
   apply(ctx, config);
   assert.equal(typeof hooks.get("agent/pre-step"), "function");
   assert.equal(typeof hooks.get("session/event"), "function");
+  assert.equal(typeof hooks.get("llm/stream"), "function");
   assert.equal("registerAdapter" in ctx.llm, false);
   assert.equal("registerConfigurableProviders" in ctx.llm, false);
   assert.equal(typeof cleanup, "function");
@@ -487,3 +496,465 @@ test("浏览器端只显示静默视觉配置", async () => {
     globalThis.fetch = previousFetch;
   }
 });
+
+test("auto 模式按主模型真实视觉能力决定是否接管", async () => {
+  const imageBlock = { type: "image", attachment: { attachmentId: "sha256:test", mediaType: "image/png" } };
+  let visionRequests = 0;
+  const previousFetch = globalThis.fetch;
+  globalThis.fetch = async () => {
+    visionRequests += 1;
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ choices: [{ message: { content: "红色" } }] })
+    };
+  };
+
+  const makeSignal = () => ({ aborted: false, addEventListener() {}, removeEventListener() {} });
+  const makeCtx = (realModalities) => {
+    let preStep;
+    const ctx = {
+      llm: {
+        resolveModelInfo: async () => ({ provider: "opencode-go", id: "x", name: "x", inputModalities: realModalities })
+      },
+      logger: { error() {} },
+      effect() {},
+      on(name, handler) {
+        if (name === "agent/pre-step") preStep = handler;
+      },
+      inject(deps, cb) {
+        if (deps[0] === "settings") {
+          cb({
+            settings: {
+              register: (_ns, _schema, options) => ({ get: () => options.base, watch() {} })
+            },
+            effect() {}
+          });
+        } else {
+          cb({ webServer: { register: () => () => {} }, effect() {} });
+        }
+      },
+      get(name) {
+        if (name === "credentials") return { resolve: async () => ({ value: "sk-test" }) };
+        if (name === "attachments") return { readImage: async () => ({ data: Buffer.from("test"), ref: { mediaType: "image/png" } }) };
+        return undefined;
+      }
+    };
+    return { ctx, preStep: () => preStep };
+  };
+
+  // 1) 主模型自带视觉 → 不接管，视觉 API 不被调用
+  const vision = makeCtx(["text", "image"]);
+  apply(vision.ctx, { ...config, mode: "auto" });
+  const messages1 = [{ id: "m1", role: "user", source: { kind: "user" }, content: [{ type: "text", text: "看图" }, imageBlock] }];
+  const decision1 = { kind: "enter", messages: messages1 };
+  const out1 = await vision.preStep()(
+    {
+      agent: {
+        options: { provider: "opencode-go", model: "kimi-k3" },
+        session: {
+          requestHeader: () => ({ config: { provider: "opencode-go", model: "kimi-k3" } }),
+          deriveMessages: () => []
+        }
+      },
+      signal: makeSignal()
+    },
+    () => decision1
+  );
+  assert.equal(out1, decision1);
+  assert.equal(visionRequests, 0);
+
+  // 2) 纯文本主模型 → 接管，视觉 API 被调用一次
+  const text = makeCtx(["text"]);
+  apply(text.ctx, { ...config, mode: "auto" });
+  const messages2 = [{ id: "m2", role: "user", source: { kind: "user" }, content: [{ type: "text", text: "看图" }, imageBlock] }];
+  const decision2 = { kind: "enter", messages: messages2 };
+  await text.preStep()(
+    {
+      agent: {
+        options: { provider: "opencode-go", model: "deepseek-v4-flash" },
+        session: {
+          requestHeader: () => ({ config: { provider: "opencode-go", model: "deepseek-v4-flash" } }),
+          deriveMessages: () => []
+        }
+      },
+      signal: makeSignal()
+    },
+    () => decision2
+  );
+  assert.equal(visionRequests, 1);
+
+  globalThis.fetch = previousFetch;
+});
+
+test("同一图片在同一消息位置重复处理时复用观察", async () => {
+  const originalFetch = globalThis.fetch;
+  let visionRequests = 0;
+  globalThis.fetch = async () => {
+    visionRequests += 1;
+    return {
+      ok: true,
+      json: async () => ({ choices: [{ message: { content: "按钮文案是保存" } }] })
+    };
+  };
+  const controller = new VisionFallbackController(createServiceContext(), () => config);
+  const first = userMessage("u1", [{ type: "text", text: "这个按钮是什么？" }, { type: "image", attachment }]);
+
+  try {
+    const [firstRewritten] = await controller.preprocess([first], [first], undefined, "session-A");
+    const [againRewritten] = await controller.preprocess([first], [first], undefined, "session-A");
+    assert.equal(visionRequests, 1);
+    assert.match(firstRewritten.content[1].text, /按钮文案是保存/);
+    assert.equal(againRewritten.content[1].text, firstRewritten.content[1].text);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("同一图片在会话不同位置再次出现时重新识别", async () => {
+  const originalFetch = globalThis.fetch;
+  let visionRequests = 0;
+  globalThis.fetch = async () => {
+    visionRequests += 1;
+    return {
+      ok: true,
+      json: async () => ({ choices: [{ message: { content: "按钮文案是保存" } }] })
+    };
+  };
+  const controller = new VisionFallbackController(createServiceContext(), () => config);
+  const first = userMessage("u1", [{ type: "text", text: "这个按钮是什么？" }, { type: "image", attachment }]);
+  const second = userMessage("u2", [{ type: "text", text: "请压缩更早的对话" }, { type: "image", attachment }]);
+
+  try {
+    const [firstRewritten] = await controller.preprocess([first], [first], undefined, "session-A");
+    const [secondRewritten] = await controller.preprocess([second], [second], undefined, "session-A");
+    assert.equal(visionRequests, 2, "同一会话的新消息位置应重新识别");
+    assert.match(secondRewritten.content[1].text, /按钮文案是保存/);
+    assert.equal(secondRewritten.content[1].text, firstRewritten.content[1].text);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("同一图片在不同会话的同一位置也重新识别", async () => {
+  const originalFetch = globalThis.fetch;
+  let visionRequests = 0;
+  globalThis.fetch = async () => {
+    visionRequests += 1;
+    return {
+      ok: true,
+      json: async () => ({ choices: [{ message: { content: "按钮文案是保存" } }] })
+    };
+  };
+  const controller = new VisionFallbackController(createServiceContext(), () => config);
+  const first = userMessage("u1", [{ type: "text", text: "这个按钮是什么？" }, { type: "image", attachment }]);
+
+  try {
+    await controller.preprocess([first], [first], undefined, "session-A");
+    await controller.preprocess([first], [first], undefined, "session-B");
+    assert.equal(visionRequests, 2, "不同会话应重新识别");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("重启后同一会话位置的图片复用持久化观察", async () => {
+  const originalFetch = globalThis.fetch;
+  let visionRequests = 0;
+  globalThis.fetch = async () => {
+    visionRequests += 1;
+    return {
+      ok: true,
+      json: async () => ({ choices: [{ message: { content: "按钮文案是保存" } }] })
+    };
+  };
+  const dir = await mkdtemp(join(tmpdir(), "vision-obs-"));
+  const logPath = join(dir, "usage.jsonl");
+  const makeController = () => new VisionFallbackController(
+    createServiceContext(),
+    () => ({ ...config, recordUsage: true, usageLogPath: logPath })
+  );
+  const first = userMessage("u1", [{ type: "text", text: "这个按钮是什么？" }, { type: "image", attachment }]);
+
+  try {
+    const controllerA = makeController();
+    const [rewrittenA] = await controllerA.preprocess([first], [first], undefined, "session-A");
+    assert.equal(visionRequests, 1);
+    // 模拟重启：新 controller 实例重新从磁盘加载观察缓存
+    const controllerB = makeController();
+    const [rewrittenB] = await controllerB.preprocess([first], [first], undefined, "session-A");
+    assert.equal(visionRequests, 1, "重启后同一位置应复用持久化观察");
+    assert.equal(rewrittenB.content[1].text, rewrittenA.content[1].text);
+  } finally {
+    globalThis.fetch = originalFetch;
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("compaction 请求不再重新识图，普通请求保持原样", async () => {
+  const imageBlock = { type: "image", attachment: { attachmentId: "sha256:compact", mediaType: "image/png", name: "compact.png" } };
+  let visionRequests = 0;
+  const previousFetch = globalThis.fetch;
+  globalThis.fetch = async () => {
+    visionRequests += 1;
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ choices: [{ message: { content: "压缩图中的关键错误是端口写错" } }] })
+    };
+  };
+
+  const makeSignal = () => ({ aborted: false, addEventListener() {}, removeEventListener() {} });
+  let streamHandler;
+  const ctx = {
+    llm: {
+      resolveModelInfo: async () => ({ provider: "opencode-go", id: "deepseek-v4-flash", name: "deepseek-v4-flash", inputModalities: ["text"] })
+    },
+    logger: { error() {} },
+    effect() {},
+    on(name, handler) {
+      if (name === "llm/stream") streamHandler = handler;
+    },
+    inject(deps, cb) {
+      if (deps[0] === "settings") {
+        cb({
+          settings: {
+            register: (_ns, _schema, options) => ({ get: () => options.base, watch() {} })
+          },
+          effect() {}
+        });
+      } else {
+        cb({ webServer: { register: () => () => {} }, effect() {} });
+      }
+    },
+    get(name) {
+      if (name === "credentials") return { resolve: async () => ({ value: "sk-test" }) };
+      if (name === "attachments") {
+        return {
+          readImage: async () => ({ data: Buffer.from("compact"), ref: { mediaType: "image/png" } })
+        };
+      }
+      return undefined;
+    }
+  };
+
+  try {
+    apply(ctx, { ...config, mode: "auto" });
+    assert.equal(typeof streamHandler, "function");
+
+    const compactionOptions = {
+      purpose: "compaction",
+      provider: "opencode-go",
+      model: "deepseek-v4-flash",
+      signal: makeSignal(),
+      messages: [userMessage("compact-1", [{ type: "text", text: "请压缩上下文" }, imageBlock])]
+    };
+    const compactionStream = streamHandler(compactionOptions, emptyStream);
+    assert.equal(typeof compactionStream[Symbol.asyncIterator], "function");
+    await consumeStream(compactionStream);
+    assert.equal(visionRequests, 0);
+    assert.equal(JSON.stringify(compactionOptions.messages).includes('"type":"image"'), false);
+    assert.match(compactionOptions.messages[0].content[1].text, /主模型已直接查看原图/);
+
+    const normalOptions = {
+      purpose: undefined,
+      provider: "opencode-go",
+      model: "deepseek-v4-flash",
+      signal: makeSignal(),
+      messages: [userMessage("normal-1", [{ type: "text", text: "正常请求" }, imageBlock])]
+    };
+    const before = JSON.stringify(normalOptions.messages);
+    await consumeStream(streamHandler(normalOptions, emptyStream));
+    assert.equal(JSON.stringify(normalOptions.messages), before);
+    assert.equal(visionRequests, 0);
+  } finally {
+    globalThis.fetch = previousFetch;
+  }
+});
+
+test("压缩优先复用主模型已经拿到的视觉观察", async () => {
+  const imageBlock = { type: "image", attachment: { attachmentId: "sha256:reuse", mediaType: "image/png", name: "reuse.png" } };
+  const original = userMessage("reuse-1", [{ type: "text", text: "看这张图" }, imageBlock]);
+  const rewritten = userMessage("reuse-1", [{ type: "text", text: "看这张图" }, { type: "text", text: "【视觉观察：vision-model · reuse.png】\n端口写的是 8080" }]);
+  let visionRequests = 0;
+  const previousFetch = globalThis.fetch;
+  globalThis.fetch = async () => {
+    visionRequests += 1;
+    return { ok: true, status: 200, json: async () => ({ choices: [{ message: { content: "不应重新识图" } }] }) };
+  };
+  const makeSignal = () => ({ aborted: false, addEventListener() {}, removeEventListener() {} });
+  let streamHandler;
+  const session = {
+    deriveMessages: () => [rewritten]
+  };
+  const ctx = {
+    sessions: {
+      get(sessionId) {
+        assert.equal(sessionId, "session-reuse");
+        return session;
+      }
+    },
+    llm: {
+      resolveModelInfo: async () => ({ provider: "opencode-go", id: "deepseek-v4-flash", name: "deepseek-v4-flash", inputModalities: ["text"] })
+    },
+    logger: { error() {} },
+    effect() {},
+    on(name, handler) {
+      if (name === "llm/stream") streamHandler = handler;
+    },
+    inject(deps, cb) {
+      if (deps[0] === "settings") {
+        cb({ settings: { register: (_ns, _schema, options) => ({ get: () => options.base, watch() {} }) }, effect() {} });
+      } else {
+        cb({ webServer: { register: () => () => {} }, effect() {} });
+      }
+    },
+    get() {
+      return undefined;
+    }
+  };
+
+  try {
+    apply(ctx, { ...config, mode: "auto" });
+    const options = {
+      purpose: "compaction",
+      sessionId: "session-reuse",
+      provider: "opencode-go",
+      model: "deepseek-v4-flash",
+      signal: makeSignal(),
+      messages: [original]
+    };
+    await consumeStream(streamHandler(options, emptyStream));
+    assert.equal(visionRequests, 0);
+    assert.equal(options.messages[0], rewritten);
+    assert.equal(JSON.stringify(options.messages).includes('"type":"image"'), false);
+  } finally {
+    globalThis.fetch = previousFetch;
+  }
+});
+
+test("compaction 请求在 mode=never 时不拦截图片", async () => {
+  const imageBlock = { type: "image", attachment: { attachmentId: "sha256:compact", mediaType: "image/png", name: "compact.png" } };
+  let visionRequests = 0;
+  const previousFetch = globalThis.fetch;
+  globalThis.fetch = async () => {
+    visionRequests += 1;
+    return { ok: true, status: 200, json: async () => ({ choices: [{ message: { content: "不应调用" } }] }) };
+  };
+  const makeSignal = () => ({ aborted: false, addEventListener() {}, removeEventListener() {} });
+  let streamHandler;
+  const ctx = {
+    llm: {
+      resolveModelInfo: async () => ({ provider: "opencode-go", id: "deepseek-v4-flash", name: "deepseek-v4-flash", inputModalities: ["text"] })
+    },
+    logger: { error() {} },
+    effect() {},
+    on(name, handler) {
+      if (name === "llm/stream") streamHandler = handler;
+    },
+    inject(deps, cb) {
+      if (deps[0] === "settings") {
+        cb({ settings: { register: (_ns, _schema, options) => ({ get: () => options.base, watch() {} }) }, effect() {} });
+      } else {
+        cb({ webServer: { register: () => () => {} }, effect() {} });
+      }
+    },
+    get() {
+      return undefined;
+    }
+  };
+
+  try {
+    apply(ctx, { ...config, mode: "never" });
+    const options = {
+      purpose: "compaction",
+      provider: "opencode-go",
+      model: "deepseek-v4-flash",
+      signal: makeSignal(),
+      messages: [userMessage("compact-never", [{ type: "text", text: "请压缩上下文" }, imageBlock])]
+    };
+    const before = JSON.stringify(options.messages);
+    await consumeStream(streamHandler(options, emptyStream));
+    assert.equal(JSON.stringify(options.messages), before);
+    assert.equal(visionRequests, 0);
+  } finally {
+    globalThis.fetch = previousFetch;
+  }
+});
+
+test("usage 记录包含响应耗时与图片信息", async () => {
+  const previousFetch = globalThis.fetch;
+  globalThis.fetch = async () => ({
+    ok: true,
+    status: 200,
+    json: async () => ({
+      choices: [{ message: { content: "按钮文案是保存" } }],
+      usage: { prompt_tokens: 100, completion_tokens: 50, prompt_tokens_details: { cached_tokens: 10 } }
+    })
+  });
+  const dir = await mkdtemp(join(tmpdir(), "vision-usage-"));
+  const logPath = join(dir, "usage.jsonl");
+  const controller = new VisionFallbackController(
+    createServiceContext(),
+    () => ({ ...config, recordUsage: true, usageLogPath: logPath })
+  );
+  const messages = [userMessage("u1", [{ type: "text", text: "这个按钮是什么？" }, { type: "image", attachment }])];
+  try {
+    await controller.preprocess(messages, messages, undefined);
+    const lines = (await readFile(logPath, "utf8")).trim().split("\n");
+    assert.equal(lines.length, 1);
+    const entry = JSON.parse(lines[0]);
+    assert.equal(entry.status, "ok");
+    assert.equal(entry.kind, "vision");
+    assert.equal(entry.model, "vision-model");
+    assert.equal(entry.inputTokens, 100);
+    assert.equal(entry.outputTokens, 50);
+    assert.equal(entry.cacheReadTokens, 10);
+    assert.equal(entry.imageName, "error.png");
+    assert.equal(entry.mediaType, "image/png");
+    assert.equal(entry.imageBytes, 3);
+    assert.equal(entry.imageIndex, 1);
+    assert.equal(entry.imageTotal, 1);
+    assert.equal(typeof entry.ts, "number");
+    assert.equal(typeof entry.durationMs, "number");
+    assert.ok(entry.durationMs >= 0, "durationMs 不应为负");
+  } finally {
+    globalThis.fetch = previousFetch;
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("usage 记录失败调用并带错误信息", async () => {
+  const previousFetch = globalThis.fetch;
+  globalThis.fetch = async () => ({
+    ok: false,
+    status: 500,
+    statusText: "Internal Server Error",
+    text: async () => "boom"
+  });
+  const dir = await mkdtemp(join(tmpdir(), "vision-usage-err-"));
+  const logPath = join(dir, "usage.jsonl");
+  const controller = new VisionFallbackController(
+    createServiceContext(),
+    () => ({ ...config, recordUsage: true, usageLogPath: logPath })
+  );
+  const messages = [userMessage("u1", [{ type: "text", text: "看这张图" }, { type: "image", attachment }])];
+  try {
+    const [rewritten] = await controller.preprocess(messages, messages, undefined);
+    assert.match(rewritten.content[1].text, /图片转换失败/);
+    const lines = (await readFile(logPath, "utf8")).trim().split("\n");
+    assert.equal(lines.length, 1);
+    const entry = JSON.parse(lines[0]);
+    assert.equal(entry.status, "error");
+    assert.equal(entry.kind, "vision");
+    assert.equal(entry.inputTokens, 0);
+    assert.equal(entry.outputTokens, 0);
+    assert.match(entry.error, /500/);
+    assert.equal(entry.imageName, "error.png");
+    assert.equal(typeof entry.durationMs, "number");
+    assert.ok(entry.durationMs >= 0, "失败记录的 durationMs 不应为负");
+  } finally {
+    globalThis.fetch = previousFetch;
+    await rm(dir, { recursive: true, force: true });
+  }
+});