dsh-vision-fallback 0.7.0 → 0.9.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.9.1 - 2026-08-18
+
+- Added the `dsh-plugin` npm keyword and a regression test for the installable DSH bundle manifest.
+- Expanded the documentation for compaction reuse, tool-result images, persistent observations, and restart recovery.
+
+## 0.9.0 - 2026-08-16
+
+- Persisted successful observations to `observations.json` and reused them across restart, replay, and compaction.
+- Scoped observations by session and message position so a newly posted copy of the same image can be analyzed again with fresh context.
+- Recorded vision-call latency, status, image metadata, and token usage in `usage.jsonl`.
+
+## 0.7.0 - 2026-08-14
+
+- Kept the selected main model in control while silently routing image understanding to the configured vision model.

package/README.md

@@ -31,6 +31,14 @@ agent/pre-step ──► image + current question + recent context
 4. A **model-only surface replacement** swaps the image for the vision observation before the request reaches the main model.
 5. Switching the main model (DeepSeek, Kimi, MiniMax, ...) never changes the fixed vision model.
 
+### Complete call paths
+
+- **Normal conversations**: `agent/pre-step` processes images before the main-model request and projects observations into the model view.
+- **Context compaction**: the `llm/stream` path with `purpose: "compaction"` reuses existing observations first and only describes genuinely unseen images.
+- **Tool-result images**: images inside `tool/result` events are projected for the model while the original tool result remains visible and traceable in the UI.
+- **Reloads and restarts**: observations are persisted to `observations.json`, so the same session/message position does not trigger another vision call after restart.
+- **Model capability detection**: in `auto` mode the plugin reads the main model's real `inputModalities`; it stays out of the way for image-capable models and bridges only text-only routes.
+
 ## Install
 
 ### From npm / local checkout
@@ -47,7 +55,7 @@ dsh plugin --profile web add dsh-vision-fallback
 git clone https://github.com/1HelloMan1/dsh-vision-fallback.git
 cd dsh-vision-fallback
 pnpm install --config.minimumReleaseAge=0   # rc.6 peers need the release-age flag bypassed
-pnpm test                                    # 10 unit tests
+pnpm test                                    # 22 unit tests
 dsh plugin --profile web add "$PWD"
 ```
 
@@ -106,6 +114,44 @@ 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.
+
+Cache location: when `usageLogPath` is set, `observations.json` is written beside that log; otherwise it is stored at
+`<dshHome>/vision-fallback/observations.json`. This lets compaction, event replay, and service restarts reuse successful observations.
+
+### Compaction, tool results, and restarts
+
+When the main model can already see images, the bridge does not call the vision model. If a later text-only compaction model encounters the original image event, the plugin first reuses the main model's projected observation and the persistent cache, then handles only images that truly have no observation. This prevents every compaction from re-describing the entire image history while still allowing the same image at a new message position to be re-read with fresh context.
+
 ## Default vision route
 
 - Model: `mimo-v2.5` · Endpoint: `https://opencode.ai/zen/go/v1/chat/completions` · Credential: `OPENCODE_GO_API_KEY`
@@ -119,7 +165,7 @@ The OpenCode community `opencode-see-image` hands a `filePath` + task `question`
 ## Development
 
 ```sh
-pnpm test    # node --test test/*.test.mjs — 10 tests
+pnpm test    # node --test test/*.test.mjs — 22 tests
 ```
 
 Structure:

package/README.zh.md

@@ -31,6 +31,14 @@ agent/pre-step ──► 图片 + 当前问题 + 最近上下文
 4. **仅模型可见的 surface replacement** 把图片换成视觉观察后再交给主模型。
 5. 切换主模型（DeepSeek、Kimi、MiniMax……）不会改变固定视觉模型。
 
+### 完整调用线路
+
+- **普通对话**：`agent/pre-step` 在主模型请求前处理图片，并把视觉观察投影到模型视图。
+- **上下文压缩**：`llm/stream` 的 `purpose: "compaction"` 线路会先复用已有观察；只有确实没有观察的图片才补一次识别。
+- **工具结果图片**：`tool/result` 中的图片也会进入模型投影，界面仍保留原始图片，不把工具结果改成用户不可追溯的纯文本。
+- **会话重载 / 重启**：观察结果持久化到 `observations.json`，重启后同一会话、同一消息位置不会再次调用视觉模型。
+- **模型能力判断**：`auto` 模式会读取主模型的真实 `inputModalities`；主模型原生支持图片时不重复接管，纯文本主模型才走视觉桥。
+
 ## 安装
 
 ### npm / 本地检出
@@ -47,7 +55,7 @@ dsh plugin --profile web add dsh-vision-fallback
 git clone https://github.com/1HelloMan1/dsh-vision-fallback.git
 cd dsh-vision-fallback
 pnpm install --config.minimumReleaseAge=0   # rc.6 peer 依赖需绕过发布年龄策略
-pnpm test                                    # 10 个单元测试
+pnpm test                                    # 22 个单元测试
 dsh plugin --profile web add "$PWD"
 ```
 
@@ -106,6 +114,44 @@ 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 淘汰），失败结果不入缓存。
+
+缓存文件位置：如果设置了 `usageLogPath`，缓存写在同一目录的 `observations.json`；否则使用
+`<dshHome>/vision-fallback/observations.json`。因此压缩、事件回放和服务重启都可以复用已经成功得到的观察。
+
+### 压缩、工具结果与重启
+
+主模型能看图时，视觉桥不会重复调用视觉模型；但如果后续使用纯文本压缩模型，压缩线路可能再次遇到原始图片。插件会优先复用主模型已有的视觉投影和持久化观察，再处理真正没有结果的图片。这样可以避免“每次压缩重新识别整段历史图片”，同时保留新消息位置重新识别的能力。
+
 ## 默认视觉路由
 
 - 模型：`mimo-v2.5` · 端点：`https://opencode.ai/zen/go/v1/chat/completions` · 凭据：`OPENCODE_GO_API_KEY`
@@ -119,7 +165,7 @@ OpenCode 社区的 `opencode-see-image` 把 `filePath` 和针对当前任务的
 ## 开发
 
 ```sh
-pnpm test    # node --test test/*.test.mjs — 10 个测试
+pnpm test    # node --test test/*.test.mjs — 22 个测试
 ```
 
 目录结构：

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";
@@ -161,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 = [];
@@ -205,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 !== ""
@@ -216,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) {
@@ -257,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 服务不可用，无法读取聊天图片");
@@ -323,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;
     }
@@ -367,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
       )
     });
   }
@@ -393,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)}】`;
@@ -468,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);
@@ -527,6 +716,41 @@ async function modelActuallySupportsImage(provider, model, signal) {
   }
 }
 
+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;
@@ -552,11 +776,41 @@ function apply(ctx, config) {
       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.7.0",
+  "version": "0.9.1",
   "description": "DSH 静默视觉增强：主模型照常选择，图片自动交给固定视觉模型后以隐藏上下文返回主模型。",
   "type": "module",
   "main": "lib/index.js",
@@ -13,6 +13,7 @@
     "lib",
     "test",
     "cordis.patch.yml",
+    "CHANGELOG.md",
     "README.md",
     "README.zh.md"
   ],
@@ -33,6 +34,7 @@
   },
   "keywords": [
     "dsh",
+    "dsh-plugin",
     "deepseek-harness",
     "vision",
     "image",

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");
@@ -577,3 +586,386 @@ test("auto 模式按主模型真实视觉能力决定是否接管", async () =>
 
   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 });
+  }
+});
+
+test("npm 包声明可安装的 DSH bundle 和市场关键词", async () => {
+  const manifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  const patch = await readFile(new URL("../cordis.patch.yml", import.meta.url), "utf8");
+
+  assert.equal(manifest.dsh?.bundle?.patch, "./cordis.patch.yml");
+  assert.ok(manifest.files.includes("cordis.patch.yml"));
+  assert.ok(manifest.keywords.includes("dsh-plugin"));
+  assert.match(patch, /id:\s*vision-fallback/);
+  assert.match(patch, /name:\s*['"]dsh-vision-fallback['"]/);
+});