dsh-moli 1.0.4 → 1.0.6

package/README.md

@@ -3,185 +3,141 @@
 [![npm version](https://img.shields.io/npm/v/dsh-moli)](https://www.npmjs.com/package/dsh-moli)
 [![license](https://img.shields.io/npm/l/dsh-moli)](LICENSE)
 
-Expose a locally installed [Moli](https://github.com/lexmount/moli) (`moli.exe`, a Rust headless
-browser for AI agents) as **DeepSeek Harness tools**, so an agent can call it instead of shelling out.
+**Two tools that let a DeepSeek Harness agent drive a real headless browser.** They wrap
+[Moli](https://github.com/lexmount/moli) — a Rust headless browser built for AI agents — so an agent can
+read pages that only exist after JavaScript runs, and can produce pictures of them.
 
 English | [中文](README.zh.md)
 
-## Quick start
+## What it does, and when you want it
 
-Published on npm as [`dsh-moli`](https://www.npmjs.com/package/dsh-moli):
+A plain HTTP fetch returns the HTML the server sent. That is enough for articles, docs and APIs, and
+DSH already covers it with `web_fetch`. It is not enough for anything a browser has to build:
 
-```powershell
-dsh plugin --profile web add dsh-moli
-```
+- **Single-page apps** — a client-rendered news site, dashboard or docs site. The response is an empty
+  shell; the content appears only after scripts run.
+- **Logins and consent walls** — a page that needs a session or cookie before it shows anything.
+- **Pictures** — a screenshot to see what a page looks like, or a PDF to keep.
+- **One value from deep inside a page** — a price, a count, a title, read with a selector instead of
+  pulling the whole document.
 
-That is the recommended route: it resolves through the npm registry, so it also works where GitHub
-is slow or unreachable, and DSH's install dialog can fall back to a regional mirror. Installing
-straight from the repository works too, and needs GitHub to be reachable:
+For those jobs this plugin gives the agent two tools:
 
-```powershell
-dsh plugin --profile web add github:27painter/dsh-moli
-```
-
-> [!IMPORTANT]
-> **The npm package contains the plugin only — it does not bundle Moli.** It is 26 kB of JavaScript;
-> the `moli.exe` engine is a separate ~101 MB Rust binary with its own release process, so this
-> plugin installs alongside Moli rather than shipping it.
->
-> **There is no npm package for Moli itself.** The names `moli` and `moli-cli` on the registry belong
-> to unrelated projects, and `@lexmount/moli` does not exist. Moli is distributed as prebuilt
-> binaries on [GitHub Releases](https://github.com/lexmount/moli/releases/latest) — do not install
-> the engine by guessing a package name.
+| Tool | What it does |
+|---|---|
+| `moli_fetch` | Renders a URL and returns Markdown, HTML, a semantic tree, or a JSON envelope carrying the HTTP status; evaluates a JavaScript expression; writes a PNG screenshot or a PDF |
+| `moli_probe` | Reports whether the engine is installed, which version, and whether HTTPS works — and installs Moli when it is missing |
 
-Either plugin route ends the same way. Restart DSH, then check the engine and fetch a page:
+The practical question is whether the agent needs the page as a **browser** would see it. If a plain
+fetch already returns the text you want, `web_fetch` is lighter and faster.
 
 ```
-moli_probe
-moli_fetch url=https://example.com dump=markdown
+  agent ──moli_fetch──▶ dsh-moli plugin ──spawns──▶ moli.exe
+                              ▲                         │
+                              │                    renders the page,
+                              │                    runs its JavaScript
+                              │                         │
+                              └──markdown / json / png / pdf◀┘
 ```
 
-### Getting the Moli engine
-
-`moli_probe` reports whether it is present. If it is not, pick one of:
+## Install
 
-**1. Let the plugin install it** — several download routes, and a SHA256 of what actually ran:
+Two routes. Both install the same plugin; pick by what your network reaches.
 
-```
-moli_probe action=install
-```
-
-**2. Official one-line installer** (Moli's own documented command):
+**Route 1 — from npm (recommended).** Resolves through the npm registry, so it works where GitHub is
+slow or blocked, and DSH's install dialog can fall back to a regional mirror:
 
 ```powershell
-# Windows
-powershell -ExecutionPolicy ByPass -c "irm https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1 | iex"
-```
-
-```sh
-# Linux / macOS
-curl --proto '=https' --tlsv1.2 -fsSL https://github.com/lexmount/moli/releases/latest/download/moli-installer.sh | sh
+dsh plugin --profile web add dsh-moli
 ```
 
-**3. Direct binary, if you would rather not run an installer:**
+**Route 2 — straight from the repository.** Tracks the source directly; needs GitHub to be reachable:
 
 ```powershell
-# pick the asset for your architecture from the releases page
-curl.exe -L -o moli.zip https://github.com/lexmount/moli/releases/latest/download/moli-x86_64-pc-windows-msvc.zip
-Expand-Archive moli.zip -DestinationPath "$env:LOCALAPPDATA\Moli" -Force
+dsh plugin --profile web add github:27painter/dsh-moli
 ```
 
-Those `releases/latest/download/...` URLs always resolve to the newest release, so they stay valid
-without pinning a version. See [Verifying the download](#verifying-the-download) to check what you
-got against GitHub's published digest, and [Manual install of Moli](#manual-install-of-moli) for the
-same commands in context.
+> [!IMPORTANT]
+> **The npm package is the plugin only — it does not contain the Moli engine.**
+>
+> The npm tarball is 26 kB: eight JavaScript and text files. `moli.exe` is a separate ~101 MB compiled
+> Rust binary, built and released by the Moli project on its own schedule.
+>
+> **Why it cannot be bundled:**
+>
+> - **Size.** The engine is roughly 4,000× the plugin. Every install and every plugin update would
+>   carry a browser.
+> - **Ownership.** Moli is `lexmount/moli` under its own MIT copyright. Redistributing its binary
+>   through this package would mean re-publishing someone else's artifact as our own.
+> - **Platforms.** The engine ships per OS and per architecture — Windows/Linux/macOS × x64/arm64.
+>   Bundling would pin one build into every user's install.
+> - **Versions.** The plugin must work with whatever Moli version a user has, including Moli releases
+>   that appear after the plugin was published. Bundling would lock the pair together.
+>
+> **There is no npm package for the engine either.** The registry names `moli` and `moli-cli` belong to
+> unrelated projects, and `@lexmount/moli` does not exist. Moli ships as prebuilt binaries on
+> [GitHub Releases](https://github.com/lexmount/moli/releases/latest) — do not install the engine by
+> guessing a package name.
 
-## What it provides
+## The two situations after installing
 
-| Tool | Purpose |
-|---|---|
-| `moli_fetch` | Fetch a URL and return rendered HTML, Markdown, the semantic tree, or a JSON envelope (`status`, `final_url`); evaluate a JavaScript expression; write a PNG screenshot or a PDF |
-| `moli_probe` | Report the engine path and version and whether HTTPS works; with `action: "install"`, download and install Moli first |
+The two download routes above install the same thing. What differs is whether Moli is already on the
+machine — and that decides whether you are finished or have one more step.
 
-`moli_fetch` parameters: `url` (required), `dump`, `writeTo`, `eval`, `wait`, `waitSelector`,
-`delayMs`, `timeoutMs`, `maxChars`, `headers`, `userAgent`, `layout`, `scrollbars`, `noJs`,
-`noCss`, `resources`, `withFrames`, `insecureTls`, `profileDir`, `cookieFile`.
+### Situation A — Moli is already installed: nothing else to do
+
+The plugin discovers `moli.exe` on its own and both tools work immediately. Just restart DSH and
+confirm:
 
 ```
-moli_fetch url=https://example.com dump=markdown            # token-efficient text
-moli_fetch url=https://example.com dump=semantic_tree_text   # nodes with backend ids
-moli_fetch url=https://example.com eval="document.title"     # one computed value
-moli_fetch url=https://example.com dump=screenshot writeTo=/abs/path/a.png
-moli_fetch url=https://example.com dump=pdf        writeTo=/abs/path/a.pdf
+moli_probe
 ```
 
-## Relationship to Moli's own agent skills
-
-Moli ships official agent skills in its repository — [`moli-webfetch`](https://github.com/lexmount/moli/tree/main/skills/moli-webfetch),
-[`moli-websearch`](https://github.com/lexmount/moli/tree/main/skills/moli-websearch), and
-[`moli-cdp-server`](https://github.com/lexmount/moli/tree/main/skills/moli-cdp-server) — and their
-README's quick start is to have an agent install them. If your agent loads skills, the simplest path
-is to point it at those; they are maintained upstream and cover web search and a CDP server too.
-
-This plugin exists because it is a different trade-off, not a replacement:
-
-- **Always-on tool schemas instead of an on-demand skill.** The tools are registered at Host startup,
-  so the model sees them every turn with no discovery step.
-- **DSH-specific failure handling.** The three traps below (sandbox pipe capture, UTF-16 mangling of
-  binary output, bare-specifier resolution for a `link:`ed plugin) plus sandbox/revocation/proxy
-  classification are solved here, because they are DSH-on-Windows problems.
-- **Smaller surface.** Only `fetch` is wrapped; the official skills also cover web search and the CDP
-  server, which this plugin does not.
-
-Both can coexist: install the skills if you want upstream coverage, keep this plugin if you want the
-capabilities always visible to the model.
+If the reported version looks right, you are done.
 
-## Installation
+### Situation B — Moli is not installed yet: fetch the engine too
 
-The plugin is installed into a DSH profile. Pick the route that matches your machine.
+`moli_fetch` will keep reporting a missing engine until you install one. Do that with either of:
 
-### Route A — Moli is already installed
-
-Nothing else to fetch. The plugin finds `moli.exe` on its own and both tools work immediately.
+```
+moli_probe action=install          # let the plugin fetch it
+```
 
 ```powershell
-dsh plugin --profile web add dsh-moli
+# or run Moli's own installer yourself
+powershell -ExecutionPolicy ByPass -c "irm https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1 | iex"
 ```
 
-Install from the repository instead if you prefer tracking the source, or if the registry is
-unreachable for you:
+Then confirm with `moli_probe` and fetch a page:
 
-```powershell
-dsh plugin --profile web add github:27painter/dsh-moli
+```
+moli_probe
+moli_fetch url=https://example.com dump=markdown
 ```
 
-Restart DSH, then confirm with `moli_probe`.
+### Getting the Moli engine
 
-### Route B — Moli is not installed yet
+`moli_probe` reports whether the engine is present. If it is not, pick one of:
 
-Install the plugin the same way, restart, then let it fetch Moli for you:
+**1. Let the plugin install it** — tries several download routes and reports a SHA256 of what it ran:
 
-```powershell
-dsh plugin --profile web add dsh-moli
-# restart DSH, then call:
+```
 moli_probe action=install
 ```
 
-The install action tries several download routes in turn and reports every outcome, because a
-filtered network can block the release host completely. It reports the SHA256 of the exact bytes it
-ran, and `expectedSha256` turns that report into an enforced gate — see
-[Verifying the download](#verifying-the-download). Installation only ever runs when a call asks for
-it; it is never a side effect of using `moli_fetch`.
-
-### Installing into the desktop profile
-
-`dsh plugin --profile desktop …` is refused — the desktop profile belongs to the Electron app. Either
-edit its `package.json` directly (add a `link:` dependency **and** the bundle entry, then run
-`pnpm install`), or use the in-app plugin page (sidebar → **Plugins** → **Add plugin**), which goes
-through the same pnpm path.
-
-A profile plugin needs both halves: a dependency edge and a `dsh.profile.bundles` entry. One without
-the other leaves the plugin invisible to the loader, and an unresolvable bundle is **skipped
-silently** apart from one stderr line (`skipping profile bundle …`). If the tools never appear, that
-line is the first thing to look for.
-
-## Manual install of Moli
-
-When the automatic routes fail, install Moli yourself. These are Moli's own documented commands.
-
-Windows (PowerShell):
+**2. Official one-line installer** (Moli's own documented commands):
 
 ```powershell
+# Windows
 powershell -ExecutionPolicy ByPass -c "irm https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1 | iex"
 ```
 
-Linux / macOS:
-
 ```sh
+# Linux / macOS
 curl --proto '=https' --tlsv1.2 -fsSL https://github.com/lexmount/moli/releases/latest/download/moli-installer.sh | sh
 ```
 
-A direct Windows binary is published too, if you would rather not run an installer:
+**3. Direct binary,** if you would rather not run an installer:
 
 ```powershell
 # pick the asset matching your architecture from the releases page
@@ -189,14 +145,17 @@ curl.exe -L -o moli.zip https://github.com/lexmount/moli/releases/latest/downloa
 Expand-Archive moli.zip -DestinationPath "$env:LOCALAPPDATA\Moli" -Force
 ```
 
-After any of these, point the plugin at the result if it landed somewhere unusual:
+Those `releases/latest/download/...` URLs always resolve to the newest release, so they stay valid
+without pinning a version.
+
+After any of them, point the plugin at the result if it landed somewhere unusual:
 
 ```yaml
 config:
   exePath: 'C:\path\to\moli.exe'
 ```
 
-### Verifying the download
+#### Verifying the download
 
 Moli's README documents no checksum or signature, and the installer publishes no checksum file. What
 does exist is GitHub's own per-asset `sha256` digest, readable from the release API:
@@ -219,12 +178,69 @@ Compare it against the file you downloaded:
 ```
 
 The plugin follows the same discipline: `moli_probe action=install` reports the SHA256 of the bytes it
-ran, and `expectedSha256` enforces a digest you supply. It does not invent a trusted default, because
-the digest is only meaningful when compared against the release page's own value.
+ran, and `expectedSha256` turns that report into an enforced gate. It does not invent a trusted
+default, because a digest only means something when compared against the release page's own value.
+
+This is a checked property rather than a claim: downloading `v1.1.17`'s installer through the plugin's
+own `downloadInstaller` reproduced `e002f7a6…964d` exactly — the digest GitHub publishes — and
+re-hashing the file from disk matched as well.
 
-This is a checked property, not a claim: downloading `v1.1.17`'s installer through
-`downloadInstaller` reproduced `e002f7a6…964d` exactly — the same digest GitHub publishes — and
-re-hashing the file from disk matched too.
+### Installing into a desktop profile
+
+`dsh plugin --profile desktop …` is refused — the desktop profile belongs to the Electron app. Either
+edit its `package.json` directly, or use the in-app plugin page (sidebar → **Plugins** → **Add
+plugin**), which installs through the same pnpm path.
+
+A profile plugin needs both halves: a dependency edge (`dependencies`) and a
+`dsh.profile.bundles` entry. One without the other leaves the plugin invisible to the loader. From a
+local checkout the four steps are:
+
+1. Put this directory anywhere, e.g. `D:\dsh_plugins\dsh-moli`.
+2. Add both entries to the profile's `package.json`:
+   - `dependencies`: `"dsh-moli": "link:D:/dsh_plugins/dsh-moli"`
+   - `dsh.profile.bundles`: `"dsh-moli"`
+3. Run `pnpm install` in the profile directory (creates `node_modules/dsh-moli`).
+4. Restart DSH.
+
+An unresolvable bundle is **skipped silently** apart from one stderr line
+(`skipping profile bundle …`). If the tools never appear, that line is the first thing to look for.
+
+## Usage
+
+`moli_fetch` parameters: `url` (required), `dump`, `writeTo`, `eval`, `wait`, `waitSelector`,
+`delayMs`, `timeoutMs`, `maxChars`, `headers`, `userAgent`, `layout`, `scrollbars`, `noJs`,
+`noCss`, `resources`, `withFrames`, `insecureTls`, `profileDir`, `cookieFile`.
+
+```
+moli_fetch url=https://example.com dump=markdown             # token-efficient text
+moli_fetch url=https://example.com dump=semantic_tree_text    # nodes with backend ids
+moli_fetch url=https://example.com eval="document.title"      # one computed value
+moli_fetch url=https://example.com dump=screenshot writeTo=/abs/path/a.png
+moli_fetch url=https://example.com dump=pdf        writeTo=/abs/path/a.pdf
+```
+
+Screenshot and PDF dumps need `writeTo`; the bytes are written verbatim rather than printed.
+
+## Relationship to Moli's own agent skills
+
+Moli ships official agent skills in its repository — [`moli-webfetch`](https://github.com/lexmount/moli/tree/main/skills/moli-webfetch),
+[`moli-websearch`](https://github.com/lexmount/moli/tree/main/skills/moli-websearch), and
+[`moli-cdp-server`](https://github.com/lexmount/moli/tree/main/skills/moli-cdp-server) — and their
+README's quick start is to have an agent install them. If your agent loads skills, the simplest path
+is to point it at those; they are maintained upstream and cover web search and a CDP server too.
+
+This plugin exists because it is a different trade-off, not a replacement:
+
+- **Always-on tool schemas instead of an on-demand skill.** The tools are registered at Host startup,
+  so the model sees them every turn with no discovery step.
+- **DSH-specific failure handling.** The three traps below (sandbox pipe capture, UTF-16 mangling of
+  binary output, bare-specifier resolution for a `link:`ed plugin) plus sandbox/revocation/proxy
+  classification are solved here, because they are DSH-on-Windows problems.
+- **Smaller surface.** Only `fetch` is wrapped; the official skills also cover web search and the CDP
+  server, which this plugin does not.
+
+Both can coexist: install the skills if you want upstream coverage, keep this plugin if you want the
+capabilities always visible to the model.
 
 ## Three design points
 
@@ -252,7 +268,7 @@ Override any field under the plugin's `config` entry in the profile patch layer.
         defaultTimeoutMs: 30000                                  # per-fetch readiness deadline
         maxChars: 200000                                         # inline text truncation
         proxy: 'http://127.0.0.1:7890'                           # forward proxy for moli and downloads
-        insecureTls: true                                        # see TLS notes below
+        insecureTls: true                                        # see the TLS notes below
 ```
 
 Without `exePath`, the plugin probes `exePath` → `MOLI_BIN` → `%LOCALAPPDATA%\Moli\bin\moli.exe` →
@@ -291,20 +307,25 @@ installation under a versioned subdirectory is still found.
 
 ## Verification
 
-`lib/moli.js` and the tool layer were exercised end to end against Moli 1.1.16 on Windows: tool
-registration, probe, Markdown and JSON dumps, `eval` (including a tight-timeout regression guard
-for the `-t` argument position), PNG and PDF artifacts written with valid signatures, truncation,
-every rejection path (binary dump without `writeTo`, unknown `dump`, unknown `wait` stage, missing
+Two suites live in [`verify/`](verify/), and both are runnable against a working tree:
+
+- `schema-verify.mjs` checks the tool definitions with the registry's own validator, including
+  controls that assert the two invalid schema shapes still fail.
+- `install-verify.mjs` drives the install pipeline against a loopback HTTP server: route ordering,
+  the SHA256 of served bytes, refusal to execute on a checksum mismatch, actual execution when the
+  digest matches, and the all-routes-failed diagnostic.
+
+Beyond those, `lib/moli.js` and the tool layer were exercised end to end against Moli 1.1.16 on
+Windows: registration, probe, Markdown and JSON dumps, `eval` (including a tight-timeout regression
+guard for the `-t` argument position), PNG and PDF artifacts with valid signatures, truncation, every
+rejection path (binary dump without `writeTo`, unknown `dump`, unknown `wait` stage, missing
 destination directory), failure classification (unreachable host, HTTP status, sandbox TLS block,
 revocation block), and the concurrency claims. The blocked-host classifier is covered by pure
 function tests using stderr text captured from real runs.
 
-Confirmed at runtime as well: a JavaScript-rendered page (GitHub search) returned 14,560 characters
-of Markdown containing 30 real repository matches when fetched through a local proxy.
-
-The install pipeline is covered against a loopback HTTP server, which proves the mechanics without
-depending on GitHub: route ordering, the SHA256 of served bytes, refusal to execute on a checksum
-mismatch, actual execution when the digest matches, and the all-routes-failed diagnostic.
+Confirmed at runtime too: a JavaScript-rendered page (GitHub search) returned 14,560 characters of
+Markdown containing 30 real repository matches when fetched through a local proxy. A throwaway
+profile with the plugin installed composes its config with no `JsonSchemaError` and no skipped bundle.
 
 ## License
 

package/README.zh.md

@@ -1,33 +1,105 @@
 # dsh-moli
 
-把本机安装的 [Moli](https://github.com/lexmount/moli)（`moli.exe`，Rust 编写的 AI agent 无头浏览器）暴露成 **DeepSeek Harness 工具**，让 agent 直接调用，不必每次手敲命令。
+**两个工具，让 DeepSeek Harness 的 agent 能驱动真正的无头浏览器。** 它们封装
+[Moli](https://github.com/lexmount/moli)——一个专为 AI agent 打造的 Rust 无头浏览器——所以 agent 能看到
+那些"必须跑完 JavaScript 才存在"的页面内容，也能把它们拍成图。
 
 [English](README.md) | 中文
 
-## 快速开始
+## 它做什么，什么时候需要它
 
-已发布到 npm：[`dsh-moli`](https://www.npmjs.com/package/dsh-moli)
+普通的 HTTP 抓取拿回的是服务器发来的 HTML。对文章、文档、API 来说这足够了，DSH 的 `web_fetch` 已经覆盖
+这种场景。但它拿不到任何**需要浏览器构建出来**的内容：
+
+- **单页应用（SPA）**——客户端渲染的新闻站、仪表盘、文档站。响应只是一个空壳，内容要等脚本跑完才出现。
+- **登录与同意墙**——必须先有会话或 cookie 才肯显示内容的页面。
+- **图**——想看一眼页面长什么样（截图），或想存档（PDF）。
+- **页面深处的一个值**——价格、计数、标题，用选择器直接取，而不是把整篇文档拉回来。
+
+针对这些场景，本插件给 agent 两个工具：
+
+| 工具 | 作用 |
+|---|---|
+| `moli_fetch` | 渲染 URL 并返回 Markdown / HTML / 语义树 / 带 HTTP 状态的 JSON；执行 JS 表达式取值；写出 PNG 截图或 PDF |
+| `moli_probe` | 报告引擎是否安装、什么版本、HTTPS 是否可用；没装时还能替你装上 |
+
+判断标准很简单：**agent 需要的是"浏览器眼里的页面"吗？** 如果普通抓取已经能拿到你要的文字，`web_fetch`
+更轻更快。
+
+```
+  agent ──moli_fetch──▶ dsh-moli 插件 ──启动──▶ moli.exe
+                            ▲                      │
+                            │                 渲染页面、
+                            │                 执行其中 JavaScript
+                            │                      │
+                            └──markdown / json / png / pdf◀┘
+```
+
+## 安装
+
+两条路，装的是同一个插件，按你的网络情况选。
+
+**路线 1 —— 从 npm 装（推荐）。** 经 npm registry 解析，所以在 GitHub 慢或不通的网络里照样能装，DSH 的
+安装对话框还能回退到国内镜像：
 
 ```powershell
 dsh plugin --profile web add dsh-moli
 ```
 
-**推荐走这条**：它经 npm registry 解析，所以在 GitHub 慢或不通的网络里照样能装，而且 DSH 的安装对话框能
-回退到国内镜像。直接从仓库装也可以，但需要 GitHub 可达：
+**路线 2 —— 直接从仓库装。** 直接跟踪源码，需要 GitHub 可达：
 
 ```powershell
 dsh plugin --profile web add github:27painter/dsh-moli
 ```
 
 > [!IMPORTANT]
-> **npm 包只有插件本身，不含 Moli 本体。** 它是 26 kB 的 JavaScript；`moli.exe` 引擎是另一个约
-> 101 MB 的 Rust 二进制、有自己的发布流程。所以本插件是**装在 Moli 旁边**，不是把 Moli 打包进来。
+> **npm 包只有插件，不含 Moli 引擎。**
+>
+> npm tarball 是 26 kB：八个 JavaScript 与文本文件。`moli.exe` 是另外的东西——约 101 MB 的 Rust 编译
+> 产物，由 Moli 项目按自己的节奏构建和发布。
 >
-> **Moli 本体没有 npm 包。** registry 上的 `moli` 和 `moli-cli` 属于无关项目，`@lexmount/moli`
-> 并不存在。Moli 以预编译二进制形式发布在
+> **为什么不能打包进来：**
+>
+> - **体积。** 引擎约为插件的 4,000 倍。每次安装、每次插件更新都要顺带搬运一个浏览器。
+> - **归属。** Moli 是 `lexmount/moli`，版权属于它自己的 MIT 署名。把它家的二进制经由本包再分发，等于
+>   把别人的产物当自己的发布。
+> - **平台。** 引擎按操作系统与架构分别发布——Windows/Linux/macOS × x64/arm64。打包进来等于把某一个
+>   构建方式钉死给所有用户。
+> - **版本。** 插件要能配合用户手上**任意** Moli 版本工作，包括插件发布之后才出现的 Moli 新版本。
+>   打包会把两者的版本绑死。
+>
+> **引擎同样没有 npm 包。** registry 上的 `moli` 和 `moli-cli` 属于无关项目，`@lexmount/moli` 并不
+> 存在。Moli 以预编译二进制形式发布在
 > [GitHub Releases](https://github.com/lexmount/moli/releases/latest)——**不要靠猜包名去装引擎**。
 
-两种方式都要重启 DSH，然后自检并抓一个页面：
+## 装好之后的两种情形
+
+上面两条下载路线装的是同一个东西。区别在于**你的机器上有没有 Moli**——这决定你是就此完事，还是还差一步。
+
+### 情形 A —— 已经装了 Moli：不用再做别的
+
+插件自己会找到 `moli.exe`，两个工具立即可用。重启 DSH 然后确认：
+
+```
+moli_probe
+```
+
+如果报出来的版本正常，就结束了。
+
+### 情形 B —— 还没装 Moli：把引擎也拉下来
+
+在你装上引擎之前，`moli_fetch` 会一直报"引擎缺失"。用下面任一种装上：
+
+```
+moli_probe action=install          # 让插件替你拉
+```
+
+```powershell
+# 或者自己跑 Moli 官方的安装器
+powershell -ExecutionPolicy ByPass -c "irm https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1 | iex"
+```
+
+然后用 `moli_probe` 确认并抓一个页面：
 
 ```
 moli_probe
@@ -36,9 +108,9 @@ moli_fetch url=https://example.com dump=markdown
 
 ### 获取 Moli 引擎
 
-`moli_probe` 会报告它是否在场。如果不在，三种方式任选：
+`moli_probe` 会报告引擎是否在场。如果不在，三种方式任选：
 
-**1. 让插件替你装** —— 多路径下载，并报告实际执行字节的 SHA256：
+**1. 让插件替你装**——多路径下载，并报告实际执行字节的 SHA256：
 
 ```
 moli_probe action=install
@@ -64,152 +136,94 @@ curl.exe -L -o moli.zip https://github.com/lexmount/moli/releases/latest/downloa
 Expand-Archive moli.zip -DestinationPath "$env:LOCALAPPDATA\Moli" -Force
 ```
 
-这些 `releases/latest/download/...` 链接始终指向最新发布，所以不用钉版本号也不会失效。想核对下载内容，
-见[校验下载](#校验下载)；同样的命令放在上下文里，见[手动安装 Moli](#手动安装-moli)。
+这些 `releases/latest/download/...` 链接始终指向最新发布，所以不用钉版本号也不会失效。
 
-## 与 Moli 官方 agent skill 的关系
-
-Moli 仓库自带官方 agent skill：[`moli-webfetch`](https://github.com/lexmount/moli/tree/main/skills/moli-webfetch)、
-[`moli-websearch`](https://github.com/lexmount/moli/tree/main/skills/moli-websearch)、
-[`moli-cdp-server`](https://github.com/lexmount/moli/tree/main/skills/moli-cdp-server)，其 README 的快速开始
-就是让 agent 去安装它们。如果你的 agent 能加载 skill，最省事的路就是直接用官方那套——上游维护，而且额外覆盖网页
-搜索与 CDP 服务。
-
-本插件的存在是因为它是另一种取舍，不是替代品：
-
-- **常驻工具 schema，而非按需 skill。** 工具在 Host 启动时注册，模型每回合都能看到，不需要发现步骤。
-- **针对 DSH 的失败处理。** 下面那三个坑（沙箱管道捕获、二进制被 UTF-16 破坏、`link:` 插件的裸包名解析）
-  以及沙箱/吊销/代理三类失败分类，都在这里解决了——因为它们本质是"DSH on Windows"的问题。
-- **面更窄。** 只封装了 `fetch`；官方 skill 还覆盖网页搜索和 CDP 服务，本插件没有。
-
-两者可以共存：想要上游覆盖就装 skill，想要能力始终对模型可见就留这个插件。
-
-## 提供的能力
-
-| 工具 | 作用 |
-|---|---|
-| `moli_fetch` | 抓取 URL 并返回渲染后的 HTML / Markdown / 语义树 / JSON（含 `status` 与 `final_url`）；执行 JS 表达式取值；写出 PNG 截图或 PDF |
-| `moli_probe` | 报告引擎路径与版本，以及调用进程能否走 HTTPS |
-
-`moli_fetch` 参数：`url`（必填）、`dump`、`writeTo`、`eval`、`wait`、`waitSelector`、`delayMs`、
-`timeoutMs`、`maxChars`、`headers`、`userAgent`、`layout`、`scrollbars`、`noJs`、`noCss`、
-`resources`、`withFrames`、`insecureTls`、`profileDir`、`cookieFile`。
+装完若位置不常规，把插件指过去：
 
+```yaml
+config:
+  exePath: 'C:\path\to\moli.exe'
 ```
-moli_fetch url=https://example.com dump=markdown           # 省 token 的正文
-moli_fetch url=https://example.com dump=semantic_tree_text  # 带节点 id 的结构
-moli_fetch url=https://example.com eval="document.title"    # 取一个值
-moli_fetch url=https://example.com dump=screenshot writeTo=/绝对路径/a.png
-moli_fetch url=https://example.com dump=pdf        writeTo=/绝对路径/a.pdf
-```
-
-## 安装
 
-插件装进某个 DSH profile。按你的机器情况选一条路。
+#### 校验下载
 
-### 路线 A —— 已经装了 Moli
-
-不需要再装别的东西。插件自己会找到 `moli.exe`，两个工具立即可用。
+Moli 的 README 没有记录任何校验和或签名，安装器也不发布校验和文件。**存在的是 GitHub 自己给每个资产的
+`sha256` 摘要**，可以从 release API 读到：
 
 ```powershell
-dsh plugin --profile web add dsh-moli
+(irm https://api.github.com/repos/lexmount/moli/releases/latest).assets | Select-Object name, digest
 ```
 
-若你更想跟踪源码，或 registry 对你不可达，改从仓库装：
+`v1.1.17` 下这个命令会给出（节选）：
 
-```powershell
-dsh plugin --profile web add github:27painter/dsh-moli
+```
+moli-installer.ps1                2,020  sha256:e002f7a6c174d78ae6ed7289aca9f5d3a62ab0b1f6e588606a80c0cb5d37964d
+moli-x86_64-pc-windows-msvc.zip  43.8 MB  sha256:5247309837b6eaf6e73bfa18f2a8d8d90473b9e2fe5cfcaaef57d7eee9b074c4
 ```
 
-重启 DSH，然后用 `moli_probe` 确认。
-
-### 路线 B —— 还没装 Moli
-
-同样方式装插件、重启，然后让它替你把 Moli 拉下来：
+与你下载的文件比对：
 
 ```powershell
-dsh plugin --profile web add dsh-moli
-# 重启 DSH，然后调用：
-moli_probe action=install
+(Get-FileHash .\moli-installer.ps1 -Algorithm SHA256).Hash.ToLower()
 ```
 
-安装动作会**依次尝试多条下载路径**并逐条报告结果——因为受限网络可能把 release 主机整个挡掉。它会报告
-实际执行的字节的 SHA256，而 `expectedSha256` 能把这份报告变成强制校验门（见
-[校验下载](#校验下载)）。安装**只在调用明确要求时**发生，使用 `moli_fetch` 永远不会触发它。
+插件遵循同样的纪律：`moli_probe action=install` 会报告它实际执行的那份字节的 SHA256，而
+`expectedSha256` 能把这份报告变成强制校验门。它**不会**编造一个可信默认值——因为摘要只有在与发布页自己
+的值比对时才有意义。
+
+这是**验证过的性质，不是声明**：用插件自己的 `downloadInstaller` 下载 `v1.1.17` 的安装器，复现出的正是
+GitHub 公布的那个摘要 `e002f7a6…964d`，从磁盘重新哈希也对得上。
 
 ### 装进 desktop profile
 
 `dsh plugin --profile desktop …` 会被拒绝——desktop profile 归 Electron 应用所有。直接改它的
-`package.json`（加 `link:` 依赖**和** bundle 条目，再跑 `pnpm install`），或用应用内插件页
-（侧边栏 →**插件**→**添加插件**），那条路径同样走 pnpm。
-
-profile 插件需要两半都齐：依赖边 + `dsh.profile.bundles` 条目。缺一个 loader 就看不到它，而无法解析的
-bundle 会被**静默跳过**，只在 stderr 留一行 `skipping profile bundle …`。工具迟迟不出现时先找这行。
+`package.json`，或用应用内插件页（侧边栏 →**插件**→**添加插件**），那条路径同样走 pnpm。
 
-从本地目录安装时，完整的四步是：
+profile 插件需要两半都齐：依赖边（`dependencies`）+ `dsh.profile.bundles` 条目。缺一个 loader 就看不到
+它。从本地目录安装的完整四步是：
 
 1. 把本目录放到任意位置，例如 `D:\dsh_plugins\dsh-moli`。
-2. 在该 profile 的 `package.json` 中加入：
+2. 在该 profile 的 `package.json` 中加入两项：
    - `dependencies`: `"dsh-moli": "link:D:/dsh_plugins/dsh-moli"`
    - `dsh.profile.bundles`: `"dsh-moli"`
 3. 在 profile 目录执行 `pnpm install`（生成 `node_modules/dsh-moli`）。
 4. 重启 DSH。
 
-## 手动安装 Moli
+无法解析的 bundle 会被**静默跳过**，只在 stderr 留一行 `skipping profile bundle …`。工具迟迟不出现时先找
+这行。
 
-自动路径都失败时（受限网络可能把 release 主机整个挡掉），自己装。下面是 Moli 官方文档里的命令。
+## 用法
 
-Windows（PowerShell）：
-
-```powershell
-powershell -ExecutionPolicy ByPass -c "irm https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1 | iex"
-```
-
-Linux / macOS：
-
-```sh
-curl --proto '=https' --tlsv1.2 -fsSL https://github.com/lexmount/moli/releases/latest/download/moli-installer.sh | sh
-```
-
-官方也发布 Windows 直接二进制，不想跑安装器就用它：
+`moli_fetch` 参数：`url`（必填）、`dump`、`writeTo`、`eval`、`wait`、`waitSelector`、`delayMs`、
+`timeoutMs`、`maxChars`、`headers`、`userAgent`、`layout`、`scrollbars`、`noJs`、`noCss`、
+`resources`、`withFrames`、`insecureTls`、`profileDir`、`cookieFile`。
 
-```powershell
-# 从 releases 页挑与你的架构匹配的资产
-curl.exe -L -o moli.zip https://github.com/lexmount/moli/releases/latest/download/moli-x86_64-pc-windows-msvc.zip
-Expand-Archive moli.zip -DestinationPath "$env:LOCALAPPDATA\Moli" -Force
 ```
-
-装完若位置不常规，把插件指过去：
-
-```yaml
-config:
-  exePath: 'C:\path\to\moli.exe'
+moli_fetch url=https://example.com dump=markdown            # 省 token 的正文
+moli_fetch url=https://example.com dump=semantic_tree_text   # 带节点 id 的结构
+moli_fetch url=https://example.com eval="document.title"     # 取一个值
+moli_fetch url=https://example.com dump=screenshot writeTo=/绝对路径/a.png
+moli_fetch url=https://example.com dump=pdf        writeTo=/绝对路径/a.pdf
 ```
 
-### 校验下载
+截图与 PDF 必须给 `writeTo`；字节是原样落盘的，不会打印到输出里。
 
-Moli 的 README 没有记录任何校验和或签名，安装器也不发布校验和文件。**存在的是 GitHub 自己给每个资产的
-`sha256` 摘要**，可以从 release API 读到：
-
-```powershell
-(irm https://api.github.com/repos/lexmount/moli/releases/latest).assets | Select-Object name, digest
-```
-
-`v1.1.17` 下这个命令会给出（节选）：
+## 与 Moli 官方 agent skill 的关系
 
-```
-moli-installer.ps1                2,020  sha256:e002f7a6c174d78ae6ed7289aca9f5d3a62ab0b1f6e588606a80c0cb5d37964d
-moli-x86_64-pc-windows-msvc.zip  43.8 MB  sha256:5247309837b6eaf6e73bfa18f2a8d8d90473b9e2fe5cfcaaef57d7eee9b074c4
-```
+Moli 仓库自带官方 agent skill：[`moli-webfetch`](https://github.com/lexmount/moli/tree/main/skills/moli-webfetch)、
+[`moli-websearch`](https://github.com/lexmount/moli/tree/main/skills/moli-websearch)、
+[`moli-cdp-server`](https://github.com/lexmount/moli/tree/main/skills/moli-cdp-server)，其 README 的快速开始
+就是让 agent 去安装它们。如果你的 agent 能加载 skill，最省事的路就是直接用官方那套——上游维护，而且额外覆盖
+网页搜索与 CDP 服务。
 
-与你下载的文件比对：
+本插件的存在是因为它是另一种取舍，不是替代品：
 
-```powershell
-(Get-FileHash .\moli-installer.ps1 -Algorithm SHA256).Hash.ToLower()
-```
+- **常驻工具 schema，而非按需 skill。** 工具在 Host 启动时注册，模型每回合都能看到，不需要发现步骤。
+- **针对 DSH 的失败处理。** 下面那三个坑（沙箱管道捕获、二进制被 UTF-16 破坏、`link:` 插件的裸包名解析）
+  以及沙箱/吊销/代理三类失败分类，都在这里解决了——因为它们本质是"DSH on Windows"的问题。
+- **面更窄。** 只封装了 `fetch`；官方 skill 还覆盖网页搜索和 CDP 服务，本插件没有。
 
-插件遵循同样的纪律：`moli_probe action=install` 会报告它实际执行的那份字节的 SHA256，而
-`expectedSha256` 能强制校验你提供的摘要。它**不会**编造一个可信默认值——因为上游根本没有校验和可比。
+两者可以共存：想要上游覆盖就装 skill，想要能力始终对模型可见就留这个插件。
 
 ## 三个设计要点
 
@@ -246,7 +260,7 @@ moli-x86_64-pc-windows-msvc.zip  43.8 MB  sha256:5247309837b6eaf6e73bfa18f2a8d8d
 
 - **面向 Windows。** 开发与验证都在 Windows 上；可执行文件探测、文件描述符绕坑、Schannel 说明都
   与 Windows 相关。移植到 POSIX 没有障碍，但未经验证。
-- **不包含 Moli 本体。** 需自行安装，插件只负责定位和驱动它。
+- **不包含 Moli 本体。** 需自行安装，或让 `moli_probe action=install` 替你拉取。
 - **只封装了 `fetch`。** `moli serve`（CDP/WebDriver 服务器）与 `moli import`（会话导入）尚未做成工具。
 - **不支持单次取消。** 引擎是同步执行的，被中断的回合无法中途终止抓取；已在进行的调用会跑完并
   写出产物。
@@ -263,17 +277,24 @@ moli-x86_64-pc-windows-msvc.zip  43.8 MB  sha256:5247309837b6eaf6e73bfa18f2a8d8d
 - **部分网络下主机可达性会波动。** 开发机上观察到的现象：同一时刻，基于 curl 的客户端（moli）访问
   `github.com` 超时，而 `git` over HTTPS 与系统浏览器几秒内就能通；`api.github.com` 正常而
   `github.com` 不通。所以超时可能是暂时性的——重试，或设置 `proxy`。正因裸超时含义不唯一，它被
-  上报为 `possiblyUnreachable` 而不当作定论。
+  上报为 `possiblyUnreachable` 而不当作定论。安装动作的多路径回退与上面的手动命令正是为这种情况准备的。
 
 ## 验证情况
 
-在 Windows 上对 Moli 1.1.16 做了端到端验证：工具注册、probe、Markdown 与 JSON dump、`eval`
-（含针对 `-t` 参数位置的紧超时回归防护）、PNG 与 PDF 产物签名、截断、全部拒绝路径（二元 dump 缺
-`writeTo`、非法 `dump`、非法 `wait`、目标目录不存在）、失败分类（不可达主机、HTTP 状态、沙箱 TLS
-阻断、吊销阻断）以及并发声明。被阻断主机的分类器用真实运行捕获的 stderr 文本做纯函数测试。
+[`verify/`](verify/) 下有两个可直接对工作区运行的测试：
+
+- `schema-verify.mjs` 用注册表自己的校验器检查工具定义，并带有断言"两种非法 schema 形状仍会被拒"的对照组。
+- `install-verify.mjs` 用本地回环 HTTP 服务器驱动安装链路：路由顺序、被提供字节的 SHA256、校验不匹配时
+  拒绝执行、匹配时真正执行、以及全部路径失败的诊断。
+
+此外，`lib/moli.js` 与工具层在 Windows 上对 Moli 1.1.16 做了端到端验证：注册、probe、Markdown 与 JSON
+dump、`eval`（含针对 `-t` 参数位置的紧超时回归防护）、PNG 与 PDF 产物签名、截断、全部拒绝路径（二元 dump
+缺 `writeTo`、非法 `dump`、非法 `wait`、目标目录不存在）、失败分类（不可达主机、HTTP 状态、沙箱 TLS 阻断、
+吊销阻断）以及并发声明。被阻断主机的分类器用真实运行捕获的 stderr 文本做纯函数测试。
 
-运行时也确认过：走本地代理抓取 JavaScript 渲染页面（GitHub 搜索）返回 14,560 字符 Markdown，
-其中包含 30 处真实结果匹配。
+运行时也确认过：走本地代理抓取 JavaScript 渲染页面（GitHub 搜索）返回 14,560 字符 Markdown，其中包含
+30 处真实结果匹配。另有一个装了本插件的一次性 profile，组合其配置时既无 `JsonSchemaError` 也无被跳过的
+bundle。
 
 ## 许可
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-moli",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "type": "module",
   "description": "DeepSeek Harness tools for the local Moli headless browser: rendered fetches, markdown, semantic trees, screenshots, and PDFs.",
   "license": "MIT",