@fffangchenghao/dsh-web-search 0.20.0 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,57 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.21.0
4
+
5
+ ### Added
6
+ - **A dependency-free MCP server for other agents.** The package now ships
7
+ `dsh-web-search-mcp` (`mcp/server.mjs`) with four tools: `search`, `fetch`,
8
+ `research` and `domain_search`. It speaks MCP over stdio, needs no DSH
9
+ context and no API key, and is installable with
10
+ `npx -y @fffangchenghao/dsh-web-search dsh-web-search-mcp`. Claude Code and
11
+ Codex setup snippets are in [docs/cross-agent.md](docs/cross-agent.md).
12
+ - **A public 30-query comparison harness.** `bench/compare30.mjs` runs the same
13
+ bilingual corpus against this plugin, keyless Firecrawl and anonymous Exa,
14
+ recording availability, latency, unique domains, official-domain presence and
15
+ every failure. [docs/comparison.md](docs/comparison.md) publishes the method
16
+ and the results, including where this plugin is slower or misses.
17
+ - **Quickstart and demo assets.** [docs/quickstart.md](docs/quickstart.md) and
18
+ `docs/images/web-tools-demo.svg` show the one-tool/eight-action surface and
19
+ the two-minute install path.
20
+
21
+ ### Fixed
22
+ - **Repeated direct 403s on IP-sensitive sources.** When a direct request is
23
+ blocked and the tunnel succeeds, the engine now remembers the working route
24
+ for ten minutes and tries it first next time, while keeping the alternate
25
+ route as a fallback. A recorded Firecrawl request went from 1,874 ms (403 +
26
+ retry) to 1,017 ms on the second call. Regression tests cover the health
27
+ memory and the transport behavior against a real `CONNECT` proxy.
28
+ - **MCP notification handling.** Unknown notifications no longer receive a
29
+ JSON-RPC response, and `notifications/cancelled` is ignored.
30
+
31
+ **Test suite: 668 tests across 52 files** (667 pass, 1 skipped).
32
+
33
+ ## 0.20.1
34
+
35
+ ### Added
36
+ - **A manual update button for deployments without `dsh-autoupdater`.** When
37
+ the Settings page is local and npm reports a newer version, it shows
38
+ **Install update**. The button posts to a loopback-only
39
+ `/api/dsh-web-search/update` bridge, which calls the Host's built-in
40
+ `pluginManager.installBundle` with exactly
41
+ `@fffangchenghao/dsh-web-search@latest`; it never accepts a package name from
42
+ the browser. A `link:`/`file:` checkout is refused rather than replaced, a
43
+ deployment without a plugin manager reports that honestly, and a successful
44
+ install says that a restart is required. This is manual, not a scheduler:
45
+ periodic checks still belong to `dsh-autoupdater`.
46
+ - **The npm version comparison is now directional.** A local build newer than
47
+ the registry is no longer labelled "update available"; the button appears
48
+ only when the registry version is actually newer.
49
+ - **Update-bridge tests.** 8 new cases cover the fixed package spec, link/file
50
+ refusal, manager absence, `ctx.get` fallback, method/loopback/origin guards,
51
+ malformed bodies and manager failure results.
52
+
53
+ **Test suite: 664 tests across 50 files** (663 pass, 1 skipped).
54
+
3
55
  ## 0.20.0
4
56
 
5
57
  ### Added
@@ -14,8 +66,8 @@
14
66
  npm bundle so the profile-level `dsh-autoupdater` manages it; `link:`/`file:`
15
67
  checkouts are intentionally excluded by that updater. The Settings card shows
16
68
  the latest npm version and the running build; the plugin never hot-swaps its
17
- own loaded code. The desktop profile is switched to the npm install after
18
- 0.20.0 is published.
69
+ own loaded code. The desktop profile is now installed from npm (`0.20.0`), so the profile
70
+ updater no longer classifies it as a local checkout.
19
71
  - **`advanced_search` uses the official Chrome Releases feed for a windowed
20
72
  Chrome security/release query.** The feed carries the real post date that a
21
73
  search snippet often loses; the result note states how many posts fell inside
@@ -66,7 +118,7 @@
66
118
 
67
119
  - **Ecosystem comparison refreshed.** The README now carries a 2026-10-25 snapshot with GitHub stars, last-month npm downloads, test evidence and package size for the main DSH competitors; stale claims about tool counts, store status and test leadership were removed.
68
120
 
69
- **Test suite: 655 tests across 49 files** (654 pass, 1 skipped). The new
121
+ **Test suite: 656 tests across 49 files** (655 pass, 1 skipped). The new
70
122
  unified-tool, platform, cache, mirror and landing-page tests are included.
71
123
  - **`engine_test`: one probe per engine, with a reason.** A new model tool tests
72
124
  one engine or all eight, bypasses the cache and never changes cooldown state,
@@ -293,7 +345,7 @@
293
345
  and a success clears its strikes. A throttled or rejected key retries the same
294
346
  request on the next key once, in both search and page extraction. Pools are
295
347
  cached per Settings value, so editing the field starts clean.
296
- - **Settings page polish.** A sticky jump bar scrolls to any of the five groups,
348
+ - **Settings page polish.** A sticky jump bar scrolls to any of the six groups,
297
349
  and a line under the title compares the installed version with npm's latest
298
350
  (hidden when the registry is unreachable rather than guessed).
299
351
  - **Portable skill.** `skills/dsh-web-search/SKILL.md` states when to search,
package/README.md CHANGED
@@ -3,13 +3,14 @@
3
3
  **Gives DeepSeek Harness a pair of hands for the web: the model can search, then open a page and read it, without you pasting links.**
4
4
 
5
5
  - [中文说明](README.zh-CN.md)
6
+ - [Quickstart](docs/quickstart.md) · [Cross-agent MCP](docs/cross-agent.md) · [30-query comparison](docs/comparison.md)
6
7
  - [Changelog](CHANGELOG.md) · [Why a plugin's settings go missing: the four-layer chain](docs/plugin-settings-form.md)
7
8
 
8
9
  <p align="center"><img src="https://raw.githubusercontent.com/fangchenghao/dsh-web-search/main/docs/images/banner.png" alt="dsh-web-search — key-free web search and page fetch for DeepSeek Harness" width="100%"></p>
9
10
 
10
11
  <p align="center">
11
12
  <a href="https://www.npmjs.com/package/@fffangchenghao/dsh-web-search"><img src="https://img.shields.io/npm/v/@fffangchenghao/dsh-web-search.svg" alt="npm version"></a>
12
- <img src="https://img.shields.io/badge/tests-655%20passing-brightgreen" alt="tests">
13
+ <img src="https://img.shields.io/badge/tests-668%20passing-brightgreen" alt="tests">
13
14
  <img src="https://img.shields.io/badge/engines-8%2C%20zero%20API%20key-brightgreen" alt="engines">
14
15
  <img src="https://img.shields.io/badge/node-%3E%3D22.18-blue" alt="node">
15
16
  <img src="https://img.shields.io/badge/dsh-%3E%3D0.2.1--rc.2%20%3C0.3.0-blueviolet" alt="dsh">
@@ -20,8 +21,10 @@
20
21
 
21
22
  - **No API key, eight engines.** AnySearch, CN Bing, DuckDuckGo HTML, www Bing, DuckDuckGo Lite and 360 Search are scraped directly; Exa joins the primary tier through its keyless MCP endpoint, and Firecrawl's search API is the measured fallback. The plugin works out of the box.
22
23
  - **The ranking is measured, not asserted.** Cross-engine reciprocal-rank fusion with authority and freshness boosts, a 20-query offline benchmark, and an 81-configuration parameter sweep — one of the few search plugins here that publishes its metric, per-query output and confidence intervals. See [How the ranking works](docs/rrf-ranking.md).
24
+ - **One package, two runtimes.** DSH gets the native plugin and one `web_tools` entry; Claude Code, Codex and other MCP clients get the same keyless search through a dependency-free stdio server with `search`, `fetch`, `research` and `domain_search`. See [Cross-agent MCP](docs/cross-agent.md).
25
+ - **Measured in public, including the losses.** A 30-query bilingual comparison records availability, latency, unique domains, official-domain presence and every failure against keyless Firecrawl and anonymous Exa. Exa is faster here; this plugin returns more distinct domains. Both test arms were keyless. The method and raw results are in [docs/comparison.md](docs/comparison.md).
23
26
  - **Fetching admits failure.** Binary documents and empty 200 responses are rejected by name (`SEARCH_UNSUPPORTED`, `SEARCH_EMPTY`) instead of being returned as noise; the direct → tunnel → render → extract ladder shares one 25 s budget and stops when there is no time left. The budget is per request — there is a regression test for exactly that.
24
- - **655 tests across 49 files**, a committed `lib/`, declared `engines.dsh` / `engines.node`, and a [SECURITY.md](SECURITY.md) that lists every process, host and file the plugin touches.
27
+ - **668 tests across 52 files**, a committed `lib/`, declared `engines.dsh` / `engines.node`, and a [SECURITY.md](SECURITY.md) that lists every process, host and file the plugin touches.
25
28
  - **Bilingual documentation.** This README and [中文说明](README.zh-CN.md) are maintained side by side.
26
29
 
27
30
  ![Ranking baseline and parameter sweep](https://raw.githubusercontent.com/fangchenghao/dsh-web-search/main/docs/images/bench.png)
@@ -37,11 +40,11 @@ The web-search corner of the DSH plugin ecosystem is crowded. A fresh snapshot
37
40
  |---|---|---|---|---|---|
38
41
  | Key-free path | 8 engines, all key-free | ~30-engine free/paid chain | 5 defaults (seam, Exa, DDG, Bing, Jina) | Firecrawl + Keenable keyless defaults | 1 anonymous AnySearch API |
39
42
  | Dedicated vertical sources | 34 (8 on by default) | 41 | platform registry, not a vertical catalog | web + X, no vertical catalog | vertical API behind AnySearch |
40
- | Model-facing tools | 1 (`web_tools`, 8 actions) | ~10 | 2 (`web_index` / `web_call`, 20 actions) | native search/fetch + skill | 5 |
41
- | Tests | 49 files / 655 cases, locally verified | no test script in `package.json` | 774 unit + 94 bench, self-reported | Vitest configured; count not published | Vitest configured; count not published |
43
+ | Model-facing tools | 1 (`web_tools`, 8 actions) + 4 MCP tools | ~10 | 2 (`web_index` / `web_call`, 20 actions) | native search/fetch + skill | 5 |
44
+ | Tests | 52 files / 668 cases, locally verified | no test script in `package.json` | 774 unit + 94 bench, self-reported | Vitest configured; count not published | Vitest configured; count not published |
42
45
  | GitHub stars | 0 | 620 | 77 | 836 | 663 |
43
46
  | npm downloads, last month | 1,087 | 52,436 | 6,420 | 43,151 | 9,251 |
44
- | npm unpacked size | 0.81 MB | 0.70 MB | 3.05 MB | 0.51 MB | 0.27 MB |
47
+ | npm unpacked size | 1.2 MB | 0.70 MB | 3.05 MB | 0.51 MB | 0.27 MB |
45
48
 
46
49
  This is a capability snapshot, not a league table with one winner. The honest
47
50
  read is:
@@ -49,7 +52,7 @@ read is:
49
52
  - **Feature depth:** upper-middle. `dsh-free-search` has more engines and
50
53
  verticals; `dsh-web-search-pro` has a deeper evidence/ranking pipeline and far
51
54
  more platform backends; `modsearch` is the stronger cross-host bridge.
52
- - **Engineering and verification:** near the top. 655 local tests, a replayable
55
+ - **Engineering and verification:** near the top. 668 local tests, a replayable
53
56
  ranking benchmark, declared security boundaries and one runtime dependency
54
57
  put it alongside the best-maintained entries, while remaining much smaller
55
58
  than the Playwright-heavy option.
@@ -57,9 +60,9 @@ read is:
57
60
  Chrome, PostgreSQL and AI Act paths and the 34-source vertical layer are not
58
61
  common in the other plugins.
59
62
  - **Adoption and maturity:** bottom third of this sample. The public npm release
60
- is 0.19.3; the 0.20.0 tree described here is newer and unpublished, and the
61
- GitHub repository is four days old with no stars.
62
- - **Tool-surface economy:** now competitive. 0.20.0 exposes one `web_tools`
63
+ is 0.21.0, matching this tree, but the GitHub repository is four days old
64
+ with no stars and little independent adoption.
65
+ - **Tool-surface economy:** now competitive. 0.20.x exposes one `web_tools`
63
66
  entry with eight actions, close to `dsh-web-search-pro`'s two tools with 20
64
67
  actions; the legacy eight-name surface remains opt-in for old prompts.
65
68
 
@@ -304,8 +307,8 @@ Each line is the plain version first, the technical note second. The technical n
304
307
  *Technical: proxy sources in order — the `proxy` setting, then `DSH_WEB_SEARCH_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `HTTP_PROXY`, then macOS `scutil --proxy`; HTTP proxies only (`CONNECT`), not `socks5://`.*
305
308
 
306
309
  14. **Every setting is editable in the UI.**
307
- Twenty-nine controls in five groups; a save takes effect on the next search, apart from `cachePersist` and `cacheFile`, which decide the cache wiring at mount.
308
- *Technical: all twenty-nine fields carry `.volatile()`, so the Host commits them in place instead of remounting the plugin; `cacheTtlMs` and `cacheEntries` are re-read per use, `fetchFormat` and `fetchMaxLength` are resolved per request, `renderJs` and `renderTimeoutMs` per fetch; `proxy` and `timeoutMs` are taken at mount, and so is the cache wiring that `cachePersist` and `cacheFile` decide.*
310
+ Thirty controls in six groups; a save takes effect on the next search, apart from `cachePersist` and `cacheFile` (cache wiring at mount) and `toolSurface` (the tool registry is built at mount).
311
+ *Technical: all thirty fields carry `.volatile()`, so the Host commits them in place instead of remounting the plugin; `cacheTtlMs` and `cacheEntries` are re-read per use, `fetchFormat` and `fetchMaxLength` are resolved per request, `renderJs` and `renderTimeoutMs` per fetch; `proxy` and `timeoutMs` are taken at mount, and so is the cache wiring that `cachePersist` and `cacheFile` decide. `toolSurface` is read at mount when the registry is built, so a change needs a reload even though the value is committed live.*
309
312
 
310
313
  15. **Failures are explained, not silently empty.**
311
314
  When nothing succeeds, the error lists which engines were tried and why each one failed.
@@ -405,7 +408,7 @@ via an optional `onPage` sink.*
405
408
 
406
409
  ## Tool surface: one entry point, eight actions
407
410
 
408
- 0.20.0 changes the model-facing surface. The eight capabilities above are now
411
+ 0.20.x changes the model-facing surface. The eight capabilities above are now
409
412
  actions on one `web_tools` tool instead of eight separate registrations. A call
410
413
  looks like:
411
414
 
@@ -444,14 +447,26 @@ Use an npm install, not a `link:`/local checkout:
444
447
  dsh plugin --profile web add @fffangchenghao/dsh-web-search@latest
445
448
  ```
446
449
 
447
- Then keep [`dsh-autoupdater`](https://github.com/raomaiping-hash/dsh-self-upgrade)
448
- or your own profile updater enabled. The updater checks the npm dist-tag,
450
+ Then keep a profile updater such as `dsh-autoupdater` (or
451
+ `dsh-self-upgrade`) enabled. The updater checks the npm dist-tag,
449
452
  updates in an idle window, and asks for a restart on desktop. `link:` and
450
453
  `file:` installs are deliberately skipped by such updaters because replacing a
451
454
  local checkout with the registry package would destroy the checkout.
452
455
 
453
- The Settings card always shows the latest npm version and whether it differs
454
- from the running build; that check is read-only and never installs anything.
456
+ The Settings card always shows the latest npm version. If it is newer and the
457
+ page is local, it also shows **Install update**. That button delegates to the
458
+ Host's built-in `pluginManager` (the same service `dsh plugin` uses), installs
459
+ the exact npm package and tells you to restart. It works **without**
460
+ `dsh-autoupdater`; what it does not do is run periodically. The remote web
461
+ surface hides the button, and a `link:`/`file:` checkout is refused before it
462
+ can be replaced. If the deployment has no plugin manager, the button reports
463
+ that instead of pretending to update.
464
+
465
+ Automatic updates trade review for freshness: the updater installs the
466
+ registry package without a human reading the diff. If that trade is wrong for
467
+ your deployment, pin an exact version and leave the profile updater off. The
468
+ plugin never spawns `pnpm` itself; the manual button only asks the Host to do
469
+ it.
455
470
 
456
471
  ## Installing and enabling it
457
472
 
@@ -559,7 +574,7 @@ Values saved from the Settings page apply immediately; only `cachePersist` and `
559
574
 
560
575
  Any one of these:
561
576
 
562
- 1. **Look at Settings**: Settings → "Web search (Bing)" should show five groups of controls, 26 in all. That means the plugin loaded and the Host accepted its schema.
577
+ 1. **Look at Settings**: Settings → "Web search (Bing)" should show six groups of controls, 30 in all. That means the plugin loaded and the Host accepted its schema.
563
578
  2. **Look at the log**: no warning such as `1 entry did not activate`.
564
579
  3. **Just try it**: ask something that obviously needs the network, such as "search for a DSH plugin tutorial and give me the links". Watch whether `web_search` is called and whether the links are real.
565
580
 
@@ -567,7 +582,7 @@ If the Settings card appears but search still fails, start with [docs/troublesho
567
582
 
568
583
  ## Using the Settings page
569
584
 
570
- Open Settings → "Web search (Bing)". Twenty-nine controls, arranged in five groups, plus an **Engine health** check. A sticky jump bar at the top scrolls to any group, and a line under the title compares the installed version with the latest one on npm (it stays hidden when the registry cannot be reached, so it never guesses). Each group owns one kind of decision:
585
+ Open Settings → "Web search (Bing)". Thirty controls, arranged in six groups, plus an **Engine health** check. A sticky jump bar at the top scrolls to any group, and a line under the title compares the installed version with the latest one on npm (it stays hidden when the registry cannot be reached, so it never guesses). Each group owns one kind of decision:
571
586
 
572
587
  | Group | Controls | What it decides |
573
588
  | --- | --- | --- |
@@ -576,6 +591,7 @@ Open Settings → "Web search (Bing)". Twenty-nine controls, arranged in five gr
576
591
  | Dedicated search | 3 | Which sources `domain_search` queries, results per source, deadline per source |
577
592
  | Fetching | 4 | What `web_fetch` returns — Markdown or plain text, how many characters, whether a browser may render a shell, and how long that render may take |
578
593
  | Cache and cooldowns | 6 | How long results are remembered, how many, whether the cache is saved to disk, and how long a throttled engine rests |
594
+ | Model tools | 1 | Whether the eight optional capabilities appear as one `web_tools` action tool or the legacy eight names. Requires a reload |
579
595
 
580
596
  ### Engines and transport (9)
581
597
 
@@ -631,9 +647,15 @@ Open Settings → "Web search (Bing)". Twenty-nine controls, arranged in five gr
631
647
  | Cooldown (ms) | `baseCooldownMs` | `300000` | First rest after throttling, five minutes |
632
648
  | Max cooldown (ms) | `maxCooldownMs` | `1800000` | Ceiling for the doubling backoff, thirty minutes |
633
649
 
650
+ ### Model tools (1)
651
+
652
+ | Control | Key | Default | Plain meaning |
653
+ | --- | --- | --- | --- |
654
+ | Tool surface | `toolSurface` | `unified` | `unified` registers one `web_tools` with eight actions; `legacy` keeps the old eight standalone names for existing prompts. Changing it builds a different registry, so reload the plugin after saving |
655
+
634
656
  ### My advice
635
657
 
636
- **For normal use: leave all twenty-nine alone. The defaults are the tuned values.**
658
+ **For normal use: leave all thirty alone. The defaults are the tuned values.**
637
659
 
638
660
  Only these situations are worth changing:
639
661
 
@@ -653,7 +675,32 @@ Three things to keep in mind:
653
675
 
654
676
  ## Using the skill from another harness
655
677
 
656
- `skills/dsh-web-search/SKILL.md` is a plain skill file: it states when to search, when to open pages, when to use `research`, and how to cite. Copy the folder into any harness that reads `SKILL.md` files from disk (for example `~/.claude/skills/`). The plugin itself is a DSH plugin, so another harness still needs its own search and fetch tools; the file is the part that transfers.
678
+ `skills/dsh-web-search/SKILL.md` is a plain skill file: it states when to search, when to open pages, when to use `research`, and how to cite. Copy the folder into any harness that reads `SKILL.md` files from disk (for example `~/.claude/skills/`).
679
+
680
+ For another harness that speaks MCP, the package also ships a dependency-free
681
+ stdio server with `search`, `fetch`, `research` and `domain_search`:
682
+
683
+ ```sh
684
+ npx -y @fffangchenghao/dsh-web-search dsh-web-search-mcp
685
+ ```
686
+
687
+ Claude Code:
688
+
689
+ ```sh
690
+ claude mcp add dsh-web-search -- npx -y @fffangchenghao/dsh-web-search dsh-web-search-mcp
691
+ ```
692
+
693
+ Codex (`~/.codex/config.toml`):
694
+
695
+ ```toml
696
+ [mcp_servers.dsh-web-search]
697
+ command = "npx"
698
+ args = ["-y", "@fffangchenghao/dsh-web-search", "dsh-web-search-mcp"]
699
+ ```
700
+
701
+ See [docs/cross-agent.md](docs/cross-agent.md) for the tool list, environment
702
+ variables and the portable skill path. The MCP server needs no DSH context and
703
+ no API key.
657
704
 
658
705
  ## FAQ
659
706
 
package/README.zh-CN.md CHANGED
@@ -9,7 +9,7 @@
9
9
 
10
10
  <p align="center">
11
11
  <a href="https://www.npmjs.com/package/@fffangchenghao/dsh-web-search"><img src="https://img.shields.io/npm/v/@fffangchenghao/dsh-web-search.svg" alt="npm 版本"></a>
12
- <img src="https://img.shields.io/badge/tests-655%20passing-brightgreen" alt="测试">
12
+ <img src="https://img.shields.io/badge/tests-668%20passing-brightgreen" alt="测试">
13
13
  <img src="https://img.shields.io/badge/engines-8%2C%20zero%20API%20key-brightgreen" alt="引擎">
14
14
  <img src="https://img.shields.io/badge/node-%3E%3D22.18-blue" alt="node">
15
15
  <img src="https://img.shields.io/badge/dsh-%3E%3D0.2.1--rc.2%20%3C0.3.0-blueviolet" alt="dsh">
@@ -20,8 +20,10 @@
20
20
 
21
21
  - **不要 API key,八个引擎。** AnySearch、必应中国、DuckDuckGo HTML、必应国际、DuckDuckGo Lite、360 搜索直接抓取;Exa 走它的免密钥 MCP 通道加入主引擎,Firecrawl 的搜索 API 作为实测后的兜底。装好就能用。
22
22
  - **排序是量出来的,不是写出来的。** 跨引擎 RRF 融合,叠加权威度与时效加权;20 条离线基准 + 81 组参数扫描,是这类插件里少数同时公开指标、逐条输出和置信区间的。方法见 [排序是怎么做的](docs/rrf-ranking.md)。
23
+ - **一个包,两种运行时。** DSH 里是原生插件和唯一的 `web_tools` 入口;Claude Code、Codex 等 MCP 客户端通过零依赖的 stdio server 使用同一套免密钥搜索,提供 `search`、`fetch`、`research`、`domain_search`。见 [跨 Agent MCP](docs/cross-agent.md)。
24
+ - **公开测量,也公开输的地方。** 30 条中英查询对比记录可用性、延迟、独立域名、官方域名命中与每一条失败;对比对象是免 key Firecrawl 和匿名 Exa。这里 Exa 更快,本插件返回的独立域名更多;两条对比路径都未使用 key。方法和原始结果在 [docs/comparison.md](docs/comparison.md)。
23
25
  - **抓取会承认失败。** 二进制文档和「200 但正文为空」会被明确拒绝(`SEARCH_UNSUPPORTED`、`SEARCH_EMPTY`),而不是当噪音返回;direct → tunnel → render → extract 四级阶梯共享 25 秒预算,预算不足就不再起新的一级。预算是「每次请求」而不是「插件启动时」,这点有回归测试守着。
24
- - **49 个测试文件、655 个用例**,`lib/` 产物入库,声明了 `engines.dsh` / `engines.node`,[SECURITY.md](SECURITY.md) 逐项列出插件会碰的进程、主机和文件。
26
+ - **52 个测试文件、668 个用例**,`lib/` 产物入库,声明了 `engines.dsh` / `engines.node`,[SECURITY.md](SECURITY.md) 逐项列出插件会碰的进程、主机和文件。
25
27
  - **双语文档。** 本文件和 [English README](README.md) 同步维护。
26
28
 
27
29
  ![排序基线参数扫描](https://raw.githubusercontent.com/fangchenghao/dsh-web-search/main/docs/images/bench.png)
@@ -37,24 +39,24 @@ DSH 插件生态里的「联网搜索」已经很挤。下面是一张 2026-10-2
37
39
  |---|---|---|---|---|---|---|
38
40
  | 免 key 路径 | 8 个引擎,全部免 key | ~30 个免费/付费引擎链 | 默认 5 个(seam、Exa、DDG、Bing、Jina) | Firecrawl + Keenable 免 key 默认 | 1 个 AnySearch 匿名 API |
39
41
  | 专门数据源 | 34 个(默认开 8 个) | 41 个 | 平台注册表,不是垂直源目录 | 网页 + X,无垂直源目录 | AnySearch 的垂直 API |
40
- | 面向模型的工具 | 1 个(`web_tools`,8 个 action) | ~10 个 | 2 个(`web_index` / `web_call`,20 个动作) | 原生搜索/抓取 + skill | 5 个 |
41
- | 测试 | 49 文件 / 655 用例,本地实测 | `package.json` 无测试脚本 | 774 单元 + 94 bench,自报 | 配了 Vitest,未公布数量 | 配了 Vitest,未公布数量 |
42
+ | 面向模型的工具 | 1 个(`web_tools`,8 个 action)+ 4 个 MCP 工具 | ~10 个 | 2 个(`web_index` / `web_call`,20 个动作) | 原生搜索/抓取 + skill | 5 个 |
43
+ | 测试 | 52 文件 / 668 用例,本地实测 | `package.json` 无测试脚本 | 774 单元 + 94 bench,自报 | 配了 Vitest,未公布数量 | 配了 Vitest,未公布数量 |
42
44
  | GitHub stars | 0 | 620 | 77 | 836 | 663 |
43
45
  | npm 近一月下载 | 1,087 | 52,436 | 6,420 | 43,151 | 9,251 |
44
- | npm 解包大小 | 0.81 MB | 0.70 MB | 3.05 MB | 0.51 MB | 0.27 MB |
46
+ | npm 解包大小 | 1.2 MB | 0.70 MB | 3.05 MB | 0.51 MB | 0.27 MB |
45
47
 
46
48
  这不是「只有一个冠军」的排行榜,比较诚实的结论是:
47
49
 
48
50
  - **功能深度:中上。** `dsh-free-search` 引擎和垂直源更多;
49
51
  `dsh-web-search-pro` 的证据/排序管线和平台后端更深;`modsearch` 的跨宿主
50
52
  能力更强。
51
- - **工程质量与可验证性:接近第一梯队。** 655 个本地测试、可重放的排序基准、
53
+ - **工程质量与可验证性:接近第一梯队。** 668 个本地测试、可重放的排序基准、
52
54
  明确的安全边界、只有 1 个运行时依赖,同时体积远小于 Playwright 重型方案。
53
55
  - **免 key + 官方源纠错:最强卖点。** Chrome、PostgreSQL、AI Act 的官方路径
54
56
  和 34 个垂直源,不是其他插件普遍具备的。
55
- - **采用度与成熟度:这个样本里的后段。** 公开 npm 仍是 0.19.3,这里的 0.20.0
56
- 还没发布;GitHub 仓库创建 4 天、0 stars。
57
- - **工具面的经济性:现在有竞争力。** 0.20.0 只暴露一个 `web_tools` + 8 个
57
+ - **采用度与成熟度:这个样本里的后段。** 公开 npm 已是 0.21.0,与这棵树一致;但 GitHub 仓库创建 4 天、0 stars,
58
+ 还缺少独立采用。
59
+ - **工具面的经济性:现在有竞争力。** 0.20.x 只暴露一个 `web_tools` + 8 个
58
60
  action,接近 `dsh-web-search-pro` 的 2 工具 + 20 动作;旧的八个工具名保留为
59
61
  可选兼容模式。
60
62
 
@@ -297,8 +299,8 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
297
299
  *技术补充:代理来源依次是配置里的 `proxy`、环境变量 `DSH_WEB_SEARCH_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `HTTP_PROXY`、macOS 的 `scutil --proxy`;只支持 HTTP 代理(`CONNECT`),不支持 `socks5://`。*
298
300
 
299
301
  14. **所有设置都能在界面上改,不用编辑文件。**
300
- 设置页有 29 个控件,分五组;保存后下一次搜索就生效;只有 `cachePersist` 与 `cacheFile` 这两项要重载插件。
301
- *技术补充:26 个字段全部标了 `.volatile()`,Host 以 live commit 方式原地更新,不重挂载插件;`cacheTtlMs` 与 `cacheEntries` 每次使用都重读;抓取提供方在挂载时取走 `proxy`、`timeoutMs`、`fetchFormat`、`fetchMaxLength`;`renderJs` 与 `renderTimeoutMs` 每次抓取重读;缓存接线也在那时取走 `cachePersist` 与 `cacheFile`。*
302
+ 设置页有 30 个控件,分六组;保存后下一次搜索就生效;只有 `cachePersist` / `cacheFile`(决定缓存接线)和 `toolSurface`(工具注册表在挂载时构建)要重载插件。
303
+ *技术补充:30 个字段全部标了 `.volatile()`,Host 以 live commit 方式原地更新,不重挂载插件;`cacheTtlMs` 与 `cacheEntries` 每次使用都重读;抓取提供方在挂载时取走 `proxy`、`timeoutMs`、`fetchFormat`、`fetchMaxLength`;`renderJs` 与 `renderTimeoutMs` 每次抓取重读;缓存接线也在那时取走 `cachePersist` 与 `cacheFile`。*
302
304
 
303
305
  15. **失败会解释原因,不会静默返回空。**
304
306
  一家都没成功时,报错里会列出「试过哪些引擎、各自为什么失败」。
@@ -386,7 +388,7 @@ URL、摘要和能拿到的日期。兜底结果还会按平台域名过滤,
386
388
 
387
389
  ## 工具面:一个入口,八个动作
388
390
 
389
- 0.20.0 改变了模型看到的工具面。上面的八种能力现在是同一个 `web_tools`
391
+ 0.20.x 改变了模型看到的工具面。上面的八种能力现在是同一个 `web_tools`
390
392
  工具的不同 `action`,不再是八个独立注册。调用长这样:
391
393
 
392
394
  ```json
@@ -421,13 +423,21 @@ URL、摘要和能拿到的日期。兜底结果还会按平台域名过滤,
421
423
  dsh plugin --profile web add @fffangchenghao/dsh-web-search@latest
422
424
  ```
423
425
 
424
- 然后保持 [`dsh-autoupdater`](https://github.com/raomaiping-hash/dsh-self-upgrade)
425
- 或你自己的 profile 更新器开启。它会按计划检查 npm dist-tag,在空闲窗口更新,
426
+ 然后保持 `dsh-autoupdater`(或 `dsh-self-upgrade`)这类 profile
427
+ 更新器开启。它会按计划检查 npm dist-tag,在空闲窗口更新,
426
428
  桌面版提示重启。`link:`/`file:` 安装会被这类更新器主动跳过,因为用 registry
427
429
  包替换本地 checkout 会破坏开发目录。
428
430
 
429
- 设置页会显示 npm 最新版以及是否与当前运行版本不同;这个检查是只读的,不会
430
- 自行安装。
431
+ 设置页会显示 npm 最新版。如果它比当前版本新,且页面在本地,还会显示
432
+ **安装更新**按钮。这个按钮不是自己跑 pnpm,而是调用 DSH 内置的
433
+ `pluginManager`(和 `dsh plugin` 同一条路径)安装精确的 npm 包,然后提示重启。
434
+ 它**不依赖 `dsh-autoupdater`**;它只是手动的,不会定时轮询。远程 Web 页面
435
+ 不显示按钮;`link:`/`file:` 安装会在替换前被拒绝。如果部署没有插件管理器,
436
+ 按钮会明确报错,而不是假装更新成功。
437
+
438
+ 自动更新是用「少一次人工 review」换「更快拿到修复」:更新器会直接安装 registry
439
+ 包,不会等人读 diff。如果你的部署不能接受这个交换,就固定精确版本并关掉
440
+ profile 更新器。插件本身从不 fork/exec `pnpm`;手动按钮只是请 Host 执行安装。
431
441
 
432
442
  ## 安装与启用
433
443
 
@@ -535,7 +545,7 @@ pnpm install
535
545
 
536
546
  三个办法,任选:
537
547
 
538
- 1. **看设置页**:设置 → 「网页搜索(Bing)」,能看到五组、共 29 个控件,说明插件被加载了,schema 也被 Host 收录了。
548
+ 1. **看设置页**:设置 → 「网页搜索(Bing)」,能看到六组、共 30 个控件,说明插件被加载了,schema 也被 Host 收录了。
539
549
  2. **看日志**:启动日志里没有 `1 entry did not activate` 这类警告。
540
550
  3. **直接试**:问一个明显需要联网的问题,比如「帮我搜一下 DSH 插件开发教程,给我链接」。看模型有没有调用 `web_search`,返回的链接是不是真实可达。
541
551
 
@@ -543,7 +553,7 @@ pnpm install
543
553
 
544
554
  ## 设置页怎么用
545
555
 
546
- 打开 设置 → 「网页搜索(Bing)」。页面上一共 29 个控件,按五组排列,外加一个**引擎健康**检查。顶部有一条随滚动固定的跳转栏,点组名直接跳过去;标题下还会拿当前版本和 npm 上的最新版比一下(连不上 npm 时这行不显示,不会瞎猜)。每组只管一类事:
556
+ 打开 设置 → 「网页搜索(Bing)」。页面上一共 30 个控件,按六组排列,外加一个**引擎健康**检查。顶部有一条随滚动固定的跳转栏,点组名直接跳过去;标题下还会拿当前版本和 npm 上的最新版比一下(连不上 npm 时这行不显示,不会瞎猜)。每组只管一类事:
547
557
 
548
558
  | 组 | 控件数 | 这组管什么 |
549
559
  | --- | --- | --- |
@@ -552,6 +562,7 @@ pnpm install
552
562
  | 专用检索 | 3 | `domain_search` 查哪些源、每个源返回几条、每个源等多久 |
553
563
  | 抓取 | 4 | `web_fetch` 返回 Markdown 还是纯文本、最多返回多少字符、要不要用浏览器渲染空壳页面、渲染最多等多久 |
554
564
  | 缓存与冷却 | 6 | 结果记多久、记多少条、要不要写进硬盘、被限流后歇多久 |
565
+ | 模型工具 | 1 | 八种可选能力是统一成一个 `web_tools`,还是保留旧的八个工具名;切换后要重载 |
555
566
 
556
567
  ### 引擎与传输(9 个)
557
568
 
@@ -607,9 +618,15 @@ pnpm install
607
618
  | 被拒后歇多久 | `baseCooldownMs` | `300000` | 被限流后第一次歇多久,5 分钟 |
608
619
  | 歇息上限 | `maxCooldownMs` | `1800000` | 连续失败时冷却翻倍的上限,30 分钟 |
609
620
 
621
+ ### 模型工具(1 个)
622
+
623
+ | 控件 | 配置键 | 默认 | 人话 |
624
+ | --- | --- | --- | --- |
625
+ | 工具面 | `toolSurface` | `unified` | `unified` 只注册一个 `web_tools`,用八个 action;`legacy` 保留旧的八个独立工具名,兼容旧提示词。切换会重建注册表,保存后要重载插件 |
626
+
610
627
  ### 给你的建议
611
628
 
612
- **只想正常用:29 个控件全都别改,默认值就是调过的。**
629
+ **只想正常用:30 个控件全都别改,默认值就是调过的。**
613
630
 
614
631
  只有这些情况值得动:
615
632
 
package/SECURITY.md CHANGED
@@ -136,7 +136,11 @@ than returned as noise; an empty 200 response is an error, not a success.
136
136
 
137
137
  ## What this plugin deliberately does not do
138
138
 
139
- - No telemetry, no analytics, no update check, no remote configuration.
139
+ - No telemetry, no analytics, no remote configuration, and no automatic update
140
+ scheduler. When the local Settings page is opened it asks
141
+ `registry.npmjs.org` for this package's version metadata; **Install update**
142
+ then delegates to the Host's own `pluginManager`. It does not download or
143
+ execute anything from the registry itself.
140
144
  - No reading of the user's files, browser profile, cookies, or session logs.
141
145
  - No modification of the Harness, its shipped plugins, or other plugins' entries.
142
146
  It registers one search provider, one fetch provider, and eight tools
package/client.js CHANGED
@@ -39,6 +39,33 @@
39
39
  var React = require('react');
40
40
  var h = React.createElement;
41
41
 
42
+ /** Compare dotted versions without treating a local build as older. */
43
+ function isNewerVersion(candidate, current) {
44
+ try {
45
+ var a = String(candidate).split('-')[0].split('.').map(function (part) { return Number(part); });
46
+ var b = String(current).split('-')[0].split('.').map(function (part) { return Number(part); });
47
+ var length = Math.max(a.length, b.length);
48
+ for (var i = 0; i < length; i += 1) {
49
+ var left = a[i] === undefined || !isFinite(a[i]) ? 0 : a[i];
50
+ var right = b[i] === undefined || !isFinite(b[i]) ? 0 : b[i];
51
+ if (left !== right) return left > right;
52
+ }
53
+ return String(candidate).indexOf('-') === -1 && String(current).indexOf('-') !== -1;
54
+ } catch (ignored) {
55
+ return false;
56
+ }
57
+ }
58
+
59
+ /** The one-click updater route only exists on the local desktop surface. */
60
+ function isLocalPage() {
61
+ try {
62
+ var host = window.location.hostname;
63
+ return host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '[::1]';
64
+ } catch (ignored) {
65
+ return false;
66
+ }
67
+ }
68
+
42
69
  /** Dictionary namespace owned by this plugin. */
43
70
  var NS = 'webSearchBing';
44
71
  /** The Settings surface slot: one settings page per list entry. */
@@ -47,7 +74,7 @@
47
74
  var ENTRY = 'web-search-bing';
48
75
  var PACKAGE_NAME = 'dsh-web-search-bing';
49
76
  /** Keep in step with package.json; compared with the npm registry. */
50
- var VERSION = '0.20.0';
77
+ var VERSION = '0.21.0';
51
78
  /** Snapshot used while no configuration service is reachable. */
52
79
  var EMPTY_STATE = { status: 'unavailable', value: undefined, base: undefined, user: undefined, revision: undefined, writable: false };
53
80
 
@@ -167,7 +194,15 @@
167
194
  title: '网页搜索(Bing)',
168
195
  jumpTo: '跳到',
169
196
  latest: 'npm 最新版',
170
- autoUpdateHint: '自动更新:用 npm 安装,并保持 profile 更新器(dsh-autoupdater)开启;link:/file: 安装会被跳过,因为替换本地 checkout 会破坏开发目录。',
197
+ autoUpdateHint: '定时自动更新需要 profile 更新器(dsh-autoupdater);「安装更新」按钮不依赖它:它会请 Host 插件管理器安装 npm 包,装完需重启。link:/file: 安装会被拒绝。',
198
+ updateButton: '安装更新',
199
+ updateInstalling: '正在安装…请保持此页打开。',
200
+ updateDone: '更新已安装。',
201
+ updateRestart: '更新已安装;重启 DeepSeek Harness 后生效。',
202
+ updateFailed: '更新失败:',
203
+ updateLocal: '当前是 link:/file: 安装。请先改成 npm 安装,再使用这个按钮。',
204
+ updateRemote: '更新按钮只在本地桌面 App 中可用。',
205
+ updateUnavailable: '当前部署没有内置插件管理器;请用 profile 的包管理器更新。',
171
206
  upToDate: '已是最新',
172
207
  updateAvailable: '有新版本',
173
208
  description: '编辑免密钥搜索提供方:引擎白名单、等待策略、代理、结果上限、排序、缓存、冷却与专用检索源。模型工具:web_search、web_fetch,以及一个统一的 web_tools action 工具(旧版八个工具名可选)。',
@@ -531,6 +566,9 @@
531
566
  var testPair = React.useState({ phase: 'idle', value: null, error: null });
532
567
  var test = testPair[0];
533
568
  var setTest = testPair[1];
569
+ var installPair = React.useState({ phase: 'idle', message: '', version: '' });
570
+ var installation = installPair[0];
571
+ var setInstallation = installPair[1];
534
572
 
535
573
  // Ask the npm registry once per mount. A failure (offline, proxy
536
574
  // down, registry error) hides the line instead of showing an
@@ -556,6 +594,47 @@
556
594
  setErrors({});
557
595
  }, [state.revision]);
558
596
 
597
+ function installUpdate() {
598
+ if (installation.phase === 'working') return;
599
+ setInstallation({ phase: 'working', message: '', version: '' });
600
+ try {
601
+ fetch('/api/dsh-web-search/update', {
602
+ method: 'POST',
603
+ headers: { 'content-type': 'application/json' },
604
+ body: '{}'
605
+ }).then(function (response) {
606
+ return response.json().then(function (body) {
607
+ return { status: response.status, body: body };
608
+ }, function () {
609
+ return { status: response.status, body: null };
610
+ });
611
+ }).then(function (out) {
612
+ var body = out.body;
613
+ if (out.status === 200 && body !== null && body.ok === true) {
614
+ setInstallation({
615
+ phase: body.restartRequired === true ? 'restart' : 'done',
616
+ message: '',
617
+ version: typeof body.version === 'string' ? body.version : ''
618
+ });
619
+ return;
620
+ }
621
+ var code = body === null ? '' : body.code;
622
+ var message = code === 'local-install'
623
+ ? t('updateLocal')
624
+ : code === 'manager-unavailable' || out.status === 404 || out.status === 405
625
+ ? t('updateUnavailable')
626
+ : body !== null && typeof body.message === 'string'
627
+ ? body.message
628
+ : t('updateFailed') + 'HTTP ' + out.status;
629
+ setInstallation({ phase: 'failed', message: message, version: '' });
630
+ }, function (error) {
631
+ setInstallation({ phase: 'failed', message: String(error), version: '' });
632
+ });
633
+ } catch (error) {
634
+ setInstallation({ phase: 'failed', message: String(error), version: '' });
635
+ }
636
+ }
637
+
559
638
  var ready = form !== null && form !== undefined && state.status === 'ready';
560
639
  var values = ready && state.value !== null && typeof state.value === 'object' ? state.value : {};
561
640
  var current = draft === null ? toDraft(values) : draft;
@@ -645,7 +724,7 @@
645
724
  h('p', { key: 'description', style: { margin: 0, fontSize: '13px', lineHeight: 1.5, color: 'var(--dsw-alias-label-tertiary)' } }, t('description'))
646
725
  ];
647
726
  if (latest !== null) {
648
- var newer = latest !== VERSION;
727
+ var newer = isNewerVersion(latest, VERSION);
649
728
  children.push(h('p', {
650
729
  key: 'latest',
651
730
  style: { margin: 0, fontSize: '12px', color: newer ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-label-tertiary)' },
@@ -654,6 +733,43 @@
654
733
  children.push(h('p', {
655
734
  key: 'auto-update', style: { margin: 0, fontSize: '11px', lineHeight: 1.5, color: 'var(--dsw-alias-label-tertiary)' }, role: 'note'
656
735
  }, t('autoUpdateHint')));
736
+ if (newer) {
737
+ if (isLocalPage()) {
738
+ children.push(h('button', {
739
+ key: 'install-update',
740
+ type: 'button',
741
+ disabled: installation.phase === 'working',
742
+ onClick: installUpdate,
743
+ style: {
744
+ alignSelf: 'flex-start',
745
+ padding: '5px 10px',
746
+ borderRadius: '6px',
747
+ border: '1px solid var(--dsw-alias-border-l1)',
748
+ background: 'var(--dsw-alias-bg-base)',
749
+ color: 'var(--dsw-alias-label-primary)',
750
+ cursor: installation.phase === 'working' ? 'wait' : 'pointer',
751
+ fontSize: '12px'
752
+ }
753
+ }, installation.phase === 'working' ? t('updateInstalling') : t('updateButton')));
754
+ } else {
755
+ children.push(h('p', {
756
+ key: 'update-remote', style: { margin: 0, fontSize: '11px', color: 'var(--dsw-alias-label-tertiary)' }
757
+ }, t('updateRemote')));
758
+ }
759
+ }
760
+ if (installation.phase === 'working') {
761
+ children.push(h('p', {
762
+ key: 'update-status', style: { margin: 0, fontSize: '12px', color: 'var(--dsw-alias-label-tertiary)' }, role: 'status', 'aria-live': 'polite'
763
+ }, t('updateInstalling')));
764
+ } else if (installation.phase === 'restart' || installation.phase === 'done') {
765
+ children.push(h('p', {
766
+ key: 'update-status', style: { margin: 0, fontSize: '12px', color: 'var(--dsw-alias-state-success-primary, var(--dsw-alias-label-secondary))' }, role: 'status'
767
+ }, t(installation.phase === 'restart' ? 'updateRestart' : 'updateDone') + (installation.version === '' ? '' : ' (' + installation.version + ')')));
768
+ } else if (installation.phase === 'failed') {
769
+ children.push(h('p', {
770
+ key: 'update-status', style: { margin: 0, fontSize: '12px', color: 'var(--dsw-alias-state-warn-primary)' }, role: 'alert'
771
+ }, t('updateFailed') + installation.message));
772
+ }
657
773
  }
658
774
 
659
775
  if (!ready) {