pi-better-web-search 0.1.6 → 0.1.8
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 +41 -0
- package/README.md +57 -35
- package/docs/README.zh-CN.md +45 -29
- package/docs/architecture.md +42 -24
- package/docs/providers.md +3 -1
- package/docs/publishing.md +6 -6
- package/docs/testing.md +4 -3
- package/lib/candidates.ts +95 -35
- package/lib/format.ts +1 -1
- package/lib/health.ts +147 -0
- package/lib/providers/deepseek.ts +23 -2
- package/lib/search.ts +46 -11
- package/lib/truncate-json.ts +111 -133
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,46 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.8
|
|
4
|
+
|
|
5
|
+
- Shorten overlong DeepSeek search queries at a word boundary before sending
|
|
6
|
+
them to the provider. DeepSeek rejects queries above 128 Unicode characters,
|
|
7
|
+
so concurrent agent search batches with long queries previously failed with
|
|
8
|
+
the generic unavailable error while shorter sibling calls succeeded. The
|
|
9
|
+
original query remains in the model-facing output.
|
|
10
|
+
- Return the provider errors when every search attempt fails, instead of
|
|
11
|
+
replacing them with the generic unavailable message. For example, an OpenAI
|
|
12
|
+
timeout and a DeepSeek validation error are now both visible to the model.
|
|
13
|
+
- Remember provider-wide and model-specific failures per search/fetch phase and
|
|
14
|
+
move the failed provider or model behind healthy candidates on later calls.
|
|
15
|
+
The cooldown is exponential (60s to 10 minutes) and is cleared by a
|
|
16
|
+
successful call. Configure with `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS`;
|
|
17
|
+
set it to `0` to disable.
|
|
18
|
+
- Surface provider error text without prepending provider/model labels to the
|
|
19
|
+
model-facing message.
|
|
20
|
+
- Rank GPT and Claude models by version number first, newest first; capability
|
|
21
|
+
tier is now only a tiebreaker for the same version. Add the
|
|
22
|
+
OpenAI `terra` tier between `luna` and `sol`. This prevents an older
|
|
23
|
+
`gpt-5.6-luna` from outranking newer `gpt-6.1-sol`/`gpt-6.1-terra` models.
|
|
24
|
+
`gpt-6-luna` now outranks `gpt-5.6-luna`.
|
|
25
|
+
- Order model brands inside a provider family as DeepSeek, OpenAI, Claude,
|
|
26
|
+
Gemini/Gemma, then other gateway brands. For non-tiered brands, order model
|
|
27
|
+
variants as `flash → base → pro` before comparing versions.
|
|
28
|
+
- Alternate fallback now includes sibling models from the current model's
|
|
29
|
+
provider id. A provider-wide failure still skips that provider, while a
|
|
30
|
+
model-specific failure can use a newer sibling instead of jumping to another
|
|
31
|
+
provider.
|
|
32
|
+
|
|
33
|
+
## 0.1.7
|
|
34
|
+
|
|
35
|
+
- Keep recognized URL/URI/link and title/name/ID fields intact when truncating;
|
|
36
|
+
omit entries that cannot fit rather than returning partial links. Preserve
|
|
37
|
+
provider order and drop incomplete URL tokens at text boundaries.
|
|
38
|
+
- Raise the default model-facing output limit from 64,000 to 96,000 Unicode
|
|
39
|
+
code points; the environment override remains available.
|
|
40
|
+
- Replace model-facing truncation metadata and per-string markers with a single
|
|
41
|
+
`[truncated]` line at the end of oversized results. Keep the existing fair
|
|
42
|
+
allocation across search results and fetched pages.
|
|
43
|
+
|
|
3
44
|
## 0.1.6
|
|
4
45
|
|
|
5
46
|
- Keep oversized results as valid JSON, sharing the character budget across
|
package/README.md
CHANGED
|
@@ -81,7 +81,9 @@ The runtime schema is logically:
|
|
|
81
81
|
|
|
82
82
|
- `query` searches the web. Search operators such as `site:`, quotes, `AND`,
|
|
83
83
|
`OR`, and `-term` are passed through unchanged (only outer whitespace is
|
|
84
|
-
trimmed).
|
|
84
|
+
trimmed). If a provider enforces a shorter query limit, its adapter shortens
|
|
85
|
+
only the provider-bound copy at a word boundary; the original query stays in
|
|
86
|
+
the output.
|
|
85
87
|
- `urls` analyzes the listed pages. URLs can be used **alone** or together with
|
|
86
88
|
`query`. A query plus URLs performs a search and then analyzes the URLs.
|
|
87
89
|
- At most **20** URLs may be supplied.
|
|
@@ -137,36 +139,48 @@ support per family.
|
|
|
137
139
|
For a search:
|
|
138
140
|
|
|
139
141
|
1. The current conversation model is tried first when its provider family
|
|
140
|
-
supports web search
|
|
142
|
+
supports web search and neither the provider nor that model is cooling down
|
|
143
|
+
after a recent failure.
|
|
141
144
|
2. A remembered successful provider from the preference cache is tried next
|
|
142
145
|
when the cache fingerprint is current.
|
|
143
146
|
3. The remaining provider families are tried in this fixed order:
|
|
144
147
|
**DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**.
|
|
145
|
-
4. Within a family,
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
148
|
+
4. Within a family, brand order comes first: DeepSeek models, then OpenAI,
|
|
149
|
+
then Claude, then Gemini/Gemma, then other gateway brands. For brands
|
|
150
|
+
without named tiers, variants order `flash → base → pro`; within a variant,
|
|
151
|
+
newer versions come first. GPT and Claude keep version-first ordering, with
|
|
152
|
+
their capability tier as a tiebreaker: OpenAI tiers are
|
|
153
|
+
`luna → terra → sol → astra` and Claude tiers are
|
|
154
|
+
`haiku → sonnet → opus → fable`. Ties are deterministic.
|
|
155
|
+
5. Alternate models from every provider are tried round-robin, so a provider
|
|
156
|
+
that rejects one specific model can still serve a sibling, including a
|
|
157
|
+
newer sibling from the same provider id. A provider-wide failure (auth,
|
|
158
|
+
balance, network, timeout, malformed request) skips the rest of that
|
|
159
|
+
provider; a model-specific failure keeps trying sibling models.
|
|
156
160
|
|
|
157
161
|
URL fetching uses the same idea, but considers only providers that implement
|
|
158
162
|
URL fetching.
|
|
159
163
|
|
|
160
|
-
The current model is
|
|
161
|
-
|
|
162
|
-
model
|
|
164
|
+
The current model is normally tried first when it supports search, unless its
|
|
165
|
+
provider or model is in a failure cooldown. The cache does not replace a
|
|
166
|
+
supported current model; it mainly lets an unsupported current model use a
|
|
167
|
+
remembered compatible provider immediately on later calls.
|
|
163
168
|
|
|
164
169
|
If a provider errors, the extension records the attempt and moves to the next
|
|
165
170
|
interface. Aborts stop immediately. Each attempt has a timeout (60 seconds by
|
|
166
171
|
default, configurable with `PI_BETTER_WEB_SEARCH_TIMEOUT_MS`). If every attempt
|
|
167
|
-
fails, the tool returns an error whose message
|
|
168
|
-
|
|
169
|
-
reports the per-URL failures.
|
|
172
|
+
fails, the tool returns an error whose message contains the provider errors.
|
|
173
|
+
Provider/model routing remains in `details.attempts`. For a URL-only call, the
|
|
174
|
+
error also reports the per-URL failures.
|
|
175
|
+
|
|
176
|
+
Provider-wide failures (auth, balance, network, timeout, malformed request) and
|
|
177
|
+
model-specific failures are remembered for the life of the extension process.
|
|
178
|
+
On later calls the failed provider or model is moved behind healthy candidates
|
|
179
|
+
for search and fetch independently. The cooldown starts at 60 seconds, doubles
|
|
180
|
+
on consecutive failures, and is capped at 10 minutes; a successful call clears
|
|
181
|
+
it. Set `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` to disable this behavior.
|
|
182
|
+
This does not prevent several calls already in flight from trying the same
|
|
183
|
+
candidate at the same time.
|
|
170
184
|
|
|
171
185
|
### Cache fingerprint invalidation
|
|
172
186
|
|
|
@@ -252,20 +266,24 @@ this:
|
|
|
252
266
|
- Redirects are not resolved and sources are not derived.
|
|
253
267
|
- Unknown provider fields are preserved when the result fits the size guard.
|
|
254
268
|
|
|
255
|
-
A final output-size guard limits successful model-facing results to **
|
|
269
|
+
A final output-size guard limits successful model-facing results to **96,000
|
|
256
270
|
Unicode code points** by default. Normal-sized results retain their original
|
|
257
271
|
fields and formatting. If indentation alone exceeds the limit, compact JSON is
|
|
258
272
|
returned without dropping data or setting the truncation flag.
|
|
259
273
|
|
|
260
274
|
When even compact JSON is too large, the guard allocates space across sibling
|
|
261
|
-
fields and array entries, redistributing unused space.
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
entries;
|
|
275
|
+
fields and array entries, redistributing unused space. Recognized link and
|
|
276
|
+
identity fields (`url`, `uri`, `href`, `link`, `title`, `name`, `id`, and common
|
|
277
|
+
aliases) stay complete; if they cannot fit, the associated entry or branch is
|
|
278
|
+
omitted instead. Standalone URLs and entries in link/citation arrays also stay
|
|
279
|
+
whole. When a text cut would split a recognizable embedded URL token (such as
|
|
280
|
+
`https://`, `mailto:`, or `www.`), the incomplete token is omitted. Relative
|
|
281
|
+
links or bare domains in unrecognized fields cannot always be identified. Other long strings may be shortened, and fields or trailing array
|
|
282
|
+
entries omitted; results are not re-ranked or summarized.
|
|
283
|
+
|
|
284
|
+
The JSON portion remains valid, followed by a single `[truncated]` line. No
|
|
285
|
+
truncation metadata or per-string markers are added to the model-facing JSON.
|
|
286
|
+
Because of the trailing line, the complete text is not itself valid JSON.
|
|
269
287
|
`details.truncated` is also set to `true` when data is actually removed.
|
|
270
288
|
|
|
271
289
|
Change the limit **before starting pi**:
|
|
@@ -276,10 +294,12 @@ export PI_BETTER_WEB_SEARCH_MAX_CHARS=100000
|
|
|
276
294
|
|
|
277
295
|
In PowerShell, use `$env:PI_BETTER_WEB_SEARCH_MAX_CHARS = "100000"`. The limit
|
|
278
296
|
is in code points, **not tokens**, and does not adapt to the current model's
|
|
279
|
-
context window.
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
297
|
+
context window. The marker counts toward the limit. If truncation is needed and
|
|
298
|
+
the limit is 11–13 characters, only `[truncated]` is returned; below 11
|
|
299
|
+
characters the marker does not fit and only a minimal JSON value is returned.
|
|
300
|
+
`details.truncated` remains true in both cases. There is no continuation or
|
|
301
|
+
pagination cache: retry individual URLs or raise the limit if more content is
|
|
302
|
+
needed.
|
|
283
303
|
|
|
284
304
|
## Exposure rules
|
|
285
305
|
|
|
@@ -310,8 +330,10 @@ Authorization: Bearer <DeepSeek API Key>
|
|
|
310
330
|
Content-Type: application/json
|
|
311
331
|
```
|
|
312
332
|
|
|
313
|
-
Search uses `query`, `count: 10`, and `need_content: true`.
|
|
314
|
-
|
|
333
|
+
Search uses `query`, `count: 10`, and `need_content: true`. DeepSeek limits
|
|
334
|
+
`query` to 128 Unicode characters, so longer queries are shortened at a word
|
|
335
|
+
boundary for the request only. The raw `results` array is returned unchanged,
|
|
336
|
+
including `rerank_score`, `title`, `url`,
|
|
315
337
|
`snippet`, `summary`, `content`, `site_name`, `site_icon`, `date`, `authority`,
|
|
316
338
|
and any unknown fields.
|
|
317
339
|
|
|
@@ -384,7 +406,7 @@ npm run build
|
|
|
384
406
|
```
|
|
385
407
|
|
|
386
408
|
`npm run build` runs the checks and tests, verifies the npm file list, and packs
|
|
387
|
-
`dist/pi-better-web-search-0.1.
|
|
409
|
+
`dist/pi-better-web-search-0.1.7.tgz`. Nothing is published automatically.
|
|
388
410
|
|
|
389
411
|
The test suite uses plain `.mjs` files that import the `.ts` sources directly.
|
|
390
412
|
It mocks `globalThis.fetch`, uses a temporary cache file, and exercises
|
package/docs/README.zh-CN.md
CHANGED
|
@@ -66,7 +66,8 @@ pi install ./path/to/pi-better-web-search
|
|
|
66
66
|
```
|
|
67
67
|
|
|
68
68
|
- `query` 搜索网页。`site:`、引号、`AND`、`OR`、`-term` 等搜索语法原样传给
|
|
69
|
-
provider
|
|
69
|
+
provider,只去掉首尾空白。如果 provider 有更短的 query 上限,adapter 只会在
|
|
70
|
+
发给该 provider 的副本上按词边界缩短;输出中仍保留原始 query。
|
|
70
71
|
- `urls` 分析指定页面。可以**单独使用**,也可以和 `query` 一起使用。两者同时
|
|
71
72
|
提供时,先搜索,再分析 URL。
|
|
72
73
|
- 最多 **20** 个 URL。
|
|
@@ -116,28 +117,36 @@ Provider 识别顺序:
|
|
|
116
117
|
|
|
117
118
|
搜索顺序:
|
|
118
119
|
|
|
119
|
-
1.
|
|
120
|
+
1. 当前模型支持搜索,且对应 provider 和该模型都不在失败冷却期时,优先当前模型。
|
|
120
121
|
2. 缓存指纹有效时,使用记住的搜索 provider。
|
|
121
122
|
3. 其余 provider family 按固定顺序尝试:
|
|
122
123
|
**DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**。
|
|
123
|
-
4. 同一 family
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
provider
|
|
130
|
-
|
|
124
|
+
4. 同一 family 内先按品牌排序:DeepSeek 模型、OpenAI、Claude、Gemini/Gemma,
|
|
125
|
+
然后其他网关品牌。没有命名等级的品牌按变体 `flash → base → pro` 排序,同一变体
|
|
126
|
+
内版本号从新到旧;GPT 和 Claude 仍按版本优先,版本相同时才按能力等级排序
|
|
127
|
+
(便宜的等级优先,未知等级排最后):OpenAI 为 `luna → terra → sol → astra`,
|
|
128
|
+
Claude 为 `haiku → sonnet → opus → fable`。
|
|
129
|
+
5. 所有 provider 的备用模型都会按 round-robin 继续尝试,包括当前模型同一
|
|
130
|
+
provider id 下的其他模型,这样即使某个账号拒绝某个具体模型,也能换用同
|
|
131
|
+
provider 的更新模型。provider 级失败(鉴权、余额、网络、超时、请求头异常)
|
|
132
|
+
会跳过该 provider 的其余模型;模型级失败则继续尝试同 provider 的其他模型。
|
|
131
133
|
|
|
132
134
|
URL 抓取使用同样的思路,但只考虑实现了 URL 抓取的 provider。
|
|
133
135
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
+
当前模型支持搜索时通常优先当前模型,除非该 provider 或该模型正处于失败冷却期。
|
|
137
|
+
缓存不会覆盖它。缓存主要用于当前模型不支持搜索时,让下一次调用直接使用之前成功
|
|
138
|
+
的兼容 provider。
|
|
136
139
|
|
|
137
140
|
Provider 报错时记录 attempt 并继续下一个接口。取消会立即停止。每次尝试有
|
|
138
141
|
超时(默认 60 秒,`PI_BETTER_WEB_SEARCH_TIMEOUT_MS` 可调)。所有尝试都失败时,
|
|
139
|
-
|
|
140
|
-
URL 的失败原因。
|
|
142
|
+
工具返回错误,消息中包含 provider 返回的错误;provider/model 路由信息保留在
|
|
143
|
+
`details.attempts` 中。URL-only 调用还会报告每个 URL 的失败原因。
|
|
144
|
+
|
|
145
|
+
Provider 级失败(鉴权、余额、网络、超时、请求头异常)和单个模型失败都会在扩展进程内
|
|
146
|
+
记住。后续调用会把失败的 provider 或模型排到健康候选之后,搜索和 URL 抓取分别记录。
|
|
147
|
+
冷却时间从 60 秒开始,连续失败时翻倍,最多 10 分钟;成功一次后清除。设置
|
|
148
|
+
`PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` 可禁用。已经在途的并发调用仍可能同时
|
|
149
|
+
尝试同一个候选。
|
|
141
150
|
|
|
142
151
|
### 缓存指纹失效
|
|
143
152
|
|
|
@@ -217,18 +226,23 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
|
|
|
217
226
|
- 不解析 redirect,不派生 sources。
|
|
218
227
|
- 未超出大小限制时,provider 的未知字段也会保留。
|
|
219
228
|
|
|
220
|
-
最终大小保护默认限制成功结果不超过 **
|
|
229
|
+
最终大小保护默认限制成功结果不超过 **96,000 个 Unicode code point**。
|
|
221
230
|
未超限时保留原始字段及格式;如果只是缩进导致超限,会先压缩 JSON,
|
|
222
231
|
不丢失数据,也不标记为截断。
|
|
223
232
|
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
`
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
233
|
+
压缩后仍超限时,按字段和数组条目分配预算,未用完的额度会重新分配。
|
|
234
|
+
已识别的链接及标识字段(包括 `url`、`uri`、`href`、`link`、`title`、
|
|
235
|
+
`name`、`id` 和常见别名)保持完整;放不下时省略对应条目或分支,而不是
|
|
236
|
+
返回半截值。独立 URL 和链接、引用数组中的条目也保持完整;正文截断点
|
|
237
|
+
若落在可识别的 URL(如 `https://`、`mailto:` 或 `www.`)中间,会省略该
|
|
238
|
+
未完整显示的 URL。未知字段中的相对链接或裸域名无法保证都能识别。
|
|
239
|
+
其他长字符串可能被缩短,字段或数组末尾的条目可能被省略;
|
|
240
|
+
不对结果重排或总结。
|
|
241
|
+
|
|
242
|
+
JSON 部分仍然合法,末尾仅追加一行 `[truncated]`。不会向模型可见的 JSON
|
|
243
|
+
中添加截断元数据,也不会逐个标记缩短的字符串。由于末尾追加了这一行,
|
|
244
|
+
整个文本不再是合法 JSON。确实丢失数据时,`details.truncated` 也会设为
|
|
245
|
+
`true`。
|
|
232
246
|
|
|
233
247
|
可在**启动 pi 之前**通过环境变量调整:
|
|
234
248
|
|
|
@@ -238,9 +252,10 @@ export PI_BETTER_WEB_SEARCH_MAX_CHARS=100000
|
|
|
238
252
|
|
|
239
253
|
PowerShell 使用 `$env:PI_BETTER_WEB_SEARCH_MAX_CHARS = "100000"`。
|
|
240
254
|
上限是 code point,**不是 token**,不会根据当前模型的上下文窗口自动调整。
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
255
|
+
标记也计入上限。需要截断且上限为 11–13 字符时,只返回 `[truncated]`;
|
|
256
|
+
少于 11 字符时放不下标记,只返回一个最小 JSON 值。这两种情况仍会通过
|
|
257
|
+
`details.truncated` 报告截断。当前没有续读或分页缓存;需要更多内容时可
|
|
258
|
+
单独重新抓取 URL 或提高上限。
|
|
244
259
|
|
|
245
260
|
## 暴露规则
|
|
246
261
|
|
|
@@ -262,8 +277,9 @@ Authorization: Bearer <DeepSeek API Key>
|
|
|
262
277
|
Content-Type: application/json
|
|
263
278
|
```
|
|
264
279
|
|
|
265
|
-
搜索使用 `query`、`count: 10`、`need_content: true
|
|
266
|
-
|
|
280
|
+
搜索使用 `query`、`count: 10`、`need_content: true`。DeepSeek 的 `query` 上限为
|
|
281
|
+
128 个 Unicode 字符,因此超长 query 只在请求中按词边界缩短。原始 `results`
|
|
282
|
+
数组原样返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
|
|
267
283
|
`site_name`、`site_icon`、`date`、`authority` 和未知字段。
|
|
268
284
|
|
|
269
285
|
Fetch 发送 `{ "url": "..." }`,原样保存 `{ title, content }`。URL 最长 8192
|
|
@@ -323,7 +339,7 @@ npm run build
|
|
|
323
339
|
```
|
|
324
340
|
|
|
325
341
|
`npm run build` 会运行检查、测试、包内容验证,并生成
|
|
326
|
-
`dist/pi-better-web-search-0.1.
|
|
342
|
+
`dist/pi-better-web-search-0.1.7.tgz`。不会自动发布。
|
|
327
343
|
|
|
328
344
|
测试是 `.mjs` 文件,直接导入 `.ts` 源码,mock `globalThis.fetch`,使用临时缓存
|
|
329
345
|
目录。详见 [测试](testing.md) 和 [发布](publishing.md)。
|
package/docs/architecture.md
CHANGED
|
@@ -14,8 +14,9 @@ output guard. It does not own provider result cleanup.
|
|
|
14
14
|
4. **Use provider-native interfaces.** Each family keeps its request shape,
|
|
15
15
|
authentication quirks, and stream format.
|
|
16
16
|
5. **Prefer the current model, remember fallbacks.** A supported current model
|
|
17
|
-
is tried first
|
|
18
|
-
provider
|
|
17
|
+
is tried first unless its provider is cooling down after a recent
|
|
18
|
+
provider-wide failure. An unsupported current model uses the remembered
|
|
19
|
+
compatible provider first.
|
|
19
20
|
6. **Do not touch pi's system prompt.** No prompt snippets, guidelines, loadout
|
|
20
21
|
hooks, commands, or extra tools.
|
|
21
22
|
|
|
@@ -72,26 +73,34 @@ Search candidates:
|
|
|
72
73
|
2. The remembered search provider when the cache fingerprint is current.
|
|
73
74
|
3. One candidate per remaining family in this order:
|
|
74
75
|
**DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**.
|
|
75
|
-
4. Alternate models from every provider
|
|
76
|
-
id, round-robin across families, up to 12 attempts. A
|
|
77
|
-
|
|
76
|
+
4. Alternate models from every provider, including the current model's
|
|
77
|
+
provider id, round-robin across families, up to 12 attempts. A provider-wide
|
|
78
|
+
failure still skips that provider id; a model-specific failure can use a
|
|
79
|
+
sibling model from the same provider.
|
|
78
80
|
|
|
79
81
|
Fetch candidates use the same shape but include only adapters with
|
|
80
82
|
`supportsUrls` and a `fetch` implementation. The fetch cap is 6 attempts.
|
|
81
83
|
|
|
82
|
-
Within a family, models are ordered by
|
|
83
|
-
|
|
84
|
-
`
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
`
|
|
84
|
+
Within a family, models are ordered by brand first: DeepSeek, OpenAI, Claude,
|
|
85
|
+
Gemini/Gemma, then other gateway brands. Brands without named tiers use variant
|
|
86
|
+
order `flash → base → pro`, then version number, newest first. GPT and Claude
|
|
87
|
+
use version number first, newest first, with capability tier as a tiebreaker:
|
|
88
|
+
OpenAI uses `luna → terra → sol → astra` and Claude uses
|
|
89
|
+
`haiku → sonnet → opus → fable`. Ties fall back to the deterministic
|
|
90
|
+
`provider/id@baseUrl` order.
|
|
88
91
|
A provider id is only retried with another model when the first failure was
|
|
89
92
|
model-specific; provider-wide failures (auth, balance, network, timeout,
|
|
90
|
-
malformed request) skip the rest of that provider.
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
93
|
+
malformed request) skip the rest of that provider. Provider failures and
|
|
94
|
+
model-specific failures are remembered per phase (search/fetch) for the life of
|
|
95
|
+
the process. On later calls the failed provider or model is moved behind healthy
|
|
96
|
+
candidates for a 60-second to 10-minute exponential cooldown; a success clears
|
|
97
|
+
it. Calls already in flight are not cancelled or reordered.
|
|
98
|
+
|
|
99
|
+
The current model is preferred when it supports search and neither its provider
|
|
100
|
+
nor that model is cooling down. The cache is a fallback, not an override. When
|
|
101
|
+
the current model
|
|
102
|
+
is unsupported, the cached provider is tried first, which avoids repeating
|
|
103
|
+
discovery on every call.
|
|
95
104
|
|
|
96
105
|
## Cache and fingerprint
|
|
97
106
|
|
|
@@ -125,6 +134,8 @@ be used. A cached provider that is no longer available is ignored.
|
|
|
125
134
|
## Input validation
|
|
126
135
|
|
|
127
136
|
- `query` is trimmed; search operators are otherwise passed through unchanged.
|
|
137
|
+
Provider adapters may shorten the provider-bound copy when that provider has
|
|
138
|
+
a lower query-length limit; the model-facing output keeps the original query.
|
|
128
139
|
- `urls` is an array of at most 20 strings.
|
|
129
140
|
- Each URL must be HTTP/HTTPS, have a host, omit username/password, and be at
|
|
130
141
|
most 8192 characters.
|
|
@@ -161,15 +172,21 @@ The result is a JSON wrapper:
|
|
|
161
172
|
Fields inside `search` and `fetched[].data` are provider data. The extension does
|
|
162
173
|
not deduplicate, normalize, filter, re-rank, summarize, insert citation markers,
|
|
163
174
|
or append source sections. The final guard keeps successful model-facing output
|
|
164
|
-
within
|
|
175
|
+
within 96,000 Unicode code points by default (`PI_BETTER_WEB_SEARCH_MAX_CHARS`).
|
|
165
176
|
It preserves ordinary formatted JSON, or uses compact JSON if that alone fits.
|
|
166
|
-
Otherwise it budgets sibling fields and array entries independently
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
177
|
+
Otherwise it budgets sibling fields and array entries independently. Recognized
|
|
178
|
+
link and identity fields stay whole; entries or branches that cannot fit them
|
|
179
|
+
are omitted instead, without re-ranking. Standalone URLs and link/citation array
|
|
180
|
+
entries remain intact, and a recognizable URL crossing a text cut is omitted
|
|
181
|
+
rather than partially emitted. Unknown relative links or bare domains may not be
|
|
182
|
+
identifiable. Other strings can be shortened, and fields or trailing array entries
|
|
183
|
+
omitted. The JSON portion
|
|
184
|
+
stays valid, followed by one `[truncated]` line; the complete text is therefore
|
|
185
|
+
not valid JSON. No truncation metadata is injected into the model-facing JSON,
|
|
186
|
+
while `details.truncated` marks actual data loss. When truncation is needed with a limit of 11–13 characters,
|
|
187
|
+
only the marker is returned; below 11, a minimal JSON value is returned instead.
|
|
188
|
+
This is a character guard, not a token or model-context limit; it does not
|
|
189
|
+
provide pagination or retain the complete provider payload for later use.
|
|
173
190
|
|
|
174
191
|
## Provider adapter contract
|
|
175
192
|
|
|
@@ -208,6 +225,7 @@ the abort signal and resolve credentials through `lib/auth.ts`.
|
|
|
208
225
|
| `extensions/index.ts` | Tool registration, exposure sync, lifecycle handlers |
|
|
209
226
|
| `lib/candidates.ts` | Current/available candidates, ordering, cache resolution |
|
|
210
227
|
| `lib/search.ts` | Input validation, search/fetch fallback, cache writes, output |
|
|
228
|
+
| `lib/health.ts` | Provider-wide failure cooldowns and candidate reordering |
|
|
211
229
|
| `lib/auth.ts` | Credential resolution, header merging, env fallback |
|
|
212
230
|
| `lib/cache.ts` | Preference cache and model-set fingerprint |
|
|
213
231
|
| `lib/families.ts` | Provider family detection |
|
package/docs/providers.md
CHANGED
|
@@ -55,7 +55,9 @@ POST https://api.deepseek.com/v1/tools/search
|
|
|
55
55
|
```
|
|
56
56
|
|
|
57
57
|
- `query` is 1–128 Unicode characters, not all whitespace. Search operators are
|
|
58
|
-
passed through unchanged.
|
|
58
|
+
passed through unchanged. Longer agent-generated queries are shortened at a
|
|
59
|
+
word boundary for the DeepSeek request only; the original query is retained
|
|
60
|
+
in the model-facing output.
|
|
59
61
|
- `count` is within the documented 1–50 range; this package uses 10.
|
|
60
62
|
- `need_content` is `true`, so `content` can contain the page body. The output
|
|
61
63
|
character guard protects the model context.
|
package/docs/publishing.md
CHANGED
|
@@ -30,7 +30,7 @@ local `pi-web-search` reference checkout, `.env` files, and `DESIGN.md`.
|
|
|
30
30
|
npm run build
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
This produces `dist/pi-better-web-search-0.1.
|
|
33
|
+
This produces `dist/pi-better-web-search-0.1.7.tgz`. The tarball is not
|
|
34
34
|
committed.
|
|
35
35
|
|
|
36
36
|
## Publish
|
|
@@ -42,7 +42,7 @@ npm publish --access public
|
|
|
42
42
|
Alternatively, publish the verified tarball directly:
|
|
43
43
|
|
|
44
44
|
```bash
|
|
45
|
-
npm publish dist/pi-better-web-search-0.1.
|
|
45
|
+
npm publish dist/pi-better-web-search-0.1.7.tgz --access public
|
|
46
46
|
```
|
|
47
47
|
|
|
48
48
|
`prepublishOnly` reruns the checks, tests, and package verification. npm may
|
|
@@ -51,10 +51,10 @@ require browser or OTP authentication.
|
|
|
51
51
|
## Tag and release
|
|
52
52
|
|
|
53
53
|
```bash
|
|
54
|
-
git tag -a v0.1.
|
|
55
|
-
git push origin v0.1.
|
|
56
|
-
gh release create v0.1.
|
|
57
|
-
--title "v0.1.
|
|
54
|
+
git tag -a v0.1.7 -m "v0.1.7"
|
|
55
|
+
git push origin v0.1.7
|
|
56
|
+
gh release create v0.1.7 dist/pi-better-web-search-0.1.7.tgz \
|
|
57
|
+
--title "v0.1.7" \
|
|
58
58
|
--notes-file /path/to/release-notes.md
|
|
59
59
|
```
|
|
60
60
|
|
package/docs/testing.md
CHANGED
|
@@ -17,7 +17,7 @@ npm run verify:package
|
|
|
17
17
|
tarball contains runtime sources, docs, assets, and metadata, while excluding
|
|
18
18
|
tests, scripts, CI files, the local reference checkout, and `DESIGN.md`.
|
|
19
19
|
- `npm run build` runs the checks, tests, package verification, and packs
|
|
20
|
-
`dist/pi-better-web-search-0.1.
|
|
20
|
+
`dist/pi-better-web-search-0.1.7.tgz`.
|
|
21
21
|
|
|
22
22
|
Tests import the TypeScript sources directly. The suite mocks `globalThis.fetch`
|
|
23
23
|
and uses temporary cache directories. Coverage includes:
|
|
@@ -30,8 +30,9 @@ and uses temporary cache directories. Coverage includes:
|
|
|
30
30
|
- search and fetch fallback, including per-URL fallback;
|
|
31
31
|
- provider request shapes and SSE parsing;
|
|
32
32
|
- HTTP/stream errors and abort propagation;
|
|
33
|
-
- structured character-guard truncation,
|
|
34
|
-
|
|
33
|
+
- structured character-guard truncation, a single trailing marker, valid JSON
|
|
34
|
+
before the marker, Unicode and escaping, boundary lengths, fair allocation,
|
|
35
|
+
and intact links and identifiers across search results and fetched pages;
|
|
35
36
|
- one-tool registration and no system-prompt hooks.
|
|
36
37
|
|
|
37
38
|
## Live DeepSeek test
|