@liustack/modlens 3.16.5 → 3.16.7

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 3.16.7 - 2026-08-15
+
+- **dsh: the vision engine has a settings card in the web UI ([#39](https://github.com/liustack/modlens/issues/39)).** Engine, API key, endpoint, model, and which local sign-ins a read may borrow, in Settings under Plugins, for the dsh users who never open a terminal. Expanding it probes the machine and lists the harnesses actually found, so auto mode is a choice between real options. The shared `~/.modlens/config.json` stays the one place those values live: the card reads and writes a loopback route that owns the file, so nothing is duplicated into a second store and every other harness sees the same edit. The host never sends a stored key to the browser, only whether one is stored, and a blank key field means leave the stored one alone. A cross-origin or non-loopback write is refused the way dsh fences its own API, since a page in the same browser could otherwise repoint someone's engine at an endpoint of its choosing. Not pinning an engine stays its own state rather than being collapsed into one, and a save carries only what it is about: toggling a grant never moves the pin or rewrites engine settings.
+- **A key can be entered without it touching argv, shell history, or the chat.** `modlens config set gemini-api.apiKey` with the value omitted prompts for it with the echo hidden, and also accepts one piped line. The conversational path is not blocked, because it cannot be: most users hand their key to whatever agent is in front of them, and the onboarding still takes exactly the key they hand over. This is the clean path for the ones who would rather not, and the docs say which boundary each form actually holds.
+
+## 3.16.6 - 2026-08-15
+
+- **A `null` where the contract asks for nothing no longer fails the read ([#37](https://github.com/liustack/modlens/issues/37)).** The reported failure named `visual.notes`, which the validator only reports when the field is present in a shape it does not accept: leaving it out was always fine. `null` is the shape a model reaches for when it has nothing to say, and it is what the reporter's own workaround had to legalize, so that is what this fixes. An optional field holding `null` is now dropped before the check rather than passing through it, which keeps the read alive and keeps `null` out of the fields this contract declares: each one is absent or holds its declared type, as the schema always promised. A key a gateway adds on its own is dropped the same way when it is null. On a required field `null` is still a violation. The error also stopped calling everything missing, since reading `missing: visual.notes` about a field that was right there sends you looking in the wrong place.
+- **The openai provider can ask the gateway to enforce the contract ([#37](https://github.com/liustack/modlens/issues/37)).** `modlens config set openai.structuredOutput true` sends it as `response_format: json_schema` in the strict form those endpoints require: every property required, `additionalProperties: false`, and the ones this contract leaves optional made nullable. It is derived from the same schema the runtime checks against, so there is no second copy to keep in step, which is the part that made the reporter's own workaround expensive: they had to hand-write the whole thing to get thinking-disabled qwen through. Off by default, since a gateway without structured-output support answers 400 for the field, and a `response_format` set in `extraBody` still wins.
+
 ## 3.16.5 - 2026-08-15
 
 - **dsh: pasting into a plain text-only model works again ([#36](https://github.com/liustack/modlens/issues/36)).** The paste takeover shipped in 3.14.0 has been dead in every default install since 3.16.0 moved the verdict server-side. The verdict refuses when any model matching the selector label declares image input, which is right for a real vision model and wrong for the one case it could not see: this plugin's own `(modlens vision)` wrapper reuses the upstream model id verbatim and declares image input, because that declaration is exactly how the wrapper unlocks admission. So selecting plain `DeepSeek-V4-Pro` matched the real text-only model and the plugin's synthetic twin of it, the twin vetoed, and the paste fell through to dsh's own gate and its `MODEL_DOES_NOT_SUPPORT_IMAGES`. The verdict now skips a twin two ways, both requiring proof rather than a name: the provider ids this instance actually registered, tracked as each wrapper lands, and a model that carries the `(modlens vision)` marker on a provider id minted by the rule this plugin uses, which is how a sibling instance in the same process is recognized. A real vision provider still vetoes even if it borrows the marker, and an id someone else already holds is never trusted as ours. The verdict had no test at all, which is how a regression this total shipped and stayed for six releases; it now has an integration suite driving the real route against a registry shaped like a live install. Thanks to @Taz-dingo for a report that arrived with the conflicting rules already quoted side by side.

package/README.md

@@ -34,7 +34,7 @@ Issues are welcome any time: [open one](https://github.com/liustack/modlens/issu
 
 ## Highlights
 
-**🥇 The first vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.5`, and the text-only DeepSeek model behind dsh reads images through a native `modlens_read_image` tool. Updating is the same command again. The version is named rather than `@latest` on purpose: pnpm 11 holds back releases published in the last 24 hours and resolves the tag against what survives, so `@latest` would install whatever shipped a day ago ([details](docs/harness-setup.md#keeping-it-up-to-date)).
+**🥇 The first vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.7`, and the text-only DeepSeek model behind dsh reads images through a native `modlens_read_image` tool. Updating is the same command again. The version is named rather than `@latest` on purpose: pnpm 11 holds back releases published in the last 24 hours and resolves the tag against what survives, so `@latest` would install whatever shipped a day ago ([details](docs/harness-setup.md#keeping-it-up-to-date)).
 
 Pasting an image works two ways. **① Just paste.** On a text-only model the pasted image lands as a private temp file and its path enters the composer — the same interaction OpenCode and Pi ship — and the `modlens_read_image` tool takes it from there. **② Pick a `(modlens vision)` entry** in the model selector (it remembers your choice, so once is enough), then paste: the thumbnail stays visible in your message, closer to the Codex app feel, and the image is converted to structured evidence at request time, answered by the same underlying route. The plugin auto-discovers every provider route carrying text-only DeepSeek or GLM models and adds a wrapped entry per route (a stock install gets **`DeepSeek-V4-Flash (modlens vision)`** and **`DeepSeek-V4-Pro (modlens vision)`**; extra routes like opencode-go or zai get their own); the two families' own vision models are excluded automatically. Which paste route applies is the host's per-model call: only a model its metadata positively confirms text-only is taken over, anything unconfirmed is left alone, so vision models keep their native paste ([details](docs/harness-setup.md)).
 

package/README.zh-CN.md

@@ -34,7 +34,7 @@ DeepSeek 和 GLM 的主力对话模型是纯文本的，无法进行图片识别
 
 ## 亮点
 
-**🥇 全网第一个支持 DeepSeek Harness（dsh）的外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.5`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `modlens_read_image` 工具读图。更新就是再跑一遍同一条命令。这里点名版本号而不用 `@latest` 是有意的：pnpm 11 会扣住最近 24 小时内发布的版本，dist-tag 只在剩下的里面解析，用 `@latest` 装到的会是一天前发布的那个（[细节](docs/harness-setup.zh-CN.md#保持更新)）。
+**🥇 全网第一个支持 DeepSeek Harness（dsh）的外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.7`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `modlens_read_image` 工具读图。更新就是再跑一遍同一条命令。这里点名版本号而不用 `@latest` 是有意的：pnpm 11 会扣住最近 24 小时内发布的版本，dist-tag 只在剩下的里面解析，用 `@latest` 装到的会是一天前发布的那个（[细节](docs/harness-setup.zh-CN.md#保持更新)）。
 
 DeepSeek Harness 粘贴识图有两种玩法。
 
@@ -69,7 +69,7 @@ agy                                                           # 浏览器完成
 **DeepSeek Harness（dsh）用户不走 skill 流程**，本包就是原生 dsh 插件：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.5
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.7
 ```
 
 装完即有 `modlens_read_image` 工具，选「(modlens vision)」模型变体即可直接粘贴识图。引擎配置同样在 `~/.modlens`，详见[宿主接入](docs/harness-setup.zh-CN.md)。

package/dist/main.js

@@ -11,6 +11,7 @@ import * as dns from "dns/promises";
 import { isIP } from "net";
 import { createRequire } from "module";
 import * as crypto from "crypto";
+import * as readline from "readline";
 function denyPatterns(guards) {
   return stringPatterns(guards?.denyModels);
 }
@@ -619,12 +620,71 @@ const VISION_RESULT_SCHEMA = {
   },
   required: ["summary", "ocr", "layout", "semantics", "visual", "uncertainty"]
 };
+function strictSchema(node) {
+  if (node.type === "object") {
+    const properties = {};
+    const required = node.required ?? [];
+    for (const [key, child] of Object.entries(node.properties ?? {})) {
+      const strict = strictSchema(child);
+      properties[key] = required.includes(key) ? strict : (
+        // Strict mode has no optional properties, only nullable ones.
+        { anyOf: [strict, { type: "null" }] }
+      );
+    }
+    return {
+      type: "object",
+      properties,
+      required: Object.keys(properties),
+      additionalProperties: false
+    };
+  }
+  if (node.type === "array" && node.items) {
+    return { ...node, items: strictSchema(node.items) };
+  }
+  return node;
+}
+function visionResponseFormat() {
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: "vision_result",
+      strict: true,
+      schema: strictSchema(VISION_RESULT_SCHEMA)
+    }
+  };
+}
 function visionResultSchemaJson() {
   return JSON.stringify(VISION_RESULT_SCHEMA);
 }
 function missingSchemaFields(result) {
   return schemaViolations(VISION_RESULT_SCHEMA, result, "");
 }
+function withoutEmptyOptionals(value, schema) {
+  if (schema.type === "object") {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return value;
+    }
+    const record = value;
+    const cleaned = {};
+    for (const [key, entry] of Object.entries(record)) {
+      const childSchema = schema.properties?.[key];
+      const isRequired = schema.required?.includes(key) ?? false;
+      if (entry === null && !isRequired) {
+        continue;
+      }
+      cleaned[key] = childSchema ? withoutEmptyOptionals(entry, childSchema) : entry;
+    }
+    return cleaned;
+  }
+  if (schema.type === "array" && schema.items && Array.isArray(value)) {
+    const itemSchema = schema.items;
+    return value.map((item) => withoutEmptyOptionals(item, itemSchema));
+  }
+  return value;
+}
+function normalizeVisionResult(result) {
+  return withoutEmptyOptionals(result, VISION_RESULT_SCHEMA);
+}
 function schemaViolations(schema, value, path2) {
   const label = path2 || "(root)";
   if (schema.type === "object") {
@@ -1256,6 +1316,13 @@ ${JSON_TEMPLATE_INSTRUCTION}`;
         mergeExtraBody(
           {
             model,
+            // Asked for, never assumed: a gateway without
+            // structured-output support answers 400 for a field
+            // it does not know (issue #37). A response_format the
+            // caller supplied wins outright rather than being
+            // merged into ours, since the two describe the same
+            // thing and a blend of them describes neither.
+            ...options.settings?.structuredOutput && options.settings?.extraBody?.response_format === void 0 ? { response_format: visionResponseFormat() } : {},
             messages: [
               {
                 role: "user",
@@ -1286,14 +1353,15 @@ ${JSON_TEMPLATE_INSTRUCTION}`;
   if (!text) {
     throw new Error("OpenAI-compatible API returned no message content.");
   }
-  const result = extractJson(text);
-  if (result === null) {
+  const rawResult = extractJson(text);
+  if (rawResult === null) {
     throw new Error(`OpenAI-compatible API returned non-JSON output: ${truncate(text)}`);
   }
+  const result = normalizeVisionResult(rawResult);
   const missing = missingSchemaFields(result);
   if (missing.length > 0) {
     throw new Error(
-      `OpenAI-compatible API returned JSON that does not match the vision schema (missing: ${missing.join(", ")}). Retry, or switch to gemini-api / anthropic for enforced schemas. Got: ${truncate(text)}`
+      `OpenAI-compatible API returned JSON that does not match the vision schema (wrong or missing: ${missing.join(", ")}). Retry, or switch to gemini-api / anthropic for enforced schemas. Got: ${truncate(text)}`
     );
   }
   return {
@@ -1432,12 +1500,31 @@ function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
     const dot = dottedKey.indexOf(".");
     if (dot <= 0 || dot === dottedKey.length - 1) {
       throw new Error(
-        `Invalid config key: ${dottedKey}. Use "provider", "reuse.<claude|codex|opencode|pi|grok>", "guards.<denyModels|allowModels|denyWhenUnknown>", or "<provider>.<apiKey|baseUrl|model|extraBody>".`
+        `Invalid config key: ${dottedKey}. Use "provider", "proxy", "reuse.<claude|codex|opencode|pi|grok>", "guards.<denyModels|allowModels|denyWhenUnknown>", or "<provider>.<apiKey|baseUrl|model|proxy|extraBody|structuredOutput>".`
       );
     }
     const providerName = dottedKey.slice(0, dot);
     const field = dottedKey.slice(dot + 1);
-    if (field === "extraBody") {
+    if (field === "structuredOutput") {
+      if ((providerAliases()[providerName] ?? providerName) !== "openai") {
+        throw new Error(
+          `structuredOutput applies to the openai provider only, not ${providerName}.`
+        );
+      }
+      const normalized = value.trim().toLowerCase();
+      if (normalized !== "" && normalized !== "true" && normalized !== "false") {
+        throw new Error(
+          `${providerName}.structuredOutput must be true or false (empty clears).`
+        );
+      }
+      config2.providers ??= {};
+      config2.providers[providerName] ??= {};
+      if (normalized === "") {
+        delete config2.providers[providerName].structuredOutput;
+      } else {
+        config2.providers[providerName].structuredOutput = normalized === "true";
+      }
+    } else if (field === "extraBody") {
       config2.providers ??= {};
       config2.providers[providerName] ??= {};
       if (value.trim() === "") {
@@ -1450,7 +1537,7 @@ function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
       }
     } else if (!STRING_FIELDS.includes(field)) {
       throw new Error(
-        `Unknown config field: ${field}. Use apiKey, baseUrl, model, proxy, or extraBody.`
+        `Unknown config field: ${field}. Use apiKey, baseUrl, model, proxy, extraBody, or structuredOutput.`
       );
     } else {
       config2.providers ??= {};
@@ -1539,6 +1626,9 @@ function renderEffectiveConfig(config2, env = process.env) {
         fields[field] = `${shown} (${source})`;
       }
     }
+    if (fileSettings.structuredOutput !== void 0) {
+      fields.structuredOutput = `${fileSettings.structuredOutput} (file)`;
+    }
     if (fileSettings.extraBody !== void 0) {
       fields.extraBody = `${JSON.stringify(fileSettings.extraBody)} (file)`;
     }
@@ -2770,10 +2860,11 @@ async function runProvider(provider, model, options, resolvedInput, timeoutMs, c
       `Provider ${provider.name} implements neither execute nor buildInvocation.`
     );
   }
+  parsed.result = normalizeVisionResult(parsed.result);
   const missing = missingSchemaFields(parsed.result);
   if (missing.length > 0) {
     throw new Error(
-      `${provider.name} returned a result that does not match the vision schema (missing: ${missing.join(", ")}).`
+      `${provider.name} returned a result that does not match the vision schema (wrong or missing: ${missing.join(", ")}).`
     );
   }
   return parsed;
@@ -4062,6 +4153,53 @@ function recoverPastedImages(options = {}) {
   }
   return result;
 }
+async function readSecret(promptText, stdin = process.stdin, stderr = process.stderr) {
+  if (!stdin.isTTY) {
+    stdin.setEncoding("utf8");
+    let data = "";
+    for await (const chunk of stdin) {
+      data += chunk;
+      if (data.includes("\n")) {
+        break;
+      }
+    }
+    const value = data.split("\n")[0].trim();
+    if (value === "") {
+      throw new Error("no key arrived on stdin (pipe one line, or run on a terminal)");
+    }
+    return value;
+  }
+  const rl = readline.createInterface({ input: stdin, output: stderr, terminal: true });
+  const muted = rl;
+  stderr.write(promptText);
+  muted._writeToOutput = () => {
+  };
+  try {
+    const value = await new Promise((resolve, reject) => {
+      let settled = false;
+      const settle = (action) => {
+        if (!settled) {
+          settled = true;
+          action();
+        }
+      };
+      rl.question("", (answer) => settle(() => resolve(answer)));
+      rl.on("SIGINT", () => settle(() => reject(new Error("cancelled, nothing was saved"))));
+      rl.on(
+        "close",
+        () => settle(() => reject(new Error("input ended before a key was entered")))
+      );
+    });
+    const trimmed = value.trim();
+    if (trimmed === "") {
+      throw new Error("no key entered");
+    }
+    return trimmed;
+  } finally {
+    stderr.write("\n");
+    rl.close();
+  }
+}
 const program = new Command();
 function parsePositiveInt(raw, flag) {
   if (!/^\d+$/.test(raw.trim()) || Number.parseInt(raw, 10) <= 0) {
@@ -4069,7 +4207,7 @@ function parsePositiveInt(raw, flag) {
   }
   return Number.parseInt(raw, 10);
 }
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.16.5");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.16.7");
 program.command("analyze", { isDefault: true }).description("Analyze an image into structured JSON evidence (default command)").requiredOption("-i, --input <path|url>", "Input image path or https URL").option("-o, --output <path>", "Write result JSON to a file").option("-m, --model <name>", "Provider model name").option("-p, --provider <name>", `Vision provider (${listProviders().join(", ")})`).option("--prompt <text>", "Extra focus for this image").option("--timeout <ms>", "Provider timeout in milliseconds", "180000").option("--provider-bin <path>", "Provider binary path (default: agy)").option("--workdir <path>", "Working directory for the provider").option(
   "--extra-body <json>",
   `JSON merged into the API request body, e.g. '{"thinking":{"type":"disabled"}}'`
@@ -4179,7 +4317,7 @@ program.command("doctor").description(
       configPath: CONFIG_PATH,
       // Lets doctor name an installed skill copy that is older than
       // the CLI reporting on it (issue #33).
-      version: "3.16.5"
+      version: "3.16.7"
     });
     const output = options.json ? JSON.stringify(report, null, 2) : renderDoctorReport(report);
     process.stdout.write(`${output}
@@ -4199,9 +4337,9 @@ config.command("init").description(`Create a starter config at ${CONFIG_PATH}`).
     process.stdout.write(
       [
         `Created ${CONFIG_PATH}`,
-        "Everything is optional. Two things you can set:",
+        "Everything is optional. The usual ones:",
         "  modlens config set provider <name>                      which provider analyzes images",
-        "  modlens config set <provider>.<apiKey|baseUrl|model> <value>   provider credentials",
+        "  modlens config set <provider>.<apiKey|baseUrl|model> <value>   provider settings",
         `  modlens config set <provider>.extraBody '{"thinking":{"type":"disabled"}}'   vendor request fields`,
         ""
       ].join("\n")
@@ -4214,9 +4352,18 @@ config.command("init").description(`Create a starter config at ${CONFIG_PATH}`).
     process.exitCode = 1;
   }
 });
-config.command("set <key> <value>").description("Set a value, e.g. modlens config set gemini-api.apiKey <key>").action((key, value) => {
+config.command("set <key> [value]").description(
+  "Set a value. Omit the value for an apiKey to enter it at a hidden prompt (out of argv and shell history), or to read one piped line (out of argv; the command feeding the pipe is yours to keep out of history)"
+).action(async (key, value) => {
   try {
-    setConfigValue(key, value);
+    let resolved = value;
+    if (resolved === void 0) {
+      if (!key.endsWith(".apiKey")) {
+        throw new Error(`${key} needs a value: modlens config set ${key} <value>`);
+      }
+      resolved = await readSecret(`${key} (input hidden): `);
+    }
+    setConfigValue(key, resolved);
     process.stdout.write(`Saved ${key} to ${CONFIG_PATH}
 `);
   } catch (error) {

package/docs/cli.md

@@ -97,6 +97,6 @@ Five providers: `antigravity-cli` (no key), `gemini-api` (fastest free route), `
 Other subcommands:
 
 - `modlens guard [--model <id>]`: should the engine run for the active model at all? Exit 0 allow, 1 deny, verdict as JSON.
-- `modlens config <init|set|show>`: keys are `provider`, `proxy` (HTTP/HTTPS proxy for the API providers, `HTTPS_PROXY`/`HTTP_PROXY` also honored), `reuse.<claude|codex|opencode|pi|grok>`, `guards.<denyModels|allowModels|denyWhenUnknown>`, and `<provider>.<apiKey|baseUrl|model|proxy|extraBody>`.
+- `modlens config <init|set|show>`: `set` with the value omitted on an `apiKey` field prompts for it with the echo hidden, so the key never enters argv, shell history, or the conversation with an agent driving the terminal. It also accepts one piped line (`pbpaste | modlens config set openai.apiKey`), which keeps the key out of argv, though whatever produced that pipe is still your own command to keep out of history. Keys are `provider`, `proxy` (HTTP/HTTPS proxy for the API providers, `HTTPS_PROXY`/`HTTP_PROXY` also honored), `reuse.<claude|codex|opencode|pi|grok>`, `guards.<denyModels|allowModels|denyWhenUnknown>`, and `<provider>.<apiKey|baseUrl|model|proxy|extraBody>`, plus `openai.structuredOutput` (that route only).
 - `modlens doctor`: Node and node:sqlite, provider readiness, the failover chains for this machine, the detected harness, the guard's rules with a live verdict, and the Reuse section with per-harness grant decisions and discovered vision. Spends no quota; `--json` for a machine-readable report.
 

package/docs/cli.zh-CN.md

@@ -94,5 +94,5 @@ modlens recover-paste                           # pull a pasted image into a fil
 其他子命令：
 
 - `modlens guard [--model <id>]`：判断当前激活的模型到底该不该运行引擎。退出码 0 表示放行，1 表示拒绝，判定结果以 JSON 输出。
-- `modlens config <init|set|show>`：可用的键有 `provider`、`proxy`（API provider 的 HTTP/HTTPS 代理，也认 `HTTPS_PROXY`/`HTTP_PROXY`）、`reuse.<claude|codex|opencode|pi|grok>`、`guards.<denyModels|allowModels|denyWhenUnknown>`，以及 `<provider>.<apiKey|baseUrl|model|proxy|extraBody>`。
+- `modlens config <init|set|show>`：`set` 在 `apiKey` 字段上省略值会进入不回显的输入提示，密钥不进 argv、不进 shell 历史，也不进你与终端里那个 agent 的对话。它也接受从管道读一行（`pbpaste | modlens config set openai.apiKey`），这样密钥不进 argv，但产生这条管道的命令本身是否留在历史里，由你自己决定。可用的键有 `provider`、`proxy`（API provider 的 HTTP/HTTPS 代理，也认 `HTTPS_PROXY`/`HTTP_PROXY`）、`reuse.<claude|codex|opencode|pi|grok>`、`guards.<denyModels|allowModels|denyWhenUnknown>`，以及 `<provider>.<apiKey|baseUrl|model|proxy|extraBody>`，另有 `openai.structuredOutput`（仅这条路线用得上）。
 - `modlens doctor`：报告 Node 与 node:sqlite、各 provider 的就绪状态、本机的故障转移链、检测到的 harness、guard 规则和一次现场判定，以及 Reuse 一节里按 harness 的授权决定与发现的视觉能力。不花任何额度，`--json` 输出机器可读报告。

package/docs/harness-setup.md

@@ -55,18 +55,33 @@ OpenCode with DeepSeek: `opencode auth login`, pick DeepSeek and paste the key (
 dsh is different from the other harnesses: modlens plugs in as a native tool, not a prompt-triggered skill. The package itself is a dsh bundle, so one command installs it into a profile:
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.5
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.7
 ```
 
 This registers a `modlens_read_image` tool whose schema reaches the model on every request (no trigger heuristics), runs the modlens CLI shipped inside the same package, and returns the structured evidence as the tool's canonical JSON output. Engines, reuse grants, and guard rules stay in `~/.modlens/config.json`, shared with every other harness. dsh is in developer preview and its plugin surface may change; the plugin keeps its touch small (raw tool registration, the llm adapter surface for the vision variants, the attachment reader, and one agent pre-step hook) and degrades loudly if any of them moves.
 
+### Configuring the engine from the web UI
+
+dsh web users have no terminal in front of them, so the engine settings have a
+card in **Settings → Plugins → Plugin configuration**: which engine reads
+images, its key, endpoint and model, and which local sign-ins a read may
+borrow. Expanding it probes this machine and lists the harnesses it actually
+found, so the grants are a choice between real options rather than five names.
+
+The values live where they always did, in `~/.modlens/config.json`, shared
+with every other harness: the card reads and writes that file through a
+loopback route, so an edit here is the same edit `modlens config set` makes.
+The card never receives a stored key, only whether one is set, and leaving the
+key field empty keeps the stored one. `settingsCard: false` in the plugin row
+removes it, route included.
+
 ### Keeping it up to date
 
 modlens ships often, and both install shapes freeze at whatever version they
 got. On dsh, re-run the install with the version named:
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.16.5
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.16.7
 ```
 
 `npm view @liustack/modlens version` prints the current one, and this page is
@@ -101,6 +116,21 @@ install-time version, so re-run the install to overwrite it in place.
 behind the CLI doing the reporting, which makes the drift visible before it
 costs anyone a debugging session.
 
+### A session that already holds an image
+
+dsh refuses to switch a session that contains image attachments to a model
+whose declared modalities exclude images, which includes every plain text-only
+DeepSeek entry. The rule is dsh's and it is sound: a text-only model cannot
+receive a history carrying image blocks, and the `(modlens vision)` variant is
+switchable there not because it declares image input but because it converts
+those blocks to evidence text at request time, which the plain entry does not
+do ([#40](https://github.com/liustack/modlens/issues/40)).
+
+Pasting through the first route above avoids the situation entirely: the image
+becomes a file path and the session never holds an attachment, so nothing locks
+the model selector. It only comes up after a paste on a variant or on a vision
+model, where an attachment is the point.
+
 ### Paste-to-path (web profile)
 
 Pasting an image into the dsh Web UI under a **text-only model** used to die at

package/docs/harness-setup.zh-CN.md

@@ -55,17 +55,23 @@ OpenCode 接 DeepSeek：执行 `opencode auth login`，选择 DeepSeek 并粘贴
 dsh 与其他 harness 不同：modlens 以原生工具的形式接入，而不是靠提示词触发的 skill。本包自身就是一个 dsh bundle，一条命令即可装进某个 profile：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.5
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.7
 ```
 
 这会注册一个 `modlens_read_image` 工具，它的 schema 随每次请求抵达模型（不靠触发启发式），运行同一个包里自带的 modlens CLI，并把结构化证据作为工具的标准 JSON 输出返回。引擎、复用授权和 guard 规则仍在 `~/.modlens/config.json` 里，与其他所有 harness 共享。dsh 还在开发者预览阶段，插件接口可能变化。这个插件刻意保持很小的接触面（原生工具注册、视觉变体所用的 llm 适配层、附件读取器，以及一个 agent 执行前钩子），其中任何一处变动，它都会大声报错而不是无声退化。
 
+### 在网页界面里配置引擎
+
+dsh 的网页用户面前没有终端，所以引擎设置有一张卡片，在**设置 → 插件 → 插件配置**里：用哪个引擎读图、它的密钥、地址和模型，以及一次读取可以借用本机哪些已有登录。展开时会探测本机，只列出真正找到的 harness，让授权是在真实选项之间做选择，而不是面对五个名字。
+
+这些值仍然住在 `~/.modlens/config.json`，与其他所有 harness 共享：卡片通过一条回环路由读写那个文件，所以在这里改一笔，和 `modlens config set` 改的是同一笔。卡片从不拿到已保存的密钥，只知道有没有；密钥框留空就不动已存的那个。在插件配置行里设 `settingsCard: false` 可以连同路由一起去掉它。
+
 ### 保持更新
 
 modlens 发布很频繁，而两种安装形态都会冻结在装进来的那个版本上。dsh 上重跑一遍安装即可，版本号要点名：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.16.5
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.16.7
 ```
 
 `npm view @liustack/modlens version` 可以查到当前版本号，本页的版本号则由发布流程自动写入。
@@ -82,6 +88,12 @@ npx -y @deepseek-ai/dsh plugin --profile <name> list
 
 skill 类 harness 上，skill 是一个拷贝出来的文件夹，拷贝会保留安装时的版本，重跑安装原地覆盖即可。`modlens doctor` 会读出它能找到的每一份拷贝里钉住的版本，并标出落后于当前 CLI 的那些，让版本漂移在坑到人之前就先暴露出来。
 
+### 会话里已经有图片时
+
+会话里存在图片附件时,dsh 会拒绝切换到声明模态不含图片的模型,普通的 DeepSeek 纯文本条目都在此列。这条规则是 dsh 的,而且站得住:纯文本模型确实收不了带图片块的历史,而 `(modlens vision)` 变体之所以能切过去,靠的不是声明了图片输入,而是它在发请求时把那些块转成证据文本,普通条目没有这层转换（[#40](https://github.com/liustack/modlens/issues/40)）。
+
+走上面第一条粘贴路线就不会遇到:图片变成文件路径,会话里从不存在附件,模型选择器也就不会被锁住。只有在变体或视觉模型上粘贴时才会产生附件,而那种场景下附件本来就是目的。
+
 ### 粘贴转路径（paste-to-path，web profile）
 
 过去在 dsh Web UI 里，**纯文本模型**下粘贴图片会死在图片准入检查这一步。插件现在带了一个浏览器端半边（由 dsh 的客户端插件系统自动加载），恰好在这种情况下接管粘贴：图片字节发到插件在 dsh web 服务器上的 `/modlens/paste` 路由（仅回环地址，校验 magic byte，上限 25 MB），落成一个私有临时文件，输入框收到的则是纯文本的文件路径。这与 Pi、OpenCode、Claude Code 递给模型的形态一致，也正是 modlens skill 和 `modlens_read_image` 工具的首要触发条件。消息里不带图片附件，准入检查根本不会触发。

package/docs/output-schema.md

@@ -71,6 +71,8 @@ The CLI prints one JSON object to stdout:
 
 Required fields: `summary`, `ocr`, `layout`, `semantics`, `visual`, `uncertainty` — every top-level field, `visual` included. (Earlier docs called `visual` optional; the enforced schema has always required it, so build to the schema.)
 
+Optional fields: `ocr.lines[].language`, `semantics.intent`, `semantics.entities[].evidence`, `semantics.relations`, `visual.dominant_colors`, `visual.style`, `visual.notes`. Each is either absent or holds its declared type. Never `null`: a model with nothing to say there often writes one, and modlens drops the key before the result reaches you, so reading an optional field means checking whether it is there, not whether it is null.
+
 `layout.regions[].type` is a free string, not a closed list. Region kinds are an open set: a fixed enum rejected `link` on any web screenshot and `search` on a portal, and a rejected result fails the whole read over a descriptive label. The field's schema `description` names the common vocabulary as guidance, which reaches every provider that enforces this schema server-side, so an unlisted kind costs nothing.
 
 Changes from v1: pixel `bbox` coordinates and numeric `confidence` scores were removed. Vision models fabricate both, so v2 stops pretending to provide them.

package/docs/output-schema.zh-CN.md

@@ -71,6 +71,8 @@ CLI 向 stdout 打印一个 JSON 对象：
 
 必填字段：`summary`、`ocr`、`layout`、`semantics`、`visual`、`uncertainty`，也就是每一个顶层字段，`visual` 也不例外。（早期文档把 `visual` 写成可选，但强制执行的 schema 一直要求它，请以 schema 为准。）
 
+可选字段：`ocr.lines[].language`、`semantics.intent`、`semantics.entities[].evidence`、`semantics.relations`、`visual.dominant_colors`、`visual.style`、`visual.notes`。每一个要么不存在，要么就是它声明的类型，绝不会是 `null`：模型在这些位置没话可说时经常写 `null`，modlens 会在结果交到你手上之前把这个键删掉，所以读可选字段只需判断它在不在，不用判断是不是 null。
+
 `layout.regions[].type` 是自由字符串，不是封闭列表。区域类型本质是开放集合：固定枚举会让任何网页截图里的 `link`、门户页里的 `search` 直接落选，而一次落选就为了一个描述性标签废掉整次识别。常用词表写在该字段的 schema `description` 里作为指引，凡是在服务端强制执行这份 schema 的 provider 都会收到，没列到的类型不会有任何代价。
 
 相对 v1 的变化：删掉了像素级 `bbox` 坐标和数值型 `confidence` 分数。视觉模型会凭空编造这两样，v2 不再假装提供。

package/docs/troubleshooting.md

@@ -98,10 +98,36 @@ Working as intended. Codex writes pasted images to disk and puts the path in the
 
 ```
 OpenAI-compatible API returned JSON that does not match the vision schema
-(missing: ocr, ocr.full_text, ...)
+(wrong or missing: visual.notes, ...)
 ```
 
-That endpoint returned a partial result. Only agy, gemini-api, anthropic, and claude-cli enforce the schema server-side, so weaker gateways can produce half a result. Retry once, then switch:
+That endpoint returned something the contract does not accept. Note the
+wording: a field named here can be absent, or present with the wrong shape.
+For an optional field like `visual.notes`, only the second is possible, since
+leaving it out is accepted. A `null` there is dropped rather than refused, so
+what remains is a genuinely wrong type.
+
+Most OpenAI-compatible gateways enforce nothing server-side, so the contract
+travels as a filled-in JSON template in the prompt and a weaker model can
+answer with half of it, especially with thinking turned off. Ask the gateway
+to enforce it instead:
+
+```bash
+modlens config set openai.structuredOutput true
+```
+
+That sends the contract as `response_format: json_schema` in strict form,
+derived from the same schema modlens checks against, so there is nothing to
+keep in sync by hand. It is off by default because a gateway that does not
+support the field answers 400 for it. If that happens:
+
+```bash
+modlens config set openai.structuredOutput false
+```
+
+A `response_format` you set yourself in `extraBody` wins over the derived one.
+
+Failing that, retry once, then switch:
 
 ```bash
 modlens -i <image> -p gemini-api
@@ -137,7 +163,7 @@ simply lands on an older one. Name the exact version instead, which pnpm treats
 as a deliberate request rather than a resolution:
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.16.5
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.16.7
 ```
 
 `npm view @liustack/modlens version` prints the current one. pnpm 11 installs a named
@@ -152,7 +178,7 @@ file:
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.16.5'
+  - '@liustack/modlens@3.16.7'
 ```
 
 Or lift the gate for a single command, which lifts it for everything that

package/docs/troubleshooting.zh-CN.md

@@ -98,10 +98,26 @@ tag in the message carries its path.
 
 ```
 OpenAI-compatible API returned JSON that does not match the vision schema
-(missing: ocr, ocr.full_text, ...)
+(wrong or missing: visual.notes, ...)
 ```
 
-那个端点返回了残缺的结果。只有 agy、gemini-api、anthropic 和 claude-cli 在服务端强制执行 schema，较弱的网关可能只产出半个结果。重试一次，然后换 provider：
+那个端点返回了不符合契约的内容。注意措辞：被点名的字段可能是缺失，也可能是存在但形状不对。像 `visual.notes` 这样的可选字段只可能是后者，因为它缺失是被接受的。写成 `null` 也会被丢弃而不是拒绝，所以剩下的就是真正的类型错误。
+
+大多数 OpenAI 兼容网关在服务端什么都不强制，契约是以填好的 JSON 模板形式随提示词发过去的，能力弱一些的模型可能只答出一半，关掉思考时尤其明显。可以改成让网关自己强制执行：
+
+```bash
+modlens config set openai.structuredOutput true
+```
+
+这会把契约以 `response_format: json_schema` 的严格形式发过去，schema 由 modlens 校验用的那份推导而来，没有需要手工同步的副本。默认关闭，因为不支持这个字段的网关会直接 400。真遇到就关回去：
+
+```bash
+modlens config set openai.structuredOutput false
+```
+
+你自己在 `extraBody` 里设的 `response_format` 优先级更高。
+
+还是不行就重试一次，然后换 provider：
 
 ```bash
 modlens -i <image> -p gemini-api
@@ -128,7 +144,7 @@ dsh profile 装到的是旧版 modlens。`dsh.bundle` 声明从 3.9.0 起才存
 `@latest` 绕不开这一层，本页早先的说法是错的。冷静期先把候选版本过滤掉，dist-tag 才在剩下的里面解析，于是它直接落到了更旧的那个上。改成写死精确版本号，pnpm 会把它当作一次明确的指定，而不是一次解析：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.16.5
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.16.7
 ```
 
 `npm view @liustack/modlens version` 可以查到当前版本号。pnpm 11 会装上被点名的版本，11.1.3 起还会把它作为一条已批准的例外写进该 profile 的 `pnpm-workspace.yaml`，其余所有包和 modlens 以后的版本仍然留在窗口后面。
@@ -137,7 +153,7 @@ npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.16.5
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.16.5'
+  - '@liustack/modlens@3.16.7'
 ```
 
 或者只为这一条命令解除冷静期，注意它解除的是这条命令解析到的所有包，不只 modlens：