dsh-vision-fallback 0.9.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"
 ```
 
@@ -137,6 +145,13 @@ 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
+
+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`
@@ -150,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"
 ```
 
@@ -137,6 +145,13 @@ API key 通过 DSH **凭证系统**（`~/.dsh/.credentials.yaml`）解析，`pro
 
 缓存上限 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`
@@ -150,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vision-fallback",
-  "version": "0.9.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

@@ -958,3 +958,14 @@ 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.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['"]/);
+});