@fffangchenghao/dsh-web-search 0.11.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/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.12.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`,直接去那几类专门的数据源里查。
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` 一次跑多条查询。这几个名字后面会反复出现,先混个脸熟就行。
21
21
 
22
22
  ## 它解决什么问题
23
23
 
@@ -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,8 @@ Agent 就是「会自己决定下一步做什么」的 AI。普通聊天是问
112
114
 
113
115
  两个一起用最顺:先用 `domain_search` 找到包或论文,再用 `web_fetch` 打开它的主页或 README 读细节。
114
116
 
117
+ 旁边还有一个帮手:**`search_many`**。当一个问题需要分别查好几件事——比如每个候选库各查一次——它一次接住 1–5 条查询,把每条查询的结果分开返回,某一条失败也不会拖垮整批。
118
+
115
119
  ### DeepSeek message 和会话(session)
116
120
 
117
121
  模型本身没有记忆。每次请求,Harness 都会把**整串消息**重新发给它:系统提示、你之前说的话、模型之前的回答,以及工具的结果。这一串就叫 messages;一次连续的对话存在一个 session(会话)里。
@@ -190,29 +194,41 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
190
194
  *技术补充:`baseCooldownMs: 300000` 起,按连续失败次数翻倍,上限 `maxCooldownMs: 1800000`;对方给了 `Retry-After` 就听对方的;解析失败和主动取消不冷却。*
191
195
 
192
196
  9. **能把网页正文读回来。**
193
- 搜索给链接,`web_fetch` 给正文;直连不通时自动换路。
194
- *技术补充:三级梯队——直连(最多 5 秒)→ 本地隧道 → AnySearch 抽取(需要 key);单页最多保留 1 MiB(`1048576` 字节),超出部分截断并标记。*
197
+ 搜索给链接,`web_fetch` 给可读的正文;直连不通时自动换路。
198
+ *技术补充:三级梯队——直连(最多 5 秒)→ 本地隧道 → AnySearch 抽取(需要 key);原始响应体最多保留 1 MiB(`1048576` 字节),随后转换(见第 10 条)并按 `fetchMaxLength` 截断。*
195
199
 
196
- 10. **受限网络下也能用。**
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`,或抓更窄的页面。*
203
+
204
+ 11. **受限网络下也能用。**
197
205
  梯子开着并且设为系统代理时,不用配置任何东西;关掉梯子会自动退回直连,不会因此报错。
198
206
  *技术补充:代理来源依次是配置里的 `proxy`、环境变量 `DSH_WEB_SEARCH_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `HTTP_PROXY`、macOS 的 `scutil --proxy`;只支持 HTTP 代理(`CONNECT`),不支持 `socks5://`。*
199
207
 
200
- 11. **所有设置都能在界面上改,不用编辑文件。**
201
- 设置页有 20 个控件,分四组;保存后下一次搜索就生效。
202
- *技术补充:20 个字段全部标了 `.volatile()`,Host 以 live commit 方式原地更新,不重挂载插件。*
208
+ 12. **所有设置都能在界面上改,不用编辑文件。**
209
+ 设置页有 24 个控件,分五组;保存后下一次搜索就生效;只有 `cachePersist` 与 `cacheFile` 这两项要重载插件。
210
+ *技术补充:24 个字段全部标了 `.volatile()`,Host 以 live commit 方式原地更新,不重挂载插件;`cacheTtlMs` 与 `cacheEntries` 每次使用都重读;抓取提供方在挂载时取走 `proxy`、`timeoutMs`、`fetchFormat`、`fetchMaxLength`,缓存接线也在那时取走 `cachePersist` 与 `cacheFile`。*
203
211
 
204
- 12. **失败会解释原因,不会静默返回空。**
212
+ 13. **失败会解释原因,不会静默返回空。**
205
213
  一家都没成功时,报错里会列出「试过哪些引擎、各自为什么失败」。
206
214
  *技术补充:失败按 `SEARCH_THROTTLED` / `SEARCH_BLOCKED` / `SEARCH_TIMEOUT` / `SEARCH_NETWORK` / `SEARCH_PARSE` / `SEARCH_ABORTED` 分类;失败是返回值,不是异常,只有调用方取消才抛出。*
207
215
 
208
- 13. **包、仓库、论文、问答能直接查。**
216
+ 14. **包、仓库、论文、问答能直接查。**
209
217
  问「这个 npm 包还维护吗」「有没有讲 RAG 的论文」时,模型可以用 `domain_search` 直接查八个专门的数据源,而不是拿网页搜索碰运气。
210
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` 服务时,工具不注册,插件其余功能照常。*
211
219
 
212
- 14. **可以只看最近发布的结果。**
220
+ 15. **可以只看最近发布的结果。**
213
221
  设置里选「最近 24 小时 / 7 天 / 30 天 / 1 年」,就只留窗口内发布的结果,适合追新闻和版本更新。
214
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 走本地过滤。开启后只保留窗口内的**带日期**结果;只有当一条带日期的都没落进窗口时,才退回无日期结果,避免空手而归。*
215
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
+
216
232
  ## 安装与启用
217
233
 
218
234
  ### 你需要什么
@@ -299,13 +315,13 @@ pnpm install
299
315
 
300
316
  改完代码或 profile 配置后,**完全退出 DSH 再打开**(macOS 上不是只关窗口,要从菜单退出,或按 `Cmd+Q`)。原因是模块在每个进程里只求值一次,热改文件不会被已运行的进程看见。
301
317
 
302
- 只改设置页里的值不需要重启,见下一节。
318
+ 设置页里大部分值不需要重启,例外情况见下一节。
303
319
 
304
320
  ### 第五步:确认生效
305
321
 
306
322
  三个办法,任选:
307
323
 
308
- 1. **看设置页**:设置 → 「网页搜索(Bing)」,能看到四组控件,说明插件被加载了,schema 也被 Host 收录了。
324
+ 1. **看设置页**:设置 → 「网页搜索(Bing)」,能看到五组、共 24 个控件,说明插件被加载了,schema 也被 Host 收录了。
309
325
  2. **看日志**:启动日志里没有 `1 entry did not activate` 这类警告。
310
326
  3. **直接试**:问一个明显需要联网的问题,比如「帮我搜一下 DSH 插件开发教程,给我链接」。看模型有没有调用 `web_search`,返回的链接是不是真实可达。
311
327
 
@@ -313,14 +329,15 @@ pnpm install
313
329
 
314
330
  ## 设置页怎么用
315
331
 
316
- 打开 设置 → 「网页搜索(Bing)」。页面上一共 20 个控件,按四组排列。每组只管一类事:
332
+ 打开 设置 → 「网页搜索(Bing)」。页面上一共 24 个控件,按五组排列。每组只管一类事:
317
333
 
318
334
  | 组 | 控件数 | 这组管什么 |
319
335
  | --- | --- | --- |
320
336
  | 引擎与传输 | 6 | 用哪些搜索引擎、等多久、走不走代理、AnySearch 的凭据和垂直域 |
321
337
  | 结果与排序 | 7 | 返回几条、只看多久内、怎么合并排序、官方文档和新内容加权多少 |
322
338
  | 专用检索 | 3 | `domain_search` 查哪些源、每个源返回几条、每个源等多久 |
323
- | 缓存与冷却 | 4 | 结果记多久、记多少条、被限流后歇多久 |
339
+ | 抓取 | 2 | `web_fetch` 返回 Markdown 还是纯文本、最多返回多少字符 |
340
+ | 缓存与冷却 | 6 | 结果记多久、记多少条、要不要写进硬盘、被限流后歇多久 |
324
341
 
325
342
  ### 引擎与传输(6 个)
326
343
 
@@ -353,29 +370,41 @@ pnpm install
353
370
  | 每个源返回几条 | `domainLimit` | `5` | `domain_search` 每个源最多返回几条,1–20 |
354
371
  | 每个源等多久 | `domainTimeoutMs` | `8000` | 单个专用源最多等多久(毫秒),最小 500;网慢可调到 15000 |
355
372
 
356
- ### 缓存与冷却(4 个)
373
+ ### 抓取(2 个)
357
374
 
358
375
  | 控件 | 配置键 | 默认 | 人话 |
359
376
  | --- | --- | --- | --- |
360
- | 缓存保留多久 | `cacheTtlMs` | `600000` | 10 分钟;填 `0` 关闭缓存 |
361
- | 缓存条数上限 | `cacheEntries` | `100` | 最多记多少个问题,超出淘汰最久没用的 |
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`。插件挂载时读取 |
362
388
  | 被拒后歇多久 | `baseCooldownMs` | `300000` | 被限流后第一次歇多久,5 分钟 |
363
389
  | 歇息上限 | `maxCooldownMs` | `1800000` | 连续失败时冷却翻倍的上限,30 分钟 |
364
390
 
365
391
  ### 给你的建议
366
392
 
367
- **只想正常用:20 个控件全都别改,默认值就是调过的。**
393
+ **只想正常用:24 个控件全都别改,默认值就是调过的。**
368
394
 
369
- 只有三种情况值得动:
395
+ 只有这些情况值得动:
370
396
 
371
397
  - **代理没被自动探测到**:在 `proxy` 里填上你的本地代理地址,比如 `http://127.0.0.1:7890`。只支持 HTTP 代理,`socks5://` 要换成客户端的 HTTP/mixed 端口。
372
398
  - **你想要 AnySearch 的更高额度或正文抽取**:填 `anysearchApiKey`;想只搜某个垂直领域再填 `anysearchDomain`。
373
399
  - **你只想让 `domain_search` 查某几个源**:把 `domainSources` 收窄成 `github,npm` 这类组合;留空就是八个全开。
400
+ - **抓回来的正文断得太早,或只想要纯文字**:把 `fetchMaxLength` 调到 `50000`,或把 `fetchFormat` 改成 `text`。
401
+ - **不想在硬盘上留缓存文件**:关掉 `cachePersist`,或把 `cacheFile` 指到别处。
374
402
 
375
- 两个提醒:
403
+ 三个提醒:
376
404
 
377
- - 保存是即时的,下一次搜索就按新值走,不用重启。
378
- - 但**排序类的改动可能被缓存挡住**:缓存键里只有 `lead|wait|limit|引擎集合|时间窗|query`,没有排序参数。同一个问题十分钟内再问,拿到的还是旧顺序。换个问法,或者等十分钟。改时间窗会换一个键,所以不受旧缓存影响。
405
+ - 保存是即时的,下一次搜索就按新值走,不用重启——但插件挂载时才读的那几项例外(`fetchFormat`、`fetchMaxLength`、`cachePersist`、`cacheFile`),改它们要重启。
406
+ - 但**排序类的改动可能被缓存挡住**:缓存键里只有 `lead|wait|limit|引擎集合|时间窗|query`,没有排序参数。同一个问题十分钟内再问,拿到的还是旧顺序——开了持久化后,重启 DSH 也清不掉。换个问法,或者等十分钟。改时间窗会换一个键,所以不受旧缓存影响。
407
+ - **正文不能从中间续读**:`web_fetch` 对一个网址只发一次请求,尾巴缺了就把 `fetchMaxLength` 调大,或者抓一个更窄的页面。
379
408
 
380
409
  ## 常见问题 FAQ
381
410
 
@@ -403,6 +432,16 @@ pnpm install
403
432
  3. **要登录或付费**:抓取没有你的登录态。
404
433
  4. **直连超时**:会先在 5 秒内试直连,失败转隧道;两个都不通、又没配 key 时报错,配了 key 还会再试服务端抽取。报错里会写清楚每一级失败的原因。
405
434
 
435
+ ### 为什么抓回来的内容和浏览器看到的不一样?
436
+
437
+ 因为 `web_fetch` 不是浏览器:
438
+
439
+ - 它只留**正文**,不留页面装修:转换前会剔掉导航、广告、脚本、页脚、表单和隐藏节点;标题、段落、列表、代码、引用、链接、图片和表格保留。
440
+ - 它**不执行 JavaScript**:正文靠前端渲染的页面抓回来接近空壳,而浏览器会把它补全。
441
+ - 它会**截掉尾巴**:超过 `fetchMaxLength`(默认 20000 字符)的转换后正文,会被一行提示替代,提示里写明原始长度,所以长页面会提前结束。
442
+
443
+ 如果正文断得太早,把 `fetchMaxLength` 调大(`50000` 是个合适的值)。如果拿回来就是个空壳,那这页大概需要浏览器——可以试它的打印版、静态镜像,或者站点自己的 API。
444
+
406
445
  ### 为什么搜索结果和我手动搜的不一样?
407
446
 
408
447
  因为这不是同一件事:
@@ -419,6 +458,14 @@ pnpm install
419
458
 
420
459
  唯一的例外是兜底:如果一条**带日期**的结果都没落进窗口,它会退回无日期的结果,免得你空手而归。所以看到的结果条数可能是 0 到 8 条之间,而不是固定的 8 条。
421
460
 
461
+ ### 缓存会不会把旧答案一直给我?
462
+
463
+ 不会。每条缓存在写入 `cacheTtlMs` 之后过期——默认 10 分钟——所以窗口内重复问拿到的是旧答案,下一次就会重新去问引擎。三件事把它关在笼子里:
464
+
465
+ - `cacheTtlMs: 0` 直接关掉缓存;`cacheEntries`(默认 100)限制最多存几条,超出淘汰最久未用的;
466
+ - 硬盘快照只存**摘要**(`url`、`title`、`snippet`、`publishedAt`),不存正文;
467
+ - 过期时间是绝对时间:从硬盘重新载入的条目沿用原截止时间,载入时就把过期条目丢掉,所以重启 DSH 不会给缓存「续命」。
468
+
422
469
  ### `domain_search` 和 `web_search` 该用哪个?
423
470
 
424
471
  看你要找的是**网页**还是**条目**:
@@ -428,11 +475,15 @@ pnpm install
428
475
 
429
476
  两者可以接力:`domain_search` 找到包或论文的条目,再用 `web_fetch` 打开主页或 README 读细节。
430
477
 
478
+ ### 一次问多个问题怎么最快?
479
+
480
+ 用 `search_many`。一次调用带 1–5 条 `queries`,批内 3 条并发,每条查询的结果分开返回;`limit`(默认 5)限制每条查询返回几条,`withSites: true` 会附上每条结果的域名。某条查询失败只变成它自己的 `failures` 一行,不会中断整批。单个问题用 `web_search`;目标是包、仓库、论文或问答时用 `domain_search`。
481
+
431
482
  ### 改了设置为什么没生效?
432
483
 
433
484
  分三种情况:
434
485
 
435
- - **在设置页改的**:保存即生效,但下一次搜索才读新值。如果问的是同一个问题、十分钟内又问了一遍,可能命中了缓存,看起来像没变——换个问法试试。
486
+ - **在设置页改的**:保存即生效,但下一次搜索才读新值——`fetchFormat`、`fetchMaxLength`、`cachePersist` 和 `cacheFile` 例外,它们在插件挂载时读取。如果问的是同一个问题、十分钟内又问了一遍,可能命中了缓存,看起来像没变——换个问法试试;开了持久化后,重启也不会清掉缓存。
436
487
  - **改的是 profile 里的 `cordis.patch.yml`**:需要完全重启 Harness。
437
488
  - **改的是 `src/*.ts`**:需要 `npm run build` 再重启。只改源码不构建,跑的还是 `lib/` 里的旧代码。
438
489
 
@@ -442,7 +493,7 @@ pnpm install
442
493
 
443
494
  - 一次搜索实测 1.4–3.8 秒(英文多等一会儿,中文快一些);命中缓存时几乎瞬间。
444
495
  - 这段时间模型在等工具结果,不是卡死;等不到会按软截止返回已经拿到的部分。
445
- - 真正的成本在上下文:搜索结果和网页正文都会占用模型的输入长度,读的页面越长,这一轮越贵、越容易挤掉别的内容。所以它默认只返回 8 条,单页最多保留 1 MiB。
496
+ - 真正的成本在上下文:搜索结果和网页正文都会占用模型的输入长度,读的页面越长,这一轮越贵、越容易挤掉别的内容。所以它默认只返回 8 条,抓回来的正文先转换、再按 20000 字符截断(原始响应体另外限制在 1 MiB)。
446
497
 
447
498
  ### 为什么模型有时候还是不搜?
448
499
 
@@ -461,13 +512,13 @@ web_search 调用
461
512
  → 按 hosts 白名单过滤;没有代理时丢掉 viaProxy 引擎
462
513
  → 跳过正在冷却的引擎(但绝不会一个都不剩)
463
514
  → 按查询语言决定主导区(ASCII → global,CJK → cn)
464
- → 查缓存(键:lead|wait|limit|排序后的引擎 id|时间窗|归一化 query)
515
+ → 查缓存(先内存、再硬盘快照;键:lead|wait|limit|排序后的引擎 id|时间窗|归一化 query)
465
516
  → primary 档并发请求,达到释放条件即返回
466
517
  → 一条结果都没有时,跑 fallback 档
467
518
  → 各引擎按 timeRange 本地过滤(DuckDuckGo 另有 df 下推)
468
519
  → 按区域融合 + RRF 排序,截到 limit
469
520
  → 合并后再按时间窗收一次(一条带日期的都没落进窗口时退回无日期结果)
470
- → 写入缓存,返回 { sources, failures, proxy }
521
+ → 写入缓存并标记快照待刷新,返回 { sources, failures, proxy }
471
522
  ```
472
523
 
473
524
  一档的释放条件是四者之一:所有引擎都落定;主导区所有引擎都落定(无论成败);已凑够 `limit` 条且贡献者数达标;软截止到点。到点还在跑的引擎会被中止,并在失败列表里记为 `still running at deadline` 或 `aborted once enough results had arrived`。
@@ -518,6 +569,17 @@ score(source) = votes / (rrfConstant + position)
518
569
 
519
570
  **冷却**针对「抓公开结果页被拦」这件事:`SEARCH_THROTTLED`(429)、`SEARCH_BLOCKED`(403、其他 4xx、回显校验不通过)、`SEARCH_TIMEOUT`、`SEARCH_NETWORK` 会让引擎休息;`SEARCH_PARSE`(上游改版,重试没用)和 `SEARCH_ABORTED`(调用方取消)不冷却。时长优先用对方给的 `Retry-After`(秒数或 HTTP 日期,取最后一次跳转的响应头),没有就 `baseCooldownMs × 2^(连续失败次数−1)`,封顶 `maxCooldownMs`。成功一次清零。全都在冷却时仍然照常尝试,不会让引擎集合空掉。
520
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
+
521
583
  ### web_fetch 的三级梯队
522
584
 
523
585
  `web_fetch` 的提供方 `http-proxy` 按顺序试三条路,前一条失败才走下一跳:
@@ -530,7 +592,18 @@ score(source) = votes / (rrfConstant + position)
530
592
 
531
593
  直连的截止时间故意比隧道短:被墙的站点通常表现成超时,把整个预算花在一条不可能成功的路上,后面能成功的路就没时间了。
532
594
 
533
- 其他细节:只接受 `http(s)` URL;单页最多保留 `1 MiB`(`1048576` 字节),超出截断并标记 `truncated`;非 2xx 是**结果**不是失败(会原样带回状态码和响应体);三级全失败才抛错,错误消息里带每一级的原因。
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`,或抓更窄的页面。
534
607
 
535
608
  ### domain_search 的管道
536
609
 
@@ -553,6 +626,20 @@ domain_search 调用
553
626
 
554
627
  工具注册走宿主真实的工具注册表:用 `ctx.get('tools')` 读取,而不是 `inject`——`inject` 是硬依赖,没有工具服务的部署会连插件都挂不上,`web_search` 也会跟着消失。读不到就不注册 `domain_search`,插件其余功能照常。如果这个名字已被别的插件占用,会改用 `web_domain_search` 注册。
555
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')` 取注册表:宿主没有工具注册表就不注册,插件其余功能照常。
642
+
556
643
  ### 代理
557
644
 
558
645
  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`。
@@ -565,6 +652,10 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
565
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)。
566
653
  - **依赖上游 HTML 结构**。上游改版会让解析失败,此时该引擎记一条原因并让位,不会静默返回空列表。
567
654
  - **结果里只有标题、链接、摘要,没有正文**。正文要 `web_fetch`。
655
+ - **抓回来的正文不能从中间续读**:宿主的 `WebFetchRequest` 只有 `url` 一个字段,超过 `fetchMaxLength` 的部分只能靠调大上限或抓更窄的页面。
656
+ - **正文提取只保留「像正文」的部分**:纯 JavaScript 渲染的页面抓回来接近空壳,选定正文根之外的内容(比如侧栏里的表格)会跟导航一起丢掉。
657
+ - **`search_many` 一次最多 5 条查询,批内最多 3 条并发。**
658
+ - **两个进程共用一个缓存文件是后写覆盖**:不会写坏文件,但一个进程较新的快照可能被另一个进程较旧的快照盖掉。
568
659
  - **时间窗只能过滤「有日期」的结果**:日期从结果页解析,引擎不给日期时这条就没有年龄信息;窗口内一条带日期的都没有时会退回无日期结果。Bing 与 360 的时间参数实测无效,真正下推的只有 DuckDuckGo 的 `df=`。
569
660
  - **PyPI 只支持精确包名**:它没有公开搜索 API,插件取查询的第一个词当包名;拼错就是空结果。
570
661
  - **Wikipedia 只查单一语言**:含中日韩字符查 `zh`,否则查 `en`。
@@ -583,9 +674,16 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
583
674
  | 专用源超时 `domainTimeoutMs` | `8000` 毫秒 |
584
675
  | 缓存有效期 `cacheTtlMs` | `600000` 毫秒 = 600 秒 |
585
676
  | 缓存条数 `cacheEntries` | `100` |
677
+ | 写入硬盘 `cachePersist` | `true` |
678
+ | 缓存文件 `cacheFile` | 空 = `~/.dsh/cache/dsh-web-search/cache.json` |
679
+ | 硬盘缓存上限 | `4194304` 字节 = 4 MiB |
586
680
  | 单引擎超时 `timeoutMs` | `15000` 毫秒 |
587
681
  | `web_fetch` 直连截止 | `5000` 毫秒 |
588
- | 单页字节上限 | `1048576`(1 MiB) |
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) |
589
687
  | RRF 常数 `rrfConstant` | `60` |
590
688
  | 基础冷却 `baseCooldownMs` | `300000` 毫秒 = 5 分钟 |
591
689
  | 最大冷却 `maxCooldownMs` | `1800000` 毫秒 = 30 分钟 |
@@ -593,14 +691,14 @@ Node 的全局 `fetch` 既不读 macOS 系统代理,也不读 `HTTPS_PROXY`—
593
691
  ### 开发与测试
594
692
 
595
693
  ```sh
596
- node --test test/*.test.ts # 全部测试(239 条)
694
+ node --test test/*.test.ts # 全部测试(283 条)
597
695
  node --test test/proxy.test.ts # 单个文件
598
696
  npm run typecheck # tsc --noEmit
599
697
  npm run build # 编译 src/ 到 lib/
600
698
  npm run check # typecheck + 测试
601
699
  ```
602
700
 
603
- 测试全程离线,共 239 条:解析器测试回放 `test/fixtures/` 里抓下来的真实响应(含八个专用源的正常/空响应),传输测试不开 socket,代理测试只验 `parseProxy`、`proxyFromEnv` 和纯函数式的响应分帧,时间窗测试用注入的 `now` 固定日期。
701
+ 测试全程离线,共 283 条:解析器测试回放 `test/fixtures/` 里抓下来的真实响应(含八个专用源的正常/空响应),传输测试不开 socket,代理测试只验 `parseProxy`、`proxyFromEnv` 和纯函数式的响应分帧,时间窗测试用注入的 `now` 固定日期;新增的几组覆盖 Markdown 正文提取(`markdown.test.ts`)、批量查询(`search-many.test.ts`)和硬盘快照(`cache-persist.test.ts`)。
604
702
 
605
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` 都可导入。
606
704
 
package/client.js CHANGED
@@ -2,7 +2,7 @@
2
2
  * Browser half of `dsh-web-search-bing`.
3
3
  *
4
4
  * Registers one Settings page into the Settings surface's `settings.section`
5
- * slot, so this plugin's 20 configuration keys can be edited in the GUI instead
5
+ * slot, so this plugin's 22 configuration keys can be edited in the GUI instead
6
6
  * of the profile's `cordis.patch.yml`. The page reads and writes the plugin's
7
7
  * Loader entry (`web-search-bing`) through the shared `configForms` service,
8
8
  * which is the same path the shipped settings pages use.
@@ -77,6 +77,10 @@
77
77
  'hint.wait': 'auto decides from the question language, all waits for everyone, fast takes the first answer',
78
78
  'field.proxy': 'Proxy (relay)',
79
79
  'hint.proxy': 'Relay address for blocked sites; empty auto-detects the system proxy',
80
+ 'field.fetchFormat': 'Fetched page style',
81
+ 'hint.fetchFormat': 'markdown keeps headings, lists, tables and links; text keeps words only',
82
+ 'field.fetchMaxLength': 'Fetched characters',
83
+ 'hint.fetchMaxLength': 'Characters returned per fetch (1000-200000); the rest is noted as truncated',
80
84
  'field.limit': 'Results per search',
81
85
  'hint.limit': 'How many results come back, and how they are split across engines',
82
86
  'field.rrfConstant': 'Result blending',
@@ -100,6 +104,12 @@
100
104
  'hint.cacheTtlMs': 'How long an identical question reuses its cached answer (ms)',
101
105
  'field.cacheEntries': 'Cache size',
102
106
  'hint.cacheEntries': 'How many answers are remembered before the least recently used goes',
107
+ 'field.cachePersist': 'Save cache to disk',
108
+ 'hint.cachePersist': 'Keep recent answers across restarts; turn it off to stay memory-only',
109
+ 'cachePersist.true': 'On (save to disk)',
110
+ 'cachePersist.false': 'Off (memory only)',
111
+ 'field.cacheFile': 'Cache file',
112
+ 'hint.cacheFile': 'Empty uses ~/.dsh/cache/dsh-web-search/cache.json',
103
113
  'field.anysearchApiKey': 'AnySearch key',
104
114
  'hint.anysearchApiKey': 'Leave empty to stay anonymous at a lower rate limit; only sent to api.anysearch.com',
105
115
  'field.anysearchDomain': 'Vertical domain',
@@ -145,6 +155,10 @@
145
155
  'hint.wait': 'auto 按提问语言自动决定,all 等全部,fast 先到先用',
146
156
  'field.proxy': '代理(中转站)',
147
157
  'hint.proxy': '上网中转站地址;留空自动识别系统代理',
158
+ 'field.fetchFormat': '抓取内容的样式',
159
+ 'hint.fetchFormat': 'markdown 保留标题、列表、表格和链接;text 只留纯文字',
160
+ 'field.fetchMaxLength': '抓取字符上限',
161
+ 'hint.fetchMaxLength': '一次抓取最多返回多少字符(1000-200000);超出部分会注明已截断',
148
162
  'field.limit': '返回几条',
149
163
  'hint.limit': '一次最多返回几条,也决定各引擎分到几条',
150
164
  'field.rrfConstant': '结果混合力度',
@@ -168,6 +182,12 @@
168
182
  'hint.cacheTtlMs': '同一问题复用旧结果多久(毫秒);想更快见新内容就调小',
169
183
  'field.cacheEntries': '缓存条数上限',
170
184
  'hint.cacheEntries': '最多记住多少条旧结果,满了丢最久没用的',
185
+ 'field.cachePersist': '缓存保存到磁盘',
186
+ 'hint.cachePersist': '重启后仍复用最近结果;关闭则只在内存中保存',
187
+ 'cachePersist.true': '开启(保存到磁盘)',
188
+ 'cachePersist.false': '关闭(仅内存)',
189
+ 'field.cacheFile': '缓存文件路径',
190
+ 'hint.cacheFile': '留空使用 ~/.dsh/cache/dsh-web-search/cache.json',
171
191
  'field.anysearchApiKey': 'AnySearch 通行证',
172
192
  'hint.anysearchApiKey': '没有就留空,仍可用但速率较低;只发给 api.anysearch.com',
173
193
  'field.anysearchDomain': '专业领域',
@@ -191,6 +211,8 @@
191
211
  { key: 'wait', group: 'engines', kind: 'select', options: ['auto', 'all', 'fast'] },
192
212
  { key: 'timeoutMs', group: 'engines', kind: 'number', integer: true, min: 500 },
193
213
  { key: 'proxy', group: 'engines', kind: 'text' },
214
+ { key: 'fetchFormat', group: 'engines', kind: 'select', options: ['markdown', 'text'] },
215
+ { key: 'fetchMaxLength', group: 'engines', kind: 'number', integer: true, min: 1000, max: 200000 },
194
216
  { key: 'anysearchApiKey', group: 'engines', kind: 'text' },
195
217
  { key: 'anysearchDomain', group: 'engines', kind: 'text' },
196
218
  { key: 'limit', group: 'ranking', kind: 'number', integer: true, min: 1, max: 20 },
@@ -202,6 +224,8 @@
202
224
  { key: 'timeRange', group: 'ranking', kind: 'select', options: ['off', 'day', 'week', 'month', 'year'] },
203
225
  { key: 'cacheTtlMs', group: 'cache', kind: 'number', integer: true, min: 0 },
204
226
  { key: 'cacheEntries', group: 'cache', kind: 'number', integer: true, min: 0 },
227
+ { key: 'cachePersist', group: 'cache', kind: 'select', options: ['true', 'false'], boolean: true },
228
+ { key: 'cacheFile', group: 'cache', kind: 'text' },
205
229
  { key: 'baseCooldownMs', group: 'cache', kind: 'number', integer: true, min: 0 },
206
230
  { key: 'maxCooldownMs', group: 'cache', kind: 'number', integer: true, min: 0 },
207
231
  { key: 'domainSources', group: 'domain', kind: 'list' },
@@ -369,8 +393,9 @@
369
393
  return { op: 'set', path: [key], value: list };
370
394
  }
371
395
  if (field.kind === 'select') {
372
- if (raw === current) return null;
373
- return raw === '' ? { op: 'unset', path: [key] } : { op: 'set', path: [key], value: raw };
396
+ var next = field.boolean === true ? raw === 'true' : raw;
397
+ if (next === current) return null;
398
+ return raw === '' ? { op: 'unset', path: [key] } : { op: 'set', path: [key], value: next };
374
399
  }
375
400
  if (field.kind === 'text') {
376
401
  var text = String(raw === undefined || raw === null ? '' : raw);
@@ -0,0 +1,96 @@
1
+ import type { Source } from './types.ts';
2
+ /** Version of the on-disk document; a different version is ignored wholesale. */
3
+ export declare const CACHE_FILE_VERSION = 1;
4
+ /** Default byte budget for the snapshot: 4 MiB. */
5
+ export declare const DEFAULT_CACHE_FILE_MAX_BYTES: number;
6
+ /** One cache entry as it travels to disk. */
7
+ export interface PersistedEntry {
8
+ /** Deterministic key produced by `cacheKey`. */
9
+ key: string;
10
+ /** Absolute expiry timestamp; expired entries are dropped on load. */
11
+ expiresAt: number;
12
+ /** The search-result summary, never a page body. */
13
+ sources: Source[];
14
+ }
15
+ /** Filesystem seam: every call may throw, and the caller contains it. */
16
+ export interface CacheFileIo {
17
+ /** Read the file as UTF-8, or return `undefined` when it is absent. */
18
+ read: (path: string) => string | undefined;
19
+ /** Write a new file (the temporary one). */
20
+ write: (path: string, data: string) => void;
21
+ /** Atomically replace the target with the temporary file. */
22
+ rename: (from: string, to: string) => void;
23
+ /** Create the containing directory, including parents. */
24
+ mkdir: (path: string) => void;
25
+ /** Best-effort removal of the temporary file. */
26
+ remove: (path: string) => void;
27
+ }
28
+ /** The real filesystem, exported so tests can override one operation. */
29
+ export declare const nodeCacheFileIo: CacheFileIo;
30
+ /** Where a snapshot is written when the config names no path. */
31
+ export declare function defaultCacheFile(): string;
32
+ /**
33
+ * Expand a configured cache path.
34
+ *
35
+ * An empty value selects {@link defaultCacheFile}; a leading `~` expands to the
36
+ * home directory so the documented default can be written verbatim in Settings.
37
+ * Relative paths are resolved against the process working directory.
38
+ *
39
+ * @param value - the `cacheFile` setting, possibly empty.
40
+ * @returns an absolute file path.
41
+ */
42
+ export declare function resolveCacheFile(value?: string): string;
43
+ /**
44
+ * Load the snapshot from disk.
45
+ *
46
+ * Every failure mode collapses to an empty list: absent file, unreadable path,
47
+ * malformed JSON, a different `version`, and individually invalid entries. An
48
+ * expired entry is dropped here rather than retained until its next read.
49
+ *
50
+ * @param file - absolute path to the snapshot.
51
+ * @param now - current time from the cache's injected clock.
52
+ * @param maxEntries - entry cap; the oldest surplus entries are discarded.
53
+ * @param io - filesystem seam, defaulting to the real one.
54
+ * @returns usable entries in stored (oldest to newest) order.
55
+ */
56
+ export declare function readCacheFile(file: string, now: number, maxEntries: number, io?: CacheFileIo): PersistedEntry[];
57
+ /** One serialised snapshot plus what survived the byte cap. */
58
+ export interface SerializedCache {
59
+ /** UTF-8 JSON document, ready for the atomic write. */
60
+ data: string;
61
+ /** Number of entries left after LRU eviction. */
62
+ entries: number;
63
+ /** Size of {@link data} in bytes. */
64
+ bytes: number;
65
+ }
66
+ /**
67
+ * Serialise entries, evicting the oldest until the document fits the budget.
68
+ *
69
+ * @param entries - entries in LRU order (oldest first).
70
+ * @param now - timestamp recorded as `savedAt`.
71
+ * @param maxBytes - byte budget; defaults to 4 MiB.
72
+ * @returns the document and how many entries it carries.
73
+ */
74
+ export declare function serializeCache(entries: readonly PersistedEntry[], now: number, maxBytes?: number): SerializedCache;
75
+ /** Write options, kept separate so the cache owns the policy, not the path. */
76
+ export interface CacheWriteOptions {
77
+ /** Byte budget; defaults to 4 MiB. */
78
+ maxBytes?: number;
79
+ /** Filesystem seam for tests. */
80
+ io?: CacheFileIo;
81
+ }
82
+ /**
83
+ * Atomically replace the snapshot.
84
+ *
85
+ * The temporary file lives beside the target so the `rename` stays on one
86
+ * filesystem. When anything fails (directory not writable, rename rejected),
87
+ * the previous document is untouched, the temporary file is removed, and the
88
+ * call returns `false` instead of throwing.
89
+ *
90
+ * @param file - absolute target path.
91
+ * @param entries - entries in LRU order (oldest first).
92
+ * @param now - timestamp recorded as `savedAt`.
93
+ * @param options - byte budget and filesystem seam.
94
+ * @returns `true` when the target now holds this snapshot.
95
+ */
96
+ export declare function writeCacheFile(file: string, entries: readonly PersistedEntry[], now: number, options?: CacheWriteOptions): boolean;