dsh-vision-fallback 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.10.0 - 2026-09-03
+
+- Adapted Host listeners to the current Cordis effect lifecycle.
+- Stopped mutating frozen `llm/stream` requests and rerouted compaction with a copied request.
+- Added explicit DSH Store compatibility metadata for `0.1.2-alpha.3`, `0.1.2-alpha.4`, and `0.1.2-alpha.5`.
+- Declared the supported Node.js and DSH ranges and expanded bundle manifest coverage.
+
 ## 0.9.1 - 2026-08-18
 
 - Added the `dsh-plugin` npm keyword and a regression test for the installable DSH bundle manifest.

package/README.md

@@ -4,6 +4,8 @@
 
 Silent vision enhancement for [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness): keep your real text-only main model (e.g. `deepseek-v4-flash`), and let chat images "just work" — every image you drop, paste, or reference in the chat box is automatically sent to a fixed vision model, converted into a factual text observation, and handed to your main model as hidden context. The UI keeps showing your original image; no model groups, no model switching, no extra tools.
 
+Compatible with the current DSH Store window: `0.1.2-alpha.3`, `0.1.2-alpha.4`, and `0.1.2-alpha.5`. Durable MCP / ACP image attachments and nested images forwarded by PTC Mode use the same vision bridge. When enabled, the plugin intentionally keeps advertising image input; otherwise the chat composer rejects the image before it can reach the bridge.
+
 ## Why
 
 - DeepSeek V4 Flash / Pro and other strong coding models are **text-only**: dropping an image into the chat box fails with "model does not support image input".
@@ -31,13 +33,28 @@ 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
+### MCP / ACP / PTC images
+
+DSH `0.1.0-rc.7` persists images produced by MCP, ACP, and PTC as durable attachments, then exposes them as core `image` content blocks. This plugin recursively handles images in ordinary messages, `tool-result`, and nested `tool-result` content while preserving the original text/image order:
+
+- MCP / ACP durable attachments are read by `attachmentId`, not temporary file paths;
+- nested PTC subtool images are converted into vision observations;
+- multiple images are sent to the vision model in their original order;
+- only the model-visible surface is replaced, so the original UI image remains intact.
+
+The image-capability override is an intentional entry-point compatibility layer. It does not claim that the main model has native visual reasoning; it lets the image reach DSH so the bridge can convert it into text context.
 
-- **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.
+### DSH compatibility evidence
+
+Verified on 2026-09-03 with Node.js `24.16.0` and a separate disposable `DSH_HOME` for each release:
+
+| DSH release | Local-path install | `--dump-config` | Authenticated cold start | Uninstall |
+| --- | --- | --- | --- | --- |
+| `0.1.2-alpha.3` | passed | passed | HTTP 200 | passed |
+| `0.1.2-alpha.4` | passed | passed | HTTP 200 | passed |
+| `0.1.2-alpha.5` | passed | passed | HTTP 200 | passed |
+
+The Profile operations use the official CLI with `plugin --profile web add -w <local-path>` and `remove -w dsh-vision-fallback`. The runtime fix does not mutate the deep-frozen `llm/stream` request introduced by current DSH builds; compaction creates a copied request and performs one guarded nested dispatch.
 
 ## Install
 
@@ -54,8 +71,8 @@ dsh plugin --profile web add dsh-vision-fallback
 ```sh
 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                                    # 22 unit tests
+pnpm install --config.minimumReleaseAge=0   # pre-release peers may need the release-age flag bypassed
+pnpm test                                    # node --test test/*.test.mjs
 dsh plugin --profile web add "$PWD"
 ```
 
@@ -82,7 +99,7 @@ Open **Settings → 视觉增强 / Vision Enhancement** in the DSH web UI. It ex
 | Vision model | `mimo-v2.5` | OpenAI-compatible `model` |
 | Base URL | `https://opencode.ai/zen/go/v1` | The plugin appends `/chat/completions` |
 | Credential ref | `OPENCODE_GO_API_KEY` | Key resolved from the DSH credential store (never written to env files) |
-| Max tokens / Timeout / Max bytes | `1536` / `60000` / `15MB` | Vision request limits |
+| Max tokens / Timeout / Max bytes | `1536` / `60000` / `15MB` | Vision request limits; oversized images fail |
 | Recent context | `includeRecentContext: true`, `contextMessages: 6`, `contextMaxChars: 6000` | How much recent chat to attach for the vision model |
 | Prompt | (Chinese detailed-analysis prompt) | Analysis instruction; the user's question is appended automatically |
 | Tag result | `true` | Prepend `【视觉观察：<model>】` to the observation |
@@ -145,12 +162,9 @@ Observations are keyed by **the image's occurrence in a session** (session id +
 
 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
+### About image compression
 
-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.
+In the current version, “compression” means **reusing an existing vision observation during conversation-context compaction**; it does not re-run vision analysis. The plugin does not yet resize, transcode, or quality-compress image files. Images above `maxBytes` fail explicitly instead of being silently changed. A future real image-compression feature should report the before/after byte counts and media type.
 
 ## Default vision route
 
@@ -165,7 +179,7 @@ The OpenCode community `opencode-see-image` hands a `filePath` + task `question`
 ## Development
 
 ```sh
-pnpm test    # node --test test/*.test.mjs — 22 tests
+pnpm test    # node --test test/*.test.mjs
 ```
 
 Structure:

package/README.zh.md

@@ -4,6 +4,8 @@
 
 为 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 提供**全局静默视觉增强**：你继续在会话顶部直接选择真实主模型（如 `deepseek-v4-flash`），聊天框里拖入、粘贴、引用的图片会自动交给固定视觉模型，转成事实性文字观察后作为隐藏上下文交给主模型。界面始终显示你的原始图片——不新增"视觉回退"模型分组、不切换模型、不调用额外工具。
 
+兼容当前 DSH STORE 版本窗口：`0.1.2-alpha.3`、`0.1.2-alpha.4`、`0.1.2-alpha.5`。MCP / ACP 的持久图片附件，以及 PTC Mode 转发的嵌套图片，都会沿用同一套视觉桥处理。插件启用时会保留图片能力声明；否则聊天框会在图片到达视觉桥之前直接提示“模型不支持图片输入”。
+
 ## 为什么需要
 
 - DeepSeek V4 Flash/Pro 等强编码模型是**纯文本**的：聊天框发图会直接报"模型不支持图片输入"。
@@ -31,13 +33,28 @@ agent/pre-step ──► 图片 + 当前问题 + 最近上下文
 4. **仅模型可见的 surface replacement** 把图片换成视觉观察后再交给主模型。
 5. 切换主模型（DeepSeek、Kimi、MiniMax……）不会改变固定视觉模型。
 
-### 完整调用线路
+### MCP / ACP / PTC 图片
+
+DSH `0.1.0-rc.7` 会把 MCP、ACP 和 PTC 产生的图片保存为持久附件，再以核心 `image` 内容块交给后续链路。本插件会递归处理普通消息、`tool-result` 和多层嵌套 `tool-result` 中的图片，并保持图片与文字的原始顺序：
+
+- MCP / ACP 持久附件：按 `attachmentId` 读取，不依赖临时文件路径；
+- PTC 嵌套图片：子调用返回的图片也会转换为视觉观察；
+- 多张图片：逐张调用视觉模型，观察结果对应原始出现顺序；
+- 原始界面：只替换模型视图，聊天界面仍保留原图。
+
+插件的图片能力声明是必要的入口兼容层。它不是说主模型真的具备视觉推理能力，而是允许图片先进入 DSH，再由视觉桥转成主模型可用的文字上下文。
 
-- **普通对话**：`agent/pre-step` 在主模型请求前处理图片，并把视觉观察投影到模型视图。
-- **上下文压缩**：`llm/stream` 的 `purpose: "compaction"` 线路会先复用已有观察；只有确实没有观察的图片才补一次识别。
-- **工具结果图片**：`tool/result` 中的图片也会进入模型投影，界面仍保留原始图片，不把工具结果改成用户不可追溯的纯文本。
-- **会话重载 / 重启**：观察结果持久化到 `observations.json`，重启后同一会话、同一消息位置不会再次调用视觉模型。
-- **模型能力判断**：`auto` 模式会读取主模型的真实 `inputModalities`；主模型原生支持图片时不重复接管，纯文本主模型才走视觉桥。
+### DSH 兼容性证据
+
+2026-09-03 使用 Node.js `24.16.0` 验证，每个版本均使用独立的一次性 `DSH_HOME`：
+
+| DSH 版本 | 本地路径安装 | `--dump-config` | 带认证冷启动 | 卸载 |
+| --- | --- | --- | --- | --- |
+| `0.1.2-alpha.3` | 通过 | 通过 | HTTP 200 | 通过 |
+| `0.1.2-alpha.4` | 通过 | 通过 | HTTP 200 | 通过 |
+| `0.1.2-alpha.5` | 通过 | 通过 | HTTP 200 | 通过 |
+
+Profile 操作使用官方 CLI：`plugin --profile web add -w <local-path>` 和 `remove -w dsh-vision-fallback`。新版 DSH 会深冻结 `llm/stream` 请求，插件不再原地修改它；上下文压缩会复制请求并执行一次带重入保护的嵌套分发。
 
 ## 安装
 
@@ -54,8 +71,8 @@ dsh plugin --profile web add dsh-vision-fallback
 ```sh
 git clone https://github.com/1HelloMan1/dsh-vision-fallback.git
 cd dsh-vision-fallback
-pnpm install --config.minimumReleaseAge=0   # rc.6 peer 依赖需绕过发布年龄策略
-pnpm test                                    # 22 个单元测试
+pnpm install --config.minimumReleaseAge=0   # 预发布 peer 依赖可能需绕过发布年龄策略
+pnpm test                                    # node --test test/*.test.mjs
 dsh plugin --profile web add "$PWD"
 ```
 
@@ -82,7 +99,7 @@ dsh --profile web --dump-config   # 应出现 "# == dsh-vision-fallback" 层
 | 视觉模型 | `mimo-v2.5` | OpenAI 兼容 `model` |
 | API 地址 | `https://opencode.ai/zen/go/v1` | 插件自动拼 `/chat/completions` |
 | 凭据引用 | `OPENCODE_GO_API_KEY` | 从 DSH 凭证系统解析（不写入环境变量） |
-| 输出上限 / 超时 / 图片上限 | `1536` / `60000` / `15MB` | 视觉请求限制 |
+| 输出上限 / 超时 / 图片上限 | `1536` / `60000` / `15MB` | 视觉请求限制；超过图片上限会失败 |
 | 最近上下文 | `includeRecentContext: true`、`contextMessages: 6`、`contextMaxChars: 6000` | 附带多少最近对话给视觉模型 |
 | 提示词 | （中文详细分析） | 分析指令；用户问题自动追加 |
 | 结果标注 | `true` | 观察前加 `【视觉观察：<model>】` |
@@ -145,12 +162,9 @@ API key 通过 DSH **凭证系统**（`~/.dsh/.credentials.yaml`）解析，`pro
 
 缓存上限 256 条（LRU 淘汰），失败结果不入缓存。
 
-缓存文件位置：如果设置了 `usageLogPath`，缓存写在同一目录的 `observations.json`；否则使用
-`<dshHome>/vision-fallback/observations.json`。因此压缩、事件回放和服务重启都可以复用已经成功得到的观察。
-
-### 压缩、工具结果与重启
+### 关于图片压缩
 
-主模型能看图时，视觉桥不会重复调用视觉模型；但如果后续使用纯文本压缩模型，压缩线路可能再次遇到原始图片。插件会优先复用主模型已有的视觉投影和持久化观察，再处理真正没有结果的图片。这样可以避免“每次压缩重新识别整段历史图片”，同时保留新消息位置重新识别的能力。
+当前版本的“压缩”指**上下文压缩时复用已经得到的视觉观察**，不会重新识图；插件暂时不会对图片文件做缩放、转码或质量压缩。图片超过 `maxBytes` 时会直接报告失败，不会静默改变原图。后续如增加真正的图片压缩，会单独记录压缩前后字节数和媒体类型。
 
 ## 默认视觉路由
 
@@ -165,7 +179,7 @@ OpenCode 社区的 `opencode-see-image` 把 `filePath` 和针对当前任务的
 ## 开发
 
 ```sh
-pnpm test    # node --test test/*.test.mjs — 22 个测试
+pnpm test    # node --test test/*.test.mjs
 ```
 
 目录结构：

package/lib/index.js

@@ -12,12 +12,11 @@ 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";
-import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "@deepseek-ai/schemastery";
 
 const name = "vision-fallback";
 const inject = ["llm"];
-const NS = settingsNamespace("vision-fallback");
+const NS = "vision-fallback";
 const CONFIG_ROUTE = "/plugins/dsh-vision-fallback/config";
 const MAX_CONFIG_BODY_BYTES = 64 * 1024;
 
@@ -128,6 +127,32 @@ function installConfigRoute(ctx, current, settingsSource) {
   });
 }
 
+function installSettingsSectionCompat(ctx, ns, schema, entry, hooks) {
+  ctx.inject(["settings"], (sctx) => {
+    if (typeof sctx.settings.installSection === "function") {
+      sctx.settings.installSection(ctx, ns, schema, entry, hooks);
+      return;
+    }
+
+    const scope = sctx.settings.register(ns, schema, {
+      base: entry,
+      ...(hooks.validate === undefined ? {} : { validate: hooks.validate })
+    });
+    const ownerIsUnloading = () => ctx.fiber !== undefined && (ctx.fiber.state === 4 || ctx.fiber.state === 5);
+    hooks.setSource(() => scope.get());
+    hooks.onChange();
+    const disposeWatch = scope.watch(() => {
+      if (!ownerIsUnloading()) hooks.onChange();
+    });
+    sctx.effect(() => disposeWatch, `vision-fallback: 停止监听 ${ns} 设置`);
+    sctx.effect(() => () => {
+      if (ownerIsUnloading()) return;
+      hooks.setSource(() => entry);
+      hooks.onChange();
+    }, `vision-fallback: 释放 ${ns} 设置源`);
+  });
+}
+
 function contentHasImage(content) {
   return content.some(
     (block) => block?.type === "image" ||
@@ -757,13 +782,17 @@ function apply(ctx, config) {
   const controller = new VisionFallbackController(ctx, () => current());
   const replacements = new ReplacementCoordinator(ctx.logger);
   const restoreCapability = installCapabilityOverride(ctx, () => current());
+  const reroutedCompactionRequests = new WeakSet();
 
   ctx.effect(() => () => {
     replacements.dispose();
     restoreCapability();
   }, "vision-fallback: 恢复模型图片能力检查与消息投影");
-  ctx.on("session/event", (session, event) => replacements.onSessionEvent(session, event));
-  ctx.on("agent/pre-step", async ({ agent, signal }, next) => {
+  ctx.effect(
+    () => ctx.on("session/event", (session, event) => replacements.onSessionEvent(session, event)),
+    "vision-fallback: 监听会话图片事件"
+  );
+  ctx.effect(() => ctx.on("agent/pre-step", async ({ agent, signal }, next) => {
     const decision = await next();
     if (decision.kind === "reject" || signal.aborted) return decision;
     const cfg = current();
@@ -780,10 +809,10 @@ function apply(ctx, config) {
     replacements.stage(agent.session, modelMessages, rewritten);
     replacements.flush(agent.session);
     return decision;
-  });
+  }), "vision-fallback: 发送前生成视觉观察");
 
-  ctx.on("llm/stream", (options, next) => (async function* () {
-    if (options.purpose !== "compaction") {
+  ctx.effect(() => ctx.on("llm/stream", (options, next) => (async function* () {
+    if (reroutedCompactionRequests.has(options) || options.purpose !== "compaction") {
       yield* next();
       return;
     }
@@ -805,11 +834,24 @@ function apply(ctx, config) {
       resolveSession(ctx, options.sessionId),
       replacements
     );
-    options.messages = projected.some((message) => contentHasImage(message.content ?? []))
+    const messages = projected.some((message) => contentHasImage(message.content ?? []))
       ? await replaceLeftoverCompactionImages(projected, controller, options.sessionId)
       : projected;
-    yield* next();
-  })(), { global: true, prepend: true });
+    if (messages === options.messages) {
+      yield* next();
+      return;
+    }
+
+    // DSH 0.1.2-alpha.5 起 LOOP 请求为深冻结只读对象。通过一次受控的
+    // 嵌套 stream 传入新请求，避免修改原对象；WeakSet 防止再次进入本桥。
+    const rerouted = { ...options, messages };
+    reroutedCompactionRequests.add(rerouted);
+    try {
+      yield* ctx.llm.stream(rerouted);
+    } finally {
+      reroutedCompactionRequests.delete(rerouted);
+    }
+  })(), { global: true, prepend: true }), "vision-fallback: 压缩时复用视觉观察");
 
   ctx.inject(["settings"], (sctx) => {
     settingsService = sctx.settings;
@@ -817,7 +859,7 @@ function apply(ctx, config) {
       if (settingsService === sctx.settings) settingsService = undefined;
     }, "vision-fallback: 释放 Settings 服务引用");
   });
-  installSettingsSection(ctx, NS, Config, config, {
+  installSettingsSectionCompat(ctx, NS, Config, config, {
     validate: assertVisionConfig,
     setSource: (source) => {
       current = source;
@@ -838,6 +880,7 @@ export {
   inject,
   installCapabilityOverride,
   installConfigRoute,
+  installSettingsSectionCompat,
   name,
   rewriteMessages,
   withImageCapability

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vision-fallback",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "DSH 静默视觉增强：主模型照常选择，图片自动交给固定视觉模型后以隐藏上下文返回主模型。",
   "type": "module",
   "main": "lib/index.js",
@@ -46,6 +46,14 @@
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
+    "compatibility": {
+      "dsh": ">=0.1.1-rc.2 <0.2.0",
+      "dshReleases": {
+        "0.1.2-alpha.3": "compatible",
+        "0.1.2-alpha.4": "compatible",
+        "0.1.2-alpha.5": "compatible"
+      }
+    },
     "client": {
       "inject": [
         "@deepseek-ai/dsh-client-connection",
@@ -55,13 +63,16 @@
       "platform": "web"
     }
   },
+  "engines": {
+    "node": ">=22.13.0"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-attachment": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.2 <0.1.2 || >=0.1.2-alpha.3 <0.2.0",
+    "@deepseek-ai/dsh-attachment": ">=0.1.1-rc.2 <0.1.2 || >=0.1.2-alpha.3 <0.2.0",
+    "@deepseek-ai/dsh-settings": ">=0.1.1-rc.2 <0.1.2 || >=0.1.2-alpha.3 <0.2.0",
+    "@deepseek-ai/dsh-credentials": ">=0.1.1-rc.2 <0.1.2 || >=0.1.2-alpha.3 <0.2.0",
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-home-paths": ">=0.1.1-rc.2 <0.1.2 || >=0.1.2-alpha.3 <0.2.0"
   }
 }

package/test/vision-fallback.test.mjs

@@ -4,12 +4,14 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import {
+  Config,
   CONFIG_ROUTE,
   ReplacementCoordinator,
   VisionFallbackController,
   apply,
   buildVisionPrompt,
   installCapabilityOverride,
+  installSettingsSectionCompat,
   rewriteMessages,
   withImageCapability
 } from "../lib/index.js";
@@ -252,6 +254,64 @@ test("历史工具结果中的图片只以文字形式进入模型视图", async
   }
 });
 
+test("rc.7 持久附件引用与 PTC 多层嵌套图片按顺序转换", async () => {
+  const originalFetch = globalThis.fetch;
+  const visionRequests = [];
+  globalThis.fetch = async (_url, options) => {
+    visionRequests.push(JSON.parse(options.body));
+    return {
+      ok: true,
+      json: async () => ({ choices: [{ message: { content: `视觉观察 ${visionRequests.length}` } }] })
+    };
+  };
+  const firstAttachment = {
+    attachmentId: "sha256:rc7-mcp-image",
+    mediaType: "image/png",
+    name: "mcp-result.png"
+  };
+  const nestedAttachment = {
+    attachmentId: "sha256:rc7-ptc-image",
+    mediaType: "image/jpeg",
+    name: "ptc-nested.jpg"
+  };
+  const original = userMessage("rc7-rich-result", [
+    { type: "text", text: "工具返回了两张图：" },
+    { type: "image", attachment: firstAttachment },
+    {
+      type: "tool-result",
+      toolCallId: "mcp-read-image",
+      content: [
+        { type: "text", text: "PTC 子调用结果" },
+        {
+          type: "tool-result",
+          toolCallId: "ptc-read-image",
+          content: [{ type: "image", attachment: nestedAttachment }],
+          isError: false
+        }
+      ],
+      isError: false
+    },
+    { type: "text", text: "请按出现顺序说明。" }
+  ]);
+  const controller = new VisionFallbackController(createServiceContext(), () => config);
+
+  try {
+    const [rewritten] = await controller.preprocess([original], [original], undefined, "rc7-session");
+    assert.equal(visionRequests.length, 2);
+    assert.equal(visionRequests[0].messages[1].content[1].image_url.url.startsWith("data:image/png;base64,"), true);
+    assert.equal(visionRequests[1].messages[1].content[1].image_url.url.startsWith("data:image/jpeg;base64,"), true);
+    assert.equal(rewritten.content[0].text, "工具返回了两张图：");
+    assert.match(rewritten.content[1].text, /视觉观察 1/);
+    assert.equal(rewritten.content[2].content[0].text, "PTC 子调用结果");
+    assert.match(rewritten.content[2].content[1].content[0].text, /视觉观察 2/);
+    assert.equal(JSON.stringify(rewritten).includes('"type":"image"'), false);
+    assert.equal(original.content[1].type, "image");
+    assert.equal(original.content[2].content[1].content[0].type, "image");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 test("图片能力覆盖可随开关变化并能恢复", async () => {
   let current = config;
   const original = async (provider, model) => ({
@@ -339,13 +399,41 @@ test("插件注册静默预处理钩子而不注册新模型 adapter", () => {
   assert.equal(typeof cleanup, "function");
   assert.equal(registeredSettings.namespace, "vision-fallback");
   assert.equal(registeredSettings.options.base, config);
-  assert.equal(settingsEffects.length, 2);
+  assert.equal(settingsEffects.length, 3);
   assert.equal(webEffects.length, 1);
   assert.equal(registeredRoute.kind, "exact");
   assert.equal(registeredRoute.path, CONFIG_ROUTE);
   assert.equal(replacements.length, 0);
 });
 
+test("alpha.5 使用 SettingsProvider.installSection 注册设置", () => {
+  let installed;
+  const ctx = {
+    inject(dependencies, callback) {
+      assert.deepEqual(dependencies, ["settings"]);
+      callback({
+        settings: {
+          installSection(...args) {
+            installed = args;
+          }
+        }
+      });
+    }
+  };
+  const hooks = {
+    validate: assert.doesNotThrow,
+    setSource() {},
+    onChange() {}
+  };
+
+  installSettingsSectionCompat(ctx, "vision-fallback", Config, config, hooks);
+  assert.equal(installed[0], ctx);
+  assert.equal(installed[1], "vision-fallback");
+  assert.equal(installed[2], Config);
+  assert.equal(installed[3], config);
+  assert.equal(installed[4], hooks);
+});
+
 test("插件私有配置路由允许本机读取和保存", async () => {
   let route;
   let stored = config;
@@ -518,7 +606,7 @@ test("auto 模式按主模型真实视觉能力决定是否接管", async () =>
         resolveModelInfo: async () => ({ provider: "opencode-go", id: "x", name: "x", inputModalities: realModalities })
       },
       logger: { error() {} },
-      effect() {},
+      effect(factory) { factory(); },
       on(name, handler) {
         if (name === "agent/pre-step") preStep = handler;
       },
@@ -528,10 +616,10 @@ test("auto 模式按主模型真实视觉能力决定是否接管", async () =>
             settings: {
               register: (_ns, _schema, options) => ({ get: () => options.base, watch() {} })
             },
-            effect() {}
+            effect(factory) { factory(); }
           });
         } else {
-          cb({ webServer: { register: () => () => {} }, effect() {} });
+          cb({ webServer: { register: () => () => {} }, effect(factory) { factory(); } });
         }
       },
       get(name) {
@@ -706,12 +794,17 @@ test("compaction 请求不再重新识图，普通请求保持原样", async ()
 
   const makeSignal = () => ({ aborted: false, addEventListener() {}, removeEventListener() {} });
   let streamHandler;
+  const rerouted = [];
   const ctx = {
     llm: {
-      resolveModelInfo: async () => ({ provider: "opencode-go", id: "deepseek-v4-flash", name: "deepseek-v4-flash", inputModalities: ["text"] })
+      resolveModelInfo: async () => ({ provider: "opencode-go", id: "deepseek-v4-flash", name: "deepseek-v4-flash", inputModalities: ["text"] }),
+      stream(options) {
+        rerouted.push(options);
+        return emptyStream();
+      }
     },
     logger: { error() {} },
-    effect() {},
+    effect(factory) { factory(); },
     on(name, handler) {
       if (name === "llm/stream") streamHandler = handler;
     },
@@ -721,10 +814,10 @@ test("compaction 请求不再重新识图，普通请求保持原样", async ()
           settings: {
             register: (_ns, _schema, options) => ({ get: () => options.base, watch() {} })
           },
-          effect() {}
+          effect(factory) { factory(); }
         });
       } else {
-        cb({ webServer: { register: () => () => {} }, effect() {} });
+        cb({ webServer: { register: () => () => {} }, effect(factory) { factory(); } });
       }
     },
     get(name) {
@@ -742,19 +835,21 @@ test("compaction 请求不再重新识图，普通请求保持原样", async ()
     apply(ctx, { ...config, mode: "auto" });
     assert.equal(typeof streamHandler, "function");
 
-    const compactionOptions = {
+    const compactionOptions = Object.freeze({
       purpose: "compaction",
       provider: "opencode-go",
       model: "deepseek-v4-flash",
       signal: makeSignal(),
-      messages: [userMessage("compact-1", [{ type: "text", text: "请压缩上下文" }, imageBlock])]
-    };
+      messages: Object.freeze([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, /主模型已直接查看原图/);
+    assert.equal(JSON.stringify(compactionOptions.messages).includes('"type":"image"'), true);
+    assert.equal(rerouted.length, 1);
+    assert.equal(JSON.stringify(rerouted[0].messages).includes('"type":"image"'), false);
+    assert.match(rerouted[0].messages[0].content[1].text, /主模型已直接查看原图/);
 
     const normalOptions = {
       purpose: undefined,
@@ -767,6 +862,7 @@ test("compaction 请求不再重新识图，普通请求保持原样", async ()
     await consumeStream(streamHandler(normalOptions, emptyStream));
     assert.equal(JSON.stringify(normalOptions.messages), before);
     assert.equal(visionRequests, 0);
+    assert.equal(rerouted.length, 1);
   } finally {
     globalThis.fetch = previousFetch;
   }
@@ -784,6 +880,7 @@ test("压缩优先复用主模型已经拿到的视觉观察", async () => {
   };
   const makeSignal = () => ({ aborted: false, addEventListener() {}, removeEventListener() {} });
   let streamHandler;
+  const rerouted = [];
   const session = {
     deriveMessages: () => [rewritten]
   };
@@ -795,18 +892,22 @@ test("压缩优先复用主模型已经拿到的视觉观察", async () => {
       }
     },
     llm: {
-      resolveModelInfo: async () => ({ provider: "opencode-go", id: "deepseek-v4-flash", name: "deepseek-v4-flash", inputModalities: ["text"] })
+      resolveModelInfo: async () => ({ provider: "opencode-go", id: "deepseek-v4-flash", name: "deepseek-v4-flash", inputModalities: ["text"] }),
+      stream(options) {
+        rerouted.push(options);
+        return emptyStream();
+      }
     },
     logger: { error() {} },
-    effect() {},
+    effect(factory) { factory(); },
     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() {} });
+        cb({ settings: { register: (_ns, _schema, options) => ({ get: () => options.base, watch() {} }) }, effect(factory) { factory(); } });
       } else {
-        cb({ webServer: { register: () => () => {} }, effect() {} });
+        cb({ webServer: { register: () => () => {} }, effect(factory) { factory(); } });
       }
     },
     get() {
@@ -816,18 +917,21 @@ test("压缩优先复用主模型已经拿到的视觉观察", async () => {
 
   try {
     apply(ctx, { ...config, mode: "auto" });
-    const options = {
+    const options = Object.freeze({
       purpose: "compaction",
       sessionId: "session-reuse",
       provider: "opencode-go",
       model: "deepseek-v4-flash",
       signal: makeSignal(),
-      messages: [original]
-    };
+      messages: Object.freeze([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);
+    assert.equal(options.messages[0], original);
+    assert.equal(JSON.stringify(options.messages).includes('"type":"image"'), true);
+    assert.equal(rerouted.length, 1);
+    assert.equal(rerouted[0].messages[0], rewritten);
+    assert.equal(JSON.stringify(rerouted[0].messages).includes('"type":"image"'), false);
   } finally {
     globalThis.fetch = previousFetch;
   }
@@ -848,15 +952,15 @@ test("compaction 请求在 mode=never 时不拦截图片", async () => {
       resolveModelInfo: async () => ({ provider: "opencode-go", id: "deepseek-v4-flash", name: "deepseek-v4-flash", inputModalities: ["text"] })
     },
     logger: { error() {} },
-    effect() {},
+    effect(factory) { factory(); },
     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() {} });
+        cb({ settings: { register: (_ns, _schema, options) => ({ get: () => options.base, watch() {} }) }, effect(factory) { factory(); } });
       } else {
-        cb({ webServer: { register: () => () => {} }, effect() {} });
+        cb({ webServer: { register: () => () => {} }, effect(factory) { factory(); } });
       }
     },
     get() {
@@ -959,12 +1063,21 @@ test("usage 记录失败调用并带错误信息", async () => {
   }
 });
 
-test("npm 包声明可安装的 DSH bundle 和市场关键词", async () => {
+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.version, "0.10.0");
   assert.equal(manifest.dsh?.bundle?.patch, "./cordis.patch.yml");
+  assert.equal(manifest.dsh?.compatibility?.dsh, ">=0.1.1-rc.2 <0.2.0");
+  assert.deepEqual(manifest.dsh?.compatibility?.dshReleases, {
+    "0.1.2-alpha.3": "compatible",
+    "0.1.2-alpha.4": "compatible",
+    "0.1.2-alpha.5": "compatible"
+  });
+  assert.equal(manifest.engines?.node, ">=22.13.0");
   assert.ok(manifest.files.includes("cordis.patch.yml"));
+  assert.ok(manifest.files.includes("CHANGELOG.md"));
   assert.ok(manifest.keywords.includes("dsh-plugin"));
   assert.match(patch, /id:\s*vision-fallback/);
   assert.match(patch, /name:\s*['"]dsh-vision-fallback['"]/);