@fffangchenghao/dsh-web-search 0.10.0 → 0.12.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 +82 -0
- package/README.md +247 -41
- package/README.zh-CN.md +247 -41
- package/client.js +66 -9
- package/lib/cache-persist.d.ts +96 -0
- package/lib/cache-persist.js +249 -0
- package/lib/cache.d.ts +56 -8
- package/lib/cache.js +141 -13
- package/lib/config.d.ts +33 -1
- package/lib/config.js +54 -2
- package/lib/domain-tool.d.ts +119 -0
- package/lib/domain-tool.js +196 -0
- package/lib/engines.js +68 -10
- package/lib/fetch.d.ts +7 -0
- package/lib/fetch.js +36 -3
- package/lib/freshness.d.ts +102 -0
- package/lib/freshness.js +359 -0
- package/lib/index.d.ts +44 -2
- package/lib/index.js +144 -23
- package/lib/markdown.d.ts +84 -0
- package/lib/markdown.js +847 -0
- package/lib/parsers.js +59 -5
- package/lib/rank.d.ts +14 -1
- package/lib/rank.js +18 -0
- package/lib/search-many.d.ts +117 -0
- package/lib/search-many.js +286 -0
- package/lib/transport.d.ts +4 -2
- package/lib/transport.js +4 -2
- package/lib/types.d.ts +22 -6
- package/lib/verticals.d.ts +164 -0
- package/lib/verticals.js +539 -0
- package/package.json +4 -4
package/README.zh-CN.md
CHANGED
|
@@ -5,18 +5,19 @@
|
|
|
5
5
|
- [English README](README.md)
|
|
6
6
|
- [更新日志](CHANGELOG.md) · [设置页为什么不显示:四层判定链](docs/plugin-settings-form.md)
|
|
7
7
|
|
|
8
|
-
> 当前版本 0.
|
|
8
|
+
> 当前版本 0.12.0。下面先讲「它跟我有什么关系」,技术细节放在后面的附录。
|
|
9
9
|
|
|
10
10
|
## 一句话说明
|
|
11
11
|
|
|
12
|
-
装好这个插件,你在对话里问「上周发布的那版怎么配置」,模型可以自己调用 `web_search` 去公开搜索引擎查,拿回排好序的标题、链接和摘要;摘要不够用时,它还能调用 `web_fetch`
|
|
12
|
+
装好这个插件,你在对话里问「上周发布的那版怎么配置」,模型可以自己调用 `web_search` 去公开搜索引擎查,拿回排好序的标题、链接和摘要;摘要不够用时,它还能调用 `web_fetch` 打开其中一条链接,把网页正文整理成 Markdown 读进对话,而不是一整屏 HTML。如果一个问题需要分别查几件事,它可以调用 `search_many`,一次拿回每条查询各自的结果。如果问题问的是某个 npm 包、GitHub 仓库、论文或问答帖,它还可以调用 `domain_search`,直接去那几类专门的数据源里查。
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
对你的实际影响就三条:
|
|
15
15
|
|
|
16
16
|
- 问题里带「搜一下」「最新」「官网」「文档」时,模型真的有机会去查,而不是回你一句「我的知识截止到某年」。
|
|
17
|
+
- 问包、仓库、论文、问答时,模型能直接查对应的数据源,不用拿网页搜索去碰运气。
|
|
17
18
|
- 你不需要准备搜索 API key,也不需要为搜索单独付费。
|
|
18
19
|
|
|
19
|
-
说白了就一句话:它给 Harness 的 `web` 服务插上两个「提供方」——搜索用 `bing`,抓网页用 `http-proxy
|
|
20
|
+
说白了就一句话:它给 Harness 的 `web` 服务插上两个「提供方」——搜索用 `bing`,抓网页用 `http-proxy`;再给模型加两个工具:`domain_search` 专查包、代码仓库、论文、问答和百科,`search_many` 一次跑多条查询。这几个名字后面会反复出现,先混个脸熟就行。
|
|
20
21
|
|
|
21
22
|
## 它解决什么问题
|
|
22
23
|
|
|
@@ -34,7 +35,7 @@
|
|
|
34
35
|
|
|
35
36
|
**有了这个插件之后**:
|
|
36
37
|
|
|
37
|
-
1. 模型调用 `web_search`,插件同时问几家搜索引擎,把重复的网址去掉,按「是不是多家都排得靠前、是不是官方文档、是否够新」重新排序,返回 8
|
|
38
|
+
1. 模型调用 `web_search`,插件同时问几家搜索引擎,把重复的网址去掉,按「是不是多家都排得靠前、是不是官方文档、是否够新」重新排序,返回 8 条左右的候选(开了时间过滤会少一些,只留窗口内的);
|
|
38
39
|
2. 模型看到某条是 `kubernetes.io` 的文档,调用 `web_fetch` 把这一页的正文读回来;
|
|
39
40
|
3. 它拿着正文回答你,还能顺手把链接给你。
|
|
40
41
|
|
|
@@ -46,6 +47,7 @@
|
|
|
46
47
|
| 你扔给它一条链接说「读一下」 | 直连超时(如 `github.com`)就失败 | 先直连,再走本地代理,还能用 AnySearch 抽取正文 |
|
|
47
48
|
| 搜索结果来源 | 单一后端,取决于凭据 | 最多六个来源交叉验证,去重后排序 |
|
|
48
49
|
| 中文提问 | 容易返回词典页、百科页 | 中文问题优先用中文来源,英文文档也不会被挤掉 |
|
|
50
|
+
| 问某个 npm 包、仓库或论文 | 只能拿网页搜索碰,常搜到二手介绍页 | `domain_search` 直接查对应数据源,拿到包名、仓库或论文条目 |
|
|
49
51
|
| 被搜索引擎限流 | 每次都失败,每次都重试 | 让这家先歇 5–30 分钟,其余照常工作 |
|
|
50
52
|
|
|
51
53
|
### 它不解决什么
|
|
@@ -73,12 +75,12 @@ Agent 就是「会自己决定下一步做什么」的 AI。普通聊天是问
|
|
|
73
75
|
这是最容易混的一对。它们解决的是两个不同的问题:
|
|
74
76
|
|
|
75
77
|
- **`web_search`:找网址。** 你给关键词,它给一张清单,每条有标题、链接、一两句摘要。
|
|
76
|
-
- **`web_fetch`:读正文。**
|
|
78
|
+
- **`web_fetch`:读正文。** 你给一个具体网址,它把那一页的正文抓回来,并整理成可读的 Markdown。
|
|
77
79
|
|
|
78
80
|
| | `web_search` | `web_fetch` |
|
|
79
81
|
| --- | --- | --- |
|
|
80
82
|
| 你给它什么 | 一句话关键词 | 一个具体网址(`http://` 或 `https://`) |
|
|
81
|
-
| 它给你什么 | 8 条左右的候选:标题 + 链接 +
|
|
83
|
+
| 它给你什么 | 默认 8 条左右的候选:标题 + 链接 + 摘要(开了时间过滤则只留窗口内的) | 那一页的正文,整理成 Markdown(或纯文本) |
|
|
82
84
|
| 能不能直接回答你 | 只能看摘要,常常不够 | 能,正文就在里面 |
|
|
83
85
|
| 什么时候用 | 不知道去哪找、要比较多个来源 | 已经知道该读哪一页 |
|
|
84
86
|
| 走哪个提供方 | `bing`(本插件) | `http-proxy`(本插件) |
|
|
@@ -92,6 +94,28 @@ Agent 就是「会自己决定下一步做什么」的 AI。普通聊天是问
|
|
|
92
94
|
|
|
93
95
|
所以两个要配合:先 search 拿到书单,再 fetch 挑中的那本。只 search 不 fetch,模型看到的永远是简介;只 fetch 不 search,模型得先知道网址——而它往往不知道。
|
|
94
96
|
|
|
97
|
+
fetch 拿回来的则是**正文**,不是页面的装修:导航、广告、脚本、页脚、表单都会被剔掉,标题、列表、代码和表格以 Markdown 形式留着。
|
|
98
|
+
|
|
99
|
+
### 专用检索(domain_search):查的不是网页,是数据源
|
|
100
|
+
|
|
101
|
+
`web_search` 问的是「公开网页上有什么」。`domain_search` 问的是更窄的一件事:「这个包存在吗、这个仓库还维护吗、有没有这篇论文、这个问题有人答过吗」。
|
|
102
|
+
|
|
103
|
+
它直接问八家公开数据源:GitHub、npm、PyPI、arXiv、Wikipedia、Hacker News、Stack Exchange、crates.io。每家都提供不用密钥的公开接口,拿回的是结构化条目(标题、链接、摘要),而不是一张搜索结果页。
|
|
104
|
+
|
|
105
|
+
类比:`web_search` 像在街上问路人「这附近哪有五金店」,得到的是各种指路;`domain_search` 像直接走到五金店柜台报型号——问对了店,回答就干脆。
|
|
106
|
+
|
|
107
|
+
| | `web_search` | `domain_search` |
|
|
108
|
+
| --- | --- | --- |
|
|
109
|
+
| 适合问什么 | 概念、新闻、官网、教程 | 包、代码仓库、论文、问答、百科条目 |
|
|
110
|
+
| 数据从哪来 | 公开搜索引擎的结果页 | 八家数据源各自的公开接口 |
|
|
111
|
+
| 一次给几条 | 默认 8 条,跨来源去重排序 | 每个源默认 5 条,按来源交错排 |
|
|
112
|
+
| 要不要 key | 不要 | 不要 |
|
|
113
|
+
| 失败时 | 报错列出每家的原因 | 单源失败只进 `failures`,其余照常 |
|
|
114
|
+
|
|
115
|
+
两个一起用最顺:先用 `domain_search` 找到包或论文,再用 `web_fetch` 打开它的主页或 README 读细节。
|
|
116
|
+
|
|
117
|
+
旁边还有一个帮手:**`search_many`**。当一个问题需要分别查好几件事——比如每个候选库各查一次——它一次接住 1–5 条查询,把每条查询的结果分开返回,某一条失败也不会拖垮整批。
|
|
118
|
+
|
|
95
119
|
### DeepSeek message 和会话(session)
|
|
96
120
|
|
|
97
121
|
模型本身没有记忆。每次请求,Harness 都会把**整串消息**重新发给它:系统提示、你之前说的话、模型之前的回答,以及工具的结果。这一串就叫 messages;一次连续的对话存在一个 session(会话)里。
|
|
@@ -151,7 +175,7 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
|
|
|
151
175
|
|
|
152
176
|
4. **排序不只看排名,还看「是不是官方」和「够不够新」。**
|
|
153
177
|
`kubernetes.io`、`developer.mozilla.org`、`rfc-editor.org` 这类域名会被加权;30 天内发布的内容也会被加权。
|
|
154
|
-
*技术补充:`score = votes / (rrfConstant + position)`,再乘 `1 + authorityBoost` 和新鲜度系数;默认 `rrfConstant: 60`、`authorityBoost: 0.25`、`freshnessBoost: 0.2`、`freshnessDays: 30
|
|
178
|
+
*技术补充:`score = votes / (rrfConstant + position)`,再乘 `1 + authorityBoost` 和新鲜度系数;默认 `rrfConstant: 60`、`authorityBoost: 0.25`、`freshnessBoost: 0.2`、`freshnessDays: 30`。发布日期由各引擎的结果解析而来,所以新鲜度这一项现在按真实日期计算,不再空转。*
|
|
155
179
|
|
|
156
180
|
5. **中英文分开处理。**
|
|
157
181
|
英文问题先看国外来源,中文问题先看中文来源,避免「how to …」被某个中文引擎按单词 `how` 匹配成词典页。
|
|
@@ -163,28 +187,48 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
|
|
|
163
187
|
|
|
164
188
|
7. **同一个问题不重复打扰搜索引擎。**
|
|
165
189
|
十分钟内问同一个问题,直接用上次的结果,几乎瞬间返回。
|
|
166
|
-
*技术补充:TTL + LRU 缓存,`cacheTtlMs: 600000`(10 分钟)、`cacheEntries: 100`;键是 `lead|wait|limit|排序后的引擎 id
|
|
190
|
+
*技术补充:TTL + LRU 缓存,`cacheTtlMs: 600000`(10 分钟)、`cacheEntries: 100`;键是 `lead|wait|limit|排序后的引擎 id|时间窗|归一化 query`,其中时间窗只在非 `off` 时出现,所以默认检索的缓存行为没变。*
|
|
167
191
|
|
|
168
192
|
8. **被限流会自己歇一会儿。**
|
|
169
193
|
某家回了验证页,就先不用它,过几分钟再试,其他家照常。
|
|
170
194
|
*技术补充:`baseCooldownMs: 300000` 起,按连续失败次数翻倍,上限 `maxCooldownMs: 1800000`;对方给了 `Retry-After` 就听对方的;解析失败和主动取消不冷却。*
|
|
171
195
|
|
|
172
196
|
9. **能把网页正文读回来。**
|
|
173
|
-
搜索给链接,`web_fetch`
|
|
174
|
-
*技术补充:三级梯队——直连(最多 5 秒)→ 本地隧道 → AnySearch 抽取(需要 key
|
|
197
|
+
搜索给链接,`web_fetch` 给可读的正文;直连不通时自动换路。
|
|
198
|
+
*技术补充:三级梯队——直连(最多 5 秒)→ 本地隧道 → AnySearch 抽取(需要 key);原始响应体最多保留 1 MiB(`1048576` 字节),随后转换(见第 10 条)并按 `fetchMaxLength` 截断。*
|
|
199
|
+
|
|
200
|
+
10. **抓回来的是整理好的 Markdown,不是原始 HTML。**
|
|
201
|
+
导航、脚本、页脚、表单会被剔掉;标题、段落、列表、代码块、引用、链接、图片和表格保留,表格转成 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`,或抓更窄的页面。*
|
|
175
203
|
|
|
176
|
-
|
|
204
|
+
11. **受限网络下也能用。**
|
|
177
205
|
梯子开着并且设为系统代理时,不用配置任何东西;关掉梯子会自动退回直连,不会因此报错。
|
|
178
206
|
*技术补充:代理来源依次是配置里的 `proxy`、环境变量 `DSH_WEB_SEARCH_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `HTTP_PROXY`、macOS 的 `scutil --proxy`;只支持 HTTP 代理(`CONNECT`),不支持 `socks5://`。*
|
|
179
207
|
|
|
180
|
-
|
|
181
|
-
设置页有
|
|
182
|
-
*技术补充:
|
|
208
|
+
12. **所有设置都能在界面上改,不用编辑文件。**
|
|
209
|
+
设置页有 24 个控件,分五组;保存后下一次搜索就生效;只有 `cachePersist` 与 `cacheFile` 这两项要重载插件。
|
|
210
|
+
*技术补充:24 个字段全部标了 `.volatile()`,Host 以 live commit 方式原地更新,不重挂载插件;`cacheTtlMs` 与 `cacheEntries` 每次使用都重读;抓取提供方在挂载时取走 `proxy`、`timeoutMs`、`fetchFormat`、`fetchMaxLength`,缓存接线也在那时取走 `cachePersist` 与 `cacheFile`。*
|
|
183
211
|
|
|
184
|
-
|
|
212
|
+
13. **失败会解释原因,不会静默返回空。**
|
|
185
213
|
一家都没成功时,报错里会列出「试过哪些引擎、各自为什么失败」。
|
|
186
214
|
*技术补充:失败按 `SEARCH_THROTTLED` / `SEARCH_BLOCKED` / `SEARCH_TIMEOUT` / `SEARCH_NETWORK` / `SEARCH_PARSE` / `SEARCH_ABORTED` 分类;失败是返回值,不是异常,只有调用方取消才抛出。*
|
|
187
215
|
|
|
216
|
+
14. **包、仓库、论文、问答能直接查。**
|
|
217
|
+
问「这个 npm 包还维护吗」「有没有讲 RAG 的论文」时,模型可以用 `domain_search` 直接查八个专门的数据源,而不是拿网页搜索碰运气。
|
|
218
|
+
*技术补充:八个免密钥源——`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
|
+
|
|
220
|
+
15. **可以只看最近发布的结果。**
|
|
221
|
+
设置里选「最近 24 小时 / 7 天 / 30 天 / 1 年」,就只留窗口内发布的结果,适合追新闻和版本更新。
|
|
222
|
+
*技术补充:`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
|
+
|
|
224
|
+
16. **一次问好几件事,只占一次调用。**
|
|
225
|
+
「比较这三个库」这类问题,模型可以把 1–5 条查询交给 `search_many`,每条查询的结果分开返回;批内最多 3 条同时跑,某一条失败不影响其他条。
|
|
226
|
+
*技术补充:`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
|
+
|
|
228
|
+
17. **缓存能活过重启。**
|
|
229
|
+
重启 DSH 后十分钟内再问同一个问题,上次的结果还在,不用重新打扰搜索引擎。
|
|
230
|
+
*技术补充:`cachePersist`(默认开启 `true`)、`cacheFile`(默认空 = `~/.dsh/cache/dsh-web-search/cache.json`)。只保存摘要(`url` / `title` / `snippet` / `publishedAt`),不保存正文。默认上限 4 MiB,超出按最久未用淘汰,原子写(同目录临时文件 + `rename`);文件损坏、版本不符或读不了都当作空缓存,绝不会因此让插件启动失败。两个进程同时写同一文件是「后写覆盖」,但不会写坏文件。`cacheTtlMs` / `cacheEntries` 改完立即生效,不需要重启。*
|
|
231
|
+
|
|
188
232
|
## 安装与启用
|
|
189
233
|
|
|
190
234
|
### 你需要什么
|
|
@@ -260,6 +304,9 @@ pnpm install
|
|
|
260
304
|
proxy: "" # 留空自动探测
|
|
261
305
|
anysearchApiKey: "" # 留空表示匿名访问
|
|
262
306
|
anysearchDomain: "" # 或 finance / academic / security / legal / code
|
|
307
|
+
timeRange: off # off / day / week / month / year
|
|
308
|
+
domainLimit: 5 # domain_search 每个源返回几条
|
|
309
|
+
domainTimeoutMs: 8000
|
|
263
310
|
```
|
|
264
311
|
|
|
265
312
|
**密钥放哪**:放在 profile 的 `cordis.patch.yml` 里,不要放进仓库。仓库里 bundle 的默认配置是空的,这样发布出去不会带上你的凭据。
|
|
@@ -268,13 +315,13 @@ pnpm install
|
|
|
268
315
|
|
|
269
316
|
改完代码或 profile 配置后,**完全退出 DSH 再打开**(macOS 上不是只关窗口,要从菜单退出,或按 `Cmd+Q`)。原因是模块在每个进程里只求值一次,热改文件不会被已运行的进程看见。
|
|
270
317
|
|
|
271
|
-
|
|
318
|
+
设置页里大部分值不需要重启,例外情况见下一节。
|
|
272
319
|
|
|
273
320
|
### 第五步:确认生效
|
|
274
321
|
|
|
275
322
|
三个办法,任选:
|
|
276
323
|
|
|
277
|
-
1. **看设置页**:设置 → 「网页搜索(Bing
|
|
324
|
+
1. **看设置页**:设置 → 「网页搜索(Bing)」,能看到五组、共 24 个控件,说明插件被加载了,schema 也被 Host 收录了。
|
|
278
325
|
2. **看日志**:启动日志里没有 `1 entry did not activate` 这类警告。
|
|
279
326
|
3. **直接试**:问一个明显需要联网的问题,比如「帮我搜一下 DSH 插件开发教程,给我链接」。看模型有没有调用 `web_search`,返回的链接是不是真实可达。
|
|
280
327
|
|
|
@@ -282,13 +329,15 @@ pnpm install
|
|
|
282
329
|
|
|
283
330
|
## 设置页怎么用
|
|
284
331
|
|
|
285
|
-
打开 设置 → 「网页搜索(Bing)」。页面上一共
|
|
332
|
+
打开 设置 → 「网页搜索(Bing)」。页面上一共 24 个控件,按五组排列。每组只管一类事:
|
|
286
333
|
|
|
287
334
|
| 组 | 控件数 | 这组管什么 |
|
|
288
335
|
| --- | --- | --- |
|
|
289
336
|
| 引擎与传输 | 6 | 用哪些搜索引擎、等多久、走不走代理、AnySearch 的凭据和垂直域 |
|
|
290
|
-
| 结果与排序 |
|
|
291
|
-
|
|
|
337
|
+
| 结果与排序 | 7 | 返回几条、只看多久内、怎么合并排序、官方文档和新内容加权多少 |
|
|
338
|
+
| 专用检索 | 3 | `domain_search` 查哪些源、每个源返回几条、每个源等多久 |
|
|
339
|
+
| 抓取 | 2 | `web_fetch` 返回 Markdown 还是纯文本、最多返回多少字符 |
|
|
340
|
+
| 缓存与冷却 | 6 | 结果记多久、记多少条、要不要写进硬盘、被限流后歇多久 |
|
|
292
341
|
|
|
293
342
|
### 引擎与传输(6 个)
|
|
294
343
|
|
|
@@ -301,39 +350,61 @@ pnpm install
|
|
|
301
350
|
| AnySearch 通行证 | `anysearchApiKey` | 空(匿名) | 可选项。只发给 `api.anysearch.com`,用于提高额度、解锁正文抽取 |
|
|
302
351
|
| 专业领域 | `anysearchDomain` | 空(通用) | 常见取值 `finance` / `academic` / `security` / `legal` / `code`,可带子域如 `finance.us_stock` |
|
|
303
352
|
|
|
304
|
-
### 结果与排序(
|
|
353
|
+
### 结果与排序(7 个)
|
|
305
354
|
|
|
306
355
|
| 控件 | 配置键 | 默认 | 人话 |
|
|
307
356
|
| --- | --- | --- | --- |
|
|
308
357
|
| 返回几条 | `limit` | `8` | 最多返回几条,1–20;调用方要得更少时以调用方为准 |
|
|
358
|
+
| 只看多久内 | `timeRange` | `off` | `off` 不限;`day` 最近 24 小时、`week` 7 天、`month` 30 天、`year` 1 年。开了只留窗口内的结果 |
|
|
309
359
|
| 结果混合力度 | `rrfConstant` | `60` | 越大越平均,越小越偏向各引擎的头部结果 |
|
|
310
360
|
| 可信网站名单 | `authorityDomains` | 空(用内置列表) | 在内置的官方文档域名之外,追加你想加权的域名 |
|
|
311
361
|
| 可信网站加分 | `authorityBoost` | `0.25` | 命中可信域名时乘 `1 + 这个值`,0–10 |
|
|
312
362
|
| 新内容加分 | `freshnessBoost` | `0.2` | 新发布内容的加成,0–10;随时间线性衰减到 0 |
|
|
313
363
|
| 多少天内算新 | `freshnessDays` | `30` | 超过这个天数就不再加成 |
|
|
314
364
|
|
|
315
|
-
###
|
|
365
|
+
### 专用检索(3 个)
|
|
316
366
|
|
|
317
367
|
| 控件 | 配置键 | 默认 | 人话 |
|
|
318
368
|
| --- | --- | --- | --- |
|
|
319
|
-
|
|
|
320
|
-
|
|
|
369
|
+
| 查哪些专用源 | `domainSources` | 八个全开 | `github`、`npm`、`pypi`、`arxiv`、`wikipedia`、`hn`、`stackexchange`、`crates` 里只留几个,逗号分隔;留空表示全开 |
|
|
370
|
+
| 每个源返回几条 | `domainLimit` | `5` | `domain_search` 每个源最多返回几条,1–20 |
|
|
371
|
+
| 每个源等多久 | `domainTimeoutMs` | `8000` | 单个专用源最多等多久(毫秒),最小 500;网慢可调到 15000 |
|
|
372
|
+
|
|
373
|
+
### 抓取(2 个)
|
|
374
|
+
|
|
375
|
+
| 控件 | 配置键 | 默认 | 人话 |
|
|
376
|
+
| --- | --- | --- | --- |
|
|
377
|
+
| 返回格式 | `fetchFormat` | `markdown` | `markdown` 保留标题、列表、表格、链接和代码;`text` 只留文字。阅读场景保持 `markdown`,想更小更朴素再选 `text`。改完立即生效 |
|
|
378
|
+
| 最多返回多少字符 | `fetchMaxLength` | `20000` | 一次抓取最多返回多少转换后的字符,1000–200000;超出会在末尾注明原始长度。长文档可调到 `50000`。改完立即生效 |
|
|
379
|
+
|
|
380
|
+
### 缓存与冷却(6 个)
|
|
381
|
+
|
|
382
|
+
| 控件 | 配置键 | 默认 | 人话 |
|
|
383
|
+
| --- | --- | --- | --- |
|
|
384
|
+
| 缓存保留多久 | `cacheTtlMs` | `600000` | 10 分钟;填 `0` 关闭缓存。改完下一次搜索就按新值走 |
|
|
385
|
+
| 缓存条数上限 | `cacheEntries` | `100` | 最多记多少个问题,超出淘汰最久没用的。改完下一次搜索就按新值走 |
|
|
386
|
+
| 是否写入硬盘 | `cachePersist` | `true` | 把缓存存成文件,重启后还能命中;不想留痕或磁盘只读时关掉。改完立即生效 |
|
|
387
|
+
| 缓存文件 | `cacheFile` | 空(默认路径) | 快照写到哪;留空用 `~/.dsh/cache/dsh-web-search/cache.json`。插件挂载时读取 |
|
|
321
388
|
| 被拒后歇多久 | `baseCooldownMs` | `300000` | 被限流后第一次歇多久,5 分钟 |
|
|
322
389
|
| 歇息上限 | `maxCooldownMs` | `1800000` | 连续失败时冷却翻倍的上限,30 分钟 |
|
|
323
390
|
|
|
324
391
|
### 给你的建议
|
|
325
392
|
|
|
326
|
-
**只想正常用:
|
|
393
|
+
**只想正常用:24 个控件全都别改,默认值就是调过的。**
|
|
327
394
|
|
|
328
|
-
|
|
395
|
+
只有这些情况值得动:
|
|
329
396
|
|
|
330
397
|
- **代理没被自动探测到**:在 `proxy` 里填上你的本地代理地址,比如 `http://127.0.0.1:7890`。只支持 HTTP 代理,`socks5://` 要换成客户端的 HTTP/mixed 端口。
|
|
331
398
|
- **你想要 AnySearch 的更高额度或正文抽取**:填 `anysearchApiKey`;想只搜某个垂直领域再填 `anysearchDomain`。
|
|
399
|
+
- **你只想让 `domain_search` 查某几个源**:把 `domainSources` 收窄成 `github,npm` 这类组合;留空就是八个全开。
|
|
400
|
+
- **抓回来的正文断得太早,或只想要纯文字**:把 `fetchMaxLength` 调到 `50000`,或把 `fetchFormat` 改成 `text`。
|
|
401
|
+
- **不想在硬盘上留缓存文件**:关掉 `cachePersist`,或把 `cacheFile` 指到别处。
|
|
332
402
|
|
|
333
|
-
|
|
403
|
+
三个提醒:
|
|
334
404
|
|
|
335
|
-
-
|
|
336
|
-
- 但**排序类的改动可能被缓存挡住**:缓存键里只有 `lead|wait|limit
|
|
405
|
+
- 保存是即时的,下一次搜索就按新值走,不用重启——但插件挂载时才读的那几项例外(`fetchFormat`、`fetchMaxLength`、`cachePersist`、`cacheFile`),改它们要重启。
|
|
406
|
+
- 但**排序类的改动可能被缓存挡住**:缓存键里只有 `lead|wait|limit|引擎集合|时间窗|query`,没有排序参数。同一个问题十分钟内再问,拿到的还是旧顺序——开了持久化后,重启 DSH 也清不掉。换个问法,或者等十分钟。改时间窗会换一个键,所以不受旧缓存影响。
|
|
407
|
+
- **正文不能从中间续读**:`web_fetch` 对一个网址只发一次请求,尾巴缺了就把 `fetchMaxLength` 调大,或者抓一个更窄的页面。
|
|
337
408
|
|
|
338
409
|
## 常见问题 FAQ
|
|
339
410
|
|
|
@@ -361,6 +432,16 @@ pnpm install
|
|
|
361
432
|
3. **要登录或付费**:抓取没有你的登录态。
|
|
362
433
|
4. **直连超时**:会先在 5 秒内试直连,失败转隧道;两个都不通、又没配 key 时报错,配了 key 还会再试服务端抽取。报错里会写清楚每一级失败的原因。
|
|
363
434
|
|
|
435
|
+
### 为什么抓回来的内容和浏览器看到的不一样?
|
|
436
|
+
|
|
437
|
+
因为 `web_fetch` 不是浏览器:
|
|
438
|
+
|
|
439
|
+
- 它只留**正文**,不留页面装修:转换前会剔掉导航、广告、脚本、页脚、表单和隐藏节点;标题、段落、列表、代码、引用、链接、图片和表格保留。
|
|
440
|
+
- 它**不执行 JavaScript**:正文靠前端渲染的页面抓回来接近空壳,而浏览器会把它补全。
|
|
441
|
+
- 它会**截掉尾巴**:超过 `fetchMaxLength`(默认 20000 字符)的转换后正文,会被一行提示替代,提示里写明原始长度,所以长页面会提前结束。
|
|
442
|
+
|
|
443
|
+
如果正文断得太早,把 `fetchMaxLength` 调大(`50000` 是个合适的值)。如果拿回来就是个空壳,那这页大概需要浏览器——可以试它的打印版、静态镜像,或者站点自己的 API。
|
|
444
|
+
|
|
364
445
|
### 为什么搜索结果和我手动搜的不一样?
|
|
365
446
|
|
|
366
447
|
因为这不是同一件事:
|
|
@@ -371,11 +452,38 @@ pnpm install
|
|
|
371
452
|
- 它可能用到十分钟前的缓存,也可能某家正在冷却没参与;
|
|
372
453
|
- 它没有你的账号、位置、浏览历史,不会个性化。
|
|
373
454
|
|
|
455
|
+
### 为什么开了时间过滤结果变少了?
|
|
456
|
+
|
|
457
|
+
因为时间过滤会拿掉「日期不在窗口内」的结果。开启后它只保留窗口内**带日期**的结果;没有日期的结果不算数,因为无法证明它够新——这是刻意的取舍:宁可少给几条,也不拿一篇不知道哪年的页面冒充「最近 24 小时」。
|
|
458
|
+
|
|
459
|
+
唯一的例外是兜底:如果一条**带日期**的结果都没落进窗口,它会退回无日期的结果,免得你空手而归。所以看到的结果条数可能是 0 到 8 条之间,而不是固定的 8 条。
|
|
460
|
+
|
|
461
|
+
### 缓存会不会把旧答案一直给我?
|
|
462
|
+
|
|
463
|
+
不会。每条缓存在写入 `cacheTtlMs` 之后过期——默认 10 分钟——所以窗口内重复问拿到的是旧答案,下一次就会重新去问引擎。三件事把它关在笼子里:
|
|
464
|
+
|
|
465
|
+
- `cacheTtlMs: 0` 直接关掉缓存;`cacheEntries`(默认 100)限制最多存几条,超出淘汰最久未用的;
|
|
466
|
+
- 硬盘快照只存**摘要**(`url`、`title`、`snippet`、`publishedAt`),不存正文;
|
|
467
|
+
- 过期时间是绝对时间:从硬盘重新载入的条目沿用原截止时间,载入时就把过期条目丢掉,所以重启 DSH 不会给缓存「续命」。
|
|
468
|
+
|
|
469
|
+
### `domain_search` 和 `web_search` 该用哪个?
|
|
470
|
+
|
|
471
|
+
看你要找的是**网页**还是**条目**:
|
|
472
|
+
|
|
473
|
+
- 查概念、新闻、官网、教程、报错信息 → 用 `web_search`,它查的是公开网页;
|
|
474
|
+
- 查包、代码仓库、论文、问答、百科条目 → 用 `domain_search`,它直接问 GitHub、npm、PyPI、arXiv、Wikipedia、Hacker News、Stack Exchange、crates.io。
|
|
475
|
+
|
|
476
|
+
两者可以接力:`domain_search` 找到包或论文的条目,再用 `web_fetch` 打开主页或 README 读细节。
|
|
477
|
+
|
|
478
|
+
### 一次问多个问题怎么最快?
|
|
479
|
+
|
|
480
|
+
用 `search_many`。一次调用带 1–5 条 `queries`,批内 3 条并发,每条查询的结果分开返回;`limit`(默认 5)限制每条查询返回几条,`withSites: true` 会附上每条结果的域名。某条查询失败只变成它自己的 `failures` 一行,不会中断整批。单个问题用 `web_search`;目标是包、仓库、论文或问答时用 `domain_search`。
|
|
481
|
+
|
|
374
482
|
### 改了设置为什么没生效?
|
|
375
483
|
|
|
376
484
|
分三种情况:
|
|
377
485
|
|
|
378
|
-
-
|
|
486
|
+
- **在设置页改的**:保存即生效,但下一次搜索才读新值——`fetchFormat`、`fetchMaxLength`、`cachePersist` 和 `cacheFile` 例外,它们在插件挂载时读取。如果问的是同一个问题、十分钟内又问了一遍,可能命中了缓存,看起来像没变——换个问法试试;开了持久化后,重启也不会清掉缓存。
|
|
379
487
|
- **改的是 profile 里的 `cordis.patch.yml`**:需要完全重启 Harness。
|
|
380
488
|
- **改的是 `src/*.ts`**:需要 `npm run build` 再重启。只改源码不构建,跑的还是 `lib/` 里的旧代码。
|
|
381
489
|
|
|
@@ -385,7 +493,7 @@ pnpm install
|
|
|
385
493
|
|
|
386
494
|
- 一次搜索实测 1.4–3.8 秒(英文多等一会儿,中文快一些);命中缓存时几乎瞬间。
|
|
387
495
|
- 这段时间模型在等工具结果,不是卡死;等不到会按软截止返回已经拿到的部分。
|
|
388
|
-
- 真正的成本在上下文:搜索结果和网页正文都会占用模型的输入长度,读的页面越长,这一轮越贵、越容易挤掉别的内容。所以它默认只返回 8
|
|
496
|
+
- 真正的成本在上下文:搜索结果和网页正文都会占用模型的输入长度,读的页面越长,这一轮越贵、越容易挤掉别的内容。所以它默认只返回 8 条,抓回来的正文先转换、再按 20000 字符截断(原始响应体另外限制在 1 MiB)。
|
|
389
497
|
|
|
390
498
|
### 为什么模型有时候还是不搜?
|
|
391
499
|
|
|
@@ -404,11 +512,13 @@ web_search 调用
|
|
|
404
512
|
→ 按 hosts 白名单过滤;没有代理时丢掉 viaProxy 引擎
|
|
405
513
|
→ 跳过正在冷却的引擎(但绝不会一个都不剩)
|
|
406
514
|
→ 按查询语言决定主导区(ASCII → global,CJK → cn)
|
|
407
|
-
→
|
|
515
|
+
→ 查缓存(先内存、再硬盘快照;键:lead|wait|limit|排序后的引擎 id|时间窗|归一化 query)
|
|
408
516
|
→ primary 档并发请求,达到释放条件即返回
|
|
409
517
|
→ 一条结果都没有时,跑 fallback 档
|
|
518
|
+
→ 各引擎按 timeRange 本地过滤(DuckDuckGo 另有 df 下推)
|
|
410
519
|
→ 按区域融合 + RRF 排序,截到 limit
|
|
411
|
-
→
|
|
520
|
+
→ 合并后再按时间窗收一次(一条带日期的都没落进窗口时退回无日期结果)
|
|
521
|
+
→ 写入缓存并标记快照待刷新,返回 { sources, failures, proxy }
|
|
412
522
|
```
|
|
413
523
|
|
|
414
524
|
一档的释放条件是四者之一:所有引擎都落定;主导区所有引擎都落定(无论成败);已凑够 `limit` 条且贡献者数达标;软截止到点。到点还在跑的引擎会被中止,并在失败列表里记为 `still running at deadline` 或 `aborted once enough results had arrived`。
|
|
@@ -429,7 +539,29 @@ score(source) = votes / (rrfConstant + position)
|
|
|
429
539
|
- 新鲜度系数:`1 + freshnessBoost × (1 − ageDays / freshnessDays)`,超过窗口就是 1;日期解析失败也按 1 处理,不惩罚。
|
|
430
540
|
- 平局依次比较:引擎顺序 → 该引擎内的排名 → URL 字符串,所以同样的输入永远得到同样的顺序。
|
|
431
541
|
|
|
432
|
-
|
|
542
|
+
**新鲜度现在算的是真实日期**:`publishedAt` 从各引擎的结果里解析出来,`freshnessBoost` / `freshnessDays` 不再空转。解析失败、或者结果本来就没日期的,按 1 处理——不惩罚也不加分。时间窗过滤发生在引擎层和合并之后,排序本身只负责打分。
|
|
543
|
+
|
|
544
|
+
### 发布时间与时间窗
|
|
545
|
+
|
|
546
|
+
各引擎把日期写在不同的地方,解析器把它们统一成 ISO 8601 UTC:
|
|
547
|
+
|
|
548
|
+
| 引擎 | 日期从哪来 |
|
|
549
|
+
| --- | --- |
|
|
550
|
+
| Bing | 摘要开头的日期(`2025年9月25日`、`2 天之前`),或 `news_dt` 时间戳元素 |
|
|
551
|
+
| 360 | 单独的「发贴时间:2026年1月22日」 |
|
|
552
|
+
| DuckDuckGo | `result-timestamp` / `result__timestamp` 元素,或摘要里的日期 |
|
|
553
|
+
| AnySearch | 正文末尾追加的 `date: 22 hours ago` |
|
|
554
|
+
|
|
555
|
+
细节:
|
|
556
|
+
|
|
557
|
+
- 绝对日期一律用 `Date.UTC` 且锚定当天 **UTC 正午**,所以同一个日期在上海、柏林、洛杉矶都是同一时刻,不会因为机器时区漂到前一天。
|
|
558
|
+
- 相对日期(`3 天前`、`22 hours ago`、`昨天`)按滚动时间算,不按日历天减,避开时区和夏令时问题。
|
|
559
|
+
- `timeRange` 的五档对应 24 小时、7 天、30 天、365 天:`day` / `week` / `month` / `year`,`off` 表示不过滤。
|
|
560
|
+
- **下推与本地过滤**:DuckDuckGo 的 `df=d/w/m/y` 是真参数,实测会改变结果集;Bing 和 360 的时间参数实测无效——页面把选项显示成已选中,返回的结果却不变——所以它们和 AnySearch 一样,在本地按解析出的日期过滤。
|
|
561
|
+
- **无日期结果的处理**:开启窗口后只保留窗口内**带日期**的结果;只有当一条带日期的都没落进窗口时,才退回无日期结果,避免空手而归。解析失败与没有日期同等对待,因为「解析不出来」不等于「很旧」。
|
|
562
|
+
- 未来日期不算越界:它仍在窗口内,排序时把年龄夹到 0。
|
|
563
|
+
- 缓存键在窗口非 `off` 时会多带一段 `timeRange`,所以切换窗口不会命中旧窗口的缓存;`off` 的键与旧版完全一致。
|
|
564
|
+
- 实测:查询 `latest AI news`,`off` 下返回 8 条(其中 5 条带日期);`day` 下返回 5 条,且全部带日期。
|
|
433
565
|
|
|
434
566
|
### 缓存与冷却
|
|
435
567
|
|
|
@@ -437,6 +569,17 @@ score(source) = votes / (rrfConstant + position)
|
|
|
437
569
|
|
|
438
570
|
**冷却**针对「抓公开结果页被拦」这件事:`SEARCH_THROTTLED`(429)、`SEARCH_BLOCKED`(403、其他 4xx、回显校验不通过)、`SEARCH_TIMEOUT`、`SEARCH_NETWORK` 会让引擎休息;`SEARCH_PARSE`(上游改版,重试没用)和 `SEARCH_ABORTED`(调用方取消)不冷却。时长优先用对方给的 `Retry-After`(秒数或 HTTP 日期,取最后一次跳转的响应头),没有就 `baseCooldownMs × 2^(连续失败次数−1)`,封顶 `maxCooldownMs`。成功一次清零。全都在冷却时仍然照常尝试,不会让引擎集合空掉。
|
|
439
571
|
|
|
572
|
+
### 硬盘上的缓存
|
|
573
|
+
|
|
574
|
+
`cachePersist`(默认 `true`)决定要不要写文件;`cacheFile` 默认空,解析成 `~/.dsh/cache/dsh-web-search/cache.json`(开头的 `~` 会展开)。文档结构是 `{ version: 1, savedAt, entries: [{ key, expiresAt, sources }] }`,每条只带摘要——`url`、`title`、`snippet`、`publishedAt`;源对象上多挂的其他字段在序列化边界丢掉,正文永远不会进文件。
|
|
575
|
+
|
|
576
|
+
- **写**:先写到同目录的临时文件(`<file>.<pid>.<n>.tmp`),再 `rename` 覆盖目标;同一文件系统上是原子操作,rename 之前失败会保留旧文件并删掉临时文件。写入有 2 秒节流,插件卸载和进程退出时也会各刷一次。
|
|
577
|
+
- **读**:文件不存在、读不了、JSON 坏、`version` 不符、单条不合法,一律当成空缓存;读取过程从不抛错,也绝不会让插件挂载失败。
|
|
578
|
+
- **上限**:序列化后的文档按最久未用顺序淘汰,直到不超过 4 MiB(`DEFAULT_CACHE_FILE_MAX_BYTES`);`cacheEntries` 仍然约束内存里的条数。
|
|
579
|
+
- **过期**:`expiresAt` 是绝对时间,从硬盘载入的条目沿用原截止时间;载入时就丢掉过期条目,重启不会给缓存续命。
|
|
580
|
+
- **两个进程**:后写覆盖。可能用较旧的快照盖掉较新的,但不会写出半个文件。
|
|
581
|
+
- **实时读取**:`cacheTtlMs` 和 `cacheEntries` 是每次使用都调用的函数,设置页改完下一次搜索就生效;`cachePersist` 和 `cacheFile` 在挂载时决定接线,改这两项要重启。
|
|
582
|
+
|
|
440
583
|
### web_fetch 的三级梯队
|
|
441
584
|
|
|
442
585
|
`web_fetch` 的提供方 `http-proxy` 按顺序试三条路,前一条失败才走下一跳:
|
|
@@ -449,7 +592,53 @@ score(source) = votes / (rrfConstant + position)
|
|
|
449
592
|
|
|
450
593
|
直连的截止时间故意比隧道短:被墙的站点通常表现成超时,把整个预算花在一条不可能成功的路上,后面能成功的路就没时间了。
|
|
451
594
|
|
|
452
|
-
其他细节:只接受 `http(s)` URL
|
|
595
|
+
其他细节:只接受 `http(s)` URL;原始响应体最多保留 `1 MiB`(`1048576` 字节)再做转换,超出截断并标记 `truncated`;非 2xx 是**结果**不是失败(会原样带回状态码和响应体);三级全失败才抛错,错误消息里带每一级的原因。
|
|
596
|
+
|
|
597
|
+
### 从 HTML 到 Markdown
|
|
598
|
+
|
|
599
|
+
转换不依赖第三方库(`src/markdown.ts`):容错的词法与树构建,因为真实页面不是 XML;一遍剪枝,去掉界面装饰标签、注释和隐藏节点;一遍正文选择,依次偏好 `<article>`、`<main>` / `role=main`、文本最密的容器;最后渲染标题、段落、列表、代码、引用、分割线、链接、图片和表格。
|
|
600
|
+
|
|
601
|
+
- `markdown` 保留语法,`text` 只留文字。实体会解码,相对链接补成绝对地址。
|
|
602
|
+
- 表格转成 Markdown 表格;不在选定正文根里的表格会跟导航一起丢掉。
|
|
603
|
+
- 字符预算在**转换之后**才生效:`truncateFetchText` 按 `fetchMaxLength` 切,去掉尾部空白,避免把代理对切成半个,并追加 `[truncated at 20000 chars; original length 40891 chars; the rest is not shown]`。
|
|
604
|
+
- 实测 `docs.python.org/3/library/urllib.parse.html`:119,614 字符 HTML → 40,891 字符 Markdown → 实际返回 20,080 字符。
|
|
605
|
+
- 抓取提供方在挂载时取走 `fetchFormat` 和 `fetchMaxLength`,所以这两项在设置页改完要重启;搜索侧的设置每次调用都重读。
|
|
606
|
+
- **不支持续读**:宿主的 `WebFetchRequest` 只有 `url` 一个字段,没有 offset、maxLength、format。所以每次抓取都从头开始;唯一的办法是调大 `fetchMaxLength`,或抓更窄的页面。
|
|
607
|
+
|
|
608
|
+
### domain_search 的管道
|
|
609
|
+
|
|
610
|
+
```
|
|
611
|
+
domain_search 调用
|
|
612
|
+
→ 读配置(domainSources / domainLimit / domainTimeoutMs 每次调用重读)
|
|
613
|
+
→ 解析代理(配置 → 环境变量 → 系统代理)
|
|
614
|
+
→ sources 缺省 = 设置里启用的源;limit 夹到 1–20,缺省用 domainLimit
|
|
615
|
+
→ 八个源并发 GET,各自独立超时(domainTimeoutMs)
|
|
616
|
+
→ 按源交错合并,截到 limit
|
|
617
|
+
→ 返回 { sources, failures, truncated }
|
|
618
|
+
```
|
|
619
|
+
|
|
620
|
+
八个源都是公开、免密钥的接口:GitHub 仓库搜索、npm registry、PyPI、arXiv Atom、Wikipedia API、Hacker News(Algolia)、Stack Exchange API、crates.io。每个源各有解析器,上游改版时该源退化成空结果,不会让整次调用失败;单个源超时、回 5xx 或网络不通,只记一条 `failures`,其余源照常返回。GitHub 与 crates.io 要求带 `User-Agent`,请求里已经带上。
|
|
621
|
+
|
|
622
|
+
两个源的行为需要单独说明:
|
|
623
|
+
|
|
624
|
+
- **PyPI 没有公开搜索 API**,所以它不是全文搜索:取查询的第一个词当**精确包名**去查,包不存在就按空结果处理(不是失败)。
|
|
625
|
+
- **Wikipedia 只查单一语言**:查询里含中日韩字符(CJK)就查 `zh`,否则查 `en`。
|
|
626
|
+
|
|
627
|
+
工具注册走宿主真实的工具注册表:用 `ctx.get('tools')` 读取,而不是 `inject`——`inject` 是硬依赖,没有工具服务的部署会连插件都挂不上,`web_search` 也会跟着消失。读不到就不注册 `domain_search`,插件其余功能照常。如果这个名字已被别的插件占用,会改用 `web_domain_search` 注册。
|
|
628
|
+
|
|
629
|
+
### search_many 的管道
|
|
630
|
+
|
|
631
|
+
```
|
|
632
|
+
search_many 调用
|
|
633
|
+
→ queries 1–5 条(必填),limit 缺省 5(取值 1–20),withSites 缺省 false
|
|
634
|
+
→ 用 SEARCH_MANY_CONCURRENCY = 3 对查询做 mapLimit
|
|
635
|
+
→ 每条查询:与 web_search 相同的引擎层、缓存和冷却记录
|
|
636
|
+
→ 抛出的查询变成 { sources: [], failures: [消息] },整批继续
|
|
637
|
+
→ 结果保持输入顺序;withSites 时附带小写域名字段 `site`
|
|
638
|
+
→ 返回 { results, truncated }
|
|
639
|
+
```
|
|
640
|
+
|
|
641
|
+
配置里的 `limit` 是每条查询的硬上限:调用方可以要得更少,不能要得更多。工具自身超时 30 秒,声明为可并发;`search_many` 被别的插件占用时注册成 `web_search_many`。和 `domain_search` 一样从 `ctx.get('tools')` 取注册表:宿主没有工具注册表就不注册,插件其余功能照常。
|
|
453
642
|
|
|
454
643
|
### 代理
|
|
455
644
|
|
|
@@ -463,21 +652,38 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
|
|
|
463
652
|
- **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)。
|
|
464
653
|
- **依赖上游 HTML 结构**。上游改版会让解析失败,此时该引擎记一条原因并让位,不会静默返回空列表。
|
|
465
654
|
- **结果里只有标题、链接、摘要,没有正文**。正文要 `web_fetch`。
|
|
466
|
-
-
|
|
655
|
+
- **抓回来的正文不能从中间续读**:宿主的 `WebFetchRequest` 只有 `url` 一个字段,超过 `fetchMaxLength` 的部分只能靠调大上限或抓更窄的页面。
|
|
656
|
+
- **正文提取只保留「像正文」的部分**:纯 JavaScript 渲染的页面抓回来接近空壳,选定正文根之外的内容(比如侧栏里的表格)会跟导航一起丢掉。
|
|
657
|
+
- **`search_many` 一次最多 5 条查询,批内最多 3 条并发。**
|
|
658
|
+
- **两个进程共用一个缓存文件是后写覆盖**:不会写坏文件,但一个进程较新的快照可能被另一个进程较旧的快照盖掉。
|
|
659
|
+
- **时间窗只能过滤「有日期」的结果**:日期从结果页解析,引擎不给日期时这条就没有年龄信息;窗口内一条带日期的都没有时会退回无日期结果。Bing 与 360 的时间参数实测无效,真正下推的只有 DuckDuckGo 的 `df=`。
|
|
660
|
+
- **PyPI 只支持精确包名**:它没有公开搜索 API,插件取查询的第一个词当包名;拼错就是空结果。
|
|
661
|
+
- **Wikipedia 只查单一语言**:含中日韩字符查 `zh`,否则查 `en`。
|
|
662
|
+
- **`domain_search` 依赖宿主提供工具注册表**:没有 `ctx.tools` 时它不注册,`web_search` 不受影响。
|
|
467
663
|
- **AnySearch 匿名调用每次最多 10 条。**
|
|
468
664
|
- **只支持 HTTP 代理**,不支持 `socks5://`。
|
|
469
|
-
- **`limit` 上限 20。**
|
|
665
|
+
- **`limit` 上限 20;`domainLimit` 上限也是 20。**
|
|
470
666
|
|
|
471
667
|
### 默认值速查
|
|
472
668
|
|
|
473
669
|
| 项 | 值 |
|
|
474
670
|
| --- | --- |
|
|
475
671
|
| 返回条数 `limit` | `8`(1–20) |
|
|
672
|
+
| 时间窗 `timeRange` | `off`(不限;`day` / `week` / `month` / `year`) |
|
|
673
|
+
| 专用源条数 `domainLimit` | `5`(1–20) |
|
|
674
|
+
| 专用源超时 `domainTimeoutMs` | `8000` 毫秒 |
|
|
476
675
|
| 缓存有效期 `cacheTtlMs` | `600000` 毫秒 = 600 秒 |
|
|
477
676
|
| 缓存条数 `cacheEntries` | `100` |
|
|
677
|
+
| 写入硬盘 `cachePersist` | `true` |
|
|
678
|
+
| 缓存文件 `cacheFile` | 空 = `~/.dsh/cache/dsh-web-search/cache.json` |
|
|
679
|
+
| 硬盘缓存上限 | `4194304` 字节 = 4 MiB |
|
|
478
680
|
| 单引擎超时 `timeoutMs` | `15000` 毫秒 |
|
|
479
681
|
| `web_fetch` 直连截止 | `5000` 毫秒 |
|
|
480
|
-
|
|
|
682
|
+
| 原始响应体上限 | `1048576`(1 MiB) |
|
|
683
|
+
| 返回格式 `fetchFormat` | `markdown`(或 `text`) |
|
|
684
|
+
| 单次抓取字符上限 `fetchMaxLength` | `20000`(1000–200000) |
|
|
685
|
+
| `search_many` 查询数 / 并发 | 1–5 条 / 3 条 |
|
|
686
|
+
| `search_many` 条数 `limit` | `5`(1–20) |
|
|
481
687
|
| RRF 常数 `rrfConstant` | `60` |
|
|
482
688
|
| 基础冷却 `baseCooldownMs` | `300000` 毫秒 = 5 分钟 |
|
|
483
689
|
| 最大冷却 `maxCooldownMs` | `1800000` 毫秒 = 30 分钟 |
|
|
@@ -485,14 +691,14 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
|
|
|
485
691
|
### 开发与测试
|
|
486
692
|
|
|
487
693
|
```sh
|
|
488
|
-
node --test test/*.test.ts #
|
|
694
|
+
node --test test/*.test.ts # 全部测试(283 条)
|
|
489
695
|
node --test test/proxy.test.ts # 单个文件
|
|
490
696
|
npm run typecheck # tsc --noEmit
|
|
491
697
|
npm run build # 编译 src/ 到 lib/
|
|
492
698
|
npm run check # typecheck + 测试
|
|
493
699
|
```
|
|
494
700
|
|
|
495
|
-
|
|
701
|
+
测试全程离线,共 283 条:解析器测试回放 `test/fixtures/` 里抓下来的真实响应(含八个专用源的正常/空响应),传输测试不开 socket,代理测试只验 `parseProxy`、`proxyFromEnv` 和纯函数式的响应分帧,时间窗测试用注入的 `now` 固定日期;新增的几组覆盖 Markdown 正文提取(`markdown.test.ts`)、批量查询(`search-many.test.ts`)和硬盘快照(`cache-persist.test.ts`)。
|
|
496
702
|
|
|
497
703
|
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` 都可导入。
|
|
498
704
|
|