@fffangchenghao/dsh-web-search 0.12.0 → 0.13.1

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/README.zh-CN.md CHANGED
@@ -5,11 +5,11 @@
5
5
  - [English README](README.md)
6
6
  - [更新日志](CHANGELOG.md) · [设置页为什么不显示:四层判定链](docs/plugin-settings-form.md)
7
7
 
8
- > 当前版本 0.12.0。下面先讲「它跟我有什么关系」,技术细节放在后面的附录。
8
+ > 当前版本 0.13.0。下面先讲「它跟我有什么关系」,技术细节放在后面的附录。
9
9
 
10
10
  ## 一句话说明
11
11
 
12
- 装好这个插件,你在对话里问「上周发布的那版怎么配置」,模型可以自己调用 `web_search` 去公开搜索引擎查,拿回排好序的标题、链接和摘要;摘要不够用时,它还能调用 `web_fetch` 打开其中一条链接,把网页正文整理成 Markdown 读进对话,而不是一整屏 HTML。如果一个问题需要分别查几件事,它可以调用 `search_many`,一次拿回每条查询各自的结果。如果问题问的是某个 npm 包、GitHub 仓库、论文或问答帖,它还可以调用 `domain_search`,直接去那几类专门的数据源里查。
12
+ 装好这个插件,你在对话里问「上周发布的那版怎么配置」,模型可以自己调用 `web_search` 去公开搜索引擎查,拿回排好序的标题、链接和摘要;摘要不够用时,它还能调用 `web_fetch` 打开其中一条链接,把网页正文整理成 Markdown 读进对话,而不是一整屏 HTML。如果一个问题需要分别查几件事,它可以调用 `search_many`,一次拿回每条查询各自的结果。如果问题问的是某个 npm 包、GitHub 仓库、论文或问答帖,它还可以调用 `domain_search`,直接去那几类专门的数据源里查。如果一页正文长到一次读不完,它还可以调用 `read_page`,从上次停下的地方接着读。
13
13
 
14
14
  对你的实际影响就三条:
15
15
 
@@ -17,7 +17,7 @@
17
17
  - 问包、仓库、论文、问答时,模型能直接查对应的数据源,不用拿网页搜索去碰运气。
18
18
  - 你不需要准备搜索 API key,也不需要为搜索单独付费。
19
19
 
20
- 说白了就一句话:它给 Harness 的 `web` 服务插上两个「提供方」——搜索用 `bing`,抓网页用 `http-proxy`;再给模型加两个工具:`domain_search` 专查包、代码仓库、论文、问答和百科,`search_many` 一次跑多条查询。这几个名字后面会反复出现,先混个脸熟就行。
20
+ 说白了就一句话:它给 Harness 的 `web` 服务插上两个「提供方」——搜索用 `bing`,抓网页用 `http-proxy`;再给模型加三个工具:`domain_search` 专查包、代码仓库、论文、问答和百科,`search_many` 一次跑多条查询,`read_page` 把长页面分段接着读。这几个名字后面会反复出现,先混个脸熟就行。
21
21
 
22
22
  ## 它解决什么问题
23
23
 
@@ -44,7 +44,7 @@
44
44
  | 场景 | 没有它 | 有它 |
45
45
  | --- | --- | --- |
46
46
  | 问最近几周才发布的东西 | 只能靠记忆,容易过时 | 现搜现读,能给出处 |
47
- | 你扔给它一条链接说「读一下」 | 直连超时(如 `github.com`)就失败 | 先直连,再走本地代理,还能用 AnySearch 抽取正文 |
47
+ | 你扔给它一条链接说「读一下」 | 直连超时(如 `github.com`)就失败 | 先直连,再走本地代理;自己装了 Playwright 还能交给浏览器渲染,最后才是 AnySearch 抽取正文 |
48
48
  | 搜索结果来源 | 单一后端,取决于凭据 | 最多六个来源交叉验证,去重后排序 |
49
49
  | 中文提问 | 容易返回词典页、百科页 | 中文问题优先用中文来源,英文文档也不会被挤掉 |
50
50
  | 问某个 npm 包、仓库或论文 | 只能拿网页搜索碰,常搜到二手介绍页 | `domain_search` 直接查对应数据源,拿到包名、仓库或论文条目 |
@@ -114,7 +114,32 @@ fetch 拿回来的则是**正文**,不是页面的装修:导航、广告、
114
114
 
115
115
  两个一起用最顺:先用 `domain_search` 找到包或论文,再用 `web_fetch` 打开它的主页或 README 读细节。
116
116
 
117
- 旁边还有一个帮手:**`search_many`**。当一个问题需要分别查好几件事——比如每个候选库各查一次——它一次接住 1–5 条查询,把每条查询的结果分开返回,某一条失败也不会拖垮整批。
117
+ 旁边还有两个帮手:**`search_many`** 和 **`read_page`**。当一个问题需要分别查好几件事——比如每个候选库各查一次——`search_many` 一次接住 1–5 条查询,把每条查询的结果分开返回,某一条失败也不会拖垮整批;`read_page` 则在网页长到一次抓不完时,接着上一次的位置继续往下读。
118
+
119
+ ### 分段读长页(read_page):一次读不完,就接着读
120
+
121
+ `web_fetch` 有两个天生限制:一次只抓一页,而且超过 `fetchMaxLength`(默认 20000 字符)的部分会被截掉。截掉的尾巴不是「读得慢」,是**根本没有下半段**——宿主的抓取请求只有 `url` 一个字段(`WebFetchRequest = { url }`),没有 offset、没有 maxLength,所以宿主工具自己没法从中间接着读。
122
+
123
+ 插件因此自己注册了一个工具 `read_page`,把这个缺口补上。它和 `web_fetch` 走同一套抓取梯队,但多了一个 `offset`:
124
+
125
+ | 参数 | 必填 | 默认 | 意思 |
126
+ | --- | --- | --- | --- |
127
+ | `url` | 是 | — | 要读的绝对地址,只接受 `http` / `https` |
128
+ | `offset` | 否 | `0` | 从第几个字符开始返回,零起始 |
129
+ | `maxLength` | 否 | 设置里的 `fetchMaxLength` | 这一段最多返回多少字符,1000–200000 |
130
+ | `format` | 否 | 设置里的 `fetchFormat` | `markdown` 保留标题、列表、表格和链接;`text` 只留文字 |
131
+
132
+ 用法就一句话:第一次 `offset=0`,看结果里的 `nextOffset`,把它原样传给下一次的 `offset`,直到 `nextOffset` 为 `null`,整页就读完了。每次返回的 `content` 只是这一段正文;「还剩多少字符、下次用哪个 offset」那行提示由工具单独生成,不算在 `content` 里,所以把所有段的 `content` 拼起来,就是逐字符不差的完整正文。
133
+
134
+ 同一页、同一格式的正文会缓存在插件里(最多 8 页,按最久未用淘汰),所以接着读不会每段重新下载整页:第一次抓取之后,后面的段落直接从内存里切片。内部那一次抓取也不按 `fetchMaxLength` 截断;转换后的正文另有 2,000,000 字符的硬上限保护。
135
+
136
+ 边界行为:
137
+
138
+ - `offset` 超过整页长度会直接报错;`offset` 正好等于长度算「已经读完」,返回空内容与 `nextOffset: null`;
139
+ - `truncated` 描述的是**来源**:整页超过 2,000,000 字符(或传输层截断)时才为 `true`,它不代表「还有下一段」——还有没有,看 `nextOffset`;
140
+ - 抓取失败(网络、HTTP 状态、被拦)会以结构化的 `failures` 返回,不会把整次工具调用弄挂。
141
+
142
+ 实测 `https://docs.python.org/3/library/asyncio-task.html`:用 `offset=0` 和 `nextOffset` 连续读,拼起来与一次性抓取的完整正文**逐字符相等**(真实联网,1.3 秒)。
118
143
 
119
144
  ### DeepSeek message 和会话(session)
120
145
 
@@ -162,8 +187,8 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
162
187
  每条都是「人话 + 技术补充」。技术补充可以跳过,不影响使用。
163
188
 
164
189
  1. **同时问好几家搜索引擎。**
165
- 主力四家一起查(AnySearch、DuckDuckGo HTML、Bing 中国站、360);如果四家一条都没给,再让 Bing 国际站和 DuckDuckGo Lite 兜底。一共六个来源。
166
- *技术补充:`HOSTS` 里 `tier: primary` / `fallback` 两档;`viaProxy` 的三家(`ddg-html`、`www.bing`、`ddg-lite`)只在检测到代理时参与。*
190
+ 主力三家一起查(AnySearch、DuckDuckGo HTML、Bing 中国站);如果三家一条都没给,再让 Bing 国际站、360 和 DuckDuckGo Lite 兜底。一共六个来源。
191
+ *技术补充:`HOSTS` 里 `tier: primary` / `fallback` 两档;360 因验证码墙降为 `fallback`;`viaProxy` 的三家(`ddg-html`、`www.bing`、`ddg-lite`)只在检测到代理时参与。*
167
192
 
168
193
  2. **完全不需要 API key。**
169
194
  AnySearch 匿名就能用,国内引擎和 DuckDuckGo 都是抓公开结果页,不需要注册。
@@ -195,40 +220,58 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
195
220
 
196
221
  9. **能把网页正文读回来。**
197
222
  搜索给链接,`web_fetch` 给可读的正文;直连不通时自动换路。
198
- *技术补充:三级梯队——直连(最多 5 秒)→ 本地隧道 → AnySearch 抽取(需要 key);原始响应体最多保留 1 MiB(`1048576` 字节),随后转换(见第 10 条)并按 `fetchMaxLength` 截断。*
223
+ *技术补充:四级梯队——直连(最多 5 秒)→ 本地隧道 → 浏览器渲染(可选,自己装了 Playwright 才启用)→ AnySearch 抽取(需要 key);原始响应体最多保留 1 MiB(`1048576` 字节),随后转换(见第 10 条)并按 `fetchMaxLength` 截断。*
199
224
 
200
225
  10. **抓回来的是整理好的 Markdown,不是原始 HTML。**
201
226
  导航、脚本、页脚、表单会被剔掉;标题、段落、列表、代码块、引用、链接、图片和表格保留,表格转成 Markdown 表格。超过默认 20000 字符的页面,末尾只有一行提示,写明原始长度。
202
- *技术补充:`fetchFormat`(默认 `markdown`,可改 `text`)与 `fetchMaxLength`(默认 `20000`,范围 1000–200000)。实测 `docs.python.org/3/library/urllib.parse.html`:119,614 字符的原始 HTML 转成 40,891 字符的正文 Markdown,工具实际返回 20,080 字符 + 一行截断提示。正文按 `<article>` → `<main>`/`role=main` → 文本最密的容器依次选取;相对链接会补成绝对地址。**不支持续读**:宿主的 `WebFetchRequest` 只有 `url` 一个字段,没有 offset、maxLength、format,所以不能从中间接着读;只能调大 `fetchMaxLength`,或抓更窄的页面。*
227
+ *技术补充:`fetchFormat`(默认 `markdown`,可改 `text`)与 `fetchMaxLength`(默认 `20000`,范围 1000–200000)。实测 `docs.python.org/3/library/urllib.parse.html`:119,614 字符的原始 HTML 转成 40,891 字符的正文 Markdown,工具实际返回 20,080 字符 + 一行截断提示。正文按 `<article>` → `<main>`/`role=main` → 文本最密的容器依次选取;相对链接会补成绝对地址。**`web_fetch` 本身不能续读**:宿主的 `WebFetchRequest` 只有 `url` 一个字段,没有 offset、maxLength、format,所以它只能从头读起;要接着读下半段,用 `read_page`(下一条)。*
228
+
229
+ 11. **一次读不完的长页面,可以分段接着读。**
230
+ 网页超过 `fetchMaxLength` 时,`web_fetch` 只能给前半段;换成 `read_page`,用 `nextOffset` 一段一段接着读,直到读完整页。
231
+ *技术补充:`read_page` 是插件自己注册的工具(宿主的 `WebFetchRequest` 只有 `url`,所以宿主工具无法续读),参数 `url`(必填)、`offset`(默认 0)、`maxLength`(默认取 `fetchMaxLength`,1000–200000)、`format`(`markdown`/`text`,默认取 `fetchFormat`);返回 `url`、`content`、`offset`、`nextOffset`(读完为 `null`)、`totalLength`、`truncated`、`chunk`、`failures`。内部一次抓取不按 `fetchMaxLength` 截断(整页硬上限 2,000,000 字符),再按 offset 切片,所以续读不会重新下载整页;同一 URL、同一格式的正文缓存在插件里(8 页,LRU)。`offset` 超过 `totalLength` 报错,`offset === totalLength` 视为读完;非 http/https 报错;抓取失败走 `failures`。名字被占用时注册为 `web_read_page`;宿主没有 `ctx.tools` 时不注册。实测 `docs.python.org/3/library/asyncio-task.html`:分段拼接与一次性正文逐字符相等(联网,1.3 秒)。*
203
232
 
204
- 11. **受限网络下也能用。**
233
+ 12. **页面只给了个壳时,可以交给真浏览器渲染。**
234
+ 有些页面的 HTML 里只有一个标题和加载脚本,正文要等浏览器把 JavaScript 跑完才出现。装了 Playwright 之后,插件可以自己开一个无头 Chromium,把页面渲染完再读。
235
+ *技术补充:插件**不打包** Playwright,也不把它写进依赖;运行时依次尝试 `import('playwright')`、`import('playwright-core')`,两个都没装就静默跳过,原因写进结果的 `render` 字段,绝不报错。梯队顺序是直连 → 本地隧道 → 浏览器渲染 → AnySearch 抽取;浏览器在本机执行,不要密钥,也不把网址交给第三方,所以排在抽取之前。`renderJs` 三值:`auto`(默认,只在疑似壳页面时渲染)/ `always`(每次都用浏览器)/ `off`(禁用);`renderTimeoutMs` 默认 `15000` 毫秒(1000–120000)。「疑似壳页面」的判定:正文可读字符为 0;或页面是 403/429 但还有内容;或可读字符少于 500;或少于 1200 且带 `__NEXT_DATA__`、`id="root"`、`__NUXT__`、`ng-version` 这类前端框架标记;404 和其他 5xx 不渲染。渲染失败、超时或被中止时,返回前一级梯队已经抓到的内容,整次抓取不会因此失败。安装:`npm i -g playwright && npx playwright install chromium`(或项目内安装),装完**重载插件**才生效;不装完全不影响现有功能。**诚实说明**:本项目开发环境没装 Playwright,所以「渲染后的正文」没有实测数据;已验证的是壳页面能被正确识别、以及没装时静默回退——用 `excalidraw.com` 实测:HTML 6862 字节、可读仅 10 字符、含 `id="root"`,判定为壳页面,因未安装 Playwright 而回退。*
236
+
237
+ 13. **受限网络下也能用。**
205
238
  梯子开着并且设为系统代理时,不用配置任何东西;关掉梯子会自动退回直连,不会因此报错。
206
239
  *技术补充:代理来源依次是配置里的 `proxy`、环境变量 `DSH_WEB_SEARCH_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `HTTP_PROXY`、macOS 的 `scutil --proxy`;只支持 HTTP 代理(`CONNECT`),不支持 `socks5://`。*
207
240
 
208
- 12. **所有设置都能在界面上改,不用编辑文件。**
209
- 设置页有 24 个控件,分五组;保存后下一次搜索就生效;只有 `cachePersist` 与 `cacheFile` 这两项要重载插件。
210
- *技术补充:24 个字段全部标了 `.volatile()`,Host 以 live commit 方式原地更新,不重挂载插件;`cacheTtlMs` 与 `cacheEntries` 每次使用都重读;抓取提供方在挂载时取走 `proxy`、`timeoutMs`、`fetchFormat`、`fetchMaxLength`,缓存接线也在那时取走 `cachePersist` 与 `cacheFile`。*
241
+ 14. **所有设置都能在界面上改,不用编辑文件。**
242
+ 设置页有 26 个控件,分五组;保存后下一次搜索就生效;只有 `cachePersist` 与 `cacheFile` 这两项要重载插件。
243
+ *技术补充:26 个字段全部标了 `.volatile()`,Host 以 live commit 方式原地更新,不重挂载插件;`cacheTtlMs` 与 `cacheEntries` 每次使用都重读;抓取提供方在挂载时取走 `proxy`、`timeoutMs`、`fetchFormat`、`fetchMaxLength`;`renderJs` 与 `renderTimeoutMs` 每次抓取重读;缓存接线也在那时取走 `cachePersist` 与 `cacheFile`。*
211
244
 
212
- 13. **失败会解释原因,不会静默返回空。**
245
+ 15. **失败会解释原因,不会静默返回空。**
213
246
  一家都没成功时,报错里会列出「试过哪些引擎、各自为什么失败」。
214
247
  *技术补充:失败按 `SEARCH_THROTTLED` / `SEARCH_BLOCKED` / `SEARCH_TIMEOUT` / `SEARCH_NETWORK` / `SEARCH_PARSE` / `SEARCH_ABORTED` 分类;失败是返回值,不是异常,只有调用方取消才抛出。*
215
248
 
216
- 14. **包、仓库、论文、问答能直接查。**
249
+ 16. **被验证码挡住时,明确报错,而不是假装没结果。**
250
+ 360 从部分网络会返回验证码页,但 HTTP 状态仍是 200。旧版本把它当成「0 条结果」静默吞掉:引擎等于消失,冷却也没触发。现在这类页面会被识别成失败,360 也降为兜底档。
251
+ *技术补充:`looksLikeBotWall` 在解析前检查 `qcaptcha`、`访问异常`、`unusual traffic`、`verify you are human`、`安全验证` 等标记;命中就返回 `SEARCH_BLOCKED`(可重试、参与冷却),而不是空列表。`so` 的 `tier` 从 `primary` 改为 `fallback`,只在主引擎一条都没给时才尝试,不再拖慢每次搜索。实测单独查该引擎现在返回失败 `so: bot verification page`,而不是 0 条。*
252
+
253
+ 17. **包、仓库、论文、问答能直接查。**
217
254
  问「这个 npm 包还维护吗」「有没有讲 RAG 的论文」时,模型可以用 `domain_search` 直接查八个专门的数据源,而不是拿网页搜索碰运气。
218
255
  *技术补充:八个免密钥源——`github`、`npm`、`pypi`、`arxiv`、`wikipedia`、`hn`(Hacker News)、`stackexchange`、`crates`(crates.io);参数 `query`(必填)、`sources`(可选数组,缺省 = 全部启用的源)、`limit`(可选,默认 5、上限 20)。每个源独立超时(默认 8000 毫秒),单源失败不影响其他源,失败名单从 `failures` 返回。实测 `react`、limit 3 时 github/npm/arxiv/wikipedia/hn/stackexchange/crates 各 3 条、pypi 1 条。已知限制:PyPI 没有公开搜索 API,只按**精确包名**查(取查询的第一个词);Wikipedia 按提问语言只查单一语言(含中日韩字符查 `zh`,否则查 `en`)。宿主没有 `ctx.tools` 服务时,工具不注册,插件其余功能照常。*
219
256
 
220
- 15. **可以只看最近发布的结果。**
257
+ 18. **可以只看最近发布的结果。**
221
258
  设置里选「最近 24 小时 / 7 天 / 30 天 / 1 年」,就只留窗口内发布的结果,适合追新闻和版本更新。
222
259
  *技术补充:`timeRange` 五值 `off`(默认)/ `day` / `week` / `month` / `year`,分别是 24 小时、7 天、30 天、1 年;发布日期从各引擎结果里解析(Bing 的摘要日期与 `news_dt`、360 的「发贴时间」、DuckDuckGo 的时间戳与摘要、AnySearch 正文末尾的 `date:`)。DuckDuckGo 把窗口下推成 `df=d/w/m/y` 参数;Bing 与 360 的参数实测无效(页面显示已选中但结果不变),因此这两家与 AnySearch 走本地过滤。开启后只保留窗口内的**带日期**结果;只有当一条带日期的都没落进窗口时,才退回无日期结果,避免空手而归。*
223
260
 
224
- 16. **一次问好几件事,只占一次调用。**
261
+ 19. **一次问好几件事,只占一次调用。**
225
262
  「比较这三个库」这类问题,模型可以把 1–5 条查询交给 `search_many`,每条查询的结果分开返回;批内最多 3 条同时跑,某一条失败不影响其他条。
226
263
  *技术补充:`queries`(1–5 条,必填)、`limit`(默认 5,1–20)、`withSites`(默认 false,为 true 时每条结果附带域名)。`SEARCH_MANY_CONCURRENCY = 3`。每条查询走与 `web_search` 相同的引擎层、缓存和冷却记录;抛出的失败只记进该条查询的 `failures`,不会中断整批。一次多问用 `search_many`,单问用 `web_search`,查包/论文/问答用 `domain_search`。工具超时 30 秒,声明为可并发。名字被占用时注册为 `web_search_many`;宿主没有 `ctx.tools` 时不注册。*
227
264
 
228
- 17. **缓存能活过重启。**
265
+ 20. **缓存能活过重启。**
229
266
  重启 DSH 后十分钟内再问同一个问题,上次的结果还在,不用重新打扰搜索引擎。
230
267
  *技术补充:`cachePersist`(默认开启 `true`)、`cacheFile`(默认空 = `~/.dsh/cache/dsh-web-search/cache.json`)。只保存摘要(`url` / `title` / `snippet` / `publishedAt`),不保存正文。默认上限 4 MiB,超出按最久未用淘汰,原子写(同目录临时文件 + `rename`);文件损坏、版本不符或读不了都当作空缓存,绝不会因此让插件启动失败。两个进程同时写同一文件是「后写覆盖」,但不会写坏文件。`cacheTtlMs` / `cacheEntries` 改完立即生效,不需要重启。*
231
268
 
269
+ 21. **搜索质量有了可重复的基准。**
270
+ 改排序不再靠感觉:仓库里有一组固定的 20 条查询,每次改完都能跑出同一套分数。
271
+ *技术补充:`bench/` 下 20 条查询(中文 10、英文 10),四类各 5 条(文档 / 版本发布 / 包与库 / 新闻),每条标注 1–3 个期望域名。`node scripts/bench.mjs` 离线读夹具重放,不联网,输出 precision@8、recall@8、MRR@8 与每个引擎的贡献;`--record` 联网重新录制(每条限速 1.5 秒),用于更新夹具;`--json` 输出机器可读结果,便于版本间对比,历史结果存在 `bench/results/`。当前基线(0.13.0):P@8 `0.3625`、R@8 `0.7417`、MRR@8 `0.7600`;中文 `0.3250 / 0.7333 / 0.6700`,英文 `0.4000 / 0.7500 / 0.8500`。对照实验和已知短板见附录。*
272
+
273
+ > **0.13.0 修了什么(一个真实缺陷)**:360(`so`)从部分网络访问会返回验证码页(302 到 qcaptcha 的「访问异常页面」),但 HTTP 状态是 200。旧代码把它当作「0 条结果」静默吞掉:引擎等于消失,冷却也没触发。现在识别到验证码/人机校验页面就报 `SEARCH_BLOCKED` 失败,并把 360 降为**兜底档**(主引擎都空时才尝试),不再拖慢每次搜索。实测:单独查该引擎现在返回失败 `so: bot verification page`,而不是 0 条。
274
+
232
275
  ## 安装与启用
233
276
 
234
277
  ### 你需要什么
@@ -236,6 +279,7 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
236
279
  - 一个带 `web` 服务的 DeepSeek Harness profile;
237
280
  - Node 22.18 以上(源码用了 Node 原生的 TypeScript 类型擦除;本仓库的 CI 跑的是 Node 24);
238
281
  - 能正常出网。没有梯子也能用,只是可用的引擎少一两个。
282
+ - 可选:想读靠 JavaScript 渲染的页面,自己装 Playwright(见能力清单第 12 条);不装不影响任何现有功能。
239
283
 
240
284
  ### 第一步:构建
241
285
 
@@ -305,6 +349,8 @@ pnpm install
305
349
  anysearchApiKey: "" # 留空表示匿名访问
306
350
  anysearchDomain: "" # 或 finance / academic / security / legal / code
307
351
  timeRange: off # off / day / week / month / year
352
+ renderJs: auto # auto / always / off
353
+ renderTimeoutMs: 15000
308
354
  domainLimit: 5 # domain_search 每个源返回几条
309
355
  domainTimeoutMs: 8000
310
356
  ```
@@ -321,7 +367,7 @@ pnpm install
321
367
 
322
368
  三个办法,任选:
323
369
 
324
- 1. **看设置页**:设置 → 「网页搜索(Bing)」,能看到五组、共 24 个控件,说明插件被加载了,schema 也被 Host 收录了。
370
+ 1. **看设置页**:设置 → 「网页搜索(Bing)」,能看到五组、共 26 个控件,说明插件被加载了,schema 也被 Host 收录了。
325
371
  2. **看日志**:启动日志里没有 `1 entry did not activate` 这类警告。
326
372
  3. **直接试**:问一个明显需要联网的问题,比如「帮我搜一下 DSH 插件开发教程,给我链接」。看模型有没有调用 `web_search`,返回的链接是不是真实可达。
327
373
 
@@ -329,14 +375,14 @@ pnpm install
329
375
 
330
376
  ## 设置页怎么用
331
377
 
332
- 打开 设置 → 「网页搜索(Bing)」。页面上一共 24 个控件,按五组排列。每组只管一类事:
378
+ 打开 设置 → 「网页搜索(Bing)」。页面上一共 26 个控件,按五组排列。每组只管一类事:
333
379
 
334
380
  | 组 | 控件数 | 这组管什么 |
335
381
  | --- | --- | --- |
336
382
  | 引擎与传输 | 6 | 用哪些搜索引擎、等多久、走不走代理、AnySearch 的凭据和垂直域 |
337
383
  | 结果与排序 | 7 | 返回几条、只看多久内、怎么合并排序、官方文档和新内容加权多少 |
338
384
  | 专用检索 | 3 | `domain_search` 查哪些源、每个源返回几条、每个源等多久 |
339
- | 抓取 | 2 | `web_fetch` 返回 Markdown 还是纯文本、最多返回多少字符 |
385
+ | 抓取 | 4 | `web_fetch` 返回 Markdown 还是纯文本、最多返回多少字符、要不要用浏览器渲染空壳页面、渲染最多等多久 |
340
386
  | 缓存与冷却 | 6 | 结果记多久、记多少条、要不要写进硬盘、被限流后歇多久 |
341
387
 
342
388
  ### 引擎与传输(6 个)
@@ -370,12 +416,14 @@ pnpm install
370
416
  | 每个源返回几条 | `domainLimit` | `5` | `domain_search` 每个源最多返回几条,1–20 |
371
417
  | 每个源等多久 | `domainTimeoutMs` | `8000` | 单个专用源最多等多久(毫秒),最小 500;网慢可调到 15000 |
372
418
 
373
- ### 抓取(2 个)
419
+ ### 抓取(4 个)
374
420
 
375
421
  | 控件 | 配置键 | 默认 | 人话 |
376
422
  | --- | --- | --- | --- |
377
423
  | 返回格式 | `fetchFormat` | `markdown` | `markdown` 保留标题、列表、表格、链接和代码;`text` 只留文字。阅读场景保持 `markdown`,想更小更朴素再选 `text`。改完立即生效 |
378
424
  | 最多返回多少字符 | `fetchMaxLength` | `20000` | 一次抓取最多返回多少转换后的字符,1000–200000;超出会在末尾注明原始长度。长文档可调到 `50000`。改完立即生效 |
425
+ | JS 渲染 | `renderJs` | `auto` | `auto` 只在页面像空壳时用浏览器;`always` 每次都渲染;`off` 从不渲染。需要自己另装 Playwright,没装就静默跳过、返回原页面。改完立即生效 |
426
+ | 渲染等待上限(毫秒) | `renderTimeoutMs` | `15000` | 一次浏览器渲染最多等多久,1000–120000;页面很重可调到 `30000`。改完立即生效 |
379
427
 
380
428
  ### 缓存与冷却(6 个)
381
429
 
@@ -390,27 +438,29 @@ pnpm install
390
438
 
391
439
  ### 给你的建议
392
440
 
393
- **只想正常用:24 个控件全都别改,默认值就是调过的。**
441
+ **只想正常用:26 个控件全都别改,默认值就是调过的。**
394
442
 
395
443
  只有这些情况值得动:
396
444
 
397
445
  - **代理没被自动探测到**:在 `proxy` 里填上你的本地代理地址,比如 `http://127.0.0.1:7890`。只支持 HTTP 代理,`socks5://` 要换成客户端的 HTTP/mixed 端口。
398
446
  - **你想要 AnySearch 的更高额度或正文抽取**:填 `anysearchApiKey`;想只搜某个垂直领域再填 `anysearchDomain`。
399
447
  - **你只想让 `domain_search` 查某几个源**:把 `domainSources` 收窄成 `github,npm` 这类组合;留空就是八个全开。
400
- - **抓回来的正文断得太早,或只想要纯文字**:把 `fetchMaxLength` 调到 `50000`,或把 `fetchFormat` 改成 `text`。
448
+ - **抓回来的正文断得太早,或只想要纯文字**:把 `fetchMaxLength` 调到 `50000`,或把 `fetchFormat` 改成 `text`;如果调大也不够、要接着读下半段,用 `read_page`(见能力清单第 11 条)。
449
+ - **抓回来是个空壳页面**:先确认正文是不是靠 JavaScript 生成。自己装了 Playwright 就把 `renderJs` 留在 `auto`,重载插件后再试;没装就换一个来源(打印版、静态镜像、站点 API)。调大 `fetchMaxLength` 只对「抓到了但被截断」有用,变不出正文。
450
+ - **浏览器渲染太慢**:把 `renderJs` 改成 `off`,或把 `renderTimeoutMs` 调小。
401
451
  - **不想在硬盘上留缓存文件**:关掉 `cachePersist`,或把 `cacheFile` 指到别处。
402
452
 
403
453
  三个提醒:
404
454
 
405
455
  - 保存是即时的,下一次搜索就按新值走,不用重启——但插件挂载时才读的那几项例外(`fetchFormat`、`fetchMaxLength`、`cachePersist`、`cacheFile`),改它们要重启。
406
456
  - 但**排序类的改动可能被缓存挡住**:缓存键里只有 `lead|wait|limit|引擎集合|时间窗|query`,没有排序参数。同一个问题十分钟内再问,拿到的还是旧顺序——开了持久化后,重启 DSH 也清不掉。换个问法,或者等十分钟。改时间窗会换一个键,所以不受旧缓存影响。
407
- - **正文不能从中间续读**:`web_fetch` 对一个网址只发一次请求,尾巴缺了就把 `fetchMaxLength` 调大,或者抓一个更窄的页面。
457
+ - **`web_fetch` 不能从中间续读**:它对一个网址只发一次请求,尾巴缺了可以调大 `fetchMaxLength`,也可以用 `read_page` 从断点接着读;抓一个更窄的页面仍然最省上下文。
408
458
 
409
459
  ## 常见问题 FAQ
410
460
 
411
461
  ### 需要 API key 吗?
412
462
 
413
- 不需要。搜索默认全部走公开渠道:AnySearch 匿名访问、Bing 和 360 抓结果页、DuckDuckGo 抓 HTML 页。`anysearchApiKey` 是可选的,填了额度更高,也能在 `web_fetch` 直连和隧道都失败时启用第三级「服务端抽取」。
463
+ 不需要。搜索默认全部走公开渠道:AnySearch 匿名访问、Bing 和 360 抓结果页、DuckDuckGo 抓 HTML 页。`anysearchApiKey` 是可选的,填了额度更高,也能在 `web_fetch` 直连和隧道都失败时启用最后一级「服务端抽取」。
414
464
 
415
465
  ### 会不会花我的钱?
416
466
 
@@ -421,26 +471,56 @@ pnpm install
421
471
 
422
472
  ### 会不会把我的搜索内容发给别人?
423
473
 
424
- 会发给本次参与的搜索引擎——这是搜索本身的意思。具体是 `api.anysearch.com`、`cn.bing.com`、`www.so.com`,有代理时还包括 DuckDuckGo 和 Bing 国际站;配了 key 时,抓取失败的页面可能被发给 `api.anysearch.com` 的抽取接口。插件没有自己的服务器,代码里也没有上报使用情况的逻辑。
474
+ 会发给本次参与的搜索引擎——这是搜索本身的意思。具体是 `api.anysearch.com`、`cn.bing.com`、`www.so.com`,有代理时还包括 DuckDuckGo 和 Bing 国际站;配了 key 时,抓取失败的页面可能被发给 `api.anysearch.com` 的抽取接口。插件没有自己的服务器,代码里也没有上报使用情况的逻辑。自己装了 Playwright 时,页面是在本机浏览器里打开的,网址不会交给插件之外的第三方。
425
475
 
426
476
  ### 为什么某个网站抓不到?
427
477
 
428
478
  常见原因有四类:
429
479
 
430
- 1. **站点拒绝自动访问**:回 403 或验证页。直连、隧道都过不去时,只有配了 AnySearch key 才会尝试服务端抽取。
431
- 2. **正文靠 JavaScript 渲染**:抓回来的是空壳 HTML,看不到内容。
480
+ 1. **站点拒绝自动访问**:回 403 或验证页。自己装了 Playwright 且页面还有内容时,`renderJs: auto` 会先试本机浏览器;否则直连、隧道都过不去时,只有配了 AnySearch key 才会尝试服务端抽取。
481
+ 2. **正文靠 JavaScript 渲染**:抓回来的是空壳 HTML,看不到内容。装了 Playwright 后会自动渲染;没装就只能看到壳。
432
482
  3. **要登录或付费**:抓取没有你的登录态。
433
483
  4. **直连超时**:会先在 5 秒内试直连,失败转隧道;两个都不通、又没配 key 时报错,配了 key 还会再试服务端抽取。报错里会写清楚每一级失败的原因。
434
484
 
485
+ 360 的验证码页属于第 1 类,但它以前特别隐蔽:从部分网络访问会 302 到 qcaptcha 的「访问异常页面」,HTTP 状态却是 200。插件现在会把它记成 `SEARCH_BLOCKED`,单独查该引擎会看到 `so: bot verification page`,而不是 0 条;360 也因此降为兜底档。
486
+
435
487
  ### 为什么抓回来的内容和浏览器看到的不一样?
436
488
 
437
489
  因为 `web_fetch` 不是浏览器:
438
490
 
439
491
  - 它只留**正文**,不留页面装修:转换前会剔掉导航、广告、脚本、页脚、表单和隐藏节点;标题、段落、列表、代码、引用、链接、图片和表格保留。
440
- - 它**不执行 JavaScript**:正文靠前端渲染的页面抓回来接近空壳,而浏览器会把它补全。
441
- - 它会**截掉尾巴**:超过 `fetchMaxLength`(默认 20000 字符)的转换后正文,会被一行提示替代,提示里写明原始长度,所以长页面会提前结束。
492
+ - 它**默认不执行 JavaScript**:正文靠前端渲染的页面抓回来接近空壳。自己装了 Playwright 并开启渲染后,这一条不再成立——浏览器会把正文补全;开关、超时和「什么算壳页面」见能力清单第 12 条。
493
+ - 它会**截掉尾巴**:超过 `fetchMaxLength`(默认 20000 字符)的转换后正文,会被一行提示替代,提示里写明原始长度,所以长页面会提前结束。要接着读下半段,用 `read_page`(见下一问)。
494
+
495
+ 如果正文断得太早,先用 `read_page` 接着读(见下一问);也可以把 `fetchMaxLength` 调大(`50000` 是个合适的值)。如果拿回来就是个空壳,先按下面「页面抓回来是空的怎么办?」处理;装不了浏览器就试它的打印版、静态镜像,或者站点自己的 API。
496
+
497
+ ### 网页太长一次读不完怎么办?
498
+
499
+ 用 `read_page`。先照常抓一次(`offset` 省略或写 `0`),结果里会带 `nextOffset`;把它原样传给下一次调用的 `offset`,直到 `nextOffset` 为 `null`。
500
+
501
+ - 只需要某一段:直接给 `offset`,比如从第 40000 个字符开始;
502
+ - 想要更大段:把 `maxLength` 调大(默认取设置里的 `fetchMaxLength`,最多 200000);
503
+ - 想换纯文本:`format: "text"`(默认取设置里的 `fetchFormat`)。
504
+
505
+ `totalLength` 是整页正文长度,`chunk.index` / `chunk.count` 告诉你读到第几段。同一页会缓存,续读不会反复下载;`truncated: true` 只表示来源本身被截断(超过 2,000,000 字符的安全上限,或传输层截断),不代表还有下一段——还有没有,看 `nextOffset`。
506
+
507
+ 如果页面本来就不长,`web_fetch` 一次能读完,不需要 `read_page`。`read_page` 和 `web_fetch` 一样走四级抓取梯队,所以代理、渲染和 AnySearch 抽取的配置照样生效。
508
+
509
+ ### 页面抓回来是空的怎么办?
510
+
511
+ 先判断它是不是「壳页面」——HTML 里只有标题和加载脚本,正文要等 JavaScript 跑完才出现。然后按顺序试:
512
+
513
+ 1. **自己装了 Playwright**(`npm i -g playwright && npx playwright install chromium`):把 `renderJs` 留在 `auto`,重载插件后再抓。插件会识别壳页面,开一个无头 Chromium 把正文渲染出来;`always` 可以强制每次都渲染,`off` 则完全禁用。
514
+ 2. **没装 Playwright**:插件不会自动装,也不会报错;结果里会写明跳过渲染的原因,并返回原来的壳。这时换一个来源(打印版、静态镜像、站点 API),或者把 `fetchMaxLength` 调大——但后者只对「其实抓到了、只是被截断」的情况有用,变不出正文。
515
+ 3. **页面本身要登录或付费**:渲染也救不回来,抓取没有你的登录态。
516
+
517
+ ### 插件会不会偷偷装浏览器?
518
+
519
+ 不会。`package.json` 里没有 Playwright,插件也不会在运行时下载或安装任何东西。只有你自己已经装过 `playwright` 或 `playwright-core`,渲染才会启用;没装就静默跳过,抓取照常返回未渲染的页面,原因写在结果里。装完要**重载插件**,因为加载器会缓存「没装」这个结论。
520
+
521
+ ### 你们怎么知道搜索质量变好了?
442
522
 
443
- 如果正文断得太早,把 `fetchMaxLength` 调大(`50000` 是个合适的值)。如果拿回来就是个空壳,那这页大概需要浏览器——可以试它的打印版、静态镜像,或者站点自己的 API。
523
+ 靠 `bench/` 里的固定查询集,而不是拍脑袋。20 条查询(中文 10、英文 10),文档 / 版本发布 / 包与库 / 新闻四类各 5 条,每条标注 1–3 个期望域名。`node scripts/bench.mjs` 离线重放录好的夹具,输出 P@8 / R@8 / MRR@8。0.13.0 的基线是 **0.3625 / 0.7417 / 0.7600**;中文 0.3250 / 0.7333 / 0.6700,英文 0.4000 / 0.7500 / 0.8500。改排序前后各跑一次,数字是变好还是变坏一目了然。样本只有 20 条,不能当统计显著性;新闻类 recall 只有 0.367,`zh-linux-612` 还是 0 命中——这些短板都写在附录里。
444
524
 
445
525
  ### 为什么搜索结果和我手动搜的不一样?
446
526
 
@@ -580,19 +660,28 @@ score(source) = votes / (rrfConstant + position)
580
660
  - **两个进程**:后写覆盖。可能用较旧的快照盖掉较新的,但不会写出半个文件。
581
661
  - **实时读取**:`cacheTtlMs` 和 `cacheEntries` 是每次使用都调用的函数,设置页改完下一次搜索就生效;`cachePersist` 和 `cacheFile` 在挂载时决定接线,改这两项要重启。
582
662
 
583
- ### web_fetch 的三级梯队
663
+ ### web_fetch 的四级梯队
584
664
 
585
- `web_fetch` 的提供方 `http-proxy` 按顺序试三条路,前一条失败才走下一跳:
665
+ `web_fetch` 的提供方 `http-proxy` 有四条路:前两条是传输,第三条是可选的浏览器渲染,第四条是 AnySearch 抽取。
586
666
 
587
667
  | 级别 | 做什么 | 超时 | 什么时候有用 |
588
668
  | --- | --- | --- | --- |
589
669
  | 1. 直连 | 直接请求目标网址 | 最多 5 秒(`DIRECT_DEADLINE_MS = 5000`) | 网络通畅时最快,也不浪费隧道的往返 |
590
670
  | 2. 本地隧道 | 通过 HTTP `CONNECT` 代理请求 | 用 `timeoutMs`,默认 15 秒 | `github.com`、`html.duckduckgo.com` 这类直连超时的站点 |
591
- | 3. AnySearch 抽取 | `POST https://api.anysearch.com/v1/extract`,服务端渲染后回正文 | 同上,默认 15 秒 | 需要 key。能救回对裸请求回 403 的页面 |
671
+ | 3. 浏览器渲染(可选) | 用 Playwright 开无头 Chromium,执行页面脚本后取回 DOM | 用 `renderTimeoutMs`,默认 15 秒;DOM 就绪后再最多等 2 秒 `networkidle` | 自己装了 Playwright,且页面是壳、或 403/429 但仍带内容。在本机执行,不要 key,不把 URL 交给第三方 |
672
+ | 4. AnySearch 抽取 | `POST https://api.anysearch.com/v1/extract`,服务端渲染后回正文 | 同上,默认 15 秒 | 需要 key。能救回对裸请求回 403 的页面 |
592
673
 
593
674
  直连的截止时间故意比隧道短:被墙的站点通常表现成超时,把整个预算花在一条不可能成功的路上,后面能成功的路就没时间了。
594
675
 
595
- 其他细节:只接受 `http(s)` URL;原始响应体最多保留 `1 MiB`(`1048576` 字节)再做转换,超出截断并标记 `truncated`;非 2xx 是**结果**不是失败(会原样带回状态码和响应体);三级全失败才抛错,错误消息里带每一级的原因。
676
+ 第 3 级不是每次都会跑。`renderJs: auto` 会先判断「这像不像壳页面」:正文可读字符为 0;或页面是 403/429 但还有内容;或可读字符少于 500;或少于 1200 且带 `__NEXT_DATA__`、`id="root"`、`__NUXT__`、`ng-version` 这类前端框架标记。404 和其他 5xx 是错误页,不渲染;非 HTML 正文(JSON、纯文本)也不会被当成壳。`always` 跳过判断、每次抓取都渲染,包括所有传输都失败时单独用浏览器救一次;`off` 完全禁用。
677
+
678
+ Playwright 不在依赖里,也不在启动时导入:抓取提供方在第一次需要渲染时做一次带保护的动态 `import()`,依次尝试 `playwright` 和 `playwright-core`,两个都找不到就静默跳过,把原因写进 `render` 报告。安装用 `npm i -g playwright && npx playwright install chromium`(或项目内安装),装完要重载插件——加载器会把「没装」这个结论缓存到本次挂载结束。
679
+
680
+ 渲染失败、超时或被中止时,抓取不会因此失败:前一级梯队已经拿到的页面会原样返回,原因写进 `render`;只有调用方取消才抛错。配了 AnySearch key 时,渲染失败后仍会先试一次抽取,抽取也失败才回退到之前的页面。
681
+
682
+ **诚实说明**:本项目开发环境没装 Playwright,所以「渲染后的正文」没有实测数据。已验证的是壳页面能被正确识别、以及没装时静默回退——用 `excalidraw.com` 实测:HTML 6862 字节、可读仅 10 字符、含 `id="root"`,判定为壳页面,因未安装 Playwright 而回退。
683
+
684
+ 其他细节:只接受 `http(s)` URL;原始响应体最多保留 `1 MiB`(`1048576` 字节)再做转换,超出截断并标记 `truncated`;非 2xx 是**结果**不是失败(会原样带回状态码和响应体);只有所有传输和抽取都失败、且没有可回退的页面时才抛错,错误消息里带每一级的原因。渲染后的 DOM 走同一套 Markdown 转换,也仍然受 `fetchMaxLength` 约束。
596
685
 
597
686
  ### 从 HTML 到 Markdown
598
687
 
@@ -603,7 +692,7 @@ score(source) = votes / (rrfConstant + position)
603
692
  - 字符预算在**转换之后**才生效:`truncateFetchText` 按 `fetchMaxLength` 切,去掉尾部空白,避免把代理对切成半个,并追加 `[truncated at 20000 chars; original length 40891 chars; the rest is not shown]`。
604
693
  - 实测 `docs.python.org/3/library/urllib.parse.html`:119,614 字符 HTML → 40,891 字符 Markdown → 实际返回 20,080 字符。
605
694
  - 抓取提供方在挂载时取走 `fetchFormat` 和 `fetchMaxLength`,所以这两项在设置页改完要重启;搜索侧的设置每次调用都重读。
606
- - **不支持续读**:宿主的 `WebFetchRequest` 只有 `url` 一个字段,没有 offset、maxLength、format。所以每次抓取都从头开始;唯一的办法是调大 `fetchMaxLength`,或抓更窄的页面。
695
+ - **`web_fetch` 不支持续读**:宿主的 `WebFetchRequest` 只有 `url` 一个字段,没有 offset、maxLength、format,所以每次抓取都从头开始。插件另外注册的 `read_page` 补上了这个缺口(见「read_page 的管道」);不换工具时,办法仍然是调大 `fetchMaxLength`,或抓更窄的页面。
607
696
 
608
697
  ### domain_search 的管道
609
698
 
@@ -640,6 +729,70 @@ search_many 调用
640
729
 
641
730
  配置里的 `limit` 是每条查询的硬上限:调用方可以要得更少,不能要得更多。工具自身超时 30 秒,声明为可并发;`search_many` 被别的插件占用时注册成 `web_search_many`。和 `domain_search` 一样从 `ctx.get('tools')` 取注册表:宿主没有工具注册表就不注册,插件其余功能照常。
642
731
 
732
+ ### read_page 的管道
733
+
734
+ ```
735
+ read_page 调用
736
+ → 读配置(fetchMaxLength / fetchFormat / 抓取相关设置每次调用重读)
737
+ → 校验参数:url 只接受 http/https;offset 默认 0;maxLength 1000–200000;format markdown/text
738
+ → 查插件内的页正文缓存(键:URL + 格式 + 影响抓取的设置;最多 8 页,按最久未用淘汰)
739
+ → 未命中:用与 web_fetch 相同的抓取梯队抓一次并转换
740
+ (内部不按 fetchMaxLength 截断;整页硬上限 2,000,000 字符,超出标记 truncated)
741
+ → 按 offset / maxLength 切片(切点会拆开代理对时回退一个 code unit)
742
+ → 返回 { url, content, offset, nextOffset, totalLength, truncated, chunk, failures }
743
+ ```
744
+
745
+ 参数:`url`(必填)、`offset`(可选,默认 `0`,零起始)、`maxLength`(可选,默认取设置里的 `fetchMaxLength`;该值不合法时回退到 `20000`;范围 1000–200000)、`format`(可选 `markdown` / `text`,默认取 `fetchFormat`)。
746
+
747
+ 返回:`url`、`content`(这一段正文)、`offset`、`nextOffset`(下次该传的 offset;读完为 `null`)、`totalLength`(整页正文长度)、`truncated`(来源本身是否被截断:2,000,000 字符安全上限或传输层截断)、`chunk`(`index` 从 1 开始,`count` 按本次 `maxLength` 估算)、`failures`(抓取失败,形状与 `domain_search` / `search_many` 相同)。
748
+
749
+ 缓存:成功的整页正文按「URL + 输出格式 + 影响抓取的设置」缓存,最多 8 页,按最久未用淘汰;因此一页分几段读也只抓一次,只有换格式或改代理、超时、渲染设置、AnySearch key 才会重新抓。失败不缓存。`content` 里不含「还剩多少字符」那行提示,所以各段 `content` 直接拼接就是完整正文。
750
+
751
+ 边界:`offset` 超过 `totalLength` 直接报错;`offset === totalLength` 视为读完,返回空 `content` 与 `nextOffset: null`;非 http/https 报错;网络、HTTP 状态或拦截失败以 `failures` 返回,不抛给宿主;调用方取消仍然抛出。切片按 JavaScript 字符串的 code unit 计数,切点落在代理对中间时回退一个 code unit,`nextOffset` 跟着回退后的边界走。
752
+
753
+ 注册与降级:宿主没有 `ctx.tools` 时整个工具不注册,`web_search` 和其他功能照常;`read_page` 这个名字已被别的插件占用时,注册为 `web_read_page`;注册表拒绝注册时只写一条警告并跳过。
754
+
755
+ 实测:`https://docs.python.org/3/library/asyncio-task.html`,从 `offset=0` 起按 `nextOffset` 连续读,拼接结果与一次性完整正文逐字符相等(联网,1.3 秒)。测试里对应的一条联网用例默认跳过,设 `READ_PAGE_LIVE=1` 才运行。
756
+
757
+ ### 检索质量基准(bench/)
758
+
759
+ `bench/queries.json` 固定 20 条查询:中文 10、英文 10;文档 / 版本发布 / 包与库 / 新闻四类各 5 条;每条 1–3 个期望域名。`bench/fixtures/<id>.json` 保存各引擎当时的原始列表,评测时按夹具里的 `recordedAt` 重放,所以新鲜度不会随真实时间漂移。
760
+
761
+ | 命令 | 做什么 |
762
+ | --- | --- |
763
+ | `node scripts/bench.mjs` | 离线评测:读夹具、重跑当前排序,输出 P@8 / R@8 / MRR@8、每个引擎的贡献和共识票 |
764
+ | `node scripts/bench.mjs --record` | 联网重录夹具,每条查询间隔 1.5 秒,失败重试一次 |
765
+ | `node scripts/bench.mjs --json` | 机器可读结果,便于版本间对比;历史结果存在 `bench/results/` |
766
+ | `node scripts/bench.mjs --compare <file>` | 与一份旧结果逐项对比 |
767
+ | `node scripts/bench.mjs --rrf 40 --weight anysearch=1 --authority-boost 0` | 不改源码做单变量对照 |
768
+
769
+ 指标:P@8 = 前 8 条里命中期望域名的行数 ÷ 8(固定分母,返回不足 8 条也不放宽);R@8 = 前 8 条覆盖的期望域名 ÷ 全部期望域名;MRR@8 = 第一条命中的排名倒数,20 条取平均,没命中记 0。域名匹配允许「子域命中父域」单向成立:`docs.python.org` 命中期望的 `python.org`,反过来不算。
770
+
771
+ **0.13.0 基线**:
772
+
773
+ | 范围 | P@8 | R@8 | MRR@8 |
774
+ | --- | --- | --- | --- |
775
+ | 全部 20 条 | 0.3625 | 0.7417 | 0.7600 |
776
+ | 中文 10 条 | 0.3250 | 0.7333 | 0.6700 |
777
+ | 英文 10 条 | 0.4000 | 0.7500 | 0.8500 |
778
+
779
+ **对照实验**(同一批夹具,只改一个参数):
780
+
781
+ | 配置 | P@8 | R@8 | MRR@8 |
782
+ | --- | --- | --- | --- |
783
+ | 默认(rrf 60、AnySearch 权重 2) | 0.3625 | 0.7417 | 0.7600 |
784
+ | AnySearch 权重 1 | 0.3875 | 0.7417 | 0.7433 |
785
+ | rrf 40 | 0.3500 | 0.7417 | 0.7767 |
786
+ | rrf 120 | 0.3875 | 0.7417 | 0.7338 |
787
+ | 关掉权威域名(authority 0) | 0.2813 | 0.6917 | 0.6950 |
788
+
789
+ 结论:
790
+
791
+ - 默认 `rrfConstant=60` 的 MRR 是 0.7600,高于 `rrf 120` 的 0.7338。`rrf 40` 的 MRR 更高(0.7767),但 P@8 从 0.3625 掉到 0.3500,R@8 不变——这是拿精度换更靠前的首条命中,所以默认仍保持 60。
792
+ - 权威域名加权明显有效:关掉后 P@8 从 0.3625 掉到 0.2813,R@8 从 0.7417 掉到 0.6917,MRR 从 0.7600 掉到 0.6950;中文整体崩掉,`zh-postgres-logical` 直接 0 命中。
793
+ - AnySearch 权重 2 时它占了 76% 的 top-8 槽位(160 行里 122 行);降到权重 1,P@8 升到 0.3875,但 MRR 掉到 0.7433,偏重与偏轻各有代价。这几组参数的差异只值 1–4 个命中,样本又只有 20 条,所以默认暂时不改。
794
+ - 已知短板:新闻类 recall 只有 0.3667(约 0.367);`zh-linux-612` 0 命中(kernel.org / lwn 被 AWS 文档、菜鸟教程压过);20 条样本没有统计显著性。这些数字用来判断方向,不用来宣布「质量已达标」。
795
+
643
796
  ### 代理
644
797
 
645
798
  Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`——除非进程启动时带了 `NODE_USE_ENV_PROXY=1`,而这个开关在进程跑起来之后打不开。所以需要代理时,插件自己连:发 `CONNECT`、对 `https:` 目标做 TLS 升级、手写请求、自己解析 `Content-Length` / chunked / gzip / deflate / brotli,最多跟 4 次跳转。`307`/`308` 保留方法和请求体,其他 `3xx` 把 `POST` 降级成无 body 的 `GET`。
@@ -648,18 +801,21 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
648
801
 
649
802
  ### 已知限制
650
803
 
651
- - **相关性受上游结果页限制**,整体不如商业搜索 API。免密钥抓取会碰到限流:实测 360 会回 `访问异常页面` 加验证码,另一家国内引擎回 `x5sec` 惩罚页。靠冷却和多引擎互补兜着,但兜不住全部。
804
+ - **相关性受上游结果页限制**,整体不如商业搜索 API。免密钥抓取会碰到限流:实测 360 会回 `访问异常页面` 加验证码,另一家国内引擎回 `x5sec` 惩罚页。现在这类页面会被识别成 `SEARCH_BLOCKED`(不再伪装成 0 条),360 也已降为兜底档;冷却和多引擎互补仍然只是兜底,兜不住全部。
652
805
  - **Google 在本网络下不可达**:走隧道请求 `www.google.com/search` 只回 JS 空壳(94 KB、1–3 个链接),无头 Chrome 被重定向到 `google.com.hk` 并回 reCAPTCHA;`gbv=1`、consent cookie、移动端 UA 都试过,均无效。8 个公共 SearXNG 实例同样不可用(429/403/非 JSON)。
653
806
  - **依赖上游 HTML 结构**。上游改版会让解析失败,此时该引擎记一条原因并让位,不会静默返回空列表。
654
807
  - **结果里只有标题、链接、摘要,没有正文**。正文要 `web_fetch`。
655
- - **抓回来的正文不能从中间续读**:宿主的 `WebFetchRequest` 只有 `url` 一个字段,超过 `fetchMaxLength` 的部分只能靠调大上限或抓更窄的页面。
656
- - **正文提取只保留「像正文」的部分**:纯 JavaScript 渲染的页面抓回来接近空壳,选定正文根之外的内容(比如侧栏里的表格)会跟导航一起丢掉。
808
+ - **`web_fetch` 抓回来的正文不能从中间续读**:宿主的 `WebFetchRequest` 只有 `url` 一个字段,超过 `fetchMaxLength` 的部分要靠 `read_page` 接着读,或调大上限、抓更窄的页面。
809
+ - **`read_page` 一页最多留 2,000,000 字符**:超过的部分会被硬上限截掉并标记 `truncated`;插件内最多缓存 8 页正文,第 9 页会挤掉最久未用的那一页。
810
+ - **正文提取只保留「像正文」的部分**:纯 JavaScript 渲染的页面默认抓回来接近空壳;自己装了 Playwright 并开启 `renderJs` 才会执行脚本。选定正文根之外的内容(比如侧栏里的表格)仍会跟导航一起丢掉。
811
+ - **浏览器渲染没有真实正文的实测数据**:本项目开发环境没装 Playwright;已验证的是壳页面识别、无渲染器时的静默回退,以及用注入的假渲染器跑通的渲染、超时和回退路径(`render-js.test.ts`)。真实站点「渲染后的正文」尚未测量。
812
+ - **基准只有 20 条查询**:新闻类 recall 0.367,`zh-linux-612` 0 命中;参数差异只值 1–4 个命中时不足以区分版本。它用来判断方向,不是统计显著性。
657
813
  - **`search_many` 一次最多 5 条查询,批内最多 3 条并发。**
658
814
  - **两个进程共用一个缓存文件是后写覆盖**:不会写坏文件,但一个进程较新的快照可能被另一个进程较旧的快照盖掉。
659
815
  - **时间窗只能过滤「有日期」的结果**:日期从结果页解析,引擎不给日期时这条就没有年龄信息;窗口内一条带日期的都没有时会退回无日期结果。Bing 与 360 的时间参数实测无效,真正下推的只有 DuckDuckGo 的 `df=`。
660
816
  - **PyPI 只支持精确包名**:它没有公开搜索 API,插件取查询的第一个词当包名;拼错就是空结果。
661
817
  - **Wikipedia 只查单一语言**:含中日韩字符查 `zh`,否则查 `en`。
662
- - **`domain_search` 依赖宿主提供工具注册表**:没有 `ctx.tools` 时它不注册,`web_search` 不受影响。
818
+ - **`domain_search`、`search_many` 和 `read_page` 都依赖宿主提供工具注册表**:没有 `ctx.tools` 时它们不注册,`web_search` 不受影响。
663
819
  - **AnySearch 匿名调用每次最多 10 条。**
664
820
  - **只支持 HTTP 代理**,不支持 `socks5://`。
665
821
  - **`limit` 上限 20;`domainLimit` 上限也是 20。**
@@ -682,6 +838,12 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
682
838
  | 原始响应体上限 | `1048576`(1 MiB) |
683
839
  | 返回格式 `fetchFormat` | `markdown`(或 `text`) |
684
840
  | 单次抓取字符上限 `fetchMaxLength` | `20000`(1000–200000) |
841
+ | `read_page` 分片 `maxLength` | 取 `fetchMaxLength`(默认 `20000`,1000–200000) |
842
+ | `read_page` 起始偏移 `offset` | `0` |
843
+ | `read_page` 单页正文硬上限 | `2000000` 字符 |
844
+ | `read_page` 正文缓存 | 8 页,按最久未用淘汰 |
845
+ | JS 渲染 `renderJs` | `auto`(或 `always` / `off`) |
846
+ | 渲染超时 `renderTimeoutMs` | `15000` 毫秒(1000–120000) |
685
847
  | `search_many` 查询数 / 并发 | 1–5 条 / 3 条 |
686
848
  | `search_many` 条数 `limit` | `5`(1–20) |
687
849
  | RRF 常数 `rrfConstant` | `60` |
@@ -691,14 +853,14 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
691
853
  ### 开发与测试
692
854
 
693
855
  ```sh
694
- node --test test/*.test.ts # 全部测试(283 条)
856
+ node --test test/*.test.ts # 离线测试(349 条,1 条联网用例默认跳过)
695
857
  node --test test/proxy.test.ts # 单个文件
696
858
  npm run typecheck # tsc --noEmit
697
859
  npm run build # 编译 src/ 到 lib/
698
860
  npm run check # typecheck + 测试
699
861
  ```
700
862
 
701
- 测试全程离线,共 283 条:解析器测试回放 `test/fixtures/` 里抓下来的真实响应(含八个专用源的正常/空响应),传输测试不开 socket,代理测试只验 `parseProxy`、`proxyFromEnv` 和纯函数式的响应分帧,时间窗测试用注入的 `now` 固定日期;新增的几组覆盖 Markdown 正文提取(`markdown.test.ts`)、批量查询(`search-many.test.ts`)和硬盘快照(`cache-persist.test.ts`)。
863
+ 测试默认全程离线,349 条中 348 条通过,第 349 条是联网分段验证,默认跳过(`READ_PAGE_LIVE=1` 时才跑):解析器测试回放 `test/fixtures/` 里抓下来的真实响应(含八个专用源的正常/空响应),传输测试不开 socket,代理测试只验 `parseProxy`、`proxyFromEnv` 和纯函数式的响应分帧,时间窗测试用注入的 `now` 固定日期;新增的几组覆盖 Markdown 正文提取(`markdown.test.ts`)、批量查询(`search-many.test.ts`)、分段续读(`read-page.test.ts`)、硬盘快照(`cache-persist.test.ts`)、可选 JS 渲染(`render-js.test.ts`)和基准计分/重放(`bench-metrics.test.ts`、`bench-replay.test.ts`)。其中 `read-page.test.ts` 有一条真实联网用例默认跳过,联网验证时用 `READ_PAGE_LIVE=1 node --test test/read-page.test.ts` 运行。
702
864
 
703
865
  CI(`.github/workflows/ci.yml`)在 Node 24 的 Ubuntu 与 macOS 上跑 `npm ci`、`npm run typecheck`、`npm test`、`npm run build`,并检查构建确实产出了 `lib/index.js` 和 `lib/index.d.ts`,且 `apply` 与 `Config` 都可导入。
704
866
 
@@ -711,6 +873,7 @@ CI(`.github/workflows/ci.yml`)在 Node 24 的 Ubuntu 与 macOS 上跑 `npm c
711
873
  - [docs/architecture.md](docs/architecture.md):模块划分和从 `web` 服务到来源列表的数据流。
712
874
  - [docs/engines.md](docs/engines.md):每个引擎的请求形状、解析怪癖与实测结论。
713
875
  - [docs/troubleshooting.md](docs/troubleshooting.md):没有结果、代理没探测到、提供方没被选中、冷却卡住。
876
+ - [bench/README.md](bench/README.md):20 条查询的检索基准怎么录制夹具、怎么计分、怎么比较版本。
714
877
  - [README.md](README.md):英文版,与中文版逐节对应。
715
878
 
716
879
  MIT © 2026 fangchenghao,见 [LICENSE](LICENSE)。
package/client.js CHANGED
@@ -81,6 +81,13 @@
81
81
  'hint.fetchFormat': 'markdown keeps headings, lists, tables and links; text keeps words only',
82
82
  'field.fetchMaxLength': 'Fetched characters',
83
83
  'hint.fetchMaxLength': 'Characters returned per fetch (1000-200000); the rest is noted as truncated',
84
+ 'field.renderJs': 'JavaScript rendering',
85
+ 'hint.renderJs': 'auto renders only a page that looks like an empty script shell, always renders every page, off never does. Needs Playwright installed separately; without it the page is returned unrendered',
86
+ 'renderJs.auto': 'Auto (only shell pages)',
87
+ 'renderJs.always': 'Always render',
88
+ 'renderJs.off': 'Off',
89
+ 'field.renderTimeoutMs': 'Render wait limit (ms)',
90
+ 'hint.renderTimeoutMs': 'How long one browser render may take (1000-120000); 15000 normally, raise it for heavy pages',
84
91
  'field.limit': 'Results per search',
85
92
  'hint.limit': 'How many results come back, and how they are split across engines',
86
93
  'field.rrfConstant': 'Result blending',
@@ -159,6 +166,13 @@
159
166
  'hint.fetchFormat': 'markdown 保留标题、列表、表格和链接;text 只留纯文字',
160
167
  'field.fetchMaxLength': '抓取字符上限',
161
168
  'hint.fetchMaxLength': '一次抓取最多返回多少字符(1000-200000);超出部分会注明已截断',
169
+ 'field.renderJs': 'JS 渲染',
170
+ 'hint.renderJs': 'auto 只在正文像空壳网页时才用浏览器渲染,always 每次抓取都渲染,off 从不渲染;需另装 Playwright,没装就跳过',
171
+ 'renderJs.auto': '自动(仅空壳页面)',
172
+ 'renderJs.always': '每次都渲染',
173
+ 'renderJs.off': '关闭',
174
+ 'field.renderTimeoutMs': '渲染等待上限(毫秒)',
175
+ 'hint.renderTimeoutMs': '一次浏览器渲染最多等多久(1000-120000);平时 15000,页面很重可调大',
162
176
  'field.limit': '返回几条',
163
177
  'hint.limit': '一次最多返回几条,也决定各引擎分到几条',
164
178
  'field.rrfConstant': '结果混合力度',
@@ -213,6 +227,8 @@
213
227
  { key: 'proxy', group: 'engines', kind: 'text' },
214
228
  { key: 'fetchFormat', group: 'engines', kind: 'select', options: ['markdown', 'text'] },
215
229
  { key: 'fetchMaxLength', group: 'engines', kind: 'number', integer: true, min: 1000, max: 200000 },
230
+ { key: 'renderJs', group: 'engines', kind: 'select', options: ['auto', 'always', 'off'] },
231
+ { key: 'renderTimeoutMs', group: 'engines', kind: 'number', integer: true, min: 1000, max: 120000 },
216
232
  { key: 'anysearchApiKey', group: 'engines', kind: 'text' },
217
233
  { key: 'anysearchDomain', group: 'engines', kind: 'text' },
218
234
  { key: 'limit', group: 'ranking', kind: 'number', integer: true, min: 1, max: 20 },
package/lib/config.d.ts CHANGED
@@ -20,6 +20,7 @@
20
20
  * @module @fangchenghao/dsh-web-search/config
21
21
  */
22
22
  import z from '@deepseek-ai/schemastery';
23
+ import type { RenderMode } from './render.ts';
23
24
  import type { RankOptions, TimeRange, WaitPolicy } from './types.ts';
24
25
  /** Schema of the plugin's configuration section. */
25
26
  export declare const Config: z<Schemastery.ObjectS<NoInfer<{
@@ -27,6 +28,8 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
27
28
  timeoutMs: z<number, number, "volatile-defined">;
28
29
  fetchFormat: z<"markdown" | "text", "markdown" | "text", "volatile-defined">;
29
30
  fetchMaxLength: z<number, number, "volatile-defined">;
31
+ renderJs: z<"off" | "auto" | "always", "off" | "auto" | "always", "volatile-defined">;
32
+ renderTimeoutMs: z<number, number, "volatile-defined">;
30
33
  wait: z<"auto" | "all" | "fast", "auto" | "all" | "fast", "volatile-defined">;
31
34
  proxy: z<string, string, "volatile-defined">;
32
35
  limit: z<number, number, "volatile-defined">;
@@ -52,6 +55,8 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
52
55
  timeoutMs: z<number, number, "volatile-defined">;
53
56
  fetchFormat: z<"markdown" | "text", "markdown" | "text", "volatile-defined">;
54
57
  fetchMaxLength: z<number, number, "volatile-defined">;
58
+ renderJs: z<"off" | "auto" | "always", "off" | "auto" | "always", "volatile-defined">;
59
+ renderTimeoutMs: z<number, number, "volatile-defined">;
55
60
  wait: z<"auto" | "all" | "fast", "auto" | "all" | "fast", "volatile-defined">;
56
61
  proxy: z<string, string, "volatile-defined">;
57
62
  limit: z<number, number, "volatile-defined">;
@@ -104,6 +109,10 @@ export interface ResolvedConfig {
104
109
  fetchFormat: 'markdown' | 'text';
105
110
  /** `web_fetch` character budget. */
106
111
  fetchMaxLength: number;
112
+ /** Browser rendering policy for `web_fetch`. */
113
+ renderJs: RenderMode;
114
+ /** Browser-render deadline in milliseconds. */
115
+ renderTimeoutMs: number;
107
116
  /** Explicit tunnel URL, or `undefined` to detect one. */
108
117
  proxy: string | undefined;
109
118
  /** Caller budget cap. */
package/lib/config.js CHANGED
@@ -42,6 +42,18 @@ export const Config = z.object({
42
42
  .default(DEFAULT_FETCH_MAX_LENGTH)
43
43
  .description('一次抓取最多返回多少个字符(1000-200000);超出会在末尾注明原始长度。想一次多读可调到 50000,日常保持 20000 即可。')
44
44
  .volatile(),
45
+ renderJs: z
46
+ .union(['auto', 'always', 'off'])
47
+ .default('auto')
48
+ .description('脚本渲染页面的处理方式:auto 只在正文像空壳网页时才用浏览器渲染(推荐),always 每次抓取都渲染(更慢),off 从不渲染。需要另外安装 Playwright;没装就静默跳过,不影响抓取。')
49
+ .volatile(),
50
+ renderTimeoutMs: z
51
+ .natural()
52
+ .min(1000)
53
+ .max(120000)
54
+ .default(15000)
55
+ .description('用浏览器渲染一个页面最多等多久(毫秒,1000-120000)。页面很重可加到 30000;平时保持 15000 即可。')
56
+ .volatile(),
45
57
  wait: z
46
58
  .union(['auto', 'all', 'fast'])
47
59
  .default('auto')
@@ -147,6 +159,8 @@ export function resolveConfig(config, callLimit) {
147
159
  timeoutMs: settings.timeoutMs,
148
160
  fetchFormat: settings.fetchFormat,
149
161
  fetchMaxLength: settings.fetchMaxLength,
162
+ renderJs: settings.renderJs,
163
+ renderTimeoutMs: settings.renderTimeoutMs,
150
164
  proxy: proxy.length > 0 ? proxy : undefined,
151
165
  limit,
152
166
  wait: settings.wait,