dsh-moli 1.0.1 → 1.0.4

package/README.md

@@ -1,10 +1,81 @@
 # dsh-moli
 
+[![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.
 
 English | [中文](README.zh.md)
 
+## Quick start
+
+Published on npm as [`dsh-moli`](https://www.npmjs.com/package/dsh-moli):
+
+```powershell
+dsh plugin --profile web add dsh-moli
+```
+
+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:
+
+```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.
+
+Either plugin route ends the same way. Restart DSH, then check the engine and fetch a page:
+
+```
+moli_probe
+moli_fetch url=https://example.com dump=markdown
+```
+
+### Getting the Moli engine
+
+`moli_probe` reports whether it is present. If it is not, pick one of:
+
+**1. Let the plugin install it** — several download routes, and a SHA256 of what actually ran:
+
+```
+moli_probe action=install
+```
+
+**2. Official one-line installer** (Moli's own documented command):
+
+```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
+```
+
+**3. Direct binary, if you would rather not run an installer:**
+
+```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
+```
+
+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.
+
 ## What it provides
 
 | Tool | Purpose |
@@ -53,6 +124,13 @@ The plugin is installed into a DSH profile. Pick the route that matches your mac
 
 Nothing else to fetch. The plugin finds `moli.exe` on its own and both tools work immediately.
 
+```powershell
+dsh plugin --profile web add dsh-moli
+```
+
+Install from the repository instead if you prefer tracking the source, or if the registry is
+unreachable for you:
+
 ```powershell
 dsh plugin --profile web add github:27painter/dsh-moli
 ```
@@ -64,7 +142,7 @@ Restart DSH, then confirm with `moli_probe`.
 Install the plugin the same way, restart, then let it fetch Moli for you:
 
 ```powershell
-dsh plugin --profile web add github:27painter/dsh-moli
+dsh plugin --profile web add dsh-moli
 # restart DSH, then call:
 moli_probe action=install
 ```

package/README.zh.md

@@ -4,6 +4,69 @@
 
 [English](README.md) | 中文
 
+## 快速开始
+
+已发布到 npm：[`dsh-moli`](https://www.npmjs.com/package/dsh-moli)
+
+```powershell
+dsh plugin --profile web add dsh-moli
+```
+
+**推荐走这条**：它经 npm registry 解析，所以在 GitHub 慢或不通的网络里照样能装，而且 DSH 的安装对话框能
+回退到国内镜像。直接从仓库装也可以，但需要 GitHub 可达：
+
+```powershell
+dsh plugin --profile web add github:27painter/dsh-moli
+```
+
+> [!IMPORTANT]
+> **npm 包只有插件本身，不含 Moli 本体。** 它是 26 kB 的 JavaScript；`moli.exe` 引擎是另一个约
+> 101 MB 的 Rust 二进制、有自己的发布流程。所以本插件是**装在 Moli 旁边**，不是把 Moli 打包进来。
+>
+> **Moli 本体没有 npm 包。** registry 上的 `moli` 和 `moli-cli` 属于无关项目，`@lexmount/moli`
+> 并不存在。Moli 以预编译二进制形式发布在
+> [GitHub Releases](https://github.com/lexmount/moli/releases/latest)——**不要靠猜包名去装引擎**。
+
+两种方式都要重启 DSH，然后自检并抓一个页面：
+
+```
+moli_probe
+moli_fetch url=https://example.com dump=markdown
+```
+
+### 获取 Moli 引擎
+
+`moli_probe` 会报告它是否在场。如果不在，三种方式任选：
+
+**1. 让插件替你装** —— 多路径下载，并报告实际执行字节的 SHA256：
+
+```
+moli_probe action=install
+```
+
+**2. 官方一行安装**（Moli 自己的文档命令）：
+
+```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
+```
+
+**3. 直接下二进制**（不想跑安装器的话）：
+
+```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
+```
+
+这些 `releases/latest/download/...` 链接始终指向最新发布，所以不用钉版本号也不会失效。想核对下载内容，
+见[校验下载](#校验下载)；同样的命令放在上下文里，见[手动安装 Moli](#手动安装-moli)。
+
 ## 与 Moli 官方 agent skill 的关系
 
 Moli 仓库自带官方 agent skill：[`moli-webfetch`](https://github.com/lexmount/moli/tree/main/skills/moli-webfetch)、
@@ -48,6 +111,12 @@ moli_fetch url=https://example.com dump=pdf        writeTo=/绝对路径/a.pdf
 
 不需要再装别的东西。插件自己会找到 `moli.exe`，两个工具立即可用。
 
+```powershell
+dsh plugin --profile web add dsh-moli
+```
+
+若你更想跟踪源码，或 registry 对你不可达，改从仓库装：
+
 ```powershell
 dsh plugin --profile web add github:27painter/dsh-moli
 ```
@@ -59,7 +128,7 @@ dsh plugin --profile web add github:27painter/dsh-moli
 同样方式装插件、重启，然后让它替你把 Moli 拉下来：
 
 ```powershell
-dsh plugin --profile web add github:27painter/dsh-moli
+dsh plugin --profile web add dsh-moli
 # 重启 DSH，然后调用：
 moli_probe action=install
 ```
@@ -77,6 +146,15 @@ moli_probe action=install
 profile 插件需要两半都齐：依赖边 + `dsh.profile.bundles` 条目。缺一个 loader 就看不到它，而无法解析的
 bundle 会被**静默跳过**，只在 stderr 留一行 `skipping profile bundle …`。工具迟迟不出现时先找这行。
 
+从本地目录安装时，完整的四步是：
+
+1. 把本目录放到任意位置，例如 `D:\dsh_plugins\dsh-moli`。
+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
 
 自动路径都失败时（受限网络可能把 release 主机整个挡掉），自己装。下面是 Moli 官方文档里的命令。
@@ -161,33 +239,8 @@ moli-x86_64-pc-windows-msvc.zip  43.8 MB  sha256:5247309837b6eaf6e73bfa18f2a8d8d
 ```
 
 未设置 `exePath` 时探测顺序：`exePath` → 环境变量 `MOLI_BIN` → `%LOCALAPPDATA%\Moli\bin\moli.exe`
-→ `%USERPROFILE%\.local\bin\moli.exe`。
-
-## 安装
-
-先装 Moli 本体——本插件只负责驱动它，不分发它。Windows 上：
-
-```powershell
-powershell -ExecutionPolicy ByPass -c "irm https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1 | iex"
-```
-
-（Linux/macOS 用对应的 `moli-installer.sh`，见 [Moli README](https://github.com/lexmount/moli#quick-start)。）
-
-然后插件自身必须**同时**是 profile 依赖与已声明的 bundle，缺一个 loader 就看不到它：
-
-1. 把本目录放到任意位置，例如 `D:\dsh_plugins\dsh-moli`。
-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。
-
-注意：
-
-- `dsh plugin --profile desktop …` 会被拒绝：desktop profile 归 Electron 应用所有。直接改它的
-  `package.json`，或用应用内插件页（侧边栏 →**插件**→**添加插件**），那条路径同样走 pnpm。
-- bundle 无法解析或未通过兼容性检查时，loader 会**静默跳过**，只在 stderr 留一行
-  `skipping profile bundle …`。工具迟迟不出现时先找这行。
+→ `%USERPROFILE%\.local\bin\moli.exe`，随后还会在 `%LOCALAPPDATA%\Moli` 内递归查找 `moli.exe`，
+所以装在带版本号的子目录里也能找到。
 
 ## 已知限制
 

package/index.js

@@ -30,49 +30,64 @@ const DEFAULTS = {
 /**
  * Parameter schema of `moli_fetch`.
  *
- * The two schema layers follow DIFFERENT rules, which is easy to get wrong:
- * - A parameter spec uses the author DSL, where a property-level `required: true`
- *   is correct. `parameterSchemaSpecToJsonSchema` hoists it into an object-level
- *   `required` array and strips the flag.
- * - A raw output schema is validated as-is, so `required` there must already be an
- *   object-level array of names. A property-level `required: true` makes the
- *   registry reject the whole tool with `JsonSchemaError`.
+ * Both schema layers must be RAW JSON Schema here — object root, with `required`
+ * as an object-level array — because this plugin registers plain definitions with
+ * `ctx.tools.register` instead of going through `defineTool`.
+ *
+ * That choice is forced: `defineTool` lives in `@deepseek-ai/dsh-tools`, a bare
+ * specifier, and a profile plugin is loaded from its real path on disk, so the
+ * specifier does not resolve. `schemaOf` then projects `definition.parameters`
+ * verbatim to the provider — it is NOT converted — so a parameter left in the
+ * author DSL reaches the model without a root `type`, and the provider rejects the
+ * request with `schema must be a JSON Schema of 'type: "object"', got 'type: null'`.
+ *
+ * The two entry points disagree, which is why one shape cannot serve both:
+ * - a raw `output.schema` must use an object-level `required` array; a
+ *   property-level `required: true` fails `assertSupportedJsonSchema` at registration
+ * - `defineTool` is the opposite: its DSL rejects an object-level `required` and
+ *   expects `required: true` on each property instead
+ * Registering raw means the raw rules apply to parameters and outputs alike.
  */
 const FETCH_PARAMETERS = {
-  url: { type: 'string', required: true, description: 'Absolute http:// or https:// URL to fetch.' },
-  dump: {
-    type: 'string',
-    enum: ['html', 'markdown', 'json', 'semantic_tree', 'semantic_tree_text', 'screenshot', 'screenshot_full', 'pdf'],
-    description: 'Output format. Omit for rendered HTML. `markdown` and `semantic_tree_text` are the token-efficient choices for reading a page; `json` carries status and final_url; screenshot/pdf need writeTo.',
-  },
-  writeTo: {
-    type: 'string',
-    description: 'Absolute path to save the output. Required for screenshot/pdf; optional for text dumps larger than maxChars.',
-  },
-  eval: {
-    type: 'string',
-    description: 'JavaScript expression evaluated once the page is ready; its value is returned as text or JSON instead of the page.',
-  },
-  wait: {
-    type: 'string',
-    enum: ['domcontentloaded', 'load', 'networkidle', 'domstable', 'done'],
-    description: 'Readiness stage to wait for. Defaults to `done`.',
+  type: 'object',
+  additionalProperties: false,
+  required: ['url'],
+  properties: {
+    url: { type: 'string', description: 'Absolute http:// or https:// URL to fetch.' },
+    dump: {
+      type: 'string',
+      enum: ['html', 'markdown', 'json', 'semantic_tree', 'semantic_tree_text', 'screenshot', 'screenshot_full', 'pdf'],
+      description: 'Output format. Omit for rendered HTML. `markdown` and `semantic_tree_text` are the token-efficient choices for reading a page; `json` carries status and final_url; screenshot/pdf need writeTo.',
+    },
+    writeTo: {
+      type: 'string',
+      description: 'Absolute path to save the output. Required for screenshot/pdf; optional for text dumps larger than maxChars.',
+    },
+    eval: {
+      type: 'string',
+      description: 'JavaScript expression evaluated once the page is ready; its value is returned as text or JSON instead of the page.',
+    },
+    wait: {
+      type: 'string',
+      enum: ['domcontentloaded', 'load', 'networkidle', 'domstable', 'done'],
+      description: 'Readiness stage to wait for. Defaults to `done`.',
+    },
+    waitSelector: { type: 'string', description: 'Wait until this CSS selector matches.' },
+    delayMs: { type: 'integer', description: 'Extra milliseconds to wait after readiness.' },
+    timeoutMs: { type: 'integer', description: 'Total readiness deadline in milliseconds. Defaults to the plugin configuration.' },
+    maxChars: { type: 'integer', description: 'Truncate inline text output to this many characters. Defaults to the plugin configuration.' },
+    headers: { type: 'array', items: { type: 'string' }, description: 'Extra request headers, each as "Name: value".' },
+    userAgent: { type: 'string', description: 'Override the User-Agent.' },
+    layout: { type: 'boolean', description: 'Force the real layout renderer on. Implied by screenshot and pdf.' },
+    scrollbars: { type: 'boolean', description: 'Show native scrollbars in rendered output.' },
+    noJs: { type: 'boolean', description: 'Disable page-authored JavaScript.' },
+    noCss: { type: 'boolean', description: 'Disable page-authored CSS.' },
+    resources: { type: 'boolean', description: 'Also fetch images, fonts, audio, video, and text tracks.' },
+    withFrames: { type: 'boolean', description: 'Include subframes in the output.' },
+    insecureTls: { type: 'boolean', description: 'Skip TLS host verification. Use only for a known-broken local endpoint.' },
+    profileDir: { type: 'string', description: 'Moli profile directory carrying imported cookies or storage.' },
+    cookieFile: { type: 'string', description: 'Netscape/curl cookie-jar file to send.' },
   },
-  waitSelector: { type: 'string', description: 'Wait until this CSS selector matches.' },
-  delayMs: { type: 'integer', description: 'Extra milliseconds to wait after readiness.' },
-  timeoutMs: { type: 'integer', description: 'Total readiness deadline in milliseconds. Defaults to the plugin configuration.' },
-  maxChars: { type: 'integer', description: 'Truncate inline text output to this many characters. Defaults to the plugin configuration.' },
-  headers: { type: 'array', items: { type: 'string' }, description: 'Extra request headers, each as "Name: value".' },
-  userAgent: { type: 'string', description: 'Override the User-Agent.' },
-  layout: { type: 'boolean', description: 'Force the real layout renderer on. Implied by screenshot and pdf.' },
-  scrollbars: { type: 'boolean', description: 'Show native scrollbars in rendered output.' },
-  noJs: { type: 'boolean', description: 'Disable page-authored JavaScript.' },
-  noCss: { type: 'boolean', description: 'Disable page-authored CSS.' },
-  resources: { type: 'boolean', description: 'Also fetch images, fonts, audio, video, and text tracks.' },
-  withFrames: { type: 'boolean', description: 'Include subframes in the output.' },
-  insecureTls: { type: 'boolean', description: 'Skip TLS host verification. Use only for a known-broken local endpoint.' },
-  profileDir: { type: 'string', description: 'Moli profile directory carrying imported cookies or storage.' },
-  cookieFile: { type: 'string', description: 'Netscape/curl cookie-jar file to send.' },
 };
 
 /**
@@ -266,14 +281,20 @@ export function apply(ctx, config) {
       + ' reports the executable and the SHA256 of the installer it ran. Use "install" only when moli_fetch'
       + ' reports that moli.exe is missing; it downloads and executes third-party code.',
     parameters: {
-      action: {
-        type: 'string',
-        enum: ['probe', 'install'],
-        description: '`probe` (default) only inspects; `install` downloads and runs the official release installer.',
-      },
-      expectedSha256: {
-        type: 'string',
-        description: 'With action "install": abort unless the downloaded installer matches this SHA256.',
+      type: 'object',
+      additionalProperties: false,
+      // No required entries: every parameter is optional, and each execution path
+      // validates what it actually needs.
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['probe', 'install'],
+          description: '`probe` (default) only inspects; `install` downloads and runs the official release installer.',
+        },
+        expectedSha256: {
+          type: 'string',
+          description: 'With action "install": abort unless the downloaded installer matches this SHA256.',
+        },
       },
     },
     output: { schema: PROBE_OUTPUT_SCHEMA, render: renderProbe },

package/package.json

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