@liustack/modlens 2.7.2 → 2.7.4

package/README.md

@@ -11,28 +11,29 @@
 
 DeepSeek-V4-Flash gives you a lot of model for very little money: fast, strong, and its one real flaw is no multimodal. And it's not just DeepSeek. Every text-only model running inside Codex, Claude Code, Pi Agent, or OpenClaw hits the same wall.
 
-ModLens fixes this the lightest way possible. It never touches your config and never adds a local proxy. It's just a vision plug-in, usable as a CLI or as an Agent Skill, that turns any image into structured visual evidence: text, layout, regions, entities, relations, visual clues. Under the hood it runs on [Antigravity CLI](https://antigravity.google) (`agy`), whose vision comes from free-quota Gemini 3.6 Flash. And Gemini's image understanding is famously good, good enough to embarrass most flagships, Fable 5 included. How it works:
+ModLens fixes this the lightest way possible: it never touches your config, never adds a local proxy, and is just a vision plug-in you can run as a CLI or install as an Agent Skill. What it hands back is not a one-line caption but structured visual evidence: text, layout, regions, entities, relations, visual clues. Five vision engines to pick from. The default one needs no key at all, and the fastest one runs on a free Gemini key whose image understanding embarrasses most flagships, Fable 5 included. How it works:
 
 ```text
 text-only model in your agent harness ──▶ modlens skill (auto-triggers on images)
                               │
                               ▼
-                   agy · Gemini 3.6 Flash (free quota)
+                  vision engine · Gemini 3.6 Flash (free)
                               │
                               ▼
               structured JSON evidence ──▶ model answers with sight
 ```
 
-## Quick start
+## You can just paste the image
 
-**1. Install Antigravity CLI and sign in** (one-time):
+Every other bridge makes you save the image to a file first, then mention the path in the chat. ModLens lets you paste it.
 
-```bash
-curl -fsSL https://antigravity.google/cli/install.sh | bash
-agy    # opens browser sign-in, then exit
-```
+That is not laziness on their part. Pasting is handled end to end by the client: the moment an image lands in the chat box it is encoded and sent, and a vision MCP server never gets a chance to step in, which is why their docs can only tell you to save the file and report the path. ModLens takes the other route. Before those bytes are ever sent, the harness has already written them to local session storage, so the skill goes there, pulls them back out into a real file, and feeds that to the vision engine. You do nothing, and the model answers with the full image instead of asking you for a path.
+
+Verified on real machines across four harnesses: Claude Code pinpoints the exact session from its injected session id, Pi stores sessions the same way, OpenCode swaps in SQLite, and Codex's pasted images already carry a temp path so the path-tag route handles them. Before touching anything, `recover-paste` works out which harness it is running inside, by walking the process ancestry and checking environment fingerprints, and reads only that harness's storage, so another tool's stale sessions can't impersonate it.
 
-**2. Install the skill.** Just tell your agent (Claude Code, Codex, OpenClaw, Cursor, ...):
+## Quick start
+
+**1. Install the skill.** Just tell your agent (Claude Code, Codex, OpenClaw, Cursor, ...):
 
 ```text
 Install the skill from https://github.com/liustack/modlens
@@ -46,7 +47,23 @@ npx -y skills add liustack/modlens
 
 Harnesses look for skills in different places: Claude Code reads `~/.claude/skills/`, Codex reads `~/.codex/skills/`, Pi and OpenCode read `~/.agents/skills/`. Symlinks work in all of them, so linking the skill folder once keeps every agent on the latest version.
 
-**3. Use it.** Paste an image path into the CLI and ask anything. The skill fires on its own.
+**2. Wire up a vision engine.** Recommended: a free Gemini key from [aistudio.google.com](https://aistudio.google.com). Three minutes, no credit card, 5-10 seconds per image:
+
+```bash
+modlens config set gemini-api.apiKey <key>
+modlens config set provider gemini-api
+```
+
+Don't feel like typing those two lines? Tell your agent "set my Gemini key in modlens" and it runs them for you.
+
+Skipping the sign-up is fine too: Antigravity CLI works with no key at all, it is just slower (15-40s) and its free quota is tight.
+
+```bash
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+agy    # opens browser sign-in, then exit
+```
+
+**3. Use it.** Paste an image, or throw a path at it, and ask anything. The skill fires on its own.
 
 ## See it work
 
@@ -92,7 +109,7 @@ Batch mode works too: drop three illustrations at once, and the model announces
 
 ![Text-only DeepSeek reading three images in one go via ModLens](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-batch.png)
 
-Stress test: a scatter plot of 128 models. ModLens pulls out the axes, the log scale, and the highlighted DeepSeek V4 Flash point at $0.028 and score 50, then walks through the cost-performance cutoff line. Dense charts are where vision models usually fold; this one holds.
+Stress test: a scatter plot of 128 models. ModLens pulls out the axes, the log scale, and the highlighted DeepSeek V4 Flash point at $0.028 and score 50, then walks through the cost-performance cutoff line. Dense charts are where vision models usually fold. This one holds.
 
 ![Text-only DeepSeek reading a 128-model scatter plot via ModLens](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-chart.png)
 
@@ -130,12 +147,14 @@ ModLens ships five vision providers. `antigravity-cli` stays the default: zero k
 
 | Provider | Needs | Typical speed | Notes |
 | :-- | :-- | :-- | :-- |
-| `antigravity-cli` (default) | `agy` signed in | 15-40s | free quota, full agent loop |
-| `gemini-api` | free AI Studio key | 5-10s | fastest free route, schema enforced server-side |
+| `antigravity-cli` (default) | `agy` signed in | 15-40s | free quota, full agent loop, quota is tight (see below) |
+| `gemini-api` (recommended) | free AI Studio key | 5-10s | fastest free route, schema enforced server-side |
 | `openai` | baseUrl + apiKey + model | endpoint-dependent | any OpenAI-compatible multimodal endpoint (qwen-vl, GLM, ...) |
 | `anthropic` | `ANTHROPIC_API_KEY` | a few seconds | Claude Haiku by default, schema via forced tool call |
 | `claude-cli` | Claude Code signed in | 20-45s | no key, rides your Claude subscription, Read-only permissions |
 
+`antigravity-cli` wins on needing no key and loses on both other fronts: it's slower (a full agent loop takes 15-40 seconds against 5-10 for `gemini-api` direct) and its quota is tight. The free tier is now a one-time weekly grant, pooled across the desktop app, the CLI, and the SDK, and parallel subagents drain it faster. Once it's gone you wait out the cycle: we hit that wall ourselves and the message read "94 hours until reset." Great for a first look, but `gemini-api` is what holds up day to day.
+
 Config lives in `~/.modlens/config.json`. Environment variables override the file (`GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY`), and CLI flags override everything.
 
 ```bash
@@ -145,7 +164,9 @@ modlens config show                          # keys come out masked
 modlens config set provider gemini-api       # switch the default provider
 ```
 
-The free Gemini key takes three minutes at [aistudio.google.com](https://aistudio.google.com), no credit card. Or skip the manual work entirely and tell your agent: "configure modlens with my Gemini API key".
+The free Gemini key takes three minutes at [aistudio.google.com](https://aistudio.google.com), no credit card.
+
+You don't actually have to remember any of these commands. The skill ships a per-provider setup guide, so once it's installed you can just ask your agent: "how do I configure modlens," "set my Gemini key in modlens," "switch modlens to claude-cli." It reads the guide and runs them.
 
 ## Using it in Codex (DeepSeek and friends)
 
@@ -160,7 +181,15 @@ One catch: once text-only is declared, the Codex TUI **blocks Ctrl+V image paste
 
 No setup needed: drag the image file into the terminal, or type its path, and the skill takes over.
 
-Paste is trickier. If you run a text-only model behind `ANTHROPIC_BASE_URL`, Claude Code never writes pasted images to a regular temp file and has no modality switch, so a pasted image reaches the model as a pathless `[Unsupported Image]` placeholder (lenient gateways like DeepSeek's Anthropic endpoint) or breaks the request outright ([#62009](https://github.com/anthropics/claude-code/issues/62009)). But the bytes are not gone: Claude Code appends every user message, images included, to the local session transcript before the gateway ever sees it. That is what `modlens recover-paste` exploits: it pulls the most recent pasted images back out of the transcript and prints real file paths, ready for `modlens -i`. The skill runs this automatically when it spots the placeholder. Verified end to end in a real DeepSeek-gateway Claude Code session: paste an image, the model sees only the placeholder, recovers the file by session id, and answers with full image content. Transcripts are per-session files. Skills can pass the exact session via `--session` (Claude Code substitutes `${CLAUDE_SESSION_ID}` into skill text since v2.1.9); without it, recovery picks the transcript holding the newest pasted image by message timestamp, so concurrent sessions in the same project do not confuse it either way. [Pi](https://github.com/earendil-works/pi) stores sessions the same way (`~/.pi/agent/sessions/`, images as base64 in JSONL). [OpenCode](https://github.com/sst/opencode) keeps them in SQLite instead (`~/.local/share/opencode/opencode.db`, images as data URLs; reading it needs Node 22.5+ for node:sqlite). `recover-paste` first identifies the harness it is running inside, by walking the process ancestry and checking env fingerprints (`CLAUDECODE`, `PI_CODING_AGENT`, `CODEX_THREAD_ID`), and reads only that harness's storage, so one tool's stale sessions can never hijack another tool's paste; in Claude Code it even targets the exact session from the injected session id, and in Codex it refuses outright and points back to the path tag. Only when detection comes up empty does it fall back to racing all three stores by newest image timestamp. Verified live in all four harnesses: Claude Code recovers the paste via its injected session id, OpenCode runs the whole loop on DeepSeek with the skill firing on its own, Pi stays scoped to its own store, and Codex is refused with the path-tag guidance. One honest caveat: transcript layouts are internal implementation details of those tools with no compatibility promise; if recovery ever breaks, dragging the file still works everywhere.
+Paste is trickier. If you run a text-only model behind `ANTHROPIC_BASE_URL`, Claude Code never writes pasted images to a regular temp file and has no modality switch. A pasted image reaches the model as a pathless `[Unsupported Image]` placeholder (lenient gateways like DeepSeek's Anthropic endpoint) or breaks the request outright ([#62009](https://github.com/anthropics/claude-code/issues/62009)). But the bytes are not gone: Claude Code appends every user message, images included, to the local session transcript before the gateway ever sees it, and that is what `modlens recover-paste` exploits: it pulls the images back out and prints real file paths, ready for `modlens -i`. The skill runs this automatically the moment it spots the placeholder.
+
+Transcripts are per-session files, so skills can pass the exact one via `--session` (Claude Code substitutes `${CLAUDE_SESSION_ID}` into skill text since v2.1.9). Without it, recovery picks the transcript holding the newest pasted image by message timestamp, so concurrent sessions in the same project do not confuse it either way.
+
+[Pi](https://github.com/earendil-works/pi) stores sessions the same way (`~/.pi/agent/sessions/`, images as base64 in JSONL). [OpenCode](https://github.com/sst/opencode) keeps them in SQLite instead (`~/.local/share/opencode/opencode.db`, images as data URLs, reading it needs Node 22.5+ for node:sqlite).
+
+`recover-paste` first identifies the harness it is running inside, by walking the process ancestry and checking env fingerprints (`CLAUDECODE`, `PI_CODING_AGENT`, `CODEX_THREAD_ID`), and reads only that harness's storage, so one tool's stale sessions can never hijack another tool's paste. In Claude Code it targets the exact session from the injected session id. In Codex it refuses outright and points back to the path tag. Only when detection comes up empty does it fall back to racing all three stores by newest image timestamp.
+
+Verified live in all four harnesses: Claude Code recovers the paste via its injected session id, OpenCode runs the whole loop on DeepSeek with the skill firing on its own, Pi stays scoped to its own store, and Codex is refused with the path-tag guidance. One honest caveat: transcript layouts are internal implementation details of those tools with no compatibility promise. If recovery ever breaks, dragging the file still works everywhere.
 
 Pointing OpenCode at DeepSeek takes two lines of setup: `opencode auth login`, pick DeepSeek and paste your key (it lands in `~/.local/share/opencode/auth.json`), then set the default model in `~/.config/opencode/opencode.jsonc` to `deepseek/deepseek-v4-flash`. Pi reads its key from `~/.pi/agent/auth.json`.
 

package/README.zh-CN.md

@@ -11,28 +11,29 @@
 
 DeepSeek-V4-Flash 碗大又好吃，速度快，性能强，要说唯一的缺点就是没有多模态。不仅 DeepSeek-V4-Flash，只要是纯文本语言模型，跑在 Codex、Claude Code、Pi Agent、OpenClaw 中，都有这个问题。
 
-ModLens 用最轻量级方案解决这个问题。ModLens 不会入侵你的配置，也不会给你添加本地代理，ModLens 只是一个视觉外挂，有 cli 或 skill 两种模式。ModLens 能产出结构化的视觉证据：文字、版面、区块、实体、关系、视觉线索。ModLens 由 Antigravity [Antigravity CLI](https://antigravity.google)（`agy`）驱动，而 Antigravity 的视觉由免费额度的 Gemini 3.6 Flash 驱动。众所周知，Gemini 的识图能力，连 Fable 5 都吊打。原理如下：
+ModLens 用最轻的方式解决它：不动你的配置，不装本地代理，就是一个视觉外挂，CLI 和 skill 两种用法。它产出的不是一句话描述，是结构化的视觉证据：文字、版面、区块、实体、关系、视觉线索。视觉引擎有五个可选，默认那个零 key 就能跑，最快的那个用免费 Gemini key，识图能力连 Fable 5 都吊打。原理如下：
 
 ```text
 Agent Harness 中的纯文本模型 ──▶ modlens skill（遇到图片自动触发）
                         │
                         ▼
-             agy · Gemini 3.6 Flash（免费额度）
+             视觉引擎 · Gemini 3.6 Flash（免费）
                         │
                         ▼
            结构化 JSON 证据 ──▶ 模型带着视力回答
 ```
 
-## 快速开始
+## 你可以直接粘贴图片
 
-**1. 安装 Antigravity CLI 并登录**（一次性）：
+别的方案让你先把图存成文件，再在对话里报一句路径。ModLens 让你直接粘贴。
 
-```bash
-curl -fsSL https://antigravity.google/cli/install.sh | bash
-agy    # 浏览器完成登录后退出
-```
+这不怪它们偷懒。粘贴这个动作从头到尾是客户端办的，图一进对话框就被转码发走，识图 MCP server 连插手的机会都没有，所以它们的文档只能教你存文件、报路径。ModLens 走的是另一条路：图片字节在发走之前，早被 harness 原样写进了本地会话存储，skill 直接去那里把它捞回来落成文件，再喂给视觉引擎。你什么都不用做，模型拿到的是完整图片，不是一句「麻烦告诉我路径」。
+
+四家 harness 真机验证过：Claude Code 按注入的会话 ID 精确定位，Pi 的存储路数和它同构，OpenCode 换成了 SQLite，Codex 的粘贴图本来就带临时路径，走路径标签就行。动手之前 `recover-paste` 会先认清自己跑在哪一家（查进程祖先链，核对环境变量指纹），只读那一家的存储，别家的旧会话冒充不了。
 
-**2. 安装 skill。** 直接告诉你的 agent（Claude Code、Codex、OpenClaw、Cursor 等）：
+## 快速开始
+
+**1. 装 skill。** 直接告诉你的 agent（Claude Code、Codex、OpenClaw、Cursor 等）：
 
 ```text
 安装这个 skill https://github.com/liustack/modlens
@@ -46,7 +47,23 @@ npx -y skills add liustack/modlens
 
 各家 harness 找 skill 的位置不一样：Claude Code 读 `~/.claude/skills/`，Codex 读 `~/.codex/skills/`，Pi 和 OpenCode 读 `~/.agents/skills/`。软链接在哪家都好使，把 skill 目录链一次，各家永远用最新版。
 
-**3. 用起来。** 在 cli 里粘贴个图片路径，随便问，skill 会自动触发。
+**2. 接一个视觉引擎。** 推荐去 [aistudio.google.com](https://aistudio.google.com) 领个免费 Gemini key，三分钟，不要信用卡，出图 5-10 秒：
+
+```bash
+modlens config set gemini-api.apiKey <key>
+modlens config set provider gemini-api
+```
+
+懒得敲这两行？跟 agent 说一句「帮我把 Gemini key 配进 modlens」，它自己会跑。
+
+不想注册也行，装上 Antigravity CLI 就能零 key 开跑，代价是慢（15-40 秒），免费额度也紧：
+
+```bash
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+agy    # 浏览器完成登录后退出
+```
+
+**3. 用起来。** 粘贴一张图，或者甩个图片路径，随便问。skill 自己会触发。
 
 ## 看看效果
 
@@ -130,12 +147,14 @@ ModLens 内置五个视觉 provider，默认还是 `antigravity-cli`：零 key
 
 | Provider | 需要什么 | 速度 | 说明 |
 | :-- | :-- | :-- | :-- |
-| `antigravity-cli`（默认） | `agy` 登录过 | 15-40 秒 | 免费额度，完整 agent 循环 |
-| `gemini-api` | 免费 AI Studio key | 5-10 秒 | 最快的免费路线，服务端强制 schema |
+| `antigravity-cli`（默认） | `agy` 登录过 | 15-40 秒 | 免费额度，完整 agent 循环，额度紧（见下文） |
+| `gemini-api`（推荐） | 免费 AI Studio key | 5-10 秒 | 最快的免费路线，服务端强制 schema |
 | `openai` | baseUrl + apiKey + model | 看端点 | 任何 OpenAI 兼容的多模态端点（qwen-vl、GLM 等） |
 | `anthropic` | `ANTHROPIC_API_KEY` | 几秒 | 默认 Claude Haiku，强制工具调用保 schema |
 | `claude-cli` | Claude Code 已登录 | 20-45 秒 | 零 key，吃你的 Claude 订阅额度，只放行 Read 工具 |
 
+`antigravity-cli` 胜在零 key，输在两头：慢（完整 agent 循环 15-40 秒，`gemini-api` 直连 5-10 秒），额度紧。它的免费档如今是一次性发放的周配额，桌面应用、CLI、SDK 共用一个池子，subagent 并行还加倍消耗，用超了得等下个周期（我们实测撞过一次，提示「94 小时后重置」）。所以它适合尝鲜，日常主力还是 `gemini-api` 稳。
+
 配置放在 `~/.modlens/config.json`，环境变量能盖过它（`GEMINI_API_KEY`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`ANTHROPIC_API_KEY`），CLI 参数最大。
 
 ```bash
@@ -145,11 +164,13 @@ modlens config show                          # key 打码显示
 modlens config set provider gemini-api       # 换默认 provider
 ```
 
-免费 Gemini key 去 [aistudio.google.com](https://aistudio.google.com) 领，三分钟，不要信用卡。嫌麻烦就直接跟你的 agent 说一句「帮我把 Gemini key 配进 modlens」，让它自己跑命令。
+免费 Gemini key 去 [aistudio.google.com](https://aistudio.google.com) 领，三分钟，不要信用卡。
+
+这些命令你其实一条都不用记。skill 自带一份分 provider 的配置手册，装完之后直接问你的 agent：「modlens 怎么配置」「帮我把 Gemini key 配进 modlens」「把默认 provider 切成 claude-cli」，它照着手册自己跑完。
 
 ## 在 Codex 里用（DeepSeek 等纯文本模型）
 
-Codex 只认 Responses API，DeepSeek 官方端点原生支持。先照着[官方集成文档](https://api-docs.deepseek.com/zh-cn/quick_start/agent_integrations/codex)配好：它的 `models.json` 把 deepseek-v4-flash 声明成纯文本（`input_modalities: ["text"]`），这一行就是打通下面整条链路的钥匙。
+Codex 只认 Responses API，DeepSeek 官方端点原生支持。先照着[官方集成文档](https://api-docs.deepseek.com/zh-cn/quick_start/agent_integrations/codex)配好：它的 `models.json` 把 deepseek-v4-flash 声明成纯文本（`input_modalities: ["text"]`），这一行就是解锁下面整条链路的钥匙。
 
 有个坑要注意：声明纯文本之后，Codex TUI 会**直接拦下 Ctrl+V 粘贴图片**（报错 `Model deepseek-v4-flash does not support image inputs`），闸门卡在输入框那一层，图片压根到不了消息里。能用的招数有两个，都拿 deepseek-v4-flash 端到端验证过：
 
@@ -160,7 +181,15 @@ Codex 只认 Responses API，DeepSeek 官方端点原生支持。先照着[官
 
 不用任何配置：把图片文件拖进终端，或手打路径，skill 直接接手。
 
-粘贴要多说两句。走 `ANTHROPIC_BASE_URL` 网关跑纯文本模型时，Claude Code 粘贴的图片从不写普通临时文件，也没有声明模型无视觉的开关，粘贴的图要么变成一个不带路径的 `[Unsupported Image]` 占位符到达模型（DeepSeek 的 Anthropic 兼容端点这类宽容网关），要么直接把请求搞挂（[#62009](https://github.com/anthropics/claude-code/issues/62009)）。但图片字节没有蒸发：Claude Code 在网关看到消息之前，就把每条用户消息（含图片）原样写进了本地会话记录。`modlens recover-paste` 干的就是这件事：从会话记录里把最近粘贴的图捞回来，落成真实文件路径，直接喂给 `modlens -i`。skill 看到占位符会自动跑这一步。已在真实的 DeepSeek 网关 Claude Code 会话里端到端验证：粘贴一张图，模型只看到占位符，按会话 ID 捞回文件，带着完整图片内容回答。会话记录本来就是一个会话一个文件。skill 可以通过 `--session` 传入精确会话（Claude Code 从 v2.1.9 起会把 `${CLAUDE_SESSION_ID}` 替换进 skill 文本），不传时按消息时间戳挑「持有最新粘贴图」的那份，两条路都不怕同项目并发多开。[Pi](https://github.com/earendil-works/pi) 的会话存储和它同构（`~/.pi/agent/sessions/`，图片以 base64 存 JSONL）。[OpenCode](https://github.com/sst/opencode) 换了个存法，图片以 data URL 塞进 SQLite（`~/.local/share/opencode/opencode.db`，读它需要 Node 22.5+ 的 node:sqlite）。`recover-paste` 会先搞清楚自己正跑在哪家宿主里（沿进程祖先链往上找，再核对 `CLAUDECODE`、`PI_CODING_AGENT`、`CODEX_THREAD_ID` 这些环境变量指纹），然后只读那一家的存储，别家的陈年会话再也没机会冒充。在 Claude Code 里还会直接用注入的会话 ID 精确定位，在 Codex 里则干脆拒绝执行并把你指回 path tag。实在识别不出来才退回按最新图片时间戳在三家赛跑。四家宿主全部活体验证过：Claude Code 靠注入的会话 ID 精确捞回粘贴，OpenCode 上 DeepSeek 全程自动触发 skill 跑完整条链路，Pi 只认自家存储不受别家污染，Codex 被拒之门外并指回 path tag。一句老实话：会话记录格式是这些工具的内部实现，没有兼容承诺，哪天捞不动了，拖文件永远是保底。
+粘贴要多说两句。走 `ANTHROPIC_BASE_URL` 网关跑纯文本模型时，Claude Code 粘贴的图片从不写普通临时文件，也没有声明模型无视觉的开关，粘贴的图要么变成一个不带路径的 `[Unsupported Image]` 占位符到达模型（DeepSeek 的 Anthropic 兼容端点这类宽容网关），要么直接把请求搞挂（[#62009](https://github.com/anthropics/claude-code/issues/62009)）。但图片字节没有蒸发：Claude Code 在网关看到消息之前，就把每条用户消息（含图片）原样写进了本地会话记录，`modlens recover-paste` 干的就是把它们捞回来、落成真实文件路径，直接喂给 `modlens -i`。skill 看到占位符会自动跑这一步。
+
+会话记录本来就是一个会话一个文件，skill 可以通过 `--session` 传入精确会话（Claude Code 从 v2.1.9 起会把 `${CLAUDE_SESSION_ID}` 替换进 skill 文本）。不传时按消息时间戳挑「持有最新粘贴图」的那份，两条路都不怕同项目并发多开。
+
+[Pi](https://github.com/earendil-works/pi) 的会话存储和它同构（`~/.pi/agent/sessions/`，图片以 base64 存 JSONL）。[OpenCode](https://github.com/sst/opencode) 换了个存法，图片以 data URL 塞进 SQLite（`~/.local/share/opencode/opencode.db`，读它需要 Node 22.5+ 的 node:sqlite）。
+
+`recover-paste` 会先搞清楚自己正跑在哪家宿主里（沿进程祖先链往上找，再核对 `CLAUDECODE`、`PI_CODING_AGENT`、`CODEX_THREAD_ID` 这些环境变量指纹），然后只读那一家的存储，别家的陈年会话再也没机会冒充。在 Claude Code 里还会直接用注入的会话 ID 精确定位，在 Codex 里则干脆拒绝执行并把你指回 path tag。实在识别不出来才退回按最新图片时间戳在三家赛跑。
+
+四家宿主全部活体验证过：Claude Code 靠注入的会话 ID 精确捞回粘贴，OpenCode 上 DeepSeek 全程自动触发 skill 跑完整条链路，Pi 只认自家存储不受别家污染，Codex 被拒之门外并指回 path tag。一句老实话：会话记录格式是这些工具的内部实现，没有兼容承诺，哪天捞不动了，拖文件永远是保底。
 
 OpenCode 接 DeepSeek 只要两步：`opencode auth login` 选 DeepSeek 贴上 key（落在 `~/.local/share/opencode/auth.json`），再把 `~/.config/opencode/opencode.jsonc` 的默认模型设成 `deepseek/deepseek-v4-flash`。Pi 的 key 放 `~/.pi/agent/auth.json`。
 

package/dist/main.js

@@ -36,8 +36,18 @@ function loadConfigFile(configPath = CONFIG_PATH) {
 function defaultProviderName(config2) {
   return config2.provider?.trim() || "antigravity-cli";
 }
+const PROVIDER_ALIASES = {
+  antigravity: "antigravity-cli",
+  agy: "antigravity-cli",
+  gemini: "gemini-api",
+  claude: "claude-cli"
+};
 function resolveProviderSettings(providerName, config2, env = process.env) {
-  const fromFile = config2.providers?.[providerName] ?? {};
+  const aliasNames = Object.entries(PROVIDER_ALIASES).filter(([, canonical]) => canonical === 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 };
   for (const [field, envName] of Object.entries(bindings)) {
@@ -314,11 +324,74 @@ function tryParseJson$1(text) {
     return null;
   }
 }
+const SWITCH_HINT = `Or switch to a provider with its own quota and no interactive login:
+  modlens config set gemini-api.apiKey <key>   # free key, no card: https://aistudio.google.com
+  modlens config set provider gemini-api`;
+function describeAntigravityFailure(context) {
+  const since = context.startedAt ?? Date.now() - LOG_FRESHNESS_MS;
+  let envelope = null;
+  try {
+    envelope = parseEnvelope$1(context.stdout);
+  } catch {
+    envelope = null;
+  }
+  if (!envelope) {
+    return null;
+  }
+  const agyError = typeof envelope?.error === "string" ? envelope.error.trim() : "";
+  const evidence = `${agyError}
+${context.stderr}
+${readRecentAgyLog(since)}`.toLowerCase();
+  if (evidence.includes("quota")) {
+    return [
+      agyError || "Antigravity CLI reported a quota error.",
+      "agy's free tier is one weekly bucket shared by the desktop app, the CLI, and the SDK, and subagents drain it in parallel. Wait for the reset shown above, or use a different provider.",
+      SWITCH_HINT
+    ].join("\n\n");
+  }
+  if (evidence.includes("not logged into antigravity") || evidence.includes("getting token source") || evidence.includes("keyring") || evidence.includes("failed to read token store")) {
+    return [
+      "Antigravity CLI cannot read its stored login token.",
+      "On Linux this usually means the OS keyring is locked, which is normal for headless sessions (agents, cron, systemd, SSH without a desktop login). agy then reports it as being signed out and tries a browser sign-in that cannot complete without a display. Unlock the keyring, or run modlens from a desktop session, or sign in again with `agy`.",
+      SWITCH_HINT
+    ].join("\n\n");
+  }
+  const totalTokens = envelope?.usage?.total_tokens;
+  if (agyError || totalTokens === 0) {
+    return [
+      agyError || "Antigravity CLI exited before doing any work (no tokens consumed).",
+      `Usually auth or quota. Check \`agy\` interactively, and look at the newest log in ${agyLogDir()} for the real reason.`,
+      SWITCH_HINT
+    ].join("\n\n");
+  }
+  return null;
+}
+function agyLogDir() {
+  return path.join(os.homedir(), ".gemini", "antigravity-cli", "log");
+}
+const LOG_FRESHNESS_MS = 2 * 60 * 1e3;
+function readRecentAgyLog(since) {
+  try {
+    const dir = agyLogDir();
+    const newest = fs.readdirSync(dir).filter((name) => name.endsWith(".log")).map((name) => {
+      const full = path.join(dir, name);
+      return { full, mtime: fs.statSync(full).mtimeMs };
+    }).sort((a, b) => b.mtime - a.mtime)[0];
+    if (!newest || newest.mtime < since) {
+      return "";
+    }
+    return fs.readFileSync(newest.full, "utf-8").slice(-8e3);
+  } catch {
+    return "";
+  }
+}
 const antigravityCliProvider = {
   name: "antigravity-cli",
   defaultModel: DEFAULT_MODEL,
   buildInvocation: buildAntigravityInvocation,
-  parseOutput: parseAntigravityOutput
+  parseOutput: parseAntigravityOutput,
+  describeFailure: describeAntigravityFailure,
+  hasInternalTimeout: true
 };
 const MIME_BY_EXT = {
   ".jpg": "image/jpeg",
@@ -671,9 +744,12 @@ Respond with ONE JSON object only, no markdown fences, no commentary. Fill this
     throw new Error(`OpenAI-compatible API returned non-JSON output: ${truncate(text)}`);
   }
   const shaped = result;
-  if (typeof shaped.summary !== "string" || typeof shaped.ocr !== "object") {
+  const missing = ["summary", "ocr", "layout", "semantics", "visual", "uncertainty"].filter(
+    (field) => shaped[field] === void 0 || shaped[field] === null
+  );
+  if (missing.length > 0 || typeof shaped.summary !== "string" || typeof shaped.ocr !== "object" || !Array.isArray(shaped.uncertainty)) {
     throw new Error(
-      `OpenAI-compatible API returned JSON that does not match the vision schema (missing summary/ocr). 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${missing.length > 0 ? ` (missing: ${missing.join(", ")})` : ""}. Retry, or switch to gemini-api / anthropic for enforced schemas. Got: ${truncate(text)}`
     );
   }
   return {
@@ -750,10 +826,12 @@ async function analyzeImage(options) {
     parsed = await provider.execute(providerOptions);
   } else if (provider.buildInvocation && provider.parseOutput) {
     const invocation = provider.buildInvocation(providerOptions);
+    const backstop = provider.hasInternalTimeout ? timeoutMs + KILL_GRACE_MS : timeoutMs;
     const commandResult = await runCommand(
       provider.name,
       invocation,
-      timeoutMs + KILL_GRACE_MS
+      backstop,
+      provider.describeFailure
     );
     parsed = provider.parseOutput(commandResult.stdout);
   } else {
@@ -798,12 +876,15 @@ function validateInputFile(filePath) {
     throw new Error(`Input is not a file: ${filePath}`);
   }
 }
-function runCommand(providerName, invocation, timeoutMs) {
+function runCommand(providerName, invocation, timeoutMs, describeFailure) {
+  const runStartedAt = Date.now();
   return new Promise((resolve, reject) => {
     const child = spawn(invocation.command, invocation.args, {
       cwd: invocation.cwd,
       stdio: ["ignore", "pipe", "pipe"]
     });
+    const outDecoder = new TextDecoder("utf-8");
+    const errDecoder = new TextDecoder("utf-8");
     let stdout = "";
     let stderr = "";
     let timedOut = false;
@@ -828,9 +909,10 @@ function runCommand(providerName, invocation, timeoutMs) {
         return;
       }
       if (code !== 0) {
+        const explained = describeFailure?.({ stdout, stderr, code, startedAt: runStartedAt }) ?? null;
         reject(
           new Error(
-            `${providerName} provider failed with code ${code}.${stderr ? ` stderr: ${stderr.trim()}` : ""}`
+            explained ?? `${providerName} provider failed with code ${code}.${stderr ? ` stderr: ${stderr.trim()}` : ""}`
           )
         );
         return;
@@ -847,11 +929,11 @@ function runCommand(providerName, invocation, timeoutMs) {
       drainTimer = setTimeout(() => settle(exitCode), DRAIN_GRACE_MS);
     };
     child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
+      stdout += outDecoder.decode(chunk, { stream: true });
       restartDrain();
     });
     child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
+      stderr += errDecoder.decode(chunk, { stream: true });
       restartDrain();
     });
     child.on("error", (error) => {
@@ -862,9 +944,10 @@ function runCommand(providerName, invocation, timeoutMs) {
       clearTimeout(timer);
       clearTimeout(drainTimer);
       if (error.code === "ENOENT") {
+        const missingCwd = !fs.existsSync(invocation.cwd);
         reject(
           new Error(
-            `Provider CLI not found: ${invocation.command}. Install Antigravity CLI and sign in first.`
+            missingCwd ? `Working directory does not exist: ${invocation.cwd}` : `Provider CLI not found: ${invocation.command}. Install it and sign in first.`
           )
         );
         return;
@@ -879,12 +962,39 @@ function runCommand(providerName, invocation, timeoutMs) {
     child.on("close", (code) => settle(code));
   });
 }
+function extensionFromMediaType(mediaType) {
+  const subtype = mediaType.split("/")[1]?.split("+")[0]?.replace(/[^a-z0-9]/gi, "");
+  return subtype ? subtype.toLowerCase() : "bin";
+}
 const EXT_BY_MIME = {
   "image/png": "png",
   "image/jpeg": "jpg",
   "image/webp": "webp",
   "image/gif": "gif"
 };
+function transcriptBelongsTo(filePath, cwd) {
+  const wanted = path.resolve(cwd);
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return false;
+  }
+  for (const line of raw.split("\n")) {
+    if (!line.includes('"cwd"')) {
+      continue;
+    }
+    try {
+      const recorded = JSON.parse(line).cwd;
+      if (typeof recorded === "string") {
+        const resolved = path.resolve(recorded);
+        return resolved === wanted || resolved.startsWith(`${wanted}${path.sep}`);
+      }
+    } catch {
+    }
+  }
+  return true;
+}
 function forEachJsonLine(filePath, visit) {
   let raw;
   try {
@@ -944,6 +1054,9 @@ function jsonlAdapter(options) {
     findNewest: (cwd) => {
       let best = null;
       for (const file of listJsonl(dirFor(cwd))) {
+        if (!transcriptBelongsTo(file, cwd)) {
+          continue;
+        }
         const timestamp = newestJsonlTimestamp(file, extractLine);
         if (timestamp !== null && (!best || timestamp > best.timestamp)) {
           best = { ref: jsonlSource(name, file, extractLine), timestamp };
@@ -953,7 +1066,7 @@ function jsonlAdapter(options) {
     },
     findSession: (cwd, sessionId) => {
       for (const file of listJsonl(dirFor(cwd))) {
-        if (matchesSession(path.basename(file), sessionId)) {
+        if (matchesSession(path.basename(file), sessionId) && transcriptBelongsTo(file, cwd)) {
           return jsonlSource(name, file, extractLine);
         }
       }
@@ -1012,6 +1125,9 @@ const piAdapter = jsonlAdapter({
 function opencodeDbPath() {
   return path.join(os.homedir(), ".local", "share", "opencode", "opencode.db");
 }
+function escapeLikePattern(value) {
+  return value.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
 function opencodeQuery(dbPath, cwd, sessionId) {
   let DatabaseSync;
   try {
@@ -1025,8 +1141,10 @@ function opencodeQuery(dbPath, cwd, sessionId) {
   const db = new DatabaseSync(dbPath, { readOnly: true });
   try {
     const resolved = path.resolve(cwd);
-    const sessionFilter = sessionId ? `AND (session.id = ? OR session.slug = ?)` : `AND (session.directory = ? OR session.directory LIKE ? || '/%' OR ? LIKE session.directory || '/%')`;
-    const params = sessionId ? [sessionId, sessionId] : [resolved, resolved, resolved];
+    const directoryFilter = `(session.directory = ? OR session.directory LIKE ? || '/%' ESCAPE '\\' OR ? LIKE session.directory || '/%' ESCAPE '\\')`;
+    const escaped = escapeLikePattern(resolved);
+    const sessionFilter = sessionId ? `AND ${directoryFilter} AND (session.id = ? OR session.slug = ?)` : `AND ${directoryFilter}`;
+    const params = sessionId ? [resolved, escaped, resolved, sessionId, sessionId] : [resolved, escaped, resolved];
     const rows = db.prepare(
       `SELECT part.data AS data, part.time_created AS time_created, part.session_id AS session_id
                  FROM part
@@ -1119,8 +1237,16 @@ function harnessFromPsTable(psOutput, startPid) {
     if (!proc) {
       return null;
     }
-    for (const token of proc.command.trim().split(/\s+/).slice(0, 8)) {
-      const mapped = HARNESS_BY_BASENAME[path.basename(token)];
+    const tokens = proc.command.trim().split(/\s+/);
+    const candidates = [tokens[0]];
+    if (/^(node|bun|deno)$/.test(path.basename(tokens[0] ?? ""))) {
+      const script = tokens.slice(1).find((token) => !token.startsWith("-"));
+      if (script) {
+        candidates.push(script);
+      }
+    }
+    for (const token of candidates) {
+      const mapped = token ? HARNESS_BY_BASENAME[path.basename(token)] : void 0;
       if (mapped) {
         return mapped;
       }
@@ -1157,26 +1283,29 @@ function detectHarness() {
   return null;
 }
 const ADAPTERS = [claudeAdapter, piAdapter, opencodeAdapter];
-function sourceForExplicitPath(filePath) {
-  if (filePath.endsWith(".db")) {
+function sourceForExplicitPath(filePath, cwd, harness) {
+  const declared = harness && harness !== "none" ? harness : void 0;
+  if (declared === "opencode" || !declared && filePath.endsWith(".db")) {
     return {
       harness: "opencode",
       location: filePath,
-      extract: () => opencodeImagesFromRows(opencodeQuery(filePath, process.cwd()))
+      extract: () => opencodeImagesFromRows(opencodeQuery(filePath, cwd))
     };
   }
-  if (filePath.includes(`${path.sep}.pi${path.sep}`)) {
+  if (declared === "pi" || !declared && filePath.includes(`${path.sep}.pi${path.sep}`)) {
     return jsonlSource("pi", filePath, piExtractLine);
   }
   return jsonlSource("claude-code", filePath, claudeExtractLine);
 }
 function locateSource(cwd, adapters = ADAPTERS) {
   let best = null;
+  const blockers = [];
   for (const adapter of adapters) {
     let candidate = null;
     try {
       candidate = adapter.findNewest(cwd);
-    } catch {
+    } catch (error) {
+      blockers.push(`${adapter.name}: ${error instanceof Error ? error.message : String(error)}`);
     }
     if (candidate && (!best || candidate.timestamp > best.timestamp)) {
       best = candidate;
@@ -1184,25 +1313,31 @@ function locateSource(cwd, adapters = ADAPTERS) {
   }
   if (!best) {
     const dirs = adapters.map((a) => a.describe(cwd)).join(" , ");
+    const blocked = blockers.length > 0 ? `
+Blocked: ${blockers.join(" | ")}` : "";
     throw new Error(
-      `No pasted images found in any session storage for this directory (looked in: ${dirs}). The user may not have pasted any, or the storage format changed; ask for a file path instead.`
+      `No pasted images found in any session storage for this directory (looked in: ${dirs}). The user may not have pasted any, or the storage format changed; ask for a file path instead.${blocked}`
     );
   }
   return best.ref;
 }
 function sourceForSession(cwd, sessionId, adapters = ADAPTERS) {
+  const blockers = [];
   for (const adapter of adapters) {
     try {
       const ref = adapter.findSession(cwd, sessionId);
       if (ref) {
         return ref;
       }
-    } catch {
+    } catch (error) {
+      blockers.push(`${adapter.name}: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
   const dirs = adapters.map((a) => a.describe(cwd)).join(" , ");
+  const blocked = blockers.length > 0 ? `
+Blocked: ${blockers.join(" | ")}` : "";
   throw new Error(
-    `No session ${sessionId} with pasted images under this project (looked in: ${dirs}). Check --cwd, or drop --session to auto-locate by newest pasted image.`
+    `No session ${sessionId} with pasted images under this project (looked in: ${dirs}). Check --cwd, or drop --session to auto-locate by newest pasted image.${blocked}`
   );
 }
 function recoverPastedImages(options = {}) {
@@ -1222,7 +1357,7 @@ function recoverPastedImages(options = {}) {
   const adapters = scoped ? ADAPTERS.filter((adapter) => adapter.name === scoped) : ADAPTERS;
   let source = null;
   if (options.transcript) {
-    source = sourceForExplicitPath(options.transcript);
+    source = sourceForExplicitPath(options.transcript, cwd, options.harness);
   } else if (options.session) {
     source = sourceForSession(cwd, options.session, adapters);
   } else {
@@ -1244,14 +1379,22 @@ function recoverPastedImages(options = {}) {
       `No pasted images found in ${source.location}. The user may not have pasted any, or the storage format changed; ask for a file path instead.`
     );
   }
-  fs.mkdirSync(outDir, { recursive: true });
+  fs.mkdirSync(outDir, { recursive: true, mode: 448 });
+  try {
+    fs.chmodSync(outDir, 448);
+  } catch {
+  }
   const picked = all.slice(-count);
   const images = picked.map((image) => {
     const buffer = Buffer.from(image.data, "base64");
     const hash = crypto.createHash("sha256").update(buffer).digest("hex").slice(0, 8);
-    const ext = EXT_BY_MIME[image.mediaType] ?? "png";
+    const ext = EXT_BY_MIME[image.mediaType] ?? extensionFromMediaType(image.mediaType);
     const filePath = path.join(outDir, `paste-${hash}.${ext}`);
-    fs.writeFileSync(filePath, buffer);
+    fs.writeFileSync(filePath, buffer, { mode: 384 });
+    try {
+      fs.chmodSync(filePath, 384);
+    } catch {
+    }
     const recovered = {
       path: filePath,
       mediaType: image.mediaType,
@@ -1269,7 +1412,7 @@ function recoverPastedImages(options = {}) {
   return result;
 }
 const program = new Command();
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.7.2");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.7.4");
 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").action(async (options) => {
   try {
     const timeoutMs = Number.parseInt(options.timeout, 10);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/modlens",
-  "version": "2.7.2",
+  "version": "2.7.4",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {