@fffangchenghao/dsh-web-search 0.11.0 → 0.13.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/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.11.0。下面先讲「它跟我有什么关系」,技术细节放在后面的附录。
8
+ > 当前版本 0.13.0。下面先讲「它跟我有什么关系」,技术细节放在后面的附录。
9
9
 
10
10
  ## 一句话说明
11
11
 
12
- 装好这个插件,你在对话里问「上周发布的那版怎么配置」,模型可以自己调用 `web_search` 去公开搜索引擎查,拿回排好序的标题、链接和摘要;摘要不够用时,它还能调用 `web_fetch` 打开其中一条链接,把网页正文读进对话。如果问题问的是某个 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`,专查包、代码仓库、论文、问答和百科。这几个名字后面会反复出现,先混个脸熟就行。
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` 直接查对应数据源,拿到包名、仓库或论文条目 |
@@ -75,12 +75,12 @@ Agent 就是「会自己决定下一步做什么」的 AI。普通聊天是问
75
75
  这是最容易混的一对。它们解决的是两个不同的问题:
76
76
 
77
77
  - **`web_search`:找网址。** 你给关键词,它给一张清单,每条有标题、链接、一两句摘要。
78
- - **`web_fetch`:读正文。** 你给一个具体网址,它把那一页的内容抓回来。
78
+ - **`web_fetch`:读正文。** 你给一个具体网址,它把那一页的正文抓回来,并整理成可读的 Markdown。
79
79
 
80
80
  | | `web_search` | `web_fetch` |
81
81
  | --- | --- | --- |
82
82
  | 你给它什么 | 一句话关键词 | 一个具体网址(`http://` 或 `https://`) |
83
- | 它给你什么 | 默认 8 条左右的候选:标题 + 链接 + 摘要(开了时间过滤则只留窗口内的) | 那一页的正文(HTML 或纯文本) |
83
+ | 它给你什么 | 默认 8 条左右的候选:标题 + 链接 + 摘要(开了时间过滤则只留窗口内的) | 那一页的正文,整理成 Markdown(或纯文本) |
84
84
  | 能不能直接回答你 | 只能看摘要,常常不够 | 能,正文就在里面 |
85
85
  | 什么时候用 | 不知道去哪找、要比较多个来源 | 已经知道该读哪一页 |
86
86
  | 走哪个提供方 | `bing`(本插件) | `http-proxy`(本插件) |
@@ -94,6 +94,8 @@ Agent 就是「会自己决定下一步做什么」的 AI。普通聊天是问
94
94
 
95
95
  所以两个要配合:先 search 拿到书单,再 fetch 挑中的那本。只 search 不 fetch,模型看到的永远是简介;只 fetch 不 search,模型得先知道网址——而它往往不知道。
96
96
 
97
+ fetch 拿回来的则是**正文**,不是页面的装修:导航、广告、脚本、页脚、表单都会被剔掉,标题、列表、代码和表格以 Markdown 形式留着。
98
+
97
99
  ### 专用检索(domain_search):查的不是网页,是数据源
98
100
 
99
101
  `web_search` 问的是「公开网页上有什么」。`domain_search` 问的是更窄的一件事:「这个包存在吗、这个仓库还维护吗、有没有这篇论文、这个问题有人答过吗」。
@@ -112,6 +114,33 @@ Agent 就是「会自己决定下一步做什么」的 AI。普通聊天是问
112
114
 
113
115
  两个一起用最顺:先用 `domain_search` 找到包或论文,再用 `web_fetch` 打开它的主页或 README 读细节。
114
116
 
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 秒)。
143
+
115
144
  ### DeepSeek message 和会话(session)
116
145
 
117
146
  模型本身没有记忆。每次请求,Harness 都会把**整串消息**重新发给它:系统提示、你之前说的话、模型之前的回答,以及工具的结果。这一串就叫 messages;一次连续的对话存在一个 session(会话)里。
@@ -158,8 +187,8 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
158
187
  每条都是「人话 + 技术补充」。技术补充可以跳过,不影响使用。
159
188
 
160
189
  1. **同时问好几家搜索引擎。**
161
- 主力四家一起查(AnySearch、DuckDuckGo HTML、Bing 中国站、360);如果四家一条都没给,再让 Bing 国际站和 DuckDuckGo Lite 兜底。一共六个来源。
162
- *技术补充:`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`)只在检测到代理时参与。*
163
192
 
164
193
  2. **完全不需要 API key。**
165
194
  AnySearch 匿名就能用,国内引擎和 DuckDuckGo 都是抓公开结果页,不需要注册。
@@ -190,29 +219,59 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
190
219
  *技术补充:`baseCooldownMs: 300000` 起,按连续失败次数翻倍,上限 `maxCooldownMs: 1800000`;对方给了 `Retry-After` 就听对方的;解析失败和主动取消不冷却。*
191
220
 
192
221
  9. **能把网页正文读回来。**
193
- 搜索给链接,`web_fetch` 给正文;直连不通时自动换路。
194
- *技术补充:三级梯队——直连(最多 5 秒)→ 本地隧道 → AnySearch 抽取(需要 key);单页最多保留 1 MiB(`1048576` 字节),超出部分截断并标记。*
222
+ 搜索给链接,`web_fetch` 给可读的正文;直连不通时自动换路。
223
+ *技术补充:四级梯队——直连(最多 5 秒)→ 本地隧道 → 浏览器渲染(可选,自己装了 Playwright 才启用)→ AnySearch 抽取(需要 key);原始响应体最多保留 1 MiB(`1048576` 字节),随后转换(见第 10 条)并按 `fetchMaxLength` 截断。*
224
+
225
+ 10. **抓回来的是整理好的 Markdown,不是原始 HTML。**
226
+ 导航、脚本、页脚、表单会被剔掉;标题、段落、列表、代码块、引用、链接、图片和表格保留,表格转成 Markdown 表格。超过默认 20000 字符的页面,末尾只有一行提示,写明原始长度。
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 秒)。*
195
232
 
196
- 10. **受限网络下也能用。**
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. **受限网络下也能用。**
197
238
  梯子开着并且设为系统代理时,不用配置任何东西;关掉梯子会自动退回直连,不会因此报错。
198
239
  *技术补充:代理来源依次是配置里的 `proxy`、环境变量 `DSH_WEB_SEARCH_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `HTTP_PROXY`、macOS 的 `scutil --proxy`;只支持 HTTP 代理(`CONNECT`),不支持 `socks5://`。*
199
240
 
200
- 11. **所有设置都能在界面上改,不用编辑文件。**
201
- 设置页有 20 个控件,分四组;保存后下一次搜索就生效。
202
- *技术补充:20 个字段全部标了 `.volatile()`,Host 以 live commit 方式原地更新,不重挂载插件。*
241
+ 14. **所有设置都能在界面上改,不用编辑文件。**
242
+ 设置页有 26 个控件,分五组;保存后下一次搜索就生效;只有 `cachePersist` 与 `cacheFile` 这两项要重载插件。
243
+ *技术补充:26 个字段全部标了 `.volatile()`,Host 以 live commit 方式原地更新,不重挂载插件;`cacheTtlMs` 与 `cacheEntries` 每次使用都重读;抓取提供方在挂载时取走 `proxy`、`timeoutMs`、`fetchFormat`、`fetchMaxLength`;`renderJs` 与 `renderTimeoutMs` 每次抓取重读;缓存接线也在那时取走 `cachePersist` 与 `cacheFile`。*
203
244
 
204
- 12. **失败会解释原因,不会静默返回空。**
245
+ 15. **失败会解释原因,不会静默返回空。**
205
246
  一家都没成功时,报错里会列出「试过哪些引擎、各自为什么失败」。
206
247
  *技术补充:失败按 `SEARCH_THROTTLED` / `SEARCH_BLOCKED` / `SEARCH_TIMEOUT` / `SEARCH_NETWORK` / `SEARCH_PARSE` / `SEARCH_ABORTED` 分类;失败是返回值,不是异常,只有调用方取消才抛出。*
207
248
 
208
- 13. **包、仓库、论文、问答能直接查。**
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. **包、仓库、论文、问答能直接查。**
209
254
  问「这个 npm 包还维护吗」「有没有讲 RAG 的论文」时,模型可以用 `domain_search` 直接查八个专门的数据源,而不是拿网页搜索碰运气。
210
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` 服务时,工具不注册,插件其余功能照常。*
211
256
 
212
- 14. **可以只看最近发布的结果。**
257
+ 18. **可以只看最近发布的结果。**
213
258
  设置里选「最近 24 小时 / 7 天 / 30 天 / 1 年」,就只留窗口内发布的结果,适合追新闻和版本更新。
214
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 走本地过滤。开启后只保留窗口内的**带日期**结果;只有当一条带日期的都没落进窗口时,才退回无日期结果,避免空手而归。*
215
260
 
261
+ 19. **一次问好几件事,只占一次调用。**
262
+ 「比较这三个库」这类问题,模型可以把 1–5 条查询交给 `search_many`,每条查询的结果分开返回;批内最多 3 条同时跑,某一条失败不影响其他条。
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` 时不注册。*
264
+
265
+ 20. **缓存能活过重启。**
266
+ 重启 DSH 后十分钟内再问同一个问题,上次的结果还在,不用重新打扰搜索引擎。
267
+ *技术补充:`cachePersist`(默认开启 `true`)、`cacheFile`(默认空 = `~/.dsh/cache/dsh-web-search/cache.json`)。只保存摘要(`url` / `title` / `snippet` / `publishedAt`),不保存正文。默认上限 4 MiB,超出按最久未用淘汰,原子写(同目录临时文件 + `rename`);文件损坏、版本不符或读不了都当作空缓存,绝不会因此让插件启动失败。两个进程同时写同一文件是「后写覆盖」,但不会写坏文件。`cacheTtlMs` / `cacheEntries` 改完立即生效,不需要重启。*
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
+
216
275
  ## 安装与启用
217
276
 
218
277
  ### 你需要什么
@@ -220,6 +279,7 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
220
279
  - 一个带 `web` 服务的 DeepSeek Harness profile;
221
280
  - Node 22.18 以上(源码用了 Node 原生的 TypeScript 类型擦除;本仓库的 CI 跑的是 Node 24);
222
281
  - 能正常出网。没有梯子也能用,只是可用的引擎少一两个。
282
+ - 可选:想读靠 JavaScript 渲染的页面,自己装 Playwright(见能力清单第 12 条);不装不影响任何现有功能。
223
283
 
224
284
  ### 第一步:构建
225
285
 
@@ -289,6 +349,8 @@ pnpm install
289
349
  anysearchApiKey: "" # 留空表示匿名访问
290
350
  anysearchDomain: "" # 或 finance / academic / security / legal / code
291
351
  timeRange: off # off / day / week / month / year
352
+ renderJs: auto # auto / always / off
353
+ renderTimeoutMs: 15000
292
354
  domainLimit: 5 # domain_search 每个源返回几条
293
355
  domainTimeoutMs: 8000
294
356
  ```
@@ -299,13 +361,13 @@ pnpm install
299
361
 
300
362
  改完代码或 profile 配置后,**完全退出 DSH 再打开**(macOS 上不是只关窗口,要从菜单退出,或按 `Cmd+Q`)。原因是模块在每个进程里只求值一次,热改文件不会被已运行的进程看见。
301
363
 
302
- 只改设置页里的值不需要重启,见下一节。
364
+ 设置页里大部分值不需要重启,例外情况见下一节。
303
365
 
304
366
  ### 第五步:确认生效
305
367
 
306
368
  三个办法,任选:
307
369
 
308
- 1. **看设置页**:设置 → 「网页搜索(Bing)」,能看到四组控件,说明插件被加载了,schema 也被 Host 收录了。
370
+ 1. **看设置页**:设置 → 「网页搜索(Bing)」,能看到五组、共 26 个控件,说明插件被加载了,schema 也被 Host 收录了。
309
371
  2. **看日志**:启动日志里没有 `1 entry did not activate` 这类警告。
310
372
  3. **直接试**:问一个明显需要联网的问题,比如「帮我搜一下 DSH 插件开发教程,给我链接」。看模型有没有调用 `web_search`,返回的链接是不是真实可达。
311
373
 
@@ -313,14 +375,15 @@ pnpm install
313
375
 
314
376
  ## 设置页怎么用
315
377
 
316
- 打开 设置 → 「网页搜索(Bing)」。页面上一共 20 个控件,按四组排列。每组只管一类事:
378
+ 打开 设置 → 「网页搜索(Bing)」。页面上一共 26 个控件,按五组排列。每组只管一类事:
317
379
 
318
380
  | 组 | 控件数 | 这组管什么 |
319
381
  | --- | --- | --- |
320
382
  | 引擎与传输 | 6 | 用哪些搜索引擎、等多久、走不走代理、AnySearch 的凭据和垂直域 |
321
383
  | 结果与排序 | 7 | 返回几条、只看多久内、怎么合并排序、官方文档和新内容加权多少 |
322
384
  | 专用检索 | 3 | `domain_search` 查哪些源、每个源返回几条、每个源等多久 |
323
- | 缓存与冷却 | 4 | 结果记多久、记多少条、被限流后歇多久 |
385
+ | 抓取 | 4 | `web_fetch` 返回 Markdown 还是纯文本、最多返回多少字符、要不要用浏览器渲染空壳页面、渲染最多等多久 |
386
+ | 缓存与冷却 | 6 | 结果记多久、记多少条、要不要写进硬盘、被限流后歇多久 |
324
387
 
325
388
  ### 引擎与传输(6 个)
326
389
 
@@ -353,35 +416,51 @@ pnpm install
353
416
  | 每个源返回几条 | `domainLimit` | `5` | `domain_search` 每个源最多返回几条,1–20 |
354
417
  | 每个源等多久 | `domainTimeoutMs` | `8000` | 单个专用源最多等多久(毫秒),最小 500;网慢可调到 15000 |
355
418
 
356
- ### 缓存与冷却(4 个)
419
+ ### 抓取(4 个)
420
+
421
+ | 控件 | 配置键 | 默认 | 人话 |
422
+ | --- | --- | --- | --- |
423
+ | 返回格式 | `fetchFormat` | `markdown` | `markdown` 保留标题、列表、表格、链接和代码;`text` 只留文字。阅读场景保持 `markdown`,想更小更朴素再选 `text`。改完立即生效 |
424
+ | 最多返回多少字符 | `fetchMaxLength` | `20000` | 一次抓取最多返回多少转换后的字符,1000–200000;超出会在末尾注明原始长度。长文档可调到 `50000`。改完立即生效 |
425
+ | JS 渲染 | `renderJs` | `auto` | `auto` 只在页面像空壳时用浏览器;`always` 每次都渲染;`off` 从不渲染。需要自己另装 Playwright,没装就静默跳过、返回原页面。改完立即生效 |
426
+ | 渲染等待上限(毫秒) | `renderTimeoutMs` | `15000` | 一次浏览器渲染最多等多久,1000–120000;页面很重可调到 `30000`。改完立即生效 |
427
+
428
+ ### 缓存与冷却(6 个)
357
429
 
358
430
  | 控件 | 配置键 | 默认 | 人话 |
359
431
  | --- | --- | --- | --- |
360
- | 缓存保留多久 | `cacheTtlMs` | `600000` | 10 分钟;填 `0` 关闭缓存 |
361
- | 缓存条数上限 | `cacheEntries` | `100` | 最多记多少个问题,超出淘汰最久没用的 |
432
+ | 缓存保留多久 | `cacheTtlMs` | `600000` | 10 分钟;填 `0` 关闭缓存。改完下一次搜索就按新值走 |
433
+ | 缓存条数上限 | `cacheEntries` | `100` | 最多记多少个问题,超出淘汰最久没用的。改完下一次搜索就按新值走 |
434
+ | 是否写入硬盘 | `cachePersist` | `true` | 把缓存存成文件,重启后还能命中;不想留痕或磁盘只读时关掉。改完立即生效 |
435
+ | 缓存文件 | `cacheFile` | 空(默认路径) | 快照写到哪;留空用 `~/.dsh/cache/dsh-web-search/cache.json`。插件挂载时读取 |
362
436
  | 被拒后歇多久 | `baseCooldownMs` | `300000` | 被限流后第一次歇多久,5 分钟 |
363
437
  | 歇息上限 | `maxCooldownMs` | `1800000` | 连续失败时冷却翻倍的上限,30 分钟 |
364
438
 
365
439
  ### 给你的建议
366
440
 
367
- **只想正常用:20 个控件全都别改,默认值就是调过的。**
441
+ **只想正常用:26 个控件全都别改,默认值就是调过的。**
368
442
 
369
- 只有三种情况值得动:
443
+ 只有这些情况值得动:
370
444
 
371
445
  - **代理没被自动探测到**:在 `proxy` 里填上你的本地代理地址,比如 `http://127.0.0.1:7890`。只支持 HTTP 代理,`socks5://` 要换成客户端的 HTTP/mixed 端口。
372
446
  - **你想要 AnySearch 的更高额度或正文抽取**:填 `anysearchApiKey`;想只搜某个垂直领域再填 `anysearchDomain`。
373
447
  - **你只想让 `domain_search` 查某几个源**:把 `domainSources` 收窄成 `github,npm` 这类组合;留空就是八个全开。
448
+ - **抓回来的正文断得太早,或只想要纯文字**:把 `fetchMaxLength` 调到 `50000`,或把 `fetchFormat` 改成 `text`;如果调大也不够、要接着读下半段,用 `read_page`(见能力清单第 11 条)。
449
+ - **抓回来是个空壳页面**:先确认正文是不是靠 JavaScript 生成。自己装了 Playwright 就把 `renderJs` 留在 `auto`,重载插件后再试;没装就换一个来源(打印版、静态镜像、站点 API)。调大 `fetchMaxLength` 只对「抓到了但被截断」有用,变不出正文。
450
+ - **浏览器渲染太慢**:把 `renderJs` 改成 `off`,或把 `renderTimeoutMs` 调小。
451
+ - **不想在硬盘上留缓存文件**:关掉 `cachePersist`,或把 `cacheFile` 指到别处。
374
452
 
375
- 两个提醒:
453
+ 三个提醒:
376
454
 
377
- - 保存是即时的,下一次搜索就按新值走,不用重启。
378
- - 但**排序类的改动可能被缓存挡住**:缓存键里只有 `lead|wait|limit|引擎集合|时间窗|query`,没有排序参数。同一个问题十分钟内再问,拿到的还是旧顺序。换个问法,或者等十分钟。改时间窗会换一个键,所以不受旧缓存影响。
455
+ - 保存是即时的,下一次搜索就按新值走,不用重启——但插件挂载时才读的那几项例外(`fetchFormat`、`fetchMaxLength`、`cachePersist`、`cacheFile`),改它们要重启。
456
+ - 但**排序类的改动可能被缓存挡住**:缓存键里只有 `lead|wait|limit|引擎集合|时间窗|query`,没有排序参数。同一个问题十分钟内再问,拿到的还是旧顺序——开了持久化后,重启 DSH 也清不掉。换个问法,或者等十分钟。改时间窗会换一个键,所以不受旧缓存影响。
457
+ - **`web_fetch` 不能从中间续读**:它对一个网址只发一次请求,尾巴缺了可以调大 `fetchMaxLength`,也可以用 `read_page` 从断点接着读;抓一个更窄的页面仍然最省上下文。
379
458
 
380
459
  ## 常见问题 FAQ
381
460
 
382
461
  ### 需要 API key 吗?
383
462
 
384
- 不需要。搜索默认全部走公开渠道:AnySearch 匿名访问、Bing 和 360 抓结果页、DuckDuckGo 抓 HTML 页。`anysearchApiKey` 是可选的,填了额度更高,也能在 `web_fetch` 直连和隧道都失败时启用第三级「服务端抽取」。
463
+ 不需要。搜索默认全部走公开渠道:AnySearch 匿名访问、Bing 和 360 抓结果页、DuckDuckGo 抓 HTML 页。`anysearchApiKey` 是可选的,填了额度更高,也能在 `web_fetch` 直连和隧道都失败时启用最后一级「服务端抽取」。
385
464
 
386
465
  ### 会不会花我的钱?
387
466
 
@@ -392,17 +471,57 @@ pnpm install
392
471
 
393
472
  ### 会不会把我的搜索内容发给别人?
394
473
 
395
- 会发给本次参与的搜索引擎——这是搜索本身的意思。具体是 `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 时,页面是在本机浏览器里打开的,网址不会交给插件之外的第三方。
396
475
 
397
476
  ### 为什么某个网站抓不到?
398
477
 
399
478
  常见原因有四类:
400
479
 
401
- 1. **站点拒绝自动访问**:回 403 或验证页。直连、隧道都过不去时,只有配了 AnySearch key 才会尝试服务端抽取。
402
- 2. **正文靠 JavaScript 渲染**:抓回来的是空壳 HTML,看不到内容。
480
+ 1. **站点拒绝自动访问**:回 403 或验证页。自己装了 Playwright 且页面还有内容时,`renderJs: auto` 会先试本机浏览器;否则直连、隧道都过不去时,只有配了 AnySearch key 才会尝试服务端抽取。
481
+ 2. **正文靠 JavaScript 渲染**:抓回来的是空壳 HTML,看不到内容。装了 Playwright 后会自动渲染;没装就只能看到壳。
403
482
  3. **要登录或付费**:抓取没有你的登录态。
404
483
  4. **直连超时**:会先在 5 秒内试直连,失败转隧道;两个都不通、又没配 key 时报错,配了 key 还会再试服务端抽取。报错里会写清楚每一级失败的原因。
405
484
 
485
+ 360 的验证码页属于第 1 类,但它以前特别隐蔽:从部分网络访问会 302 到 qcaptcha 的「访问异常页面」,HTTP 状态却是 200。插件现在会把它记成 `SEARCH_BLOCKED`,单独查该引擎会看到 `so: bot verification page`,而不是 0 条;360 也因此降为兜底档。
486
+
487
+ ### 为什么抓回来的内容和浏览器看到的不一样?
488
+
489
+ 因为 `web_fetch` 不是浏览器:
490
+
491
+ - 它只留**正文**,不留页面装修:转换前会剔掉导航、广告、脚本、页脚、表单和隐藏节点;标题、段落、列表、代码、引用、链接、图片和表格保留。
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
+ ### 你们怎么知道搜索质量变好了?
522
+
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 命中——这些短板都写在附录里。
524
+
406
525
  ### 为什么搜索结果和我手动搜的不一样?
407
526
 
408
527
  因为这不是同一件事:
@@ -419,6 +538,14 @@ pnpm install
419
538
 
420
539
  唯一的例外是兜底:如果一条**带日期**的结果都没落进窗口,它会退回无日期的结果,免得你空手而归。所以看到的结果条数可能是 0 到 8 条之间,而不是固定的 8 条。
421
540
 
541
+ ### 缓存会不会把旧答案一直给我?
542
+
543
+ 不会。每条缓存在写入 `cacheTtlMs` 之后过期——默认 10 分钟——所以窗口内重复问拿到的是旧答案,下一次就会重新去问引擎。三件事把它关在笼子里:
544
+
545
+ - `cacheTtlMs: 0` 直接关掉缓存;`cacheEntries`(默认 100)限制最多存几条,超出淘汰最久未用的;
546
+ - 硬盘快照只存**摘要**(`url`、`title`、`snippet`、`publishedAt`),不存正文;
547
+ - 过期时间是绝对时间:从硬盘重新载入的条目沿用原截止时间,载入时就把过期条目丢掉,所以重启 DSH 不会给缓存「续命」。
548
+
422
549
  ### `domain_search` 和 `web_search` 该用哪个?
423
550
 
424
551
  看你要找的是**网页**还是**条目**:
@@ -428,11 +555,15 @@ pnpm install
428
555
 
429
556
  两者可以接力:`domain_search` 找到包或论文的条目,再用 `web_fetch` 打开主页或 README 读细节。
430
557
 
558
+ ### 一次问多个问题怎么最快?
559
+
560
+ 用 `search_many`。一次调用带 1–5 条 `queries`,批内 3 条并发,每条查询的结果分开返回;`limit`(默认 5)限制每条查询返回几条,`withSites: true` 会附上每条结果的域名。某条查询失败只变成它自己的 `failures` 一行,不会中断整批。单个问题用 `web_search`;目标是包、仓库、论文或问答时用 `domain_search`。
561
+
431
562
  ### 改了设置为什么没生效?
432
563
 
433
564
  分三种情况:
434
565
 
435
- - **在设置页改的**:保存即生效,但下一次搜索才读新值。如果问的是同一个问题、十分钟内又问了一遍,可能命中了缓存,看起来像没变——换个问法试试。
566
+ - **在设置页改的**:保存即生效,但下一次搜索才读新值——`fetchFormat`、`fetchMaxLength`、`cachePersist` 和 `cacheFile` 例外,它们在插件挂载时读取。如果问的是同一个问题、十分钟内又问了一遍,可能命中了缓存,看起来像没变——换个问法试试;开了持久化后,重启也不会清掉缓存。
436
567
  - **改的是 profile 里的 `cordis.patch.yml`**:需要完全重启 Harness。
437
568
  - **改的是 `src/*.ts`**:需要 `npm run build` 再重启。只改源码不构建,跑的还是 `lib/` 里的旧代码。
438
569
 
@@ -442,7 +573,7 @@ pnpm install
442
573
 
443
574
  - 一次搜索实测 1.4–3.8 秒(英文多等一会儿,中文快一些);命中缓存时几乎瞬间。
444
575
  - 这段时间模型在等工具结果,不是卡死;等不到会按软截止返回已经拿到的部分。
445
- - 真正的成本在上下文:搜索结果和网页正文都会占用模型的输入长度,读的页面越长,这一轮越贵、越容易挤掉别的内容。所以它默认只返回 8 条,单页最多保留 1 MiB。
576
+ - 真正的成本在上下文:搜索结果和网页正文都会占用模型的输入长度,读的页面越长,这一轮越贵、越容易挤掉别的内容。所以它默认只返回 8 条,抓回来的正文先转换、再按 20000 字符截断(原始响应体另外限制在 1 MiB)。
446
577
 
447
578
  ### 为什么模型有时候还是不搜?
448
579
 
@@ -461,13 +592,13 @@ web_search 调用
461
592
  → 按 hosts 白名单过滤;没有代理时丢掉 viaProxy 引擎
462
593
  → 跳过正在冷却的引擎(但绝不会一个都不剩)
463
594
  → 按查询语言决定主导区(ASCII → global,CJK → cn)
464
- → 查缓存(键:lead|wait|limit|排序后的引擎 id|时间窗|归一化 query)
595
+ → 查缓存(先内存、再硬盘快照;键:lead|wait|limit|排序后的引擎 id|时间窗|归一化 query)
465
596
  → primary 档并发请求,达到释放条件即返回
466
597
  → 一条结果都没有时,跑 fallback 档
467
598
  → 各引擎按 timeRange 本地过滤(DuckDuckGo 另有 df 下推)
468
599
  → 按区域融合 + RRF 排序,截到 limit
469
600
  → 合并后再按时间窗收一次(一条带日期的都没落进窗口时退回无日期结果)
470
- → 写入缓存,返回 { sources, failures, proxy }
601
+ → 写入缓存并标记快照待刷新,返回 { sources, failures, proxy }
471
602
  ```
472
603
 
473
604
  一档的释放条件是四者之一:所有引擎都落定;主导区所有引擎都落定(无论成败);已凑够 `limit` 条且贡献者数达标;软截止到点。到点还在跑的引擎会被中止,并在失败列表里记为 `still running at deadline` 或 `aborted once enough results had arrived`。
@@ -518,19 +649,50 @@ score(source) = votes / (rrfConstant + position)
518
649
 
519
650
  **冷却**针对「抓公开结果页被拦」这件事:`SEARCH_THROTTLED`(429)、`SEARCH_BLOCKED`(403、其他 4xx、回显校验不通过)、`SEARCH_TIMEOUT`、`SEARCH_NETWORK` 会让引擎休息;`SEARCH_PARSE`(上游改版,重试没用)和 `SEARCH_ABORTED`(调用方取消)不冷却。时长优先用对方给的 `Retry-After`(秒数或 HTTP 日期,取最后一次跳转的响应头),没有就 `baseCooldownMs × 2^(连续失败次数−1)`,封顶 `maxCooldownMs`。成功一次清零。全都在冷却时仍然照常尝试,不会让引擎集合空掉。
520
651
 
521
- ### web_fetch 的三级梯队
652
+ ### 硬盘上的缓存
653
+
654
+ `cachePersist`(默认 `true`)决定要不要写文件;`cacheFile` 默认空,解析成 `~/.dsh/cache/dsh-web-search/cache.json`(开头的 `~` 会展开)。文档结构是 `{ version: 1, savedAt, entries: [{ key, expiresAt, sources }] }`,每条只带摘要——`url`、`title`、`snippet`、`publishedAt`;源对象上多挂的其他字段在序列化边界丢掉,正文永远不会进文件。
655
+
656
+ - **写**:先写到同目录的临时文件(`<file>.<pid>.<n>.tmp`),再 `rename` 覆盖目标;同一文件系统上是原子操作,rename 之前失败会保留旧文件并删掉临时文件。写入有 2 秒节流,插件卸载和进程退出时也会各刷一次。
657
+ - **读**:文件不存在、读不了、JSON 坏、`version` 不符、单条不合法,一律当成空缓存;读取过程从不抛错,也绝不会让插件挂载失败。
658
+ - **上限**:序列化后的文档按最久未用顺序淘汰,直到不超过 4 MiB(`DEFAULT_CACHE_FILE_MAX_BYTES`);`cacheEntries` 仍然约束内存里的条数。
659
+ - **过期**:`expiresAt` 是绝对时间,从硬盘载入的条目沿用原截止时间;载入时就丢掉过期条目,重启不会给缓存续命。
660
+ - **两个进程**:后写覆盖。可能用较旧的快照盖掉较新的,但不会写出半个文件。
661
+ - **实时读取**:`cacheTtlMs` 和 `cacheEntries` 是每次使用都调用的函数,设置页改完下一次搜索就生效;`cachePersist` 和 `cacheFile` 在挂载时决定接线,改这两项要重启。
522
662
 
523
- `web_fetch` 的提供方 `http-proxy` 按顺序试三条路,前一条失败才走下一跳:
663
+ ### web_fetch 的四级梯队
664
+
665
+ `web_fetch` 的提供方 `http-proxy` 有四条路:前两条是传输,第三条是可选的浏览器渲染,第四条是 AnySearch 抽取。
524
666
 
525
667
  | 级别 | 做什么 | 超时 | 什么时候有用 |
526
668
  | --- | --- | --- | --- |
527
669
  | 1. 直连 | 直接请求目标网址 | 最多 5 秒(`DIRECT_DEADLINE_MS = 5000`) | 网络通畅时最快,也不浪费隧道的往返 |
528
670
  | 2. 本地隧道 | 通过 HTTP `CONNECT` 代理请求 | 用 `timeoutMs`,默认 15 秒 | `github.com`、`html.duckduckgo.com` 这类直连超时的站点 |
529
- | 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 的页面 |
530
673
 
531
674
  直连的截止时间故意比隧道短:被墙的站点通常表现成超时,把整个预算花在一条不可能成功的路上,后面能成功的路就没时间了。
532
675
 
533
- 其他细节:只接受 `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` 约束。
685
+
686
+ ### 从 HTML 到 Markdown
687
+
688
+ 转换不依赖第三方库(`src/markdown.ts`):容错的词法与树构建,因为真实页面不是 XML;一遍剪枝,去掉界面装饰标签、注释和隐藏节点;一遍正文选择,依次偏好 `<article>`、`<main>` / `role=main`、文本最密的容器;最后渲染标题、段落、列表、代码、引用、分割线、链接、图片和表格。
689
+
690
+ - `markdown` 保留语法,`text` 只留文字。实体会解码,相对链接补成绝对地址。
691
+ - 表格转成 Markdown 表格;不在选定正文根里的表格会跟导航一起丢掉。
692
+ - 字符预算在**转换之后**才生效:`truncateFetchText` 按 `fetchMaxLength` 切,去掉尾部空白,避免把代理对切成半个,并追加 `[truncated at 20000 chars; original length 40891 chars; the rest is not shown]`。
693
+ - 实测 `docs.python.org/3/library/urllib.parse.html`:119,614 字符 HTML → 40,891 字符 Markdown → 实际返回 20,080 字符。
694
+ - 抓取提供方在挂载时取走 `fetchFormat` 和 `fetchMaxLength`,所以这两项在设置页改完要重启;搜索侧的设置每次调用都重读。
695
+ - **`web_fetch` 不支持续读**:宿主的 `WebFetchRequest` 只有 `url` 一个字段,没有 offset、maxLength、format,所以每次抓取都从头开始。插件另外注册的 `read_page` 补上了这个缺口(见「read_page 的管道」);不换工具时,办法仍然是调大 `fetchMaxLength`,或抓更窄的页面。
534
696
 
535
697
  ### domain_search 的管道
536
698
 
@@ -553,6 +715,84 @@ domain_search 调用
553
715
 
554
716
  工具注册走宿主真实的工具注册表:用 `ctx.get('tools')` 读取,而不是 `inject`——`inject` 是硬依赖,没有工具服务的部署会连插件都挂不上,`web_search` 也会跟着消失。读不到就不注册 `domain_search`,插件其余功能照常。如果这个名字已被别的插件占用,会改用 `web_domain_search` 注册。
555
717
 
718
+ ### search_many 的管道
719
+
720
+ ```
721
+ search_many 调用
722
+ → queries 1–5 条(必填),limit 缺省 5(取值 1–20),withSites 缺省 false
723
+ → 用 SEARCH_MANY_CONCURRENCY = 3 对查询做 mapLimit
724
+ → 每条查询:与 web_search 相同的引擎层、缓存和冷却记录
725
+ → 抛出的查询变成 { sources: [], failures: [消息] },整批继续
726
+ → 结果保持输入顺序;withSites 时附带小写域名字段 `site`
727
+ → 返回 { results, truncated }
728
+ ```
729
+
730
+ 配置里的 `limit` 是每条查询的硬上限:调用方可以要得更少,不能要得更多。工具自身超时 30 秒,声明为可并发;`search_many` 被别的插件占用时注册成 `web_search_many`。和 `domain_search` 一样从 `ctx.get('tools')` 取注册表:宿主没有工具注册表就不注册,插件其余功能照常。
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 页,按最久未用淘汰;因此一页分几段读也只抓一次,只有换格式或改代理、超时、渲染设置才会重新抓。失败不缓存。`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
+
556
796
  ### 代理
557
797
 
558
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`。
@@ -561,14 +801,21 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
561
801
 
562
802
  ### 已知限制
563
803
 
564
- - **相关性受上游结果页限制**,整体不如商业搜索 API。免密钥抓取会碰到限流:实测 360 会回 `访问异常页面` 加验证码,另一家国内引擎回 `x5sec` 惩罚页。靠冷却和多引擎互补兜着,但兜不住全部。
804
+ - **相关性受上游结果页限制**,整体不如商业搜索 API。免密钥抓取会碰到限流:实测 360 会回 `访问异常页面` 加验证码,另一家国内引擎回 `x5sec` 惩罚页。现在这类页面会被识别成 `SEARCH_BLOCKED`(不再伪装成 0 条),360 也已降为兜底档;冷却和多引擎互补仍然只是兜底,兜不住全部。
565
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)。
566
806
  - **依赖上游 HTML 结构**。上游改版会让解析失败,此时该引擎记一条原因并让位,不会静默返回空列表。
567
807
  - **结果里只有标题、链接、摘要,没有正文**。正文要 `web_fetch`。
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 个命中时不足以区分版本。它用来判断方向,不是统计显著性。
813
+ - **`search_many` 一次最多 5 条查询,批内最多 3 条并发。**
814
+ - **两个进程共用一个缓存文件是后写覆盖**:不会写坏文件,但一个进程较新的快照可能被另一个进程较旧的快照盖掉。
568
815
  - **时间窗只能过滤「有日期」的结果**:日期从结果页解析,引擎不给日期时这条就没有年龄信息;窗口内一条带日期的都没有时会退回无日期结果。Bing 与 360 的时间参数实测无效,真正下推的只有 DuckDuckGo 的 `df=`。
569
816
  - **PyPI 只支持精确包名**:它没有公开搜索 API,插件取查询的第一个词当包名;拼错就是空结果。
570
817
  - **Wikipedia 只查单一语言**:含中日韩字符查 `zh`,否则查 `en`。
571
- - **`domain_search` 依赖宿主提供工具注册表**:没有 `ctx.tools` 时它不注册,`web_search` 不受影响。
818
+ - **`domain_search`、`search_many` 和 `read_page` 都依赖宿主提供工具注册表**:没有 `ctx.tools` 时它们不注册,`web_search` 不受影响。
572
819
  - **AnySearch 匿名调用每次最多 10 条。**
573
820
  - **只支持 HTTP 代理**,不支持 `socks5://`。
574
821
  - **`limit` 上限 20;`domainLimit` 上限也是 20。**
@@ -583,9 +830,22 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
583
830
  | 专用源超时 `domainTimeoutMs` | `8000` 毫秒 |
584
831
  | 缓存有效期 `cacheTtlMs` | `600000` 毫秒 = 600 秒 |
585
832
  | 缓存条数 `cacheEntries` | `100` |
833
+ | 写入硬盘 `cachePersist` | `true` |
834
+ | 缓存文件 `cacheFile` | 空 = `~/.dsh/cache/dsh-web-search/cache.json` |
835
+ | 硬盘缓存上限 | `4194304` 字节 = 4 MiB |
586
836
  | 单引擎超时 `timeoutMs` | `15000` 毫秒 |
587
837
  | `web_fetch` 直连截止 | `5000` 毫秒 |
588
- | 单页字节上限 | `1048576`(1 MiB) |
838
+ | 原始响应体上限 | `1048576`(1 MiB) |
839
+ | 返回格式 `fetchFormat` | `markdown`(或 `text`) |
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) |
847
+ | `search_many` 查询数 / 并发 | 1–5 条 / 3 条 |
848
+ | `search_many` 条数 `limit` | `5`(1–20) |
589
849
  | RRF 常数 `rrfConstant` | `60` |
590
850
  | 基础冷却 `baseCooldownMs` | `300000` 毫秒 = 5 分钟 |
591
851
  | 最大冷却 `maxCooldownMs` | `1800000` 毫秒 = 30 分钟 |
@@ -593,14 +853,14 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
593
853
  ### 开发与测试
594
854
 
595
855
  ```sh
596
- node --test test/*.test.ts # 全部测试(239 条)
856
+ node --test test/*.test.ts # 离线测试(349 条,1 条联网用例默认跳过)
597
857
  node --test test/proxy.test.ts # 单个文件
598
858
  npm run typecheck # tsc --noEmit
599
859
  npm run build # 编译 src/ 到 lib/
600
860
  npm run check # typecheck + 测试
601
861
  ```
602
862
 
603
- 测试全程离线,共 239 条:解析器测试回放 `test/fixtures/` 里抓下来的真实响应(含八个专用源的正常/空响应),传输测试不开 socket,代理测试只验 `parseProxy`、`proxyFromEnv` 和纯函数式的响应分帧,时间窗测试用注入的 `now` 固定日期。
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` 运行。
604
864
 
605
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` 都可导入。
606
866
 
@@ -613,6 +873,7 @@ CI(`.github/workflows/ci.yml`)在 Node 24 的 Ubuntu 与 macOS 上跑 `npm c
613
873
  - [docs/architecture.md](docs/architecture.md):模块划分和从 `web` 服务到来源列表的数据流。
614
874
  - [docs/engines.md](docs/engines.md):每个引擎的请求形状、解析怪癖与实测结论。
615
875
  - [docs/troubleshooting.md](docs/troubleshooting.md):没有结果、代理没探测到、提供方没被选中、冷却卡住。
876
+ - [bench/README.md](bench/README.md):20 条查询的检索基准怎么录制夹具、怎么计分、怎么比较版本。
616
877
  - [README.md](README.md):英文版,与中文版逐节对应。
617
878
 
618
879
  MIT © 2026 fangchenghao,见 [LICENSE](LICENSE)。