@liustack/modlens 3.23.1 → 3.24.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 3.24.1 - 2026-08-24
+
+- **dsh bundle startup no longer logs `inactive context` before `llm` is ready ([#79](https://github.com/liustack/modlens/issues/79)).** Bundle loaders can invoke the plugin while required services are still inactive. The first auto-discovery sweep read `ctx.llm` immediately, logged one to three errors, then relied on later topology events to recover. Discovery now runs inside Cordis's injected `llm` lifecycle. Each activation binds its own service, invalidates pending probes before teardown, and releases its wrapper ownership. A Cordis effect boundary also stops Promise continuations that were already queued from registering or refreshing adapters after the scope starts unloading. Existing and late providers are still discovered exactly once, and preview hosts without injection retain their previous feature-detected path.
+
+## 3.24.0 - 2026-08-22
+
+- A single `gemini-api`, `openai`, or `anthropic` provider can now use multiple API keys. Both `providers.<name>.apiKey` and the corresponding environment variable accept a comma-separated list, trim each item, and ignore empty entries. Requests use the configured order and rotate only after authentication, rate-limit, or quota failures. Network, 5xx, and response-parsing failures skip the remaining keys and preserve the existing cross-provider failover. Quota cooldown is recorded per key, and a provider moves to the back only when every configured key is cooling. Legacy provider-level cooldown state still loads. Every sibling key is registered for redaction, `doctor` reports the key count, and the dsh settings card explains the syntax. Single-key and keyless attempts keep their previous JSON shape, while multi-key attempts add a zero-based `keyIndex`.
+- Quota cooldown is new. A quota-spent key cools for 45 minutes by default, a monthly HTTP 432/433 for 24 hours, and an engine-reported `Resets in 94h19m9s` clause wins when present. A pure 429 rate-limit without quota wording is not recorded. State lives in `~/.modlens/state.json`. A cooling key is still tried last. Success of one key clears that key only. `modlens state clear` forgets every cooldown. `modlens config set cooldown on|off` turns the store off entirely (on by default).
+- `GEMINI_BASE_URL` now binds to `gemini-api.baseUrl` the same way `OPENAI_BASE_URL` and `ANTHROPIC_BASE_URL` bind, and only while the file does not name gemini-api.
+
 ## 3.23.1 - 2026-08-21
 
 - **dsh 0.1.1: `(modlens vision)` routes work again ([#73](https://github.com/liustack/modlens/issues/73)).** dsh 0.1.1 dispatches every call — and its replay path — through a new required adapter method, `prepareCall(provider, model, signal)`, and threw `registration.adapter.prepareCall is not a function` on every turn of a wrapped route. Real adapters inherit a base-class default that binds `resolveModel` and `stream` into one generation; the wrapper registers a plain object, so it now carries the same pair itself, exactly mirroring the upstream default. Hosts that never call `prepareCall` (dsh 0.1.0) ignore the extra method. The regression test drives the wrapper through the 0.1.1 dispatch shape and failed with the reported TypeError before the fix. Thanks to @5ME for a report that had already located both call sites.

package/README.md

@@ -33,7 +33,7 @@ Issues are welcome any time: [open one](https://github.com/liustack/modlens/issu
 
 ## Highlights
 
-**🥇 The most capable vision plugin for DeepSeek Harness (dsh):** install it instantly with one command: `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.23.1`. See the [setup guide](docs/harness-setup.md) for installation and update details. If the command line is not your thing but you still want to try DSH, check out <a href="https://github.com/liustack/aimanager"><b>AIManager</b></a>, the lightest desktop wrapper for DeepSeek Harness. It gets you started with zero code or configuration and installs every dependency for you with one click.
+**🥇 The most capable vision plugin for DeepSeek Harness (dsh):** install it instantly with one command: `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.1`. See the [setup guide](docs/harness-setup.md) for installation and update details. If the command line is not your thing but you still want to try DSH, check out <a href="https://github.com/liustack/aimanager"><b>AIManager</b></a>, the lightest desktop wrapper for DeepSeek Harness. It gets you started with zero code or configuration and installs every dependency for you with one click.
 
 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)).
 
@@ -43,6 +43,7 @@ A hotkey that captures the screen into DeepSeek Harness is a separate plugin: [d
 
 - **The lightest touch on the market.** No hooks, no wrappers, no local proxy daemon, not a single line changed in any harness config: on the skill harnesses it is exactly one skill folder, on dsh exactly one plugin. Uninstalling is deleting a folder, and your agents are back to stock.
 - **Zero-config start.** Reuses existing setup in Claude Code, Codex, OpenCode, and Pi, plus other multimodal models already on your machine. Nothing installed locally? Antigravity CLI is a free no-key channel, and a free Gemini key brings a read down to 5-10 seconds. API keys from every major OpenAI-compatible provider work too.
+- **Comma-separated keys rotate on auth, rate-limit, or quota failures.** Other failures skip remaining keys and keep the existing provider failover.
 - **Evidence, not imagination.** Full transcription, reading-order layout regions, entity and relation lists. The model quotes specifics.
 - **Install once, use everywhere.** Verified on real machines in Claude Code, Codex, Pi, and OpenCode.
 
@@ -96,6 +97,8 @@ modlens config set openai.apiKey  <key>
 modlens config set openai.model   qwen3-vl-plus
 ```
 
+`apiKey` (and the matching env var) also accepts a comma-separated list. ModLens rotates to the next key after authentication, rate-limit, or quota failures. Network, 5xx, and parse failures skip remaining keys and keep provider failover.
+
 The same three keys work for GLM's open platform, SiliconFlow, OpenRouter, a self-hosted vLLM/Ollama, or any gateway of your own. If your favorite vision model has an OpenAI-compatible API, ModLens can drive it.
 
 ### Reusing what your machine already has
@@ -162,13 +165,19 @@ ModLens does not accept pull requests. The project is maintained by a single aut
 
 ## Shameless plug
 
-This project runs on LIUSTACK Skills: `shaping` before you build, `coding` while you build, `dig` when it breaks, `snapshot` when you hand off. Lighter than Superpowers, and stronger.
+**[ModSearch](https://github.com/liustack/modsearch)** is ModLens's sibling project, the same craft applied to another missing sense: it gives models with no web access web search, X search, and single-page fetch. Free, no signup, no API key. A model that needs ModLens for its eyes usually needs ModSearch for the web:
 
 ```bash
-npx -y skills add liustack/vibemaster -g
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modsearch@latest
 ```
 
-⭐ If it helps, star [ModLens](https://github.com/liustack/modlens) and [VibeMaster](https://github.com/liustack/vibemaster). Stars are how the next developer finds them.
+Follow the **liustack** WeChat official account: AI startup opportunities, indie-dev insights, and hands-on AI tooling, delivered as they happen. Scan the QR code in WeChat, or search for "liustack":
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/liustack/modlens/main/assets/wechat-qrcode.png" width="420" alt="liustack WeChat official account" />
+</p>
+
+⭐ If it helps, star [ModLens](https://github.com/liustack/modlens) and [ModSearch](https://github.com/liustack/modsearch). Stars are how the next developer finds them.
 
 ## Key ecosystem partners
 

package/README.zh-CN.md

@@ -33,7 +33,7 @@ DeepSeek 和 GLM 的主力对话模型是纯文本的，无法进行图片识别
 
 ## 亮点
 
-**🥇 全网最强的 DeepSeek Harness（dsh）外挂视觉识别插件：**一条命令即刻安装 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.23.1`。更多安装与更新细节参考 [配置手册](docs/harness-setup.zh-CN.md) 。如果用不惯命令行，也想想玩玩 DSH，推荐食用全网最轻量级的 DeepSeek Harness 桌面版封装 <a href="https://github.com/liustack/aimanager"><b> AIManager</b></a>，零代码零配置起手，一键帮你安装所有依赖环境。
+**🥇 全网最强的 DeepSeek Harness（dsh）外挂视觉识别插件：**一条命令即刻安装 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.1`。更多安装与更新细节参考 [配置手册](docs/harness-setup.zh-CN.md) 。如果用不惯命令行，也想想玩玩 DSH，推荐食用全网最轻量级的 DeepSeek Harness 桌面版封装 <a href="https://github.com/liustack/aimanager"><b> AIManager</b></a>，零代码零配置起手，一键帮你安装所有依赖环境。
 
 DeepSeek Harness 粘贴识图有两种玩法。
 
@@ -47,6 +47,7 @@ DeepSeek Harness 粘贴识图有两种玩法。
 
 - **全网最轻量。** 不用 hook，不套壳，不跑本地代理进程，不改任何 harness 配置的一行字：在 skill 类 harness 里它就是一个 skill 文件夹，在 dsh 里就是一个插件。卸载等于删个文件夹，你的 agent 立刻回到原样。
 - **零配置起手。** 复用 Claude Code、Codex、OpenCode、Pi 已有配置，直接复用你本机的其他多模态模型。如果你本机什么都没安装？Antigravity CLI 是免 key 的免费通道，配一个免费 Gemini key 可将识别耗时降至 5 到 10 秒。也支持所有主流的 OpenAI 兼容格式 API key。
+- **多个密钥用英文逗号分隔，鉴权、限流或配额失败时自动轮换。** 其他失败会跳过剩余密钥，并继续走现有的 provider 故障转移。
 - **基于证据，而非想象。** 全文转录、按阅读顺序划分的版面区块、实体与关系列表，模型引用的是具体内容。
 - **一次安装，多端可用。** Claude Code、Codex、Pi、OpenCode 均经真机验证。
 
@@ -70,7 +71,7 @@ agy                                                           # 浏览器完成
 **DeepSeek Harness（dsh）用户不走 skill 流程**，本包就是原生 dsh 插件：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.23.1
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.1
 ```
 
 装完即有 `modlens_read_image` 工具，选「(modlens vision)」模型变体即可直接粘贴识图。引擎配置同样在 `~/.modlens`，详见[宿主接入](docs/harness-setup.zh-CN.md)。
@@ -108,6 +109,8 @@ modlens config set openai.apiKey  <key>
 modlens config set openai.model   qwen3-vl-plus
 ```
 
+`apiKey`（以及对应的环境变量）也接受英文逗号分隔的列表。鉴权、限流或配额失败时会轮换到下一个密钥。网络、5xx 和解析失败会跳过剩余密钥，并继续走现有的 provider 故障转移。
+
 同样三个键，换成 GLM 开放平台、SiliconFlow、OpenRouter、自建 vLLM/Ollama 或你自己的网关都一样。你常用的视觉模型只要有 OpenAI 兼容 API，ModLens 就能驱动它。
 
 ### 复用你机器上已有的东西
@@ -174,13 +177,19 @@ Codex 桌面 App 中识别一张推文截图。作者、配文、照片内容（
 
 ## 插入一条硬广
 
+**[ModSearch](https://github.com/liustack/modsearch)** 是 ModLens 的同门项目，同一套手艺补另一种感官：给不能联网的模型补上网页搜索、X 搜索和单页抓取。免费，免注册，免 API key。模型既然需要 ModLens 当眼睛，多半也需要 ModSearch 联网：
+
+```bash
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modsearch@latest
+```
+
 关注微信公众号「liustack」：AI 创业机会、独立开发见解、AI 实战与工具，第一时间推送。微信扫码，或搜一搜「liustack」：
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/liustack/modlens/main/assets/wechat-qrcode.png" width="420" alt="微信公众号 liustack" />
 </p>
 
-⭐ 如果它对你有用，请给 [ModLens](https://github.com/liustack/modlens) 一个 star，这是其他开发者找到它的方式。
+⭐ 如果它对你有用，请给 [ModLens](https://github.com/liustack/modlens) 和 [ModSearch](https://github.com/liustack/modsearch) 一个 star，这是其他开发者找到它们的方式。
 
 ## 重要生态伙伴