dsh-web-search-pro 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # 更新记录
 
+## 未发布
+
+## 0.2.4（2026-11-09）
+
+**用户能得到什么：** 插件现在能在 DSH 0.2.2 线（`0.2.2-rc.1` 起）上正常安装和运行，同时继续支持 0.2.0-rc.2 与 0.2.1-rc.2 ~ rc.5。设置卡片在 0.2.2 线上不再 405；含 `!!js` 表达式的配置不再启动失败，也不再误报“待重启”。没有 Config schema 变化，没有破坏性变更。
+
+**谁应该升级：** 所有在 DSH `0.2.2-rc.1`（含 DSH Desktop）上的用户——0.2.3 的 peer 把这条线挡在外面，Desktop 会直接拒绝安装。仍在 0.2.0 / 0.2.1 线的用户可升可不升（运行时没有针对这两条线的改动）。0.2.2 线宿主上的配套浏览器插件请用 `@anweat/dsh-browser@0.2.3` 或更新。
+
+**致谢：** @snailium 的 PR #44（0.2.2 线 peer 与 cordis 4.1 的起点）；设置卡片通道的做法来自 @shuaigekda 的 [anweat/dsh-browser#49](https://github.com/anweat/dsh-browser/issues/49)。
+
+**已知限制：** `0.2.2` 正式版靠 `0.2.2-rc.1` 的验证放行，没有对正式版另做验证；没有在 Electron 版 DSH Desktop 上实测，也没有带模型会话的端到端测试（验证用宿主自己的 `ctx.tools.execute` 调 `web_call`）。
+
+升级命令见下面“从旧版本升级”。
+
+- 兼容 DSH 0.2.2 线（`0.2.2-rc.1` 起；贡献者 @snailium 的 PR #44 为起点，本条在其基础上核实并修正）。0.2.2 线把 cordis 从 4.0.x 升到 4.1.x，`Fiber.config` 的含义随之改变，因此除 peer 之外有两处必须改的代码：
+  - **修复：读取插件配置的位置。** cordis 4.0.x 的 `ctx.fiber.config` 是**解析后**的对象（schema 默认值、`internal/config` 钩子都已应用），没有 `effectiveConfig`；cordis 4.1.x 的 `fiber.config` 是**原始输入**（没写配置的 entry 上是 `undefined`，`!!js` 表达式不求值），解析后的对象在 `fiber.effectiveConfig`。插件的 `baseline()` 以前直接把 `fiber.config` 交给 `resolveConfig()`，现在读 `fiber.effectiveConfig ?? fiber.config ?? {}`（`src/fiber-config.ts`，单元测试固定三种情形：只有 `effectiveConfig`、只有 `config`、都没有）。
+    - 只加 `?? {}` 的修法（PR #44 原样）只挡住了“没写配置的 entry 无法激活”这一种崩溃。在真实 0.2.2-rc.1 宿主上，配置里含表达式的 entry（例如 `dbPath: !!js dshHomePath(...)`）仍然启动失败，`timeoutMs: !!js 45000` 则让 `config.inspect` / `sources.status` 误报“待重启：timeoutMs（当前生效 45000，配置为 [object Object]）”。改读 `effectiveConfig` 后两者都正常。写成普通值的部分配置，原样的代码与 `?? {}` 版本在 0.2.2-rc.1 上表现一致（`resolveConfig` 自己会补缺省值）。
+    - 没有配置的 entry 在 cordis 4.1 上无法挂载的原始现象：宿主只报一行 `warning: 1 entry did not activate`，所有工具缺席。
+  - **peer：** 每个受管 `@deepseek-ai/dsh-*` 增加第三段 `>=0.2.2-rc.1 <0.2.3-0`，即 `>=0.2.0-rc.2 <0.2.1-0 || >=0.2.1-rc.2 <0.2.2-0 || >=0.2.2-rc.1 <0.2.3-0`。每段都显式写出该线的预发布元组，否则 Host 在组合期会跳过（`semver` 的默认预发布规则）。0.2.3 及更早的宿主线行为不变。
+  - **cordis peer** 从 `~4.0.4` 改为 `~4.0.4 || ~4.1.0`：0.2.0-rc.2 宿主依赖 `~4.0.4`、0.2.1-rc.x 依赖 `~4.0.5`、0.2.2-rc.1 依赖 `~4.1.0`。没有用 `^4.0.4`，它会把没验证过的 4.2、4.3 一并放进来。
+  - **测试：** `config-actions.test.ts` 里“宿主审批缝”的钉死测试改为在 `dsh-tools/lib` 的所有文件里找（0.2.2 把 `serviceAsk` 与 `tools/pre-execute` 闸门从 `lib/index.js` 移到了 `lib/pipeline.js`，行为不变）。
+  - **修复：设置卡片的私有 RPC 通道在 0.2.2-rc.1 上挂不上。** `connection.rpc.handle()` 在 cordis 4.1 的新服务解析规则（按方法**定义处**检查 `inject`）下对外部插件抛 `cannot get property "webServer" without inject`：根因在宿主 `packages/client/connection/src/rpc-host.ts` 的 `register()` 里读 `owner.webServer`，而 Connection 插件自己没有声明该注入；抛错发生在 inject 回调里，原先没有任何报告，现象是卡片的实时状态、“agent 修改”面板、自定义 CLI 试运行全部 405。现在经派生上下文 `connectionCtx.extend({ webServer: connectionCtx.get('webServer') })` 读取 `connection` 并调 `rpc.handle`：`rpc` getter 捕获的 `owner` 是这个派生上下文，`webServer` 在它上面是自有属性，同一条路由、同一套认证。**只用公开的 Context API，不依赖宿主的 TypeScript-private `register` 方法**；三条宿主线（0.2.0-rc.2、0.2.1-rc.5、0.2.2-rc.1）都走这一种写法，没有“先试 handle、失败再回退”的分支。做法来自 [anweat/dsh-browser#49](https://github.com/anweat/dsh-browser/issues/49)（@shuaigekda，当时只在 dsh-browser 的 0.2.2-rc.1 上验证；这里补验了 0.2.0-rc.2 与 0.2.1-rc.5）。挂载失败时（例如某个未来宿主又改了规则），在 effect 里捕获，用 `console.warn` 打一行（频道名、原因、卡片仍渲染但实时状态 / agent 修改面板 / CLI 试运行不可用），返回空的卸载函数，插件照常运行；不用 `ctx.logger`，因为宿主默认级别会丢掉这类 warn，也不报告 inject 回调里的抛错。单元测试 `test/rpc-channel.test.ts` 固定：派生上下文自有 `webServer`、`handle` 在它上面被调用、抛错向上传、告警行含频道名与原因且无 ANSI。三个真实宿主的 Web profile 上无 405、状态摘要、停用时通道卸载都正常；0.2.2-rc.1 上另验证覆盖层读取、采纳与撤销、自定义 CLI 试运行、设置保存与恢复，以及 headless 的 `web_index` + `web_call config.inspect`（[验证记录](docs/validation/2026-11-05-dsh-0.2.2.md) 的 2026-11-09 一节）。
+  - 真实宿主验证（隔离 `DSH_HOME`，tgz 以 `file:` 安装，走安装闸门；无模型探针用宿主自己的 `ctx.tools.execute` 调 `web_call`，判定标准是完成的工具调用结果）：`0.2.0-rc.2`、`0.2.1-rc.5`、`0.2.2-rc.1` 三个宿主上，无配置与有配置的 entry 都通过，包括不联网的 `search.run`（本地 SearXNG 形状的夹具）、不重启改 `searchMaxResults`、审批闸门、skill。`0.2.2` 正式版靠 `0.2.2-rc.1` 的这轮验证放行，没有对正式版另做验证。
+- 兼容：新增实测 `dsh-v0.2.1-rc.5`（npm `@deepseek-ai/dsh@0.2.1-rc.5`，dist-tag `next`，2026-10-30 验证）。**插件源码与 peer 范围没有改动**：rc.5 与 rc.4 的依赖版本相同，源码差异只在客户端对话的推理块渲染，不涉及插件用到的宿主接口。npm 上已发布的 `0.2.3`（搭配 `@anweat/dsh-browser@0.2.2`）在 rc.5 宿主上干净安装（pnpm 11.7.0 与 12.4.2 都退出码 0、无警告）、headless 下 `web_index` / `web_call` 可用、Web 设置卡片渲染并保存一项都通过。`test:peers` 的受支持基线加了 `0.2.1-rc.5`。验证记录见 [docs/validation/2026-10-30-dsh-rc5.md](docs/validation/2026-10-30-dsh-rc5.md)。
+- 文档整理：README 精简为中文入口并新增英文版 `README.en.md`；其余内容按主题拆到 `docs/guide/`，设计与调研记录移到 `docs/dev/`；`LOGIN.md` 并入 `docs/guide/platform-login.md` 并按当前的 opencli 优先做法改写（登录由用户自己完成，插件没有登录窗口）；README 里的兼容表与升级说明移到本文件；新增 `scripts/check-docs-links.mjs`（`pnpm run check:docs`，已并入 `verify`）检查文档链接、锚点和中英文 README 的标题数量。没有改动运行时行为。
+
+## 从旧版本升级
+
+适用于 0.2.x 各版本之间的升级（0.1.x 宿主或 dsh-browser 0.1.x 请不要升级，停留在 `dsh-web-search-pro@0.1.15`，见[兼容与发布通道（历史）](#兼容与发布通道历史)）。DSH Desktop 用户在插件页卸载后重新 Add plugin，写法见 [安装与首次使用](docs/guide/install.md#用-dsh-desktop-安装)。
+
+先确认宿主是 `dsh-v0.2.0-rc.2`、`dsh-v0.2.1-rc.2` ~ `rc.5` 或 `dsh-v0.2.2-rc.1` 起，浏览器插件（如果装了）是 `@anweat/dsh-browser@0.2.3`（0.2.1 线宿主上 0.2.2 起即可；0.2.2 线宿主上请用 0.2.3 或更新；0.2.0-rc.2 宿主上 0.2.0 / 0.2.1 也可以）；两者都需要作为 profile 的直接依赖。
+
+```bash
+dsh plugin --profile web add @anweat/dsh-browser@0.2.3 dsh-web-search-pro@0.2.4
+```
+
+> **不再支持旧线**：宿主仍是 DSH 0.1.x，或浏览器插件仍是 `@anweat/dsh-browser` 0.1.x，请不要升级。只升级本插件、保留旧浏览器插件时，本插件照常工作，但所有浏览器相关能力都会返回 `CAPABILITY_UNAVAILABLE`，`sources.status` 显示 `browser: legacy (unsupported)`。
+
+> **破坏性变更（工具面，0.2.0 起）**：旧的 `web_search_pro`、`web_fetch_pro` 等 11 个工具名不再注册，也没有兼容包装。旧会话里对它们的调用会失败；把调用改成对应动作即可，对照表见 [旧工具到新动作](docs/guide/tools-and-actions.md#旧工具到新动作)。模型在 `web_call` 里写旧工具名会得到新动作名和翻译后的参数，`web_index()` 根目录也列出同一张对照。已存储的数据（历史、页面、规则、证据、账本）与 `ctx.web` provider 不受影响。其他不兼容变化与新功能见下面各版本。
+
+升级完成后需要**完整停止并重新启动 Web profile**；仅刷新网页不会重新扫描插件的 `client.js`。随后依次检查：
+
+1. `browser_call({action:"runtime.status"})`：确认 OpenCLI、`playwright | patchright` 运行时、`automationMode` 与 `usagePolicy` 符合预期。
+2. `web_call({action:"sources.status"})`：确认搜索、CLI、Agent Reach 与浏览器后端是否 ready（浏览器应显示 `ready`，不是 `legacy (unsupported)`）。
+3. 打开 `插件 → 已安装` 中两个 bundle 各自的详情页，确认配置表单都已加载；浏览器表单负责自由度、运行时、OpenCLI 与调用缓冲。
+
+> `automationMode` 和防止过度调用的 `usagePolicy` 都属于 dsh-browser，升级不会自动改写现有配置。生产 profile 建议保留 `standard`；`unrestricted` 只用于隔离的自动化测试 profile，并且仍受并发、突发、页数/深度和 429/503 退避保护。
+
+升级到 0.2.3 时请特别注意：已有 `DEEPSEEK_API_KEY` 的用户，默认搜索会先走按请求计费的 DeepSeek 搜索（见下面 0.2.3 的“请先看：默认行为会变”）。
 ## 0.2.3（2026-10-28）
 
 接入 **DeepSeek Search / Fetch API**（[文档](https://api-docs.deepseek.com/guides/search/)，2026-10-17 上线）并标为“**常用**”。兼容范围见下面“同时支持 DSH 0.2.0-rc.2 与 0.2.1-rc.2 ~ rc.4”（DSH `>=0.2.0-rc.2 <0.2.1-0 || >=0.2.1-rc.2 <0.2.2-0`，可选 `@anweat/dsh-browser ^0.2.0`），没有破坏性变更，Config schema 只增不改（`deepseekFetch`、`keyedSources.deepseek`；`playwright.snapshotDir` 现在声明为 volatile，见下文面板保存的修复）。
@@ -232,3 +281,17 @@
 - 需要登录的平台（小红书、知乎、微博、豆瓣、贴吧、抖音、快手、Twitter / X 等）需要真实登录态才能验证，尚未在真实账号下测过。
 - 设置面板在桌面端的观感（折叠、暗色主题、窄屏）与保存后的热更新只做过组件渲染与内存 scope 测试，需在真实桌面界面确认。
 - `toolSurface` 与 `registerProvider` 需重启 profile 才生效。
+
+## 兼容与发布通道（历史）
+
+各发布通道对应的宿主基线与兼容承诺。当前版本的兼容范围见 [README](./README.md#兼容性) 与 [兼容范围](docs/guide/compatibility.md)；0.2.x 各版本的详细变化见上面对应小节。
+
+| 插件发布通道 | DSH 基线 | 兼容承诺 |
+|---|---|---|
+| `0.1.11` 及更早的维护版本 | `dsh-v0.1.1-rc.2` | 旧基线；不再维护，不与新插件混装 |
+| `0.1.15` | `dsh-v0.1.7-rc.2` + Browser `0.1.15` | 精确锁定该宿主版本；**仍停留在 DSH 0.1.x 宿主或 dsh-browser 0.1.x 的用户请使用这一版**（后续不再更新） |
+| `0.1.17` | `dsh-v0.1.7-rc.2` ~ `dsh-v0.2.0-rc.2` + Browser `0.1.17` | 过渡版本，已不再演进；新功能不会回到这条线（2026-10-29 核对：npm 上 `dsh-web-search-pro` 没有发布过 0.1.17，0.1.x 线实际最后一版是 0.1.15） |
+| `0.2.0`（正式版） | **只支持 `dsh-v0.2.0-rc.2` 这一条线**（peer `>=0.2.0-rc.2 <0.2.1-0`）+ 可选 `@anweat/dsh-browser ^0.2.0` | 第一个 0.2.0 线版本，**破坏性变更**（见 [0.2.0-rc.1](#020-rc1预发布) 的“破坏性变更”）；711 项单元测试、94 项 bench 测试，`pnpm run test:peers` 两种解析模式检查，真实 Host（DSH 0.2.0-rc.2）验收 |
+| `0.2.1` | 同 `0.2.0` | 独立 CLI 适配层与平台后端链，无破坏性变更；774 项单元测试、94 项 bench 测试，真实 Host（DSH 0.2.0-rc.2）验收 |
+| `0.2.2`（未单独发布，并入 0.2.3） | **只支持 `dsh-v0.2.1-rc.2` / `dsh-v0.2.1-rc.3`（0.2.1 线）**（peer `>=0.2.1-rc.2 <0.2.2-0`）+ 可选 `@anweat/dsh-browser ^0.2.0`（配套 `0.2.2` 起，旧的 0.2.0 / 0.2.1 只适用于 0.2.0-rc.2 宿主） | 适配 DSH 0.2.1-rc.2 / rc.3 并修复 twitter 平台结果全错（[#38](https://github.com/anweat/dsh-web-search-pro/issues/38)）；无破坏性变更。npm 上的 0.2.1 在 0.2.1-rc.x 宿主上会被安装闸门拒绝。twitter 的搜索输出契约来自 twitter-cli 0.8.5 源码与 issue 里的真实输出，我们自己没有用 Token 跑过搜索。详见 [0.2.2](#022未单独发布内容并入-023) |
+| `0.2.3` | **两条宿主线同时支持**：`dsh-v0.2.0-rc.2`（0.2.0 线）与 `dsh-v0.2.1-rc.2` ~ `rc.4`（0.2.1 线）；peer `>=0.2.0-rc.2 <0.2.1-0 \|\| >=0.2.1-rc.2 <0.2.2-0`，cordis `~4.0.4`；可选 `@anweat/dsh-browser ^0.2.0`（0.2.0 线配 Browser `0.2.0` / `0.2.1` / `0.2.2`，0.2.1 线配 `0.2.2` 起） | 接入 DeepSeek Search / Fetch API 并标为“常用”（按请求计费）；设置面板同步调整。无破坏性变更，但**已有 `DEEPSEEK_API_KEY` 的用户升级后默认搜索会走这个付费接口**（`sources.disabled: [deepseek]` 关闭）。宿主适配没有改任何运行时代码，验证见 `docs/validation/2026-10-28-host-lines-and-install.md`；测试数见 [0.2.3](#0232026-10-28) |

package/README.en.md

@@ -0,0 +1,117 @@
+# dsh-web-search-pro
+
+English | [中文](./README.md)
+
+An enhanced web search plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH): multi-engine search, platform search, a persistent cache and evidence packs, with only two tools resident in the model's context.
+
+> The detailed guides linked below are written in Chinese. This page covers install, first use and the everyday settings in English.
+
+- **Evidence-pack mode**: give `search.run` a one-sentence task and it returns scored excerpts plus the gaps that remain, instead of a result list. It uses far less context.
+- **Multi-engine plus platform sources**: web engines (ddg, bing, Exa, Jina ...) and platforms (GitHub, Bilibili, YouTube, Xiaohongshu, Zhihu, Reddit, X, RSS ...) share one probing, cooldown, fallback and history path. DeepSeek Search / Fetch is the "common" source (billed per request).
+- **You do the logging in**: platforms that need a login go opencli-first (your everyday Chrome's session). The plugin has no login window and never reads cookies.
+- **Two resident tools**: `web_index` (catalog) then `web_call` (execute). 27 actions are disclosed on demand, about 800 characters resident.
+- **Persistence**: SQLite plus in-memory LRU cache, query history, re-importable per-site extraction rules.
+- **Visual settings**: one settings card for search order, keys, custom CLIs and the scoring model. Changes an agent makes appear as an overlay you can adopt or revert with one click.
+
+## Compatibility
+
+| Item | Range |
+|---|---|
+| dsh-web-search-pro | `0.2.4` |
+| DSH host (peer) | `>=0.2.0-rc.2 <0.2.1-0 \|\| >=0.2.1-rc.2 <0.2.2-0 \|\| >=0.2.2-rc.1 <0.2.3-0`; verified on `0.2.0-rc.2`, `0.2.1-rc.3`, `0.2.1-rc.4`, `0.2.1-rc.5`, `0.2.2-rc.1` |
+| cordis (peer) | `~4.0.4 \|\| ~4.1.0` (0.2.2-line hosts ship 4.1.x) |
+| Optional companion `@anweat/dsh-browser` | `^0.2.0` (on 0.2.1-line hosts it must be `0.2.2` or later; on 0.2.2-line hosts use `0.2.3` or later) |
+| DSH 0.1.x hosts or dsh-browser 0.1.x | Stay on `dsh-web-search-pro@0.1.15`; it is no longer updated |
+
+**Settings card channel on the 0.2.2 line**: the host's `connection.rpc.handle()` throws for external plugins under cordis 4.1 (root cause: the host's `dsh-client-connection` `register()` reads `owner.webServer`, and cordis 4.1 checks `inject` at the service's definition site). The plugin calls `handle` through a derived context that owns `webServer` (`ctx.extend({ webServer: ctx.get('webServer') })`): public Context API only, no private host method, the same code on all three host lines (0.2.0-rc.2, 0.2.1-rc.5, 0.2.2-rc.1). The approach comes from [anweat/dsh-browser#49](https://github.com/anweat/dsh-browser/issues/49) (@shuaigekda). If mounting fails the plugin prints one console warning and keeps running (live status, agent-edits panel and CLI dry-run unavailable). See the [CHANGELOG](./CHANGELOG.md) and the [validation record](docs/validation/2026-11-05-dsh-0.2.2.md) (Chinese).
+
+The compatibility table of earlier versions is in the [CHANGELOG](./CHANGELOG.md#兼容与发布通道历史); how the peer range is written is explained in [Compatibility](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/compatibility.md) (Chinese).
+
+## Installation
+
+**DSH CLI** (restart the profile afterwards):
+
+```bash
+# Search only:
+dsh plugin --profile web add dsh-web-search-pro@0.2.4
+# Plus rendered pages / browser platforms: install the optional browser plugin together (both must be direct dependencies of the profile)
+dsh plugin --profile web add @anweat/dsh-browser@0.2.3 dsh-web-search-pro@0.2.4
+dsh --profile web
+```
+
+**DSH Desktop**: Desktop manages its profile itself and the CLI cannot operate it. Open the **Plugins** page, click **Add plugin**, enter the package name (a version may be appended, for example `dsh-web-search-pro@0.2.4`, the same text as after `add` above), then Install. The dialog also lets you pick a **Registry**. Upgrading a non-official plugin means uninstalling and reinstalling it. Mirrors such as npmmirror can lag the official registry by minutes to hours; if a new version cannot be installed, switch the Registry to `https://registry.npmjs.org`.
+
+**Local directory / tarball (development)**: `dsh plugin --profile web add ../dsh-browser ./dsh-web-search-pro`.
+
+More (first-install notes and troubleshooting) in [Install and first use](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/install.md) (Chinese); upgrading is covered in the [CHANGELOG](./CHANGELOG.md#从旧版本升级).
+
+## First use
+
+- **Settings card**: `Settings -> Plugins -> Plugin config -> Web Search Pro`. The status summary at the top shows the default engine chain in the order it is actually tried, how many sources have a key, whether DeepSeek is ready, and pending restarts.
+- **Check the backends**: have the model call `web_call` with `sources.status`; the readiness of every source and platform, and why a backend was skipped, are listed there.
+- **Sources and keys**: web search and the evidence pipeline work right after install (ddg / bing need no key). With a `DEEPSEEK_API_KEY` the default search leads with DeepSeek Search, which is **billed per request**; put `deepseek` under `sources.disabled` to opt out. Exa, Jina, Bocha, GitHub and other keys are entered in the card's "Sources" group (stored in DSH Credentials and never read back).
+- **Defaults out of the box:** Jev is off by default (`evidence.jevMode: off`; evidence scoring uses the local rules and no model is called, no model key is needed); Bocha is used only when you configure a key. **Exception:** DeepSeek Search (the common, 常用, source; billed per request) leads the default order as soon as a DeepSeek API key resolves (settings key field, DSH credential `DEEPSEEK_API_KEY`, or the process environment); put `deepseek` under `sources.disabled` or write your own `engines` list to opt out.
+- **Optional dependencies**: the browser plugin `@anweat/dsh-browser` (`read.snapshot`, `read.fetch mode=playwright`, search-page platforms; an installed Chrome / Edge is used directly, no Chromium download); `npm i -g @jackwener/opencli` plus its Browser Bridge extension (Xiaohongshu / Zhihu / Reddit / X, using your everyday Chrome's login, see [Platform login](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/platform-login.md)); CLIs such as bili, yt-dlp and gh are detected by `sources.deps`.
+
+## Quick examples
+
+The model calls `web_call({action, args})`. An evidence pack (pass `task` or `profile`):
+
+```json
+{"action":"search.run","args":{"query":"node:sqlite busy timeout","task":"how to set a busy timeout in node:sqlite","profile":"docs_code"}}
+```
+
+Search one platform (login platforms use the opencli-first backend chain):
+
+```json
+{"action":"search.run","args":{"query":"机械键盘 轴体 推荐","task":"了解知乎上对机械键盘轴体的真实经验","profile":"experience","platform":"zhihu"}}
+```
+
+Read a page with `read.fetch` (pass `offset` to continue a long page); ask `search.recommend` when you do not know which source to use. More in [Search and evidence](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/search-and-evidence.md) (Chinese).
+
+## Tools and actions
+
+Only two tools are resident: `web_index({group?, action?, query?})`, a progressive-disclosure catalog, and `web_call({action, args})`, which runs an action and returns a uniform envelope. Usage guidance ships in the skill `dsh-web-search-pro`.
+
+| Group | Actions | Purpose |
+|---|---|---|
+| `search` | `run` `recommend` | Multi-engine / platform search and evidence packs; recommend at most 3 sources for a task |
+| `read` | `fetch` `contents` `snapshot` | Readable fetch with continuation; Exa batch contents; browser snapshot |
+| `history` | `list` `replay` `expand` `export` `delete` | List, replay, expand evidence blocks, export and delete query history |
+| `sources` | `status` `deps` `install` | Backend probing and diagnostics; external dependency check and install |
+| `rules` | `list` `upsert` `remove` `import` `export` | Per-site extraction rules |
+| `cache` | `clear` `stats` | Cache cleanup and statistics |
+| `config` | `inspect` `set_order` `set_confidence` `upsert_cli` `remove_cli` `reset` `export` | Agent overlay: adjust search order, confidence and custom CLIs at runtime |
+
+Full parameters, approval rules, output budgets and the old tool mapping are in [Tools and actions](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/tools-and-actions.md) (Chinese).
+
+## Common settings
+
+Set them under `web-search-pro:` in `$DSH_HOME/settings.yaml`, or use the settings card. Almost all are hot-reloaded.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `engines` | `[ddg, bing, exa, seam, jina]` | Fallback order of general search |
+| `sources.priority` / `sources.disabled` | empty | Source ids to move first / never use (for example `disabled: [deepseek]`) |
+| `searchMaxResults` | `8` | Default number of results of a plain search |
+| `evidence.jevMode` | `off` | Bocha Jev scoring: `off` \| `shadow` \| `control` \| `hybrid` (paid, not called by default) |
+| `evidence.sourcePolicy` | `default` | `anonymous-only` = automatic planning never uses a source that needs a key, account or login |
+| `deepseekFetch` | `false` | `true` = `read.fetch` may use the DeepSeek Fetch API (billed per request) |
+| `fetchDefaultChars` | `20000` | Default characters returned by `read.fetch` |
+| `toolSurface` | `indexed` | `flat` = one tool per action (for comparison and debugging only); **restart required** |
+| `registerProvider` | `false` | Route the host's built-in `web_search` / `web_fetch` through this plugin; **restart required** |
+
+Only these need a plugin restart: `toolSurface`, `registerProvider`, `providerId`, `timeoutMs`, `memoryCacheEntries`, `dbPath`, `verbose`, `playwright.snapshotDir`. All keys and defaults are in the [configuration reference](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/config.md) (Chinese).
+
+## Documentation
+
+The detailed guides (Chinese) are under [docs/](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/README.md):
+
+- Usage: [Install and first use](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/install.md) · [Search and evidence](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/search-and-evidence.md) · [Tools and actions](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/tools-and-actions.md) · [History](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/history.md)
+- Configuration: [Configuration reference](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/config.md) · [Settings panel](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/settings-panel.md) · [Sources and engines](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/sources.md) · [Built-in web tool routing](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/web-provider.md) · [Jev scoring](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/evidence-scoring.md)
+- Platforms and CLIs: [Platform login](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/platform-login.md) · [CLI adapters and custom CLIs](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/cli-adapters.md) · [External dependencies](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/dependencies.md) · [Custom platforms](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/custom-platforms.md) · [Browser scripts and automation tiers](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/browser-scripts.md)
+- Versions and development: [Compatibility](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/compatibility.md) · [CHANGELOG](./CHANGELOG.md) · [Development](https://github.com/anweat/dsh-web-search-pro/blob/master/docs/guide/development.md) · [Design and research notes](https://github.com/anweat/dsh-web-search-pro/tree/master/docs/dev) · [Validation records](https://github.com/anweat/dsh-web-search-pro/tree/master/docs/validation)
+
+## License
+
+MIT. The routing control plane borrows the backend probing, ordered selection and failure-cooldown ideas of Agent-Reach; the core logic is this project's own TypeScript.