dsh-vision-fallback 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# 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.
+- 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

@@ -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,6 +33,29 @@ 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.
 
+### 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.
+
+### 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
 
 ### From npm / local checkout
@@ -46,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                                    # 10 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"
 ```
 
@@ -74,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 |
@@ -137,6 +162,10 @@ 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.
 
+### About image compression
+
+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
 
 - Model: `mimo-v2.5` · Endpoint: `https://opencode.ai/zen/go/v1/chat/completions` · Credential: `OPENCODE_GO_API_KEY`
@@ -150,7 +179,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
 ```
 
 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,6 +33,29 @@ 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，再由视觉桥转成主模型可用的文字上下文。
+
+### 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` 请求，插件不再原地修改它；上下文压缩会复制请求并执行一次带重入保护的嵌套分发。
+
 ## 安装
 
 ### npm / 本地检出
@@ -46,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                                    # 10 个单元测试
+pnpm install --config.minimumReleaseAge=0   # 预发布 peer 依赖可能需绕过发布年龄策略
+pnpm test                                    # node --test test/*.test.mjs
 dsh plugin --profile web add "$PWD"
 ```
 
@@ -74,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>】` |
@@ -137,6 +162,10 @@ API key 通过 DSH **凭证系统**（`~/.dsh/.credentials.yaml`）解析，`pro
 
 缓存上限 256 条（LRU 淘汰），失败结果不入缓存。
 
+### 关于图片压缩
+
+当前版本的“压缩”指**上下文压缩时复用已经得到的视觉观察**，不会重新识图；插件暂时不会对图片文件做缩放、转码或质量压缩。图片超过 `maxBytes` 时会直接报告失败，不会静默改变原图。后续如增加真正的图片压缩，会单独记录压缩前后字节数和媒体类型。
+
 ## 默认视觉路由
 
 - 模型：`mimo-v2.5` · 端点：`https://opencode.ai/zen/go/v1/chat/completions` · 凭据：`OPENCODE_GO_API_KEY`
@@ -150,7 +179,7 @@ OpenCode 社区的 `opencode-see-image` 把 `filePath` 和针对当前任务的
 ## 开发
 
 ```sh
-pnpm test    # node --test test/*.test.mjs — 10 个测试
+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.0",
+  "version": "0.10.0",
   "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",
@@ -44,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",
@@ -53,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() {
@@ -958,3 +1062,23 @@ test("usage 记录失败调用并带错误信息", async () => {
     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.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['"]/);
+});