dsh-plugin-discover 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# 更新日志
+
+## 1.0.0 — 2026-10-25
+
+首个发布版本。
+
+**是什么**：DSH 本地插件检索器。用中文或英文口语找 DeepSeek Harness 插件：本地 BM25 词面检索加可选向量重排，返回排好序的候选和安装目标。不连服务端、查询不调模型、插件永不安装、模型不自动下载。
+
+**安装**：
+
+```bash
+dsh plugin --profile web add dsh-plugin-discover
+```
+
+装完建一次索引（约 25 MB 下载）：`npx dsh-plugin-discover build`，或直接在会话里让 AI 建。详见 README。
+
+**主要能力**：
+
+- 中文口语查询，AI 自动补英文改写；4 路 BM25 检索、RRF 融合、同仓库合并
+- 质量过滤四档（strict / balanced / loose / off）与无关结果筛选四档（none / low / medium / high）
+- 可选向量模式（balance / high）：独立模型包显式拉取，默认关闭，不开零开销
+- CLI：`build` / `status` / `search` / `model pull`
+- 插件详情页配置表单，保存即热生效
+
+**已知限制**：
+
+- 仅在 Windows 上验证过；macOS / Linux 理论可用，未实测
+- 向量模式需先显式拉取约 420 MB 模型包，不会自动下载
+- 中文查询依赖 AI 补英文改写；改写漂移可能带进相邻插件
+
+**数据**：索引来自 dsh.so（CC-BY-4.0）与 dsh-plugin-catalog（CC0-1.0），仅本地缓存，按更新周期自动刷新。

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 dsh-plugin-discover contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The plugin index data fetched at runtime from dsh.so is licensed CC-BY-4.0;
+search results must keep the attribution "Powered by dsh.so — DSH Developer
+Hub" and the source's generatedAt timestamp. This package does not include
+index data or model weights.

package/README.md

@@ -1,3 +1,209 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-plugin-discover
+
+English | [中文](README.zh.md)
+
+Find DeepSeek Harness (DSH) plugins by asking the AI in plain Chinese or English. Once installed, just say "find me a plugin that …" and you get ranked candidates with their install targets.
+
+- **Local**: the index is a file on your machine — no server, no upload, no telemetry.
+- **No model calls at query time**: ranking is deterministic and regression-testable; the AI only explains the results.
+- **The plugin never installs**: it returns install targets only; whether and when to install is decided by you and the current LLM session, through DSH's own plugin manager and approval channel.
+- **No automatic model download**: the embedding model is a separate optional package, installed only when you explicitly pull it. You don't need it unless you enable vector enhancement.
+
+## Install
+
+Like any DSH plugin: **Plugins → Add plugin** in the Web UI, or
+
+```bash
+dsh plugin --profile web add dsh-plugin-discover
+```
+
+From a local directory (development or an unpublished version):
+
+```bash
+dsh plugin --profile web add link:D:\dsh-plugin-discover
+```
+
+The package contains code only (about 72 kB): no index data, no model weights, no native binaries — installation takes seconds.
+
+## Quick start
+
+**1. Build the index (once)**
+
+Nothing is downloaded during installation. Build the local index once:
+
+```bash
+npx dsh-plugin-discover build
+```
+
+About 25 MB to download (the dsh.so plugin directory), typically a minute or two depending on the network. You can also just ask the AI in a session to build it — it runs in the background and returns immediately, without blocking the conversation.
+
+The index is stored per user and shared by all profiles, about 20 MB on disk:
+
+| OS | Directory |
+|---|---|
+| Windows | `%LOCALAPPDATA%\dsh-plugin-discover\` |
+| macOS | `~/Library/Caches/dsh-plugin-discover/` |
+| Linux | `${XDG_CACHE_HOME:-~/.cache}/dsh-plugin-discover/` |
+
+Builds always write a new directory and switch only on success; a failed build never touches the existing index, and a lock guarantees one build at a time. To reset completely, delete the directory and build again.
+
+**2. Just ask**
+
+> 帮我找一个任务完成时能发微信通知的插件
+
+The AI calls `plugin_discover` and explains the results, for example:
+
+```
+🔍 10 个候选 · 过滤 balanced（排除 1094 条）
+
+① dsh-wecom-notify · 1★ · L5 已验证 · 低风险
+   DSH 插件：任务完成 / 报错 / 需要用户选择时，自动通过企业微信群机器人 webhook 发送通知
+   [装: github:ljnljn2005/dsh-wecom-notify]
+② dsh-clawbot · 11★ · L5 已验证 · 低风险
+   在 DSH 里接入微信官方 ilink 机器人网关：扫码绑定后，AI 能主动给自己发微信通知
+   [装: github:cryjkd/dsh-clawbot#1.5.0]
+③ @chenweigao/dsh-perch-notify · L5 已验证 · 低风险
+   Webhook notifications for DSH sessions — POST on approval requests and turn ends
+   [装: github:chenweigao/dsh-perch-notify]
+
+数据截至 2026-10-25 · Powered by dsh.so
+```
+
+Each result carries stars, verification level, security risk, update date, and an install target; the AI explains the descriptions in its answer. To install one, hand the install target to DSH's plugin manager — this tool never installs anything itself.
+
+**3. (Optional) enable vector mode**: see [Optional vector mode and model package](#optional-vector-mode-and-model-package).
+
+## How it works
+
+```
+your original words + up to 3 AI rewrites
+  → local BM25 lexical search (four query routes, RRF fusion,
+    packages from one repository merged into one card)
+  → quality filters (security / verification / compatibility)
+  → irrelevant candidates screened out
+  → candidates + install targets
+```
+
+- **Chinese queries need an English rewrite**: plugin names, topics, and descriptions in the catalog are English; the AI adds the rewrite automatically — you don't need to do anything.
+- **Not every term must match**: lexical search combines terms with OR, so long Chinese sentences still return results; names and topics weigh more than descriptions.
+- **`noMatch` is a correct result**: when there is not enough evidence that a matching plugin exists, the tool returns empty and suggests rephrasing instead of forcing a candidate. Better empty than misleading.
+- **The local index goes stale**: the report header carries a "data as of" date; when the index exceeds the update cycle (one week by default), the next search refreshes it first and waits for success; only a failed refresh falls back to the old index, with a clear notice.
+
+## Tool parameters
+
+The parameters of `plugin_discover` are filled in by the session model; you never construct them by hand. They are listed for integration and troubleshooting:
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `query` | string | The user's original words, not paraphrased. Required for a search; pass `""` for `explain` / `refresh`. |
+| `queryAlts` | string[] | Up to 3 rewrites: an English/term version (required for Chinese), 3–5 capability keywords, one usage-scenario sentence. |
+| `limit` | number | Result count, 1–20; defaults to the configured value when omitted. |
+| `explain` | string | A result id / exact name / install target; returns that record without searching. |
+| `refresh` | boolean | Returns immediately; builds/updates the index in the background. |
+| `filters` | object | Temporary override of `preset` (strict/balanced/loose/off) and `minVerificationLevel` (0–5). |
+
+## Configuration
+
+Open this plugin's **detail page** in the plugin manager; the configuration section is rendered right on that page. Saving takes effect immediately — the host reloads only this plugin; the process and sessions do not restart.
+
+| Setting | Default | Notes |
+|---|---|---|
+| Index directory | OS default | See the table above. After changing it, point the CLI at the same directory with `--index-dir`. |
+| Index update cycle | Week (7 days) | Day / week / month (30 days) / 3 months (90 days). A search that finds the index older than the cycle refreshes it first and waits for success. |
+| Filter preset | Balanced | Strict / balanced / loose / off — see the table below. |
+| Minimum verification level (balanced only) | 4 | 0 = no floor; 1–5 require level ≥ N. Entries with unknown verification are not removed. |
+| Result count (top N) | 10 | Range 1–20. |
+| Irrelevant-result filter strength | medium | none (off) / low / medium / high. Higher levels are less likely to force results and more likely to return empty for edge needs. |
+| Vector search enhancement | off | off / balance (field vectors) / high (README vectors) — see [Optional vector mode and model package](#optional-vector-mode-and-model-package). |
+| Vectorization range (top N) | 50 | Number of candidates entering vector rerank, range 2–200; ignored when enhancement is off. |
+| Single-request timeout (seconds) | 30 | README single-request timeout, range 5–300. |
+| Total README fetch timeout (minutes) | 5 | Range 1–10; after it, remaining records skip GitHub and go to the npm CDN. |
+| GitHub request concurrency | 4 | Range 1–8; the rate is fixed at 1 request/second per worker and is not configurable. |
+
+Filter presets:
+
+| Preset | Security | Verification | Compatibility |
+|---|---|---|---|
+| `strict` | audited + low | L5 | must pass |
+| `balanced` (default) | excludes audited high/critical; unaudited pass with a badge | ≥ L4 (configurable); missing passes | pass or unknown |
+| `loose` | only excludes high/critical | no floor | annotated only |
+| `off` | only excludes critical | no floor | not checked |
+
+"Unknown" is not "failing": entries with missing fields are down-weighted and annotated, not filtered. Fewer than three surviving candidates relaxes the preset one step, noted in the report.
+
+## CLI
+
+```bash
+dsh-plugin-discover build   [--index-dir <dir>] [--json] [--quiet]
+dsh-plugin-discover status  [--index-dir <dir>] [--json]
+dsh-plugin-discover search  <query> [--alt <text>]... [--limit <n>] \
+                             [--preset strict|balanced|loose|off] \
+                             [--min-verification <0-5>] [--explain <id>] [--json]
+dsh-plugin-discover model status [--index-dir <dir>] [--profile <name>] [--json]
+dsh-plugin-discover model pull   [--spec <spec>] [--profile <name>] \
+                                  [--index-dir <dir>] [--dry-run] [--no-verify] [--json]
+```
+
+- `build` / `status`: build the index, check its status.
+- `search`: try a query without a session; `--alt` repeats up to three times for rewrites.
+- `model pull` / `model status`: explicit pull and status for the optional model package, see below.
+
+DSH plugins cannot register `dsh` subcommands, so the CLI ships as the package's own bin. With a linked install (`link:`) there is no global bin; use `node lib/cli.js build` instead.
+
+## Optional vector mode and model package
+
+Lexical search (the default) covers most needs. Vector mode reranks candidates with a local embedding model, improving matches where the wording differs but the meaning is close; in measured comparisons it showed no clear advantage for most queries (better in some, worse in others), so it is off by default — enable it if you want to experiment.
+
+The cost is a separate model package `dsh-plugin-discover-model` (int8-quantized [multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small), 384 dimensions): about 80 MB to download, roughly 420 MB installed with the ONNX runtime; runtime memory about 400–500 MB. The model runs in a child process, exits after 5 minutes idle, and costs nothing while vector mode is off; ONNX defaults to 4 threads (override with the `DSH_MODEL_THREADS` environment variable). It is not a dependency of the plugin; only `model pull` installs it:
+
+```bash
+# from npm (once published)
+dsh-plugin-discover model pull --spec dsh-plugin-discover-model@0.1.0
+
+# from a local directory
+dsh-plugin-discover model pull --spec "link:D:\dsh-plugin-discover\models\multilingual-e5-small"
+
+# from a packed tarball
+dsh-plugin-discover model pull --spec "file:D:\path\to\dsh-plugin-discover-model-0.1.0.tgz"
+
+dsh-plugin-discover model status
+```
+
+`model pull` verifies every file against the manifest (SHA-256 by default) and writes a `model.json` pointer into the index directory. pnpm may exit with an `ERR_PNPM_IGNORED_BUILDS` warning because `onnxruntime-node`'s build script is skipped — the prebuilt CPU binary still works; it is a warning, not a failure.
+
+Once installed, set **Vector search enhancement** on the plugin detail page to:
+
+| Mode | Behavior |
+|---|---|
+| `off` (default) | No model, no vectors. |
+| `balance` | Field-vector rerank: concatenates the candidate's catalog fields — name, title, topics, capability tags, description — into one text, computes semantic similarity, and fuses it with the lexical ranking. |
+| `high` | Field + README vectors: besides the field vectors, fetches each candidate's README for semantic comparison. |
+
+Network behavior (only `high` goes online):
+
+- README source order: GitHub raw → exact-version npm CDN → field-vector fallback; cache hits stay offline.
+- Fixed rate limit (4 req/s globally), a 30-second per-request guard, and a total budget of 5 minutes by default; timeouts degrade gracefully and never fail the whole query.
+- Networks that cannot reach GitHub directly fall back to the npm CDN, then to field vectors.
+- Three consecutive GitHub 403/429 responses or timeouts open a 10-minute circuit; the result carries a `readme.circuit` notice the AI relays to you.
+- Vector caches stay local (`<indexDir>/cache/`) and invalidate automatically when the data changes.
+- A missing model or a failed model start degrades to lexical ranking with a notice — never silent, never an automatic download.
+
+## Data and privacy
+
+- Primary source: the [dsh.so plugin directory](https://www.dsh.so/plugins-index.json), CC-BY-4.0. Every report carries `Powered by dsh.so — DSH Developer Hub` and the source data timestamp.
+- Supplement: [dsh-plugin-catalog](https://cdn.jsdelivr.net/npm/dsh-plugin-catalog/index.json), CC0-1.0 (compatibility info and repository URLs).
+- The npm registry is used only to resolve exact README versions, not for inclusion or ranking.
+- Only entries with an install target are included — every result answers "how do I install it".
+- The index is a local cache: not uploaded, not shared, not served.
+
+## Known limits
+
+- Chinese queries depend on the AI's English rewrite; a drifted rewrite can pull in adjacent plugins or miss the target. The evidence gates suppress part of it, not all of it.
+- Some broad scenarios (e.g. "use it from my phone" needs) may recall weakly.
+- `updatedAt` comes from catalog data; entries outside the catalog show no update date.
+- Vector mode is off by default; pull the model package before enabling it.
+- Verified on Windows only; macOS / Linux should work in theory but are untested.
+
+## License
+
+MIT for the code. Index data keeps its source licenses and attribution (CC-BY-4.0 for dsh.so, CC0-1.0 for the catalog).

package/README.zh.md

@@ -0,0 +1,208 @@
+# dsh-plugin-discover
+
+[English](README.md) | 中文
+
+用中文或英文口语找 DeepSeek Harness（DSH）插件。装好之后，直接对 AI 说"帮我找一个能……的插件"，它会返回排好序的候选和对应的安装目标。
+
+- **本地运行**：索引是你机器上的文件——不连服务端、不上传、不采集任何数据。
+- **查询不调模型**：排序由代码确定、可回归；AI 只负责解释结果。
+- **插件不安装**：只给安装目标；装不装、何时装由你和当前LLM会话决定，走 DSH 自己的插件管理与审批通道。
+- **向量模型不自动下载**：向量模型是独立可选包，只有你显式拉取才会安装。不使用向量增强时不需要下载向量模型。
+
+## 安装
+
+和装任何 DSH 插件一样：Web 端 **插件 → 添加插件**，或命令行
+
+```bash
+dsh plugin --profile web add dsh-plugin-discover
+```
+
+从本地目录安装（开发或试用未发布版本）：
+
+```bash
+dsh plugin --profile web add link:D:\dsh-plugin-discover
+```
+
+包里只有代码（约 72 kB）：不带索引数据、不带模型权重、不带原生二进制，安装是秒级的。
+
+## 快速开始
+
+**1. 建索引（一次性）**
+
+安装阶段不下载任何东西，先建一次本地索引：
+
+```bash
+npx dsh-plugin-discover build
+```
+
+下载约 25 MB（dsh.so 插件目录），视网络通常一两分钟完成。也可以直接在会话里让 AI 建库——后台执行、立即返回，不阻塞对话。
+
+索引按用户全局存放，所有 profile 共用，约占 20 MB 磁盘：
+
+| 系统 | 目录 |
+|---|---|
+| Windows | `%LOCALAPPDATA%\dsh-plugin-discover\` |
+| macOS | `~/Library/Caches/dsh-plugin-discover/` |
+| Linux | `${XDG_CACHE_HOME:-~/.cache}/dsh-plugin-discover/` |
+
+构建总是写入新目录、成功后才切换，失败不影响现有索引；同一时刻只会有一份构建（锁保护）。想彻底重置，删掉整个目录再建即可。
+
+**2. 直接问**
+
+> 帮我找一个任务完成时能发微信通知的插件
+
+AI 会调用 `plugin_discover` 检索并解释结果，例如：
+
+```
+🔍 10 个候选 · 过滤 balanced（排除 1094 条）
+
+① dsh-wecom-notify · 1★ · L5 已验证 · 低风险
+   DSH 插件：任务完成 / 报错 / 需要用户选择时，自动通过企业微信群机器人 webhook 发送通知
+   [装: github:ljnljn2005/dsh-wecom-notify]
+② dsh-clawbot · 11★ · L5 已验证 · 低风险
+   在 DSH 里接入微信官方 ilink 机器人网关：扫码绑定后，AI 能主动给自己发微信通知
+   [装: github:cryjkd/dsh-clawbot#1.5.0]
+③ @chenweigao/dsh-perch-notify · L5 已验证 · 低风险
+   Webhook notifications for DSH sessions — POST on approval requests and turn ends
+   [装: github:chenweigao/dsh-perch-notify]
+
+数据截至 2026-10-25 · Powered by dsh.so
+```
+
+每条带星数、验证等级、安全风险、更新时间和安装目标；描述保持英文，由 AI 在回答里翻译。想装哪个，把安装目标交给 DSH 的插件管理即可——本工具自己永远不装。
+
+**3.（可选）开启向量模式**：见[可选向量模式与模型包](#可选向量模式与模型包)。
+
+## 它怎么工作
+
+```
+你的原话 + AI 给的最多 3 条改写
+  → 本地 BM25 词面检索（4 路查询分别检索，RRF 融合，同仓库的多个包合并成一张卡）
+  → 质量过滤（安全 / 验证等级 / 兼容性）
+  → 筛去不相关的候选
+  → 返回候选 + 安装目标
+```
+
+- **中文查询需要英文改写**：目录里的插件名、标签、描述都是英文，AI 会自动补英文/术语改写，你不用管。
+- **不要求所有词都命中**：词面检索按 OR 组合，中文长句也能出结果；名称和标签的权重高于描述。
+- **`noMatch` 是正确结果**：没有足够证据表明存在匹配插件时，工具返回空并建议换说法，而不是硬凑一个。宁可空，不误导。
+- **本地索引数据会过期**：报告头部带"数据截至"；索引超过更新周期（默认一周）时，下次检索会先自动刷新、等待成功后再出结果；刷新失败才用旧索引兜底，并明确提示。
+
+## 工具参数
+
+`plugin_discover` 的参数由会话模型填写，你不需要手工构造；列出供集成与排查参考：
+
+| 参数 | 类型 | 语义 |
+|---|---|---|
+| `query` | string | 用户原话，不转述。检索必填；`explain` / `refresh` 时传 `""`。 |
+| `queryAlts` | string[] | 最多 3 条改写：英文/术语版（中文查询必需）、3–5 个能力词、一句使用场景。 |
+| `limit` | number | 返回条数，1–20；省略时用配置值。 |
+| `explain` | string | 传结果 id / 精确名称 / 安装目标，返回该条完整记录，不检索。 |
+| `refresh` | boolean | 立即返回，后台建/更新索引。 |
+| `filters` | object | 临时覆盖 `preset`（strict/balanced/loose/off）与 `minVerificationLevel`（0–5）。 |
+
+## 配置
+
+打开插件管理页里本插件的**详情页**，配置区直接显示在页面中。保存即生效——宿主只重载本插件，进程与会话不重启。
+
+| 配置项 | 默认 | 说明 |
+|---|---|---|
+| 索引目录 | 系统默认路径 | 见上表。改后 CLI 需用 `--index-dir` 指向同一目录。 |
+| 索引更新周期 | 周（7 天） | 天 / 周 / 月（30 天）/ 3 个月（90 天）。检索时发现超过周期，先刷新并等待成功再出结果。 |
+| 过滤档位 | 均衡（balanced） | 严格 / 均衡 / 宽松 / 关闭，见下表。 |
+| 最低验证等级（仅均衡档） | 4 | 0 = 不限；1–5 要求验证等级 ≥ N。验证等级未知的条目不因此被删。 |
+| 结果返回数量（top N） | 10 | 范围 1–20。 |
+| 无关结果筛选强度 | medium | none（关闭）/ low / medium / high。越高越不容易硬凑结果，也越可能对边缘需求返回空。 |
+| 向量化检索增强 | off | off / balance（字段向量）/ high（README 向量），见[可选向量模式与模型包](#可选向量模式与模型包)。 |
+| 向量化范围（top N） | 50 | 参与向量重排的候选数，范围 2–200；增强为 off 时不生效。 |
+| 单请求超时（秒） | 30 | README 单请求超时，范围 5–300。 |
+| README抓取总超时时长（分钟） | 5 | 范围 1–10；超时后剩余记录跳过 GitHub、走 npm CDN。 |
+| GitHub 请求并发 | 4 | 范围 1–8；速率固定为每 worker 1 次/秒，不可配置。 |
+
+过滤档位：
+
+| 档位 | 安全 | 验证 | 兼容 |
+|---|---|---|---|
+| `strict` | audited + low | L5 | 必须通过 |
+| `balanced`（默认） | 排除 audited high/critical；未审计放行并标注 | ≥ L4（可配）；缺失放行 | 通过或未知 |
+| `loose` | 只排除 high/critical | 不限 | 只标注 |
+| `off` | 只排除 critical | 不限 | 不判断 |
+
+"未知"不等于"不达标"：字段缺失的条目降权并标注，不过滤。过滤后不足 3 条时自动放宽一档，报告中注明。
+
+## CLI
+
+```bash
+dsh-plugin-discover build   [--index-dir <dir>] [--json] [--quiet]
+dsh-plugin-discover status  [--index-dir <dir>] [--json]
+dsh-plugin-discover search  <query> [--alt <text>]... [--limit <n>] \
+                             [--preset strict|balanced|loose|off] \
+                             [--min-verification <0-5>] [--explain <id>] [--json]
+dsh-plugin-discover model status [--index-dir <dir>] [--profile <name>] [--json]
+dsh-plugin-discover model pull   [--spec <spec>] [--profile <name>] \
+                                  [--index-dir <dir>] [--dry-run] [--no-verify] [--json]
+```
+
+- `build` / `status`：建索引、看状态。
+- `search`：不进会话直接试查询；`--alt` 可重复最多 3 次给改写。
+- `model pull` / `model status`：可选模型包的显式拉取与状态，见下节。
+
+DSH 插件不能向 `dsh` 命令注册子命令，所以 CLI 作为包自带的 bin 提供。链接安装（`link:`）时没有全局 bin，用 `node lib/cli.js build` 代替。
+
+## 可选向量模式与模型包
+
+词面检索（默认）已覆盖大多数需求。向量模式用本地嵌入模型对候选做语义重排，能改善"说法不同但意思相近"的匹配；实测中它对多数查询没有明显优势（部分场景略优、部分略劣），所以默认关闭，想试再开。
+
+代价是一个独立模型包 `dsh-plugin-discover-model`（int8 量化的 [multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small)，384 维）：下载约 80 MB，连同 ONNX 运行时装完约 420 MB；运行时内存约 400–500 MB。模型跑在子进程，空闲 5 分钟自动退出，不开向量时零开销；ONNX 默认 4 线程（可用环境变量 `DSH_MODEL_THREADS` 覆盖）。它不是主插件的依赖，只有 `model pull` 才装：
+
+```bash
+# 从 npm（发布后）
+dsh-plugin-discover model pull --spec dsh-plugin-discover-model@0.1.0
+
+# 从本地目录
+dsh-plugin-discover model pull --spec "link:D:\dsh-plugin-discover\models\multilingual-e5-small"
+
+# 从 tarball 文件
+dsh-plugin-discover model pull --spec "file:D:\path\to\dsh-plugin-discover-model-0.1.0.tgz"
+
+dsh-plugin-discover model status
+```
+
+`model pull` 按 manifest 逐文件校验（默认 SHA-256），并在索引目录写 `model.json` 指针。安装时 pnpm 可能以 `ERR_PNPM_IGNORED_BUILDS` 警告 `onnxruntime-node` 的构建脚本被跳过——预编译 CPU 二进制仍然可用，这是警告不是失败。
+
+装好后，在插件详情页把「向量化检索增强」改为：
+
+| 模式 | 行为 |
+|---|---|
+| `off`（默认） | 不加载模型、不算向量。 |
+| `balance` | 字段向量重排：把候选的目录字段——名称、标题、标签（topics）、能力标签、描述——拼成文本算语义相似度，与词面名次加权融合。 |
+| `high` | 字段 + README 向量重排：在字段向量之外，额外抓取候选的 README 做语义比对。 |
+
+网络行为（仅 `high` 模式联网）：
+
+- README 来源顺序：GitHub raw → npm CDN 精确版本 → 字段向量兜底；命中缓存不联网。
+- 固定限速（全局 4 req/s）、单请求 30 秒保护、总预算默认 5 分钟；超时自动降级，不影响整次查询。
+- 无法直连 GitHub 的网络环境下自动走 npm CDN，再不行回退字段向量。
+- GitHub 连续返回 403/429 或连续超时会熔断 10 分钟；结果带 `readme.circuit` 提示，AI 会转告你。
+- 向量缓存放本地（`<indexDir>/cache/`），随数据更新自动失效。
+- 模型缺失或启动失败时自动降级为词面排序并附提示，不会静默出错，也不会自动下载。
+
+## 数据与隐私
+
+- 主源：[dsh.so 插件目录](https://www.dsh.so/plugins-index.json)，CC-BY-4.0。每份报告带 `Powered by dsh.so — DSH Developer Hub` 与源数据时间戳。
+- 补充：[dsh-plugin-catalog](https://cdn.jsdelivr.net/npm/dsh-plugin-catalog/index.json)，CC0-1.0（兼容信息与仓库地址）。
+- npm registry 只用于解析 README 的精确版本，不参与收录与排序。
+- 只收录有安装目标的条目——每条结果都能回答"怎么装"。
+- 索引只是本机缓存：不上传、不共享、不作为服务分发。
+
+## 已知限制
+
+- 中文查询依赖 AI 补英文改写；改写偏了会带进相邻插件或漏掉目标。判断门槛能压掉一部分，压不干净。
+- 某些泛化场景（如"手机上用"类需求）召回可能偏弱。
+- `updatedAt` 来自目录数据；不在目录里的条目不显示更新时间。
+- 向量模式默认关闭；开启前需先显式拉取模型包。
+- 目前仅在 Windows 上验证过；macOS / Linux 理论可用，未实测。
+
+## 许可
+
+代码 MIT。索引数据保留源许可与署名（dsh.so CC-BY-4.0，catalog CC0-1.0）。