@liustack/modlens 2.7.6 → 2.7.8

package/README.md

@@ -13,15 +13,16 @@ DeepSeek-V4-Flash gives you a lot of model for very little money: fast, strong,
 
 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)
-                              │
-                              ▼
-                  vision engine · Gemini 3.6 Flash (free)
-                              │
-                              ▼
-              structured JSON evidence ──▶ model answers with sight
-```
+![Paste an image into the terminal, a lens reads it, structured evidence comes back](https://raw.githubusercontent.com/liustack/modlens/main/assets/flow.jpg)
+
+- **You just paste.** Every other bridge makes you save a file and report its path. ModLens pulls the pasted image back out of session storage.
+- **Evidence, not an impression.** Full OCR text, layout regions in reading order, semantic entities, visual clues. Your model can quote specifics.
+- **It says when it cannot read something.** Anything uncertain lands in `uncertainty` rather than being invented. Pixel coordinates and confidence scores, the two things models fabricate most, were dropped in v2.
+- **No model swap, no config changes, no local proxy.** You picked your model for price and reasoning, not eyesight. That choice stays.
+- **Starts with no key, gets faster with a free one.** agy needs no key at all, and a free AI Studio Gemini key takes three minutes and reads an image in 5-10 seconds.
+- **Install once, works in four harnesses.** Verified in Claude Code, Codex, Pi, and OpenCode.
+
+**Requirements**: Node 18+ (22.5+ for OpenCode paste recovery), macOS or Linux. Hit a problem? [Troubleshooting](docs/troubleshooting.md) lists every error this CLI prints, with causes and fixes.
 
 ## You can just paste the image
 
@@ -31,6 +32,19 @@ That is not laziness on their part. Pasting is handled end to end by the client:
 
 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.
 
+Side by side:
+
+| | Swap in a multimodal model | Vision MCP servers | ModLens |
+| :-- | :-- | :-- | :-- |
+| Your chosen model | has to change | stays | stays |
+| An image pasted into the chat | visible if the model supports it | not reachable, their docs say save a file and report the path | handled directly |
+| What you get back | the model's own reading | usually a description | OCR text, layout regions, semantics, visual clues |
+| Where it cannot read | may invent | may invent | says so in `uncertainty` |
+| Cost | multimodal model pricing | usually per API call | agy's free quota, or a free Gemini key |
+| Setup | change config, change model | install a server, edit config | one CLI or one skill |
+
+The honest weaknesses: agy's free tier is a weekly quota and heavy use hits the wall (a free Gemini key sidesteps that). Session storage layouts are each harness's internals with no compatibility promise, so if recovery ever breaks, dragging the file in still works everywhere.
+
 ## Quick start
 
 **1. Install the skill.** Just tell your agent (Claude Code, Codex, OpenClaw, Cursor, ...):

package/README.zh-CN.md

@@ -13,15 +13,16 @@ DeepSeek-V4-Flash 碗大又好吃，速度快，性能强，要说唯一的缺
 
 ModLens 用最轻的方式解决它：不动你的配置，不装本地代理，就是一个视觉外挂，CLI 和 skill 两种用法。它产出的不是一句话描述，是结构化的视觉证据：文字、版面、区块、实体、关系、视觉线索。视觉引擎有五个可选，默认那个零 key 就能跑，最快的那个用免费 Gemini key，识图能力连 Fable 5 都吊打。原理如下：
 
-```text
-Agent Harness 中的纯文本模型 ──▶ modlens skill（遇到图片自动触发）
-                        │
-                        ▼
-             视觉引擎 · Gemini 3.6 Flash（免费）
-                        │
-                        ▼
-           结构化 JSON 证据 ──▶ 模型带着视力回答
-```
+![把图片粘进终端，放大镜读图，结构化证据回到终端](https://raw.githubusercontent.com/liustack/modlens/main/assets/flow.jpg)
+
+- **你直接粘贴就行。** 别的方案让你先存成文件再报路径，ModLens 从会话存储里把粘贴的图捞回来。
+- **给的是证据，不是印象。** OCR 全文、按阅读顺序排好的版面区块、语义实体、视觉线索，模型能引用具体内容。
+- **读不准就说读不准。** 拿不准的地方进 `uncertainty`，不编。像素坐标和置信度分数这两样模型最爱编的，v2 直接删了。
+- **不换模型，不改配置，不装代理。** 你选 DeepSeek 图的是价格和推理，不是视力，这个选择不用动。
+- **零 key 起步，想快就领个免费 key。** agy 不要 key，AI Studio 的免费 Gemini key 三分钟到手，识图 5-10 秒。
+- **装一次，四家 harness 通用。** Claude Code、Codex、Pi、OpenCode 都验证过。
+
+**环境要求**：Node 18+（OpenCode 的粘贴恢复需要 22.5+），macOS 或 Linux。 出问题看[故障排查](docs/troubleshooting.md)，里面按报错原文列了每一条的成因和解法。
 
 ## 你可以直接粘贴图片
 
@@ -31,6 +32,19 @@ Agent Harness 中的纯文本模型 ──▶ modlens skill（遇到图片自动
 
 四家 harness 真机验证过：Claude Code 按注入的会话 ID 精确定位，Pi 的存储路数和它同构，OpenCode 换成了 SQLite，Codex 的粘贴图本来就带临时路径，走路径标签就行。动手之前 `recover-paste` 会先认清自己跑在哪一家（查进程祖先链，核对环境变量指纹），只读那一家的存储，别家的旧会话冒充不了。
 
+放在一起看更清楚：
+
+| | 换个多模态模型 | 识图类 MCP server | ModLens |
+| :-- | :-- | :-- | :-- |
+| 你选的模型 | 得换掉 | 不用换 | 不用换 |
+| 粘贴进对话的图 | 模型支持就能看 | 接不住，文档让你先存文件报路径 | 直接接住 |
+| 拿到手的是什么 | 模型自己的理解 | 通常是一段描述 | OCR 全文、版面区块、语义、视觉线索 |
+| 读不准的地方 | 可能编 | 可能编 | 进 `uncertainty`，明说读不准 |
+| 花费 | 多模态模型的价格 | 多数按 API 计费 | agy 免费额度，或免费 Gemini key |
+| 上手 | 改配置换模型 | 装 server、改配置 | 一个 CLI 或一个 skill |
+
+诚实说短板：agy 的免费额度是周配额，重度用会撞墙（换成免费 Gemini key 就绕开了）。会话存储格式是各家 harness 的内部实现，没有兼容承诺，哪天捞不动了，拖文件永远是保底。
+
 ## 快速开始
 
 **1. 装 skill。** 直接告诉你的 agent（Claude Code、Codex、OpenClaw、Cursor 等）：

package/dist/main.js

@@ -1478,7 +1478,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.6");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.7.8");
 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.6",
+  "version": "2.7.8",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {
@@ -50,6 +50,7 @@
     "build": "vite build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "release": "node scripts/release.mjs",
     "docs:list": "node scripts/docs-list.js"
   }
 }

package/skills/modlens/SKILL.md

@@ -101,6 +101,8 @@ Structure is enforced by schema on antigravity-cli and claude-cli (`--json-schem
 
 ## Failure Handling
 
+Every error this CLI prints is catalogued with its cause and fix in the project's `docs/troubleshooting.md`. Read the message first: most of them already name the fix.
+
 - `Provider CLI not found`: Antigravity CLI is not installed. Install it, or switch provider: `-p gemini-api`.
 - Missing key errors name the exact env var and `config set` command to run. Relay that to the user.
 - `does not match the vision schema` on the openai route: retry once, then switch to `-p gemini-api` or `-p anthropic` for enforced schemas.