@liustack/modlens 3.16.6 → 3.17.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 3.17.0 - 2026-08-16
+
+- **Breaking: a provider takes its settings from one place, whole ([#42](https://github.com/liustack/modlens/issues/42)).** `GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` used to override `~/.modlens/config.json` field by field. The reported failure was a configured Kimi endpoint answering 401, and the reason is worth stating precisely: a baseUrl and an apiKey are one credential, so taking the endpoint from the file and the key from an ambient variable built a pairing that existed in neither place, and nothing in the error named the environment as the source. Merging the other way round keeps that shape, which is why this is not a change of precedence: name a provider in the config file and the file is its source, name nothing and the environment is. A container or CI job that only exports variables keeps working exactly as before, both halves still matching. What changes is the mixture. If the file configures a provider and you were completing it from the environment, put the rest in the file: a key variable becomes `modlens config set <provider>.apiKey` at the hidden prompt, an endpoint variable becomes `modlens config set <provider>.baseUrl "$THE_VARIABLE"` (`$env:THE_VARIABLE` in PowerShell), and until you do, a run that names such a provider refuses with that exact command rather than quietly using the vendor's own endpoint. Naming a provider is about the key existing, not what it holds: an entry emptied down to `{}` still takes that provider off its variables, since the alternative is a file you edited quietly handing the provider back to the environment. `modlens config show` and `modlens doctor` label each provider with the source actually in effect. `MODLENS_MODEL`, `MODLENS_HARNESS` and the `HTTPS_PROXY` family are untouched: none is a credential, and none can be split from a matching half. This also defuses the documented `ANTHROPIC_BASE_URL` trap, where a shell that routed Claude Code through a text-only gateway silently sent vision requests there too. Thanks to @StarChen-Cycler for a report that arrived with the mechanism, a deterministic repro in both directions, and a patch.
+- **The openai route still requires `baseUrl`, deliberately.** Defaulting it to official OpenAI was the obvious convenience and the wrong call: anyone whose endpoint came from `OPENAI_BASE_URL` would have had their third-party key, and the image beside it, sent to OpenAI instead. That is the same fault this release removes, pointed the other way. The error now names the setting, so the fix is one `modlens config set openai.baseUrl <url>` away. The same trap existed for `anthropic`, which does have a default endpoint: a run that names `anthropic` while the file configures it without a `baseUrl` and `ANTHROPIC_BASE_URL` is still set now refuses and prints the exact command to keep the endpoint it was using, rather than delivering that gateway's key to Anthropic. All three conditions have to hold, so a setup configured entirely through those variables is not affected.
+- **A `kimi-cli` provider rides a Kimi Code login ([#44](https://github.com/liustack/modlens/issues/44)).** Kimi Code subscribers read images without a key, the way `claude-cli` rides a Claude login: `modlens config set provider kimi-cli`, with `kimi-cli.model` taking one of kimi's own `<provider>/<model>` aliases. It runs only when you name it, with `-p kimi-cli` or `config set provider kimi-cli`: it spends a Kimi Code subscription, and having the CLI installed is not agreement to spend it. (`claude-cli` joins the chain automatically only because it predates that model.) It never serves a remote URL either, since the CLI reads local files. Requests that go over an API keep using the `openai` route: there is no bespoke Kimi API provider. Worth knowing if you ever debug it: modlens runs `kimi` with skill discovery pointed at a fresh empty directory, because otherwise kimi can find the modlens skill in the shared skill directories and read the image by running modlens, which is modlens calling itself. Thanks to @StarChen-Cycler for the request and the groundwork.
+
+## 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.

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.6`, 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.17.0`, 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)).
 
@@ -66,9 +66,9 @@ The install also inventories vision reachable through your other local harness C
 
 Once installed, just chat. Paste an image or drop a path, ask anything, and the skill triggers on its own: the image goes to a vision engine and the answer comes back grounded in what it read.
 
-## Vision engines: five built-in providers, four reusable CLIs, one failover chain
+## Vision engines: six built-in providers, four reusable CLIs, one failover chain
 
-ModLens does not depend on any single vision service. Nine sources of vision in total: five built-in providers, any one of which is enough, plus four local agent CLIs whose logins can be reused. The built-ins:
+ModLens does not depend on any single vision service. Ten sources of vision in total: six built-in providers, any one of which is enough, plus four local agent CLIs whose logins can be reused. The built-ins:
 
 | Provider | What it needs | Speed per read | Good for |
 | :-- | :-- | :-- | :-- |
@@ -77,6 +77,7 @@ ModLens does not depend on any single vision service. Nine sources of vision in
 | `anthropic` | an Anthropic API key | 5-10s | machines already holding one |
 | `antigravity-cli` | the free `agy` CLI, one browser sign-in, no key | 15-45s | zero-signup starts |
 | `claude-cli` | a signed-in Claude Code | 20-45s | riding your existing Claude subscription |
+| `kimi-cli` | a signed-in Kimi Code | 20-45s | riding your existing Kimi subscription, named explicitly |
 
 Without a pinned provider, every configured engine forms one failover chain: the fast API providers try first, the agent CLIs back them up, the first good result wins, and `meta.attempts` records every attempt so a fallback is never silent.
 

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.6`，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.17.0`，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.6
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.17.0
 ```
 
 装完即有 `modlens_read_image` 工具，选「(modlens vision)」模型变体即可直接粘贴识图。引擎配置同样在 `~/.modlens`，详见[宿主接入](docs/harness-setup.zh-CN.md)。
@@ -78,9 +78,9 @@ npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.16.6
 
 装好之后不需要记任何命令。正常聊天，粘贴图片或给出图片路径，提问即可，skill 自动触发：图片交给视觉引擎，答案基于读到的内容返回。
 
-## 视觉引擎：五个内置 provider，四家可复用 CLI，一条故障转移链
+## 视觉引擎：六个内置 provider，四家可复用 CLI，一条故障转移链
 
-ModLens 不绑定任何单一视觉服务。视觉来源一共九个：五个内置 provider（配好任意一个就能用），加四家本机 agent CLI 的登录可以复用。先看内置的：
+ModLens 不绑定任何单一视觉服务。视觉来源一共十个：六个内置 provider（配好任意一个就能用），加四家本机 agent CLI 的登录可以复用。先看内置的：
 
 | Provider          | 需要什么                                                                 | 单次识别耗时 | 适合谁                 |
 | :---------------- | :----------------------------------------------------------------------- | :----------- | :--------------------- |
@@ -89,6 +89,7 @@ ModLens 不绑定任何单一视觉服务。视觉来源一共九个：五个内
 | `anthropic`       | Anthropic API key                                                        | 5-10 秒      | 手上已有 key 的机器    |
 | `antigravity-cli` | 免费的 `agy` CLI，浏览器登录一次，无需 key                               | 15-45 秒     | 完全免注册起步         |
 | `claude-cli`      | 已登录的 Claude Code                                                     | 20-45 秒     | 复用现有 Claude 订阅   |
+| `kimi-cli`        | 已登录的 Kimi Code                                                       | 20-45 秒     | 复用现有 Kimi 订阅，需显式点名 |
 
 不钉死 provider 时，所有配好的引擎组成一条故障转移链：API 快车道先试，agent CLI 兜底，第一个可用结果胜出，`meta.attempts` 记录每次尝试，回退永远不是无声的。
 

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);
 }
@@ -889,10 +890,11 @@ const ANTHROPIC_DEFAULT_MODEL = "claude-haiku-4-5-20251001";
 const DEFAULT_BASE_URL$1 = "https://api.anthropic.com";
 const TOOL_NAME = "report_vision_evidence";
 async function executeAnthropicApi(options) {
+  assertNoRetiredEndpointBinding("anthropic", options.settings ?? {});
   const apiKey = options.settings?.apiKey;
   if (!apiKey) {
     throw new Error(
-      "anthropic provider needs an API key. Set ANTHROPIC_API_KEY, or run: modlens config set anthropic.apiKey <key>"
+      "anthropic provider needs an API key. Run: modlens config set anthropic.apiKey and paste it at the hidden prompt"
     );
   }
   const model = options.model || options.settings?.model || ANTHROPIC_DEFAULT_MODEL;
@@ -1200,7 +1202,7 @@ async function executeGeminiApi(options) {
   const apiKey = options.settings?.apiKey;
   if (!apiKey) {
     throw new Error(
-      "gemini-api provider needs an API key. Set GEMINI_API_KEY, or run: modlens config set gemini-api.apiKey <key> (free key: https://aistudio.google.com)"
+      "gemini-api provider needs an API key. Run: modlens config set gemini-api.apiKey and paste it at the hidden prompt (free key: https://aistudio.google.com)"
     );
   }
   const model = options.model || options.settings?.model || GEMINI_API_DEFAULT_MODEL;
@@ -1285,13 +1287,99 @@ const geminiApiProvider = {
   defaultModel: GEMINI_API_DEFAULT_MODEL,
   execute: executeGeminiApi
 };
+const KIMI_REENTRY_ENV = "MODLENS_INSIDE_KIMI_CLI";
+function freshEmptySkillsDir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "modlens-kimi-skills-"));
+  process.once("exit", () => {
+    try {
+      fs.rmdirSync(dir);
+    } catch {
+    }
+  });
+  return dir;
+}
+function buildKimiCliInvocation(options) {
+  if (process.env[KIMI_REENTRY_ENV] === "1") {
+    throw new Error(
+      "kimi-cli refused: this modlens run was started by kimi itself, so calling kimi again would loop. Pick another provider for the nested read, or let the outer read answer."
+    );
+  }
+  if (options.imageKind === "remote") {
+    throw new Error(
+      "kimi-cli provider reads local files only. Download the image first, or use -p gemini-api for remote URLs."
+    );
+  }
+  const prompt = `${buildVisionPrompt({
+    imageSource: options.imageSource,
+    imageKind: "local",
+    extraPrompt: options.extraPrompt
+  })}
+
+${JSON_TEMPLATE_INSTRUCTION}`;
+  const model = options.model || options.settings?.model;
+  const args = [
+    "-p",
+    prompt,
+    "--output-format",
+    "stream-json",
+    // Not a preference: without it kimi may load the modlens skill and
+    // read the image by running modlens, which is this process calling
+    // itself. Observed, and intermittent, which is the bad kind.
+    "--skills-dir",
+    freshEmptySkillsDir(),
+    ...model ? ["-m", model] : []
+  ];
+  return {
+    command: options.providerBin || "kimi",
+    args,
+    cwd: path.resolve(options.workdir || path.dirname(options.imageSource)),
+    env: { [KIMI_REENTRY_ENV]: "1" }
+  };
+}
+function parseKimiCliOutput(stdout) {
+  let answer = null;
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    let entry;
+    try {
+      entry = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (entry.role === "assistant" && typeof entry.content === "string" && entry.content) {
+      answer = entry.content;
+    }
+  }
+  if (answer === null) {
+    throw new Error(
+      `Kimi CLI produced no answer. Check that it is signed in (run \`kimi\` and /login) and that its model accepts image input. Got: ${truncate(stdout)}`
+    );
+  }
+  const result = extractJson(answer);
+  if (result === null) {
+    throw new Error(`Kimi CLI returned non-JSON output: ${truncate(answer)}`);
+  }
+  return { result, meta: { conversationId: null, durationSeconds: null, usage: null } };
+}
+const KIMI_CLI_DEFAULT_MODEL = "";
+const kimiCliProvider = {
+  name: "kimi-cli",
+  defaultModel: KIMI_CLI_DEFAULT_MODEL,
+  buildInvocation: buildKimiCliInvocation,
+  parseOutput: parseKimiCliOutput,
+  // Same reason claude-cli isolates: the agent runs with a real toolset, so
+  // it gets a throwaway directory holding only the image.
+  isolateWorkdir: true
+};
 async function executeOpenaiCompat(options) {
+  assertNoRetiredEndpointBinding("openai", options.settings ?? {});
   const apiKey = options.settings?.apiKey;
   const baseUrl = options.settings?.baseUrl?.replace(/\/$/, "");
   const model = options.model || options.settings?.model;
   if (!apiKey || !baseUrl || !model) {
     throw new Error(
-      "openai provider needs baseUrl, apiKey, and model. Set OPENAI_BASE_URL and OPENAI_API_KEY, or run: modlens config set openai.baseUrl <url> / openai.apiKey <key> / openai.model <name>"
+      "openai provider needs baseUrl, apiKey, and model: modlens config set openai.baseUrl <url>, modlens config set openai.apiKey (a hidden prompt), modlens config set openai.model <name>. There is no default endpoint (official OpenAI is https://api.openai.com/v1). OPENAI_BASE_URL and OPENAI_API_KEY still supply this provider on their own, but only while the config file names no openai entry, since 3.17.0 takes a provider whole from one source; no variable carries the model, so an environment-only setup passes -m <name>."
     );
   }
   const imageUrl = options.imageKind === "remote" ? options.imageSource : toDataUrl(readLocalImageBase64(options.imageSource));
@@ -1391,7 +1479,10 @@ const PROVIDERS = {
   anthropic: anthropicApiProvider,
   claude: anthropicApiProvider,
   "claude-cli": claudeCliProvider,
-  "claude-code": claudeCliProvider
+  "claude-code": claudeCliProvider,
+  "kimi-cli": kimiCliProvider,
+  kimi: kimiCliProvider,
+  "kimi-code": kimiCliProvider
 };
 function resolveProvider(providerName = "antigravity-cli") {
   const normalized = providerName.trim().toLowerCase();
@@ -1420,6 +1511,54 @@ const ENV_BINDINGS = {
   openai: { apiKey: "OPENAI_API_KEY", baseUrl: "OPENAI_BASE_URL" },
   anthropic: { apiKey: "ANTHROPIC_API_KEY", baseUrl: "ANTHROPIC_BASE_URL" }
 };
+function fileKeysFor(providerName, config2) {
+  const aliases = providerAliases();
+  return Object.keys(config2.providers ?? {}).filter(
+    (key) => (aliases[key] ?? key) === providerName
+  );
+}
+function fileSettingsFor(providerName, config2) {
+  const keys = fileKeysFor(providerName, config2);
+  const ordered = [
+    ...keys.filter((key) => key !== providerName),
+    ...keys.filter((key) => key === providerName)
+  ];
+  return Object.assign({}, ...ordered.map((key) => config2.providers?.[key] ?? {}));
+}
+function envSettingsFor(providerName, env) {
+  const settings = {};
+  for (const [field, variable] of Object.entries(ENV_BINDINGS[providerName] ?? {})) {
+    const value = env[variable]?.trim();
+    if (value) {
+      settings[field] = value;
+    }
+  }
+  return settings;
+}
+const ENDPOINT_BINDINGS = {
+  // No default endpoint, so the run cannot misroute: it simply has nowhere
+  // to go, and saying otherwise would invent a danger to justify the error.
+  openai: {
+    variable: "OPENAI_BASE_URL",
+    consequence: "this run has no endpoint left to send the image to"
+  },
+  anthropic: {
+    variable: "ANTHROPIC_BASE_URL",
+    consequence: "this run would have sent your key and the image to Anthropic's own endpoint"
+  }
+};
+function assertNoRetiredEndpointBinding(providerName, settings, env = process.env) {
+  const binding = ENDPOINT_BINDINGS[providerName];
+  const variable = binding?.variable;
+  if (!variable || settings.baseUrl?.trim() || !env[variable]?.trim()) {
+    return;
+  }
+  const shown = maskUrlCredentials(env[variable]?.trim() ?? "");
+  const reference = process.platform === "win32" ? `$env:${variable}` : `"$${variable}"`;
+  throw new Error(
+    `${variable} is set (${shown}), but the config file configures ${providerName}, and since 3.17.0 a provider takes its settings from one place: the file, whole. ${providerName}.baseUrl is not in it, so ${binding.consequence}. To keep the endpoint you were using, run: modlens config set ${providerName}.baseUrl ${reference}`
+  );
+}
 function loadConfigFile(configPath = CONFIG_PATH) {
   let raw;
   try {
@@ -1444,23 +1583,15 @@ function loadConfigFile(configPath = CONFIG_PATH) {
     );
   }
 }
+function providerConfiguredInFile(providerName, config2) {
+  return fileKeysFor(providerName, config2).length > 0;
+}
 function resolveProviderSettings(providerName, config2, env = process.env) {
-  const aliasNames = Object.entries(providerAliases()).filter(([alias, canonical]) => canonical === providerName && alias !== providerName).map(([alias]) => alias);
-  const fromFile = {
-    ...Object.assign({}, ...aliasNames.map((alias) => config2.providers?.[alias] ?? {})),
-    ...config2.providers?.[providerName] ?? {}
-  };
-  const bindings = ENV_BINDINGS[providerName] ?? {};
-  const settings = { ...fromFile };
+  const mentioned = providerConfiguredInFile(providerName, config2);
+  const settings = mentioned ? { ...fileSettingsFor(providerName, config2) } : envSettingsFor(providerName, env);
   if (!settings.proxy && config2.proxy?.trim()) {
     settings.proxy = config2.proxy.trim();
   }
-  for (const [field, envName] of Object.entries(bindings)) {
-    const value = env[envName]?.trim();
-    if (value) {
-      settings[field] = value;
-    }
-  }
   return settings;
 }
 function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
@@ -1604,23 +1735,25 @@ function initConfigFile(configPath = CONFIG_PATH, force = false) {
   }
 }
 function renderEffectiveConfig(config2, env = process.env) {
-  const providerNames = new Set(Object.keys(config2.providers ?? {}));
+  const aliases = providerAliases();
+  const providerNames = new Set(
+    Object.keys(config2.providers ?? {}).map((key) => aliases[key] ?? key)
+  );
   for (const [providerName, bindings] of Object.entries(ENV_BINDINGS)) {
-    if (Object.values(bindings).some((envName) => env[envName]?.trim())) {
+    if (Object.values(bindings).some((variable) => env[variable]?.trim())) {
       providerNames.add(providerName);
     }
   }
   const providers = {};
   for (const name of [...providerNames].sort()) {
-    const fileSettings = config2.providers?.[name] ?? {};
-    const bindings = ENV_BINDINGS[name] ?? {};
+    const fileSettings = fileSettingsFor(name, config2);
+    const mentioned = providerConfiguredInFile(name, config2);
+    const effective2 = mentioned ? fileSettings : envSettingsFor(name, env);
+    const source = mentioned ? "file" : "env";
     const fields = {};
     for (const field of STRING_FIELDS) {
-      const envName = bindings[field];
-      const envValue = envName ? env[envName]?.trim() : void 0;
-      const value = envValue ?? fileSettings[field];
-      const source = envValue ? "env" : fileSettings[field] !== void 0 ? "file" : null;
-      if (value !== void 0 && source) {
+      const value = effective2[field];
+      if (value !== void 0) {
         const shown = field === "apiKey" ? maskKey(value) : field === "proxy" ? maskUrlCredentials(value) : value;
         fields[field] = `${shown} (${source})`;
       }
@@ -1631,7 +1764,7 @@ function renderEffectiveConfig(config2, env = process.env) {
     if (fileSettings.extraBody !== void 0) {
       fields.extraBody = `${JSON.stringify(fileSettings.extraBody)} (file)`;
     }
-    if (Object.keys(fields).length > 0) {
+    if (Object.keys(fields).length > 0 || mentioned) {
       providers[name] = fields;
     }
   }
@@ -1688,30 +1821,32 @@ const PROVIDER_DESCRIPTORS = [
   {
     name: "gemini-api",
     kind: "api",
-    required: [{ field: "apiKey", env: "GEMINI_API_KEY" }],
-    fix: "modlens config set gemini-api.apiKey <key>   # free key: https://aistudio.google.com"
+    required: [{ field: "apiKey" }],
+    fix: "modlens config set gemini-api.apiKey   # hidden prompt; free key: https://aistudio.google.com"
   },
   {
     name: "openai",
     kind: "api",
-    required: [
-      { field: "baseUrl", env: "OPENAI_BASE_URL" },
-      { field: "apiKey", env: "OPENAI_API_KEY" },
-      { field: "model" }
-    ],
-    fix: "modlens config set openai.baseUrl <url> / openai.apiKey <key> / openai.model <name>"
+    required: [{ field: "baseUrl" }, { field: "apiKey" }, { field: "model" }],
+    fix: "modlens config set openai.baseUrl <url> / openai.apiKey (hidden prompt) / openai.model <name>"
   },
   {
     name: "anthropic",
     kind: "api",
-    required: [{ field: "apiKey", env: "ANTHROPIC_API_KEY" }],
-    fix: "modlens config set anthropic.apiKey <key>"
+    required: [{ field: "apiKey" }],
+    fix: "modlens config set anthropic.apiKey   # hidden prompt"
   },
   {
     name: "claude-cli",
     kind: "subprocess",
     bin: "claude",
     install: "install the Claude Code CLI, then run `claude` once to sign in"
+  },
+  {
+    name: "kimi-cli",
+    kind: "subprocess",
+    bin: "kimi",
+    install: "https://moonshotai.github.io/kimi-code/ (then run `kimi` and /login)"
   }
 ];
 function findOnPath(bin, env) {
@@ -1748,6 +1883,7 @@ const LOCAL_FAILOVER_ORDER = [
   "antigravity-cli",
   "claude-cli"
 ];
+const PIN_ONLY_PROVIDERS = ["kimi-cli"];
 const REMOTE_FAILOVER_ORDER = ["gemini-api", "openai", "anthropic", "antigravity-cli"];
 function providerChain(kind, config2, env = process.env) {
   let names = [...kind === "remote" ? REMOTE_FAILOVER_ORDER : LOCAL_FAILOVER_ORDER];
@@ -1769,6 +1905,10 @@ function providerChain(kind, config2, env = process.env) {
         names.splice(index, 1);
         names.unshift(canonical);
       }
+    } else if (index === -1 && canonical && PIN_ONLY_PROVIDERS.includes(canonical)) {
+      if (kind === "local") {
+        names.unshift(canonical);
+      }
     }
   }
   return names.filter((name) => providerAvailable(name, config2, env)).map((name) => resolveProvider(name));
@@ -2667,6 +2807,17 @@ async function analyzeImage(options) {
   }
   const config2 = options.config ?? loadConfigFile();
   const chain = options.provider ? [resolveProvider(options.provider)] : options.providerBin ? [resolveProvider("antigravity-cli")] : composeChain(resolvedInput.kind, config2, options.autoOptions);
+  const named = options.provider ?? config2.provider?.trim();
+  if (named) {
+    try {
+      const canonical = resolveProvider(named).name;
+      assertNoRetiredEndpointBinding(canonical, resolveProviderSettings(canonical, config2));
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("takes its settings from one place")) {
+        throw error;
+      }
+    }
+  }
   if (chain.length === 0) {
     throw new Error(
       "No vision provider is set up on this machine. Install Antigravity CLI (curl -fsSL https://antigravity.google/cli/install.sh | bash, then run agy once to sign in), or configure a key: modlens config set gemini-api.apiKey <key>. Run modlens doctor for the full picture." + reuseHint(config2, options.autoOptions)
@@ -2714,7 +2865,10 @@ async function analyzeImage(options) {
         result: parsed.result,
         meta: {
           generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-          model,
+          // Empty means the provider ran whatever it was already
+          // configured with and never told us which (kimi-cli), so
+          // the field says unknown rather than naming nothing.
+          model: model === "" ? null : model,
           conversationId: parsed.meta.conversationId,
           durationSeconds: parsed.meta.durationSeconds,
           usage: parsed.meta.usage,
@@ -2917,7 +3071,10 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
     const plan = resolveSpawnPlan(invocation.command, invocation.args);
     const child = spawn(plan.command, plan.args, {
       cwd: invocation.cwd,
-      stdio: ["ignore", "pipe", "pipe"]
+      stdio: ["ignore", "pipe", "pipe"],
+      // A provider may mark its own child, which is how kimi-cli tells a
+      // modlens started by kimi that running kimi again would loop.
+      ...invocation.env ? { env: { ...process.env, ...invocation.env } } : {}
     });
     const outDecoder = new TextDecoder("utf-8");
     const errDecoder = new TextDecoder("utf-8");
@@ -3759,11 +3916,14 @@ function inspectProvider(descriptor, config2, env) {
     };
   }
   const settings = resolveProviderSettings(descriptor.name, config2, env);
+  const settingsSource = providerConfiguredInFile(descriptor.name, config2) ? "file" : "env";
   const statuses = (descriptor.required ?? []).map((req) => {
-    const envValue = req.env ? env[req.env]?.trim() : void 0;
     const value = settings[req.field]?.trim();
-    const source = envValue ? "env" : value ? "file" : "missing";
-    return { field: req.field, present: Boolean(value), source, env: req.env };
+    return {
+      field: req.field,
+      present: Boolean(value),
+      source: value ? settingsSource : "missing"
+    };
   });
   const missing = statuses.filter((s) => !s.present).map((s) => s.field);
   const ready = missing.length === 0;
@@ -4152,6 +4312,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) {
@@ -4159,7 +4366,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.6");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.17.0");
 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"}}'`
@@ -4269,7 +4476,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.6"
+      version: "3.17.0"
     });
     const output = options.json ? JSON.stringify(report, null, 2) : renderDoctorReport(report);
     process.stdout.write(`${output}
@@ -4304,9 +4511,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

@@ -48,7 +48,7 @@ Output is a fixed JSON shape:
 }
 ```
 
-`meta` records how the result was produced: when (`generatedAt`), which `model`, the provider's `conversationId` when it has one, wall-clock `durationSeconds`, and the raw `usage` the provider reported (shape varies by provider, `null` when none). `attempts` lists every provider the failover chain tried, in order, with failure reasons; `warnings` carries routing notices (failovers, ignored extraBody, whose quota an auto-mode read spent).
+`meta` records how the result was produced: when (`generatedAt`), which `model` (`null` when the provider ran one it never named, as `kimi-cli` does with kimi's own default), the provider's `conversationId` when it has one, wall-clock `durationSeconds`, and the raw `usage` the provider reported (shape varies by provider, `null` when none). `attempts` lists every provider the failover chain tried, in order, with failure reasons; `warnings` carries routing notices (failovers, ignored extraBody, whose quota an auto-mode read spent).
 
 ## Flags
 
@@ -79,6 +79,7 @@ The default `-m` model depends on the provider:
 | `gemini-api` | `gemini-3.6-flash` |
 | `anthropic` | `claude-haiku-4-5-20251001` |
 | `claude-cli` | `haiku` |
+| `kimi-cli` | whatever kimi is configured with |
 | `openai` | none, `-m` is required |
 
 `modlens recover-paste`:
@@ -92,11 +93,11 @@ The default `-m` model depends on the provider:
 | `--harness <name>` | Force storage scope: `claude-code`, `pi`, `opencode`, `none` | auto-detect |
 | `--cwd <path>` | Project directory the image was pasted in | current directory |
 
-Five providers: `antigravity-cli` (no key), `gemini-api` (fastest free route), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic`, and `claude-cli` (uses your existing Claude subscription). Without `-p`, a run tries every provider that is set up, inline API providers first (5-10s), then the agents; the first good result wins and `meta.attempts` records the rest. Harnesses granted via `reuse.<harness>` contribute reused engines to the same regions (pi credentials inline, agent CLIs behind), with no priority over the user's own; details and the `guards` deny/allow lists are in [Configuration](../skills/modlens/references/configure.md).
+Six providers: `antigravity-cli` (no key), `gemini-api` (fastest free route), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic`, `claude-cli` (uses your existing Claude subscription), and `kimi-cli` (uses your existing Kimi Code subscription, and runs only when named, never as a failover peer). Without `-p`, a run tries every provider that is set up, inline API providers first (5-10s), then the agents; the first good result wins and `meta.attempts` records the rest. Harnesses granted via `reuse.<harness>` contribute reused engines to the same regions (pi credentials inline, agent CLIs behind), with no priority over the user's own; details and the `guards` deny/allow lists are in [Configuration](../skills/modlens/references/configure.md).
 
 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>`, plus `openai.structuredOutput` (that route only).
+- `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

@@ -48,7 +48,7 @@ modlens recover-paste                           # pull a pasted image into a fil
 }
 ```
 
-`meta` 记录结果是怎么产生的：什么时间（`generatedAt`）、用了哪个 `model`、provider 有会话时的 `conversationId`、实际耗时 `durationSeconds`，以及 provider 上报的原始 `usage`（结构因 provider 而异，没有时为 `null`）。`attempts` 按顺序列出故障转移链尝试过的每个 provider 和失败原因。`warnings` 携带路由通知（故障转移、被忽略的 extraBody、自动模式下这次识别花了谁的额度）。
+`meta` 记录结果是怎么产生的：什么时间（`generatedAt`）、用了哪个 `model`（provider 跑的是它自己配好、又没告诉我们型号的模型时为 `null`，`kimi-cli` 用 kimi 默认模型就是这种情况）、provider 有会话时的 `conversationId`、实际耗时 `durationSeconds`，以及 provider 上报的原始 `usage`（结构因 provider 而异，没有时为 `null`）。`attempts` 按顺序列出故障转移链尝试过的每个 provider 和失败原因。`warnings` 携带路由通知（故障转移、被忽略的 extraBody、自动模式下这次识别花了谁的额度）。
 
 ## 参数
 
@@ -76,6 +76,7 @@ modlens recover-paste                           # pull a pasted image into a fil
 | `gemini-api` | `gemini-3.6-flash` |
 | `anthropic` | `claude-haiku-4-5-20251001` |
 | `claude-cli` | `haiku` |
+| `kimi-cli` | 用 kimi 自己配好的模型 |
 | `openai` | 无，必须传 `-m` |
 
 `modlens recover-paste`：
@@ -89,10 +90,10 @@ modlens recover-paste                           # pull a pasted image into a fil
 | `--harness <name>` | 强制指定存储范围：`claude-code`、`pi`、`opencode`、`none` | 自动检测 |
 | `--cwd <path>` | 粘贴图片时所在的项目目录 | 当前目录 |
 
-共五个 provider：`antigravity-cli`（免 key）、`gemini-api`（最快的免费通道）、`openai`（任意 OpenAI 兼容的多模态端点）、`anthropic`，以及 `claude-cli`（复用你现有的 Claude 订阅）。不带 `-p` 时，一次运行会依次尝试每个已配好的 provider：API 快车道（inline API provider，不启动 agent、直接调 API 的引擎）先试（5-10 秒），agent 类兜底，第一个可用结果胜出，其余尝试记录在 `meta.attempts` 里。通过 `reuse.<harness>` 授权的 harness 会把复用来的引擎补进相同的区段（pi 的凭据算快车道，agent CLI 排在后面），不会插到你自己引擎的前面。细节和 `guards` 的 deny/allow 名单见[配置手册](../skills/modlens/references/configure.zh-CN.md)。
+共六个 provider：`antigravity-cli`（免 key）、`gemini-api`（最快的免费通道）、`openai`（任意 OpenAI 兼容的多模态端点）、`anthropic`，`claude-cli`（复用你现有的 Claude 订阅），以及 `kimi-cli`（复用你现有的 Kimi Code 订阅，只在被点名时运行，绝不作为故障转移备选）。不带 `-p` 时，一次运行会依次尝试每个已配好的 provider：API 快车道（inline API provider，不启动 agent、直接调 API 的引擎）先试（5-10 秒），agent 类兜底，第一个可用结果胜出，其余尝试记录在 `meta.attempts` 里。通过 `reuse.<harness>` 授权的 harness 会把复用来的引擎补进相同的区段（pi 的凭据算快车道，agent CLI 排在后面），不会插到你自己引擎的前面。细节和 `guards` 的 deny/allow 名单见[配置手册](../skills/modlens/references/configure.zh-CN.md)。
 
 其他子命令：
 
 - `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>`，另有 `openai.structuredOutput`（仅这条路线用得上）。
+- `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` 输出机器可读报告。