@liustack/modlens 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
-## 3.0.0 - 2026-08-06
+## 3.1.1 - 2026-08-07
+
+Fixes from a deep acceptance review (external audit, reproduced and verified here).
+
+- The isolated workdir now actually isolates. The "isolated copy" of a local image was a hardlink sharing the original's inode, so a provider writing its temp path mutated the user's file: it is now always a real 0600 copy, with a regression test asserting the original survives a provider that overwrites everything in its cwd. A remote image skipped isolation entirely and ran the agent in the caller's directory: it now gets an empty throwaway cwd, and the antigravity fallback is the tmpdir, never `process.cwd()`. `docs/security.md` states plainly that this is exposure reduction, not an OS sandbox, and that untrusted images are better served by an inline API provider.
+- Remote image downloads go through SSRF guards ported from modsearch. The old path called bare `fetch` on the user-supplied URL, so a URL pointing at loopback, RFC-private, link-local, or cloud-metadata addresses was downloaded and its bytes uploaded to the vision provider. Now the hostname is checked against a blocklist, every resolved address must be public, the connection is pinned to the exact validated IP via an undici dispatcher (closing DNS rebinding), and every redirect hop is re-normalized, re-validated, and re-pinned. There is deliberately no allow-private switch: for a genuinely local image the answer is a file path, and the error says so.
+- Schema validation has one source of truth. `missingSchemaFields` checked only that arrays existed, so `[42]` in `ocr.lines`, a string `reading_order`, and numbers in `uncertainty` all passed as evidence, and the runtime check required `visual` while the provider schema did not. The walk is now driven by `VISION_RESULT_SCHEMA` itself (types, array elements, enums, nested requireds, present-but-optional fields), and `visual` joins the schema's required list.
+- The launchers skip npx when node is below the CLI's 22.13 floor: an old node with a working npx used to be selected anyway, a path known to fail at run time. The diagnosis explains an unusable npx and reports `nodeMeetsFloor`, and the no-runtime next step names the actual node version. Doc wording is corrected: `doctor` spends no quota but the npx/bunx paths may download the pinned package on first use, and Bun cannot load `node:sqlite`, so OpenCode paste recovery on a bunx-resolved machine needs a real Node install.
+
+## 3.1.0 - 2026-08-07
+
+- Windows joins the CI matrix (Node 22 and 24), so the CLI core, config, `doctor`, harness detection, and OpenCode paste recovery run on a real Windows runner rather than being assumed. The POSIX-only cases (subprocess signal handling, permission-bit assertions, and the Claude Code and Pi JSONL home-layout fixtures) are guarded with `describe.skipIf`, and the OpenCode path normalization from #11 now runs end to end on Windows, not only as an injected-path unit test. A `.gitattributes` pins text files to LF so the Windows checkout matches the other platforms and Biome does not fail on line endings.
+- Two guards that assumed POSIX permissions are fixed for Windows, where files report `0o666`/`0o777` and access is ACL-based. `recover-paste --out-dir` no longer rejects an existing private directory, and `doctor` no longer flags the config file's mode. Both checks now run only where `process.getuid` exists, and the symlink guard on `--out-dir` stays in force everywhere.
+- The skill now launches the CLI through a bundled launcher (`skills/modlens/scripts/run.sh` for macOS/Linux, `run.ps1` for Windows) instead of a hard-coded `npx`, because a Claude Code native install has none of `node`, `npx`, `bun`, or `bunx` on PATH, so a fixed command failed for a whole class of users. Both launchers resolve the same way, forward every argument to the CLI unchanged, and share a `doctor --json` diagnosis: a compatible `modlens` already on PATH (same major version and not older than the pinned one), then the pinned-version `npx`, then `bunx --bun`, then a structured diagnosis on stderr with `nextSteps` and exit 78 when nothing can run. `doctor` is offline and chains the CLI's own provider/config doctor when a CLI is reachable. The native-artifact branch is a phase-B placeholder that reports none is published yet. The two scripts are POSIX sh and PowerShell 5.1, identical apart from their version constants and shell syntax, and a new `references/runtime.md` documents the pin, the compatibility rule, and the diagnostic fields.
+- `SKILL.md` is rewritten to drive the launcher: the usage section runs `run.sh` / `run.ps1`, keeps a plain-language version of the same resolution order for harnesses that forbid running scripts, and drops the bare-`npx` fallback. Its frontmatter is brought in line with the Agent Skills spec: `allowed-tools` becomes the spec's space-separated string (`Bash`) instead of a YAML list, and a `compatibility` field states the runtime requirement.
+- Release tooling stamps the pinned version so it cannot drift. A new `scripts/stamp.mjs` rewrites the version constant in `run.sh`, `run.ps1`, and `runtime.md` from `package.json`, `scripts/release.mjs` calls it on every bump, and `scripts/stamp.test.mjs` fails the build if the three copies ever disagree with `package.json`. The npm `files` list now ships `skills/modlens/scripts`.
+- Root `INSTALL.md`, written for an AI agent installing the skill on a user's behalf, is rebuilt around the launcher and the machine as found. Four ordered, idempotent steps (find the harness's skill directory, copy `skills/modlens` in, give it one vision engine, verify), each with an "if it fails" branch and Windows notes. It installs into the user-global skill directory by default, probes before configuring (the README now has the user prepare an engine first, so an already-ready provider is the common case), prefers the Gemini key for headless reliability with Antigravity as the no-signup path, and verifies through the launcher, including the exit-78 no-runtime diagnosis.
+- The README installation section (both languages) is reordered to match how the install actually flows: step 1 is the only human part, preparing an engine (get a free Gemini key, or install Antigravity and sign in), and step 2 hands one line to the user's AI, which follows `INSTALL.md` and reports back. The hero one-liner above the fold, three highlight bullets, and the how-it-works section are removed, keeping the highlights to evidence output, free start, and install-once-use-everywhere, and the docs table links `INSTALL.md`. The platform line is rewritten to state per-OS support honestly, and the harness and troubleshooting docs gain a Windows section.
 
 A code-review pass. Two user-facing bugs, a stack of doc corrections, and the tooling a public repo is expected to carry.
 

package/README.md

@@ -17,84 +17,38 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@liustack/modlens"><img src="https://img.shields.io/npm/v/@liustack/modlens?style=flat-square&label=npm&color=cb3837" alt="npm"></a>
-  <a href="https://github.com/liustack/modlens/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/liustack/modlens/ci.yml?branch=main&style=flat-square&label=ci" alt="CI"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@liustack/modlens?style=flat-square" alt="Node.js"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
 </p>
 
-```bash
-npx -y skills add liustack/modlens             # install the skill
-npx @liustack/modlens -i screenshot.png        # or just use the CLI
-```
-
-Models like DeepSeek-V4-Flash are cheap, fast, capable, and blind. Throw one a screenshot of an error and it sees nothing. ModLens hands the image to a real vision engine and brings back evidence your model can quote: every word transcribed, the layout mapped, the doubts declared. And **you just paste**: other bridges make you save a file and report its path, while ModLens pulls the pasted image straight back out of session storage.
+DeepSeek-V4-Flash has no vision capability and cannot process screenshots or images. ModLens is a plug-in vision engine that gives a text-only model sight. **ModLens reads images pasted straight into the chat**, no saving to a file and passing a path first.
 
 ## Highlights
 
-- **Pasting works.** A pasted image never becomes a file, which is why other vision bridges cannot see it. ModLens recovers it from the harness's local session storage instead.
-- **Evidence, not an impression.** Every word transcribed, layout cut into regions in reading order, entities and relations listed. Your model quotes specifics instead of trusting a vibe.
-- **It says when it cannot read something.** Uncertain parts land in `uncertainty`. Pixel coordinates and confidence scores, the two things vision models fabricate most, were deliberately dropped.
-- **Keep your model.** You picked it for price and reasoning, not eyesight. That choice stays.
-- **Starts with no key.** The default engine (Antigravity CLI) needs none. A free Gemini key cuts a read to 5-10 seconds.
-- **Install once, works everywhere.** Verified on real machines in Claude Code, Codex, Pi, and OpenCode.
+- **Completely free.** The default channel is Antigravity CLI, no API key needed. A free Gemini key brings a read down to 5-10 seconds.
+- **Evidence, not an impression.** 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.
 
 ## Installation
 
-```bash
-npx -y skills add liustack/modlens
-```
+**Step 1, set up a vision engine (the only part that needs your hands).** The recommended choice is a free Gemini API key: get one at [Google AI Studio](https://aistudio.google.com), about three minutes, no credit card.
 
-Or tell your agent: "Install the skill from https://github.com/liustack/modlens".
+A free API key in the OpenAI-compatible format from another platform is also a good option.
 
-Then give it a vision engine. A free **[AI Studio](https://aistudio.google.com) Gemini key** is the fast answer (three minutes, no credit card, 5-10 seconds per image):
+To avoid any sign-up, install Antigravity CLI instead, then sign in:
 
 ```bash
-modlens config set gemini-api.apiKey <key>
-modlens config set provider gemini-api
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+agy                                                           # sign in, then exit
 ```
 
-Skipping the sign-up is fine: **Antigravity CLI** works with no key, it is just slower (15-40 seconds) with a tight free quota:
-
-```bash
-curl -fsSL https://antigravity.google/cli/install.sh | bash && agy   # sign in, then exit
-```
+**Step 2, hand the rest to your AI.** Send it this line, along with the key if you chose the Gemini API key:
 
-Requires Node 22.13+, macOS or Linux.
+> Install and configure the modlens skill following https://github.com/liustack/modlens/blob/main/INSTALL.md, then run the health check and tell me the result.
 
 ## Usage
 
-With the skill installed you do not type commands: paste an image or drop a path, ask anything, and it fires on its own. By hand:
-
-```bash
-modlens -i screenshot.png                       # local image
-modlens -i https://example.com/chart.png        # remote image
-modlens -i chart.png --prompt "focus on axes"   # extra focus
-modlens recover-paste                           # pull a pasted image into a file
-```
-
-Output is a fixed JSON shape:
-
-```json
-{
-  "image": "/path/to/screenshot.png",
-  "provider": "gemini-api",
-  "result": {
-    "summary": "A workflow diagram with four nodes connected by labeled arrows.",
-    "ocr": { "full_text": "/shaping\nBEFORE YOU BUILD\n...", "lines": [] },
-    "layout": { "regions": [{ "reading_order": 1, "type": "title", "text": "/shaping" }] },
-    "uncertainty": []
-  },
-  "meta": {
-    "generatedAt": "2026-08-06T12:00:00.000Z",
-    "model": "gemini-3.6-flash",
-    "conversationId": null,
-    "durationSeconds": 6.4,
-    "usage": { "promptTokenCount": 1234, "candidatesTokenCount": 567 }
-  }
-}
-```
-
-`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).
+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.
 
 ## See it work
 
@@ -108,7 +62,7 @@ Three images pasted at once. The model queues them up and reads them one by one,
 
 ![Three images dropped together, read one by one](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-batch.png)
 
-The stress test: a scatter plot of 128 models. It identifies the chart, both axes, the log scale, and picks the one highlighted point out of the crowd with its coordinates (about $0.028, intelligence score 50). Dense charts are where vision models usually fold.
+The stress test: a scatter plot of 128 models. It identifies the chart, both axes, the log scale, and picks the one highlighted point out of the crowd with its coordinates (about $0.028, intelligence score 50). Dense charts are where vision models most often fail.
 
 ![The 128-model scatter plot, highlighted point read with exact coordinates](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-chart.png)
 
@@ -116,71 +70,12 @@ And the paste path, end to end: Claude Code on a DeepSeek gateway, two images pa
 
 ![Two pasted images recovered from session storage and read in a gateway Claude Code session](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-claude-paste-recovery.png)
 
-## How it works
-
-![A text-only model hands an image to the vision engine through the modlens skill and gets structured JSON evidence back](https://raw.githubusercontent.com/liustack/modlens/main/assets/flow.en.png)
-
-No magic, four steps:
-
-1. The skill triggers when an image shows up: a path, a URL, or the bare placeholder a text-only model gets left with after a paste.
-2. It runs the `modlens` CLI, which hands the image to a vision engine. Five to choose from, the free Antigravity CLI by default.
-3. The engine's reading is forced into a fixed JSON schema: transcription, layout, semantics, uncertainty. Output that does not match the schema is rejected, never patched up.
-4. Your model quotes the evidence and answers.
-
-The paste trick is the part nobody else does. A pasted image is handled inside the client: encoded and sent the moment it lands, gone before any outside tool can touch it, which is why other bridges tell you to save a file and report the path. But before those bytes leave, the harness has already written them into its local session record. `recover-paste` reads them back from there: JSONL in Claude Code and Pi, SQLite in OpenCode, and Codex needs no recovery at all because its pastes already land as temp files. Details in [harness setup](docs/harness-setup.md).
-
-| | Swap in a multimodal model | Other vision bridges (MCP servers etc.) | ModLens |
-| :-- | :-- | :-- | :-- |
-| Your chosen model | has to change | stays | stays |
-| An image pasted into the chat | visible if the model supports it | out of reach | recovered and read |
-| What you get back | the model's own reading | usually a description | transcription, layout regions, entities |
-| 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 |
-
-The weaknesses, in the same place: agy's free tier is a weekly quota and heavy use hits the wall (a free Gemini key sidesteps it). Session storage layouts are each harness's internals with no compatibility promise, so if recovery ever breaks, dragging the file in still works everywhere.
-
-## CLI reference
-
-`modlens analyze` (the default command):
-
-| Flag | Meaning | Default |
-| :-- | :-- | :-- |
-| `-i, --input <path\|url>` | Image to analyze (required) | |
-| `-p, --provider <name>` | Vision provider | `antigravity-cli` |
-| `-m, --model <name>` | Provider model | per provider (below) |
-| `-o, --output <path>` | Also write JSON to a file | |
-| `--prompt <text>` | Extra focus | |
-| `--timeout <ms>` | Provider timeout | `180000` |
-| `--provider-bin <path>` | Provider binary path | `agy` / `claude` |
-| `--workdir <path>` | Working directory for the provider | image's directory |
-
-The default `-m` model depends on the provider:
-
-| Provider | Default model |
-| :-- | :-- |
-| `antigravity-cli` (default) | `gemini-3.6-flash-low` |
-| `gemini-api` | `gemini-3.6-flash` |
-| `anthropic` | `claude-haiku-4-5-20251001` |
-| `claude-cli` | `haiku` |
-| `openai` | none, `-m` is required |
-
-`modlens recover-paste`:
-
-| Flag | Meaning | Default |
-| :-- | :-- | :-- |
-| `--count <n>` | How many recent pasted images to recover | `1` |
-| `--out-dir <path>` | Where to write recovered images | a fresh private `<tmpdir>/modlens-paste-*` per run |
-| `--session <id>` | Session id for exact targeting | auto-detect |
-| `--transcript <path>` | Explicit transcript `.jsonl` or `.db` (overrides `--session`) | |
-| `--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` (default, no key), `gemini-api` (fastest free route), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic`, and `claude-cli` (rides your Claude subscription). Two more subcommands: `modlens config <init|set|show>`, and `modlens doctor` (checks Node, provider readiness, which provider will be selected and why, and the detected harness, without spending quota or touching the network. Add `--json` for a machine-readable report).
-
 ## Documentation
 
 | Doc | Read it when |
 | :-- | :-- |
+| [INSTALL.md](INSTALL.md) | Installing the skill step by step (written for an agent) |
+| [CLI manual](skills/modlens/references/cli.md) | The CLI the skill drives: flags, config, doctor |
 | [Troubleshooting](docs/troubleshooting.md) | A command failed and the message needs decoding |
 | [Configuration](skills/modlens/references/configure.md) | Setting a key, switching providers, fixing config |
 | [Output contract](skills/modlens/references/output-schema.md) | Parsing the JSON or building on it |
@@ -191,10 +86,10 @@ Five providers: `antigravity-cli` (default, no key), `gemini-api` (fastest free
 
 ## Contributing
 
-ModLens does not accept pull requests. It is a small tool with one pair of hands on it, and every line stays author-owned: that tight loop is what keeps it dependable. Two ways to contribute that genuinely help:
+ModLens does not accept pull requests. The project is maintained by a single author who reviews every line, which is a deliberate choice for reliability. Two effective ways to contribute:
 
-- **[Open an issue](https://github.com/liustack/modlens/issues).** Bugs, ideas, a confusing error, docs that read wrong. Issues get read and drive what gets built.
-- **Fork it.** MIT means your copy is fully yours: rename it, rewire it, ship it.
+- **[Open an issue](https://github.com/liustack/modlens/issues).** Bugs, suggestions, confusing errors, unclear docs. Issues are read and shape what gets built next.
+- **Fork it.** Under MIT your copy is fully yours to modify and publish.
 
 ## Shameless plug
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">ModLens</h1>
 
-<p align="center"><b>给纯文本模型装上视力，而且你直接粘贴就行。</b></p>
+<p align="center"><b>为纯文本模型补上视觉能力，直接粘贴图片就能识别。</b></p>
 
 <p align="center">
   <a href="./README.md">English</a> ·
@@ -17,198 +17,93 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@liustack/modlens"><img src="https://img.shields.io/npm/v/@liustack/modlens?style=flat-square&label=npm&color=cb3837" alt="npm"></a>
-  <a href="https://github.com/liustack/modlens/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/liustack/modlens/ci.yml?branch=main&style=flat-square&label=ci" alt="CI"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@liustack/modlens?style=flat-square" alt="Node.js"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
 </p>
 
-```bash
-npx -y skills add liustack/modlens                # 装 skill
-npx @liustack/modlens -i screenshot.png           # 或者直接当 CLI 用
-```
-
-DeepSeek-V4-Flash 这类模型便宜、快、能打，唯独看不见图。你甩过去一张报错截图，它一片漆黑。ModLens 把图交给真正的视觉引擎，带回你的模型能引用的证据：图里的字一句不落地转录，版面切好，读不准的地方明说。而且**你直接粘贴就行**：别的方案都要你先存成文件再报路径，ModLens 直接从会话存储里把粘贴的图捞回来。
+DeepSeek-V4-Flash 没有视觉能力，无法处理截图和图片。ModLens 借助外挂视觉引擎，为纯文本模型补上视觉能力。**ModLens 支持直接粘贴图片识别**，无需先保存成文件再提供路径。
 
 ## 亮点
 
-- **粘贴就能用。** 粘贴的图从来不会落成文件，所以别的识图外挂都接不住。ModLens 换了条路，从 harness 的本地会话存储里捞。
-- **给的是证据，不是印象。** 全文转录、版面按阅读顺序切块、实体和关系单列。模型引用的是具体内容，不是大概感觉。
-- **读不准就说读不准。** 拿不准的地方进 `uncertainty`。像素坐标和置信度分数这两样视觉模型最爱编的字段，v2 直接删了。
-- **模型不用换。** 你选 DeepSeek 图的是价格和推理，不是视力，这个选择不用动。
-- **零 key 起步。** 默认引擎 Antigravity CLI 不要 key；领个免费 Gemini key，识图缩到 5 到 10 秒。
-- **一次装好，处处能用。** Claude Code、Codex、Pi、OpenCode 都在真机上验证过。
+- **完全免费。** 默认走 Antigravity CLI 通道，无需 api key。配一个免费的 Gemini key 可将识别耗时降至 5 到 10 秒。
+- **返回证据，而非印象。** 全文转录、按阅读顺序划分的版面区块、实体与关系列表，模型引用的是具体内容。
+- **一次安装，多端可用。** Claude Code、Codex、Pi、OpenCode 均经真机验证。
 
 ## 安装
 
-```bash
-npx -y skills add liustack/modlens
-```
+**第一步，准备一个视觉引擎（唯一需要你亲手做的）。** 推荐免费的 Gemini api key：到 [Google AI Studio](https://aistudio.google.com) 领取，约三分钟，无需信用卡。
 
-或者跟你的 agent 说一句「安装这个 skill https://github.com/liustack/modlens」。
+也推荐申请其他平台免费的 openai api 兼容格式的 api key。
 
-再给它一个视觉引擎。推荐 **[AI Studio](https://aistudio.google.com) 的免费 Gemini key**（三分钟，不要信用卡，识图 5 到 10 秒）：
+想完全免注册就改装 Antigravity CLI，然后完成登录：
 
 ```bash
-modlens config set gemini-api.apiKey <key>
-modlens config set provider gemini-api
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+agy                                                           # 浏览器完成登录后退出
 ```
 
-不想注册就用 **Antigravity CLI**，零 key，代价是慢（15 到 40 秒）且免费额度紧：
-
-```bash
-curl -fsSL https://antigravity.google/cli/install.sh | bash && agy   # 浏览器登录后退出
-```
+**第二步，剩下的交给你的 AI。** 把这句话发给它，用 Gemini api key 的话把 key 一起发：
 
-需要 Node 22.13+，macOS 或 Linux。
+> 按 https://github.com/liustack/modlens 的 INSTALL.md 安装并配置 modlens skill，完成后运行体检并把结果告诉我。
 
 ## 用法
 
-装完 skill 就不用记命令：粘一张图或甩个图片路径，问什么都行，skill 自己触发。手动用：
-
-```bash
-modlens -i screenshot.png                      # 本地图片
-modlens -i https://example.com/chart.png       # 远程图片
-modlens -i chart.png --prompt "重点看数据轴"    # 指定关注点
-modlens recover-paste                          # 把刚粘贴的图捞成文件
-```
-
-输出是结构固定的 JSON：
-
-```json
-{
-  "image": "/path/to/screenshot.png",
-  "provider": "gemini-api",
-  "result": {
-    "summary": "四个节点的工作流图，箭头带标注。",
-    "ocr": { "full_text": "/shaping\nBEFORE YOU BUILD\n...", "lines": [] },
-    "layout": { "regions": [{ "reading_order": 1, "type": "title", "text": "/shaping" }] },
-    "uncertainty": []
-  },
-  "meta": {
-    "generatedAt": "2026-08-06T12:00:00.000Z",
-    "model": "gemini-3.6-flash",
-    "conversationId": null,
-    "durationSeconds": 6.4,
-    "usage": { "promptTokenCount": 1234, "candidatesTokenCount": 567 }
-  }
-}
-```
-
-`meta` 记录这份结果是怎么来的：生成时间（`generatedAt`）、用的 `model`、provider 给的 `conversationId`（没有就是 null）、实际耗时 `durationSeconds`、以及 provider 报告的原始 `usage`（结构随 provider 而定，没有就是 null）。
+装好之后不需要记任何命令。正常聊天，粘贴图片或给出图片路径，提问即可，skill 自动触发：图片交给视觉引擎，答案基于读到的内容返回。
 
 ## 实测
 
-以下全是原样实录，驱动的都是纯文本的 DeepSeek-V4-Flash。
+以下均为原样记录，驱动的都是纯文本的 DeepSeek-V4-Flash。
 
-Codex 桌面 App 里丢一张推文截图。配文、互动数据（2.9K 回复、270K 点赞、5M 浏览），连图片的 alt 文字都没放过。分辨率不够的地方它老实说读不清，不硬编。
+Codex 桌面 App 中识别一张推文截图。配文、互动数据（2.9K 回复、270K 点赞、5M 浏览）以及图片的 alt 文字全部读出。分辨率不足的部分明确说明无法确认，没有编造。
 
 ![纯文本 DeepSeek 通过 ModLens 读出推文截图的全部细节](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-app.png)
 
-一次粘三张图。模型自己排队逐张读，连设计意图都点出来了。
+一次粘贴三张图。模型依次读取，包括对设计意图的判断。
 
-![一次丢三张图，逐张读取](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-batch.png)
+![一次粘贴三张图，逐张读取](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-batch.png)
 
-压力测试：128 个模型的散点图。它认出了图表类型、双轴定义、对数刻度，还把高亮的那个点从点堆里精准拎出来（成本约 $0.028，智能指数 50）。密集图表是识图模型最容易露怯的地方。
+压力测试：128 个模型的散点图。图表类型、双轴定义、对数刻度全部识别，并从密集点群中准确读出高亮点的位置（成本约 $0.028，智能指数 50）。密集图表是视觉模型最容易出错的场景。
 
 ![128 个模型的散点图，精确读出高亮点的坐标](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-chart.png)
 
-粘贴链路的端到端实录：接了 DeepSeek 的 Claude Code，两张图直接粘进对话。界面里只剩占位符，skill 从会话存储把两张图都捞回来读了，连 PPT 封面的配色色值都读出来了。
-
-![接了 DeepSeek 的 Claude Code 里粘贴的两张图被捞回并逐张读出](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-claude-paste-recovery.png)
-
-## 它是怎么干活的
-
-![纯文本模型经 modlens skill 把图片交给视觉引擎，回来的是结构化 JSON 证据](https://raw.githubusercontent.com/liustack/modlens/main/assets/flow.zh.png)
-
-没有魔法，四步：
-
-1. 图片出现时 skill 触发：一个路径、一个 URL，或者纯文本模型粘贴后剩下的那个占位符。
-2. skill 跑 `modlens` 命令，把图交给视觉引擎。五个引擎可选，默认是免费的 Antigravity CLI。
-3. 引擎的识读结果被强制装进固定的 JSON 结构：转录、版面、语义、不确定项。不合规的输出直接拒收，绝不凑合。
-4. 模型引用证据，回答问题。
-
-粘贴这一手是别家都没有的。粘贴从头到尾在客户端内部完成：图一落进对话框就被编码发走，外部工具根本没机会碰到，所以别的方案只能教你存文件报路径。但字节发走之前，harness 已经把它原样写进了本地会话记录，`recover-paste` 就是去那里捞：Claude Code 和 Pi 存 JSONL，OpenCode 存 SQLite，Codex 的粘贴本来就落成临时文件所以不需要捞。细节见[宿主接入](docs/harness-setup.md)。
-
-| | 换个多模态模型 | 其他识图外挂（MCP server 这类） | ModLens |
-| :-- | :-- | :-- | :-- |
-| 你选的模型 | 得换掉 | 不用换 | 不用换 |
-| 粘贴进对话的图 | 模型支持才看得见 | 接不住 | 捞回来直接读 |
-| 拿到手的是什么 | 模型自己的理解 | 通常一段描述 | 全文转录、版面区块、实体关系 |
-| 读不准的地方 | 可能编 | 可能编 | 进 `uncertainty` |
-| 花费 | 多模态模型的价格 | 多数按 API 计费 | agy 免费额度或免费 Gemini key |
-
-短板一并摆这儿：agy 免费额度是周配额，重度用会撞墙（换免费 Gemini key 绕开）。会话存储格式是各家 harness 的内部实现，没有兼容承诺，哪天捞不动了，拖文件永远是保底。
-
-## CLI 参数
-
-`modlens analyze`（默认命令）：
-
-| 参数 | 含义 | 默认值 |
-| :-- | :-- | :-- |
-| `-i, --input <path\|url>` | 要解析的图片（必填） | |
-| `-p, --provider <name>` | 视觉 provider | `antigravity-cli` |
-| `-m, --model <name>` | provider 模型 | 按 provider（见下） |
-| `-o, --output <path>` | 同时把 JSON 写入文件 | |
-| `--prompt <text>` | 额外关注点 | |
-| `--timeout <ms>` | provider 超时 | `180000` |
-| `--provider-bin <path>` | provider 可执行文件路径 | `agy` / `claude` |
-| `--workdir <path>` | provider 的工作目录 | 图片所在目录 |
-
-`-m` 的默认模型取决于 provider：
-
-| Provider | 默认模型 |
-| :-- | :-- |
-| `antigravity-cli`（默认） | `gemini-3.6-flash-low` |
-| `gemini-api` | `gemini-3.6-flash` |
-| `anthropic` | `claude-haiku-4-5-20251001` |
-| `claude-cli` | `haiku` |
-| `openai` | 无默认，必须指定 `-m` |
-
-`modlens recover-paste`：
-
-| 参数 | 含义 | 默认值 |
-| :-- | :-- | :-- |
-| `--count <n>` | 恢复最近几张粘贴的图 | `1` |
-| `--out-dir <path>` | 恢复的图写到哪个目录 | 每次运行新建的私有目录 `<tmpdir>/modlens-paste-*` |
-| `--session <id>` | 精确锁定的 session id | 自动检测 |
-| `--transcript <path>` | 显式指定 `.jsonl` 或 `.db`（优先于 `--session`） | |
-| `--harness <name>` | 强制存储范围：`claude-code`、`pi`、`opencode`、`none` | 自动检测 |
-| `--cwd <path>` | 图片是在哪个项目目录粘贴的 | 当前目录 |
+粘贴链路的端到端记录：接入 DeepSeek 的 Claude Code，两张图直接粘贴进对话。界面中只显示占位符，skill 从会话存储恢复两张图片并逐一读出，包括 PPT 封面的配色色值。
 
-五个 provider 可选：`antigravity-cli`（默认，零 key）、`gemini-api`（最快的免费路线）、`openai`（任何 OpenAI 兼容多模态端点）、`anthropic`、`claude-cli`（吃你的 Claude 订阅）。另有两个子命令：`modlens config <init|set|show>` 管配置，`modlens doctor` 体检本机（Node 版本、各 provider 就绪状态、最终会选哪个 provider 及原因、检测到的 harness），不消耗额度、不发网络请求，加 `--json` 输出机器可读报告。
+![接入 DeepSeek 的 Claude Code 中，粘贴的两张图被恢复并逐张读出](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-claude-paste-recovery.png)
 
 ## 文档
 
-| 文档 | 什么时候看 |
-| :-- | :-- |
-| [故障排查](docs/troubleshooting.md) | 命令报错，想知道成因和解法 |
-| [配置手册](skills/modlens/references/configure.md) | 配 key、换 provider、排查配置 |
-| [输出契约](skills/modlens/references/output-schema.md) | 要解析 JSON 或写下游工具 |
-| [宿主接入](docs/harness-setup.md) | 在 Codex、Claude Code、Pi、OpenCode 里配置 |
-| [安全说明](docs/security.md) | 恢复文件的权限、图片内容作为不可信输入 |
-| [更新日志](CHANGELOG.md) | 想知道某个版本改了什么 |
-| [AGENTS.md](AGENTS.md) | 要改这个项目的代码 |
+| 文档                                                   | 适用场景                                   |
+| :----------------------------------------------------- | :----------------------------------------- |
+| [INSTALL.md](INSTALL.md)                               | 一步步安装 skill（为 agent 编写）          |
+| [CLI 手册](skills/modlens/references/cli.md)           | skill 所驱动的 CLI：参数、配置与体检       |
+| [故障排查](docs/troubleshooting.md)                    | 命令报错，查成因和解法                     |
+| [配置手册](skills/modlens/references/configure.md)     | 配置 key、切换 provider、排查配置          |
+| [输出契约](skills/modlens/references/output-schema.md) | 解析 JSON 或构建下游工具                   |
+| [宿主接入](docs/harness-setup.md)                      | 在 Codex、Claude Code、Pi、OpenCode 中配置 |
+| [安全说明](docs/security.md)                           | 恢复文件的权限、图片内容作为不可信输入     |
+| [更新日志](CHANGELOG.md)                               | 查询版本变更                               |
+| [AGENTS.md](AGENTS.md)                                 | 修改本项目代码                             |
 
 ## 参与方式
 
-本仓不收 PR。工具小，一双手维护，每一行代码都要作者自己背，这个闭环收紧了它才可靠。真正帮得上忙的两条路：
+本仓库不接受 PR。项目由作者独立维护，所有代码经作者本人审阅，这是它可靠性的前提。两种有效的参与方式：
 
-- **[提 issue](https://github.com/liustack/modlens/issues)。** bug、想法、看不懂的报错、读着别扭的文档都算。issue 一定会被读，也真的会影响接下来做什么。
-- **Fork。** MIT 协议下你的副本完全归你：改名、魔改、发布都随意。
+- **[提交 issue](https://github.com/liustack/modlens/issues)。** bug、建议、难以理解的报错或文档都欢迎。issue 会被认真阅读，并影响后续开发方向。
+- **Fork。** MIT 协议下你的副本完全归你，修改和发布不受限制。
 
-## 关注公众号
+## 插入硬广一条
 
-AI 工具、实践与想法，第一时间推送。微信扫码，或搜一搜「liustack」关注：
+关注微信公众号「liustack」：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) 一个 star，这是其他开发者找到它的方式。
 
 ## 免责声明
 
-本项目依下方 MIT 协议按现状提供。作者不对任何特定用途（含商业使用）提供保证或背书。上游引擎（Antigravity CLI，Gemini、OpenAI、Anthropic 的 API，以及任何 OpenAI 兼容端点）的使用受各自条款和额度约束，由使用者自行负责。
+本项目依下方 MIT 协议按现状提供。作者不对任何特定用途（含商业使用）提供保证或背书。上游引擎（Antigravity CLI，Gemini、OpenAI、Anthropic 的 API，以及任何 OpenAI 兼容端点）的使用受各自条款和额度约束，由使用者负责。
 
 ## License