pi-better-web-search 0.1.7 → 0.1.9
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 +46 -0
- package/README.md +61 -33
- package/docs/README.zh-CN.md +46 -28
- package/docs/architecture.md +45 -25
- package/docs/providers.md +9 -4
- package/docs/publishing.md +6 -6
- package/docs/testing.md +1 -1
- package/lib/candidates.ts +127 -50
- package/lib/format.ts +9 -2
- package/lib/health.ts +159 -0
- package/lib/providers/deepseek.ts +12 -10
- package/lib/providers/http.ts +56 -6
- package/lib/providers/ollama.ts +5 -2
- package/lib/providers/types.ts +20 -0
- package/lib/search.ts +127 -21
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,51 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.9
|
|
4
|
+
|
|
5
|
+
- Preserve provider diversity and apply cooldowns before limiting actual search
|
|
6
|
+
and fetch attempts, so skipped siblings cannot crowd out healthy providers.
|
|
7
|
+
- Reject DeepSeek search queries over 128 Unicode characters with a generic,
|
|
8
|
+
actionable `Search query is too long` error instead of silently shortening
|
|
9
|
+
them or trying a fallback.
|
|
10
|
+
- Distinguish model-access 403 errors from provider-wide failures, and track
|
|
11
|
+
URL-fetch transport failures while preserving partial successes.
|
|
12
|
+
- Count concurrent failures during one cooldown as a single outage; increase
|
|
13
|
+
backoff only when a subsequent attempt after expiry also fails.
|
|
14
|
+
- Bound HTTP error bodies, individual attempt messages, and model-facing error
|
|
15
|
+
text. Fix Claude version parsing when a date follows the major version.
|
|
16
|
+
- Clarify that brand ranking only covers supported APIs, and test OpenCode Go
|
|
17
|
+
against the actual pi model catalog rather than a fabricated API assignment.
|
|
18
|
+
|
|
19
|
+
## 0.1.8
|
|
20
|
+
|
|
21
|
+
- Shorten overlong DeepSeek search queries at a word boundary before sending
|
|
22
|
+
them to the provider. DeepSeek rejects queries above 128 Unicode characters,
|
|
23
|
+
so concurrent agent search batches with long queries previously failed with
|
|
24
|
+
the generic unavailable error while shorter sibling calls succeeded. The
|
|
25
|
+
original query remains in the model-facing output.
|
|
26
|
+
- Return the provider errors when every search attempt fails, instead of
|
|
27
|
+
replacing them with the generic unavailable message. For example, an OpenAI
|
|
28
|
+
timeout and a DeepSeek validation error are now both visible to the model.
|
|
29
|
+
- Remember provider-wide and model-specific failures per search/fetch phase and
|
|
30
|
+
move the failed provider or model behind healthy candidates on later calls.
|
|
31
|
+
The cooldown is exponential (60s to 10 minutes) and is cleared by a
|
|
32
|
+
successful call. Configure with `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS`;
|
|
33
|
+
set it to `0` to disable.
|
|
34
|
+
- Surface provider error text without prepending provider/model labels to the
|
|
35
|
+
model-facing message.
|
|
36
|
+
- Rank GPT and Claude models by version number first, newest first; capability
|
|
37
|
+
tier is now only a tiebreaker for the same version. Add the
|
|
38
|
+
OpenAI `terra` tier between `luna` and `sol`. This prevents an older
|
|
39
|
+
`gpt-5.6-luna` from outranking newer `gpt-6.1-sol`/`gpt-6.1-terra` models.
|
|
40
|
+
`gpt-6-luna` now outranks `gpt-5.6-luna`.
|
|
41
|
+
- Order model brands inside a provider family as DeepSeek, OpenAI, Claude,
|
|
42
|
+
Gemini/Gemma, then other gateway brands. For non-tiered brands, order model
|
|
43
|
+
variants as `flash → base → pro` before comparing versions.
|
|
44
|
+
- Alternate fallback now includes sibling models from the current model's
|
|
45
|
+
provider id. A provider-wide failure still skips that provider, while a
|
|
46
|
+
model-specific failure can use a newer sibling instead of jumping to another
|
|
47
|
+
provider.
|
|
48
|
+
|
|
3
49
|
## 0.1.7
|
|
4
50
|
|
|
5
51
|
- Keep recognized URL/URI/link and title/name/ID fields intact when truncating;
|
package/README.md
CHANGED
|
@@ -17,6 +17,9 @@ and returns provider data as-is.
|
|
|
17
17
|
|
|
18
18
|

|
|
19
19
|
|
|
20
|
+
> The npm registry may lag GitHub releases. If the version you want is not yet
|
|
21
|
+
> published to npm, install the tagged GitHub release below instead.
|
|
22
|
+
|
|
20
23
|
```bash
|
|
21
24
|
pi install npm:pi-better-web-search
|
|
22
25
|
```
|
|
@@ -26,7 +29,7 @@ Then start a new pi process, or run `/reload` in an existing session.
|
|
|
26
29
|
GitHub and local installations also work:
|
|
27
30
|
|
|
28
31
|
```bash
|
|
29
|
-
pi install git:github.com/zhexusun10/pi-better-web-search
|
|
32
|
+
pi install git:github.com/zhexusun10/pi-better-web-search@v0.1.9
|
|
30
33
|
pi install ./path/to/pi-better-web-search
|
|
31
34
|
```
|
|
32
35
|
|
|
@@ -79,9 +82,11 @@ The runtime schema is logically:
|
|
|
79
82
|
}
|
|
80
83
|
```
|
|
81
84
|
|
|
82
|
-
- `query` searches the web.
|
|
83
|
-
|
|
84
|
-
|
|
85
|
+
- `query` searches the web. Outer whitespace is trimmed; search operators are
|
|
86
|
+
otherwise passed through unchanged. If DeepSeek is selected and the query
|
|
87
|
+
exceeds 128 Unicode characters, the tool returns an error with the actual
|
|
88
|
+
length and limit, asking the model to shorten the query and retry. It does not
|
|
89
|
+
send the query or silently truncate it. Other providers may accept longer queries.
|
|
85
90
|
- `urls` analyzes the listed pages. URLs can be used **alone** or together with
|
|
86
91
|
`query`. A query plus URLs performs a search and then analyzes the URLs.
|
|
87
92
|
- At most **20** URLs may be supplied.
|
|
@@ -137,36 +142,54 @@ support per family.
|
|
|
137
142
|
For a search:
|
|
138
143
|
|
|
139
144
|
1. The current conversation model is tried first when its provider family
|
|
140
|
-
supports web search
|
|
145
|
+
supports web search and neither the provider nor that model is cooling down
|
|
146
|
+
after a recent failure.
|
|
141
147
|
2. A remembered successful provider from the preference cache is tried next
|
|
142
148
|
when the cache fingerprint is current.
|
|
143
149
|
3. The remaining provider families are tried in this fixed order:
|
|
144
150
|
**DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**.
|
|
145
|
-
4. Within a family,
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
URL fetching.
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
151
|
+
4. Within a family, brand order comes first: DeepSeek models, then OpenAI,
|
|
152
|
+
then Claude, then Gemini/Gemma, then other gateway brands. For brands
|
|
153
|
+
without named tiers, variants order `flash → base → pro`; within a variant,
|
|
154
|
+
newer versions come first. GPT and Claude keep version-first ordering, with
|
|
155
|
+
their capability tier as a tiebreaker: OpenAI tiers are
|
|
156
|
+
`luna → terra → sol → astra` and Claude tiers are
|
|
157
|
+
`haiku → sonnet → opus → fable`. Ties are deterministic.
|
|
158
|
+
5. Alternate providers are considered before additional models of an already
|
|
159
|
+
represented provider; siblings are then tried round-robin across families.
|
|
160
|
+
A provider-wide failure skips that provider, while a model-specific failure
|
|
161
|
+
(including a model-specific 403) can fall back to a sibling.
|
|
162
|
+
|
|
163
|
+
The search limit is 12 actual attempts; skipped candidates do not consume it.
|
|
164
|
+
URL fetching follows the same idea with a separate limit of 6 actual attempts.
|
|
165
|
+
Model ranking applies only to supported APIs: for example, the built-in
|
|
166
|
+
`opencode-go` DeepSeek models use `openai-completions`, which this extension
|
|
167
|
+
cannot search through and does not reinterpret as Responses.
|
|
168
|
+
|
|
169
|
+
The current model is normally tried first when it supports search, unless its
|
|
170
|
+
provider or model is in a failure cooldown. The cache does not replace a
|
|
171
|
+
supported current model; it mainly lets an unsupported current model use a
|
|
172
|
+
remembered compatible provider immediately on later calls.
|
|
163
173
|
|
|
164
174
|
If a provider errors, the extension records the attempt and moves to the next
|
|
165
|
-
interface.
|
|
175
|
+
interface. An overlong query rejected by DeepSeek instead returns immediately
|
|
176
|
+
without trying another provider or updating its health state. Aborts stop immediately. Each attempt has a timeout (60 seconds by
|
|
166
177
|
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.
|
|
178
|
+
fails, the tool returns an error whose message contains the provider errors.
|
|
179
|
+
Provider/model routing remains in `details.attempts`. For a URL-only call, the
|
|
180
|
+
error also reports the per-URL failures. Provider error bodies and model-facing
|
|
181
|
+
error text are bounded to prevent an oversized error from filling the context.
|
|
182
|
+
|
|
183
|
+
Provider-wide failures (auth, balance, network, timeout, malformed request) and
|
|
184
|
+
model-specific failures are remembered for the life of the extension process.
|
|
185
|
+
On later calls the failed provider or model is moved behind healthy candidates
|
|
186
|
+
for search and fetch independently. The cooldown starts at 60 seconds, doubles
|
|
187
|
+
when a subsequent attempt after expiry fails, and is capped at 10 minutes.
|
|
188
|
+
Concurrent failures during the same cooldown do not extend it; a successful
|
|
189
|
+
search or a fetch with at least one successful URL and no provider transport
|
|
190
|
+
error clears it. Set
|
|
191
|
+
`PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` to disable this behavior. Calls
|
|
192
|
+
already in flight may still try the same candidate at the same time.
|
|
170
193
|
|
|
171
194
|
### Cache fingerprint invalidation
|
|
172
195
|
|
|
@@ -252,7 +275,7 @@ this:
|
|
|
252
275
|
- Redirects are not resolved and sources are not derived.
|
|
253
276
|
- Unknown provider fields are preserved when the result fits the size guard.
|
|
254
277
|
|
|
255
|
-
A final output-size guard limits
|
|
278
|
+
A final output-size guard limits model-facing results and errors to **96,000
|
|
256
279
|
Unicode code points** by default. Normal-sized results retain their original
|
|
257
280
|
fields and formatting. If indentation alone exceeds the limit, compact JSON is
|
|
258
281
|
returned without dropping data or setting the truncation flag.
|
|
@@ -268,7 +291,7 @@ links or bare domains in unrecognized fields cannot always be identified. Other
|
|
|
268
291
|
entries omitted; results are not re-ranked or summarized.
|
|
269
292
|
|
|
270
293
|
The JSON portion remains valid, followed by a single `[truncated]` line. No
|
|
271
|
-
truncation metadata or per-string markers are added to the
|
|
294
|
+
output-size truncation metadata or per-string markers are added to the JSON.
|
|
272
295
|
Because of the trailing line, the complete text is not itself valid JSON.
|
|
273
296
|
`details.truncated` is also set to `true` when data is actually removed.
|
|
274
297
|
|
|
@@ -316,8 +339,13 @@ Authorization: Bearer <DeepSeek API Key>
|
|
|
316
339
|
Content-Type: application/json
|
|
317
340
|
```
|
|
318
341
|
|
|
319
|
-
Search uses `query`, `count: 10`, and `need_content: true`.
|
|
320
|
-
|
|
342
|
+
Search uses `query`, `count: 10`, and `need_content: true`. DeepSeek limits
|
|
343
|
+
`query` to 128 Unicode characters. Longer queries return an error before any
|
|
344
|
+
DeepSeek request is sent; the model should shorten the query and retry. For
|
|
345
|
+
example: `Search query is too long (129 Unicode characters). The maximum is
|
|
346
|
+
128 Unicode characters. Shorten the query and retry.` The raw `results` array
|
|
347
|
+
is returned unchanged,
|
|
348
|
+
including `rerank_score`, `title`, `url`,
|
|
321
349
|
`snippet`, `summary`, `content`, `site_name`, `site_icon`, `date`, `authority`,
|
|
322
350
|
and any unknown fields.
|
|
323
351
|
|
|
@@ -348,7 +376,7 @@ See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
|
|
|
348
376
|
|
|
349
377
|
## Verified
|
|
350
378
|
|
|
351
|
-
- **
|
|
379
|
+
- **Unit and integration tests** covering exposure, schema variants,
|
|
352
380
|
provider request shapes, SSE parsing, raw-result preservation, fallback,
|
|
353
381
|
cache invalidation, URL handling, truncation, and abort behavior.
|
|
354
382
|
- **Real DeepSeek Search/Fetch run** with a real API key: 10 raw search results,
|
|
@@ -390,7 +418,7 @@ npm run build
|
|
|
390
418
|
```
|
|
391
419
|
|
|
392
420
|
`npm run build` runs the checks and tests, verifies the npm file list, and packs
|
|
393
|
-
`dist/pi-better-web-search-0.1.
|
|
421
|
+
`dist/pi-better-web-search-0.1.9.tgz`. Nothing is published automatically.
|
|
394
422
|
|
|
395
423
|
The test suite uses plain `.mjs` files that import the `.ts` sources directly.
|
|
396
424
|
It mocks `globalThis.fetch`, uses a temporary cache file, and exercises
|
package/docs/README.zh-CN.md
CHANGED
|
@@ -10,6 +10,9 @@
|
|
|
10
10
|
|
|
11
11
|

|
|
12
12
|
|
|
13
|
+
> npm 版本可能落后于 GitHub Release。如果所需版本尚未发布到 npm,可使用
|
|
14
|
+
> 下方指定标签的 GitHub 安装方式。
|
|
15
|
+
|
|
13
16
|
```bash
|
|
14
17
|
pi install npm:pi-better-web-search
|
|
15
18
|
```
|
|
@@ -19,7 +22,7 @@ pi install npm:pi-better-web-search
|
|
|
19
22
|
也可以从 GitHub 或本地安装:
|
|
20
23
|
|
|
21
24
|
```bash
|
|
22
|
-
pi install git:github.com/zhexusun10/pi-better-web-search
|
|
25
|
+
pi install git:github.com/zhexusun10/pi-better-web-search@v0.1.9
|
|
23
26
|
pi install ./path/to/pi-better-web-search
|
|
24
27
|
```
|
|
25
28
|
|
|
@@ -65,8 +68,9 @@ pi install ./path/to/pi-better-web-search
|
|
|
65
68
|
}
|
|
66
69
|
```
|
|
67
70
|
|
|
68
|
-
- `query`
|
|
69
|
-
|
|
71
|
+
- `query` 搜索网页,只去掉首尾空白,搜索语法其余部分原样保留。如果选中
|
|
72
|
+
DeepSeek 且 query 超过 128 个 Unicode 字符,工具会直接返回实际长度和上限,
|
|
73
|
+
提示模型缩短后重试;不会发送请求或静默截断。其他 provider 可以接受更长的查询。
|
|
70
74
|
- `urls` 分析指定页面。可以**单独使用**,也可以和 `query` 一起使用。两者同时
|
|
71
75
|
提供时,先搜索,再分析 URL。
|
|
72
76
|
- 最多 **20** 个 URL。
|
|
@@ -116,28 +120,41 @@ Provider 识别顺序:
|
|
|
116
120
|
|
|
117
121
|
搜索顺序:
|
|
118
122
|
|
|
119
|
-
1.
|
|
123
|
+
1. 当前模型支持搜索,且对应 provider 和该模型都不在失败冷却期时,优先当前模型。
|
|
120
124
|
2. 缓存指纹有效时,使用记住的搜索 provider。
|
|
121
125
|
3. 其余 provider family 按固定顺序尝试:
|
|
122
126
|
**DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**。
|
|
123
|
-
4. 同一 family
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
provider
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
127
|
+
4. 同一 family 内先按品牌排序:DeepSeek 模型、OpenAI、Claude、Gemini/Gemma,
|
|
128
|
+
然后其他网关品牌。没有命名等级的品牌按变体 `flash → base → pro` 排序,同一变体
|
|
129
|
+
内版本号从新到旧;GPT 和 Claude 仍按版本优先,版本相同时才按能力等级排序
|
|
130
|
+
(便宜的等级优先,未知等级排最后):OpenAI 为 `luna → terra → sol → astra`,
|
|
131
|
+
Claude 为 `haiku → sonnet → opus → fable`。
|
|
132
|
+
5. 优先尝试尚未覆盖的 provider,再按 family 的 round-robin 尝试各 provider
|
|
133
|
+
的备用模型。provider 级失败会跳过该 provider;模型级失败(包括模型权限 403)
|
|
134
|
+
则可继续尝试同 provider 的其他模型。
|
|
135
|
+
|
|
136
|
+
搜索最多发起 12 次实际尝试;URL 抓取采用同样的思路,最多发起 6 次。跳过的候选
|
|
137
|
+
不占用次数。排序只适用于支持的 API:例如内置的 `opencode-go` DeepSeek 模型
|
|
138
|
+
使用 `openai-completions`,本扩展不会将它们当作 Responses 搜索接口。
|
|
139
|
+
|
|
140
|
+
当前模型支持搜索时通常优先当前模型,除非该 provider 或该模型正处于失败冷却期。
|
|
141
|
+
缓存不会覆盖它。缓存主要用于当前模型不支持搜索时,让下一次调用直接使用之前成功
|
|
142
|
+
的兼容 provider。
|
|
143
|
+
|
|
144
|
+
Provider 报错时记录 attempt 并继续下一个接口。DeepSeek 查询超长则直接返回错误,
|
|
145
|
+
不继续尝试其他 provider,也不记录为 provider 健康故障。取消会立即停止。每次尝试有
|
|
138
146
|
超时(默认 60 秒,`PI_BETTER_WEB_SEARCH_TIMEOUT_MS` 可调)。所有尝试都失败时,
|
|
139
|
-
|
|
140
|
-
URL 的失败原因。
|
|
147
|
+
工具返回错误,消息中包含 provider 返回的错误;provider/model 路由信息保留在
|
|
148
|
+
`details.attempts` 中。URL-only 调用还会报告每个 URL 的失败原因。provider 错误
|
|
149
|
+
响应体与发给模型的错误文本都有大小限制,避免错误内容占满上下文。
|
|
150
|
+
|
|
151
|
+
Provider 级失败(鉴权、余额、网络、超时、请求头异常)和单个模型失败都会在扩展进程内
|
|
152
|
+
记住。后续调用会把失败的 provider 或模型排到健康候选之后,搜索和 URL 抓取分别记录。
|
|
153
|
+
冷却时间从 60 秒开始,冷却结束后的再次尝试失败时翻倍,最多 10 分钟;同一冷却期内
|
|
154
|
+
的并发失败不会延长时间。搜索成功,或至少一个 URL 抓取成功且没有 provider
|
|
155
|
+
网络错误时,清除对应冷却。设置
|
|
156
|
+
`PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` 可禁用。已经在途的并发调用仍可能同时
|
|
157
|
+
尝试同一个候选。
|
|
141
158
|
|
|
142
159
|
### 缓存指纹失效
|
|
143
160
|
|
|
@@ -217,7 +234,7 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
|
|
|
217
234
|
- 不解析 redirect,不派生 sources。
|
|
218
235
|
- 未超出大小限制时,provider 的未知字段也会保留。
|
|
219
236
|
|
|
220
|
-
|
|
237
|
+
最终大小保护默认限制结果及错误文本不超过 **96,000 个 Unicode code point**。
|
|
221
238
|
未超限时保留原始字段及格式;如果只是缩进导致超限,会先压缩 JSON,
|
|
222
239
|
不丢失数据,也不标记为截断。
|
|
223
240
|
|
|
@@ -230,8 +247,8 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
|
|
|
230
247
|
其他长字符串可能被缩短,字段或数组末尾的条目可能被省略;
|
|
231
248
|
不对结果重排或总结。
|
|
232
249
|
|
|
233
|
-
JSON 部分仍然合法,末尾仅追加一行 `[truncated]
|
|
234
|
-
|
|
250
|
+
成功结果的 JSON 部分仍然合法,末尾仅追加一行 `[truncated]`。输出大小截断不会在
|
|
251
|
+
JSON 中添加元数据,也不会逐个标记字符串。由于末尾追加了这一行,
|
|
235
252
|
整个文本不再是合法 JSON。确实丢失数据时,`details.truncated` 也会设为
|
|
236
253
|
`true`。
|
|
237
254
|
|
|
@@ -268,8 +285,9 @@ Authorization: Bearer <DeepSeek API Key>
|
|
|
268
285
|
Content-Type: application/json
|
|
269
286
|
```
|
|
270
287
|
|
|
271
|
-
搜索使用 `query`、`count: 10`、`need_content: true
|
|
272
|
-
|
|
288
|
+
搜索使用 `query`、`count: 10`、`need_content: true`。DeepSeek 的 `query` 上限为
|
|
289
|
+
128 个 Unicode 字符,超长时会在发送请求前直接返回错误,提示缩短后重试。
|
|
290
|
+
原始 `results` 数组原样返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
|
|
273
291
|
`site_name`、`site_icon`、`date`、`authority` 和未知字段。
|
|
274
292
|
|
|
275
293
|
Fetch 发送 `{ "url": "..." }`,原样保存 `{ title, content }`。URL 最长 8192
|
|
@@ -294,7 +312,7 @@ provider;`403`/`404` 作为单个 URL 的错误上报,orchestrator 只重试
|
|
|
294
312
|
|
|
295
313
|
## 已验证
|
|
296
314
|
|
|
297
|
-
-
|
|
315
|
+
- **单元/集成测试**:暴露规则、schema 变体、provider 请求形状、SSE 解析、
|
|
298
316
|
原始结果保留、fallback、缓存失效、URL 处理、截断和取消。
|
|
299
317
|
- **真实 DeepSeek Search/Fetch**:使用真实 API key,返回 10 条原始搜索结果、
|
|
300
318
|
summary/content、合法 fetch 页面,以及文档中的 404/非法 URL 错误。
|
|
@@ -329,7 +347,7 @@ npm run build
|
|
|
329
347
|
```
|
|
330
348
|
|
|
331
349
|
`npm run build` 会运行检查、测试、包内容验证,并生成
|
|
332
|
-
`dist/pi-better-web-search-0.1.
|
|
350
|
+
`dist/pi-better-web-search-0.1.9.tgz`。不会自动发布。
|
|
333
351
|
|
|
334
352
|
测试是 `.mjs` 文件,直接导入 `.ts` 源码,mock `globalThis.fetch`,使用临时缓存
|
|
335
353
|
目录。详见 [测试](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,40 @@ 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.
|
|
76
|
-
|
|
77
|
-
|
|
76
|
+
4. Prefer previously unrepresented provider ids, then try remaining sibling
|
|
77
|
+
models round-robin across families. Provider-wide failures skip that
|
|
78
|
+
provider; model-specific failures, including model-access 403s, can use a
|
|
79
|
+
sibling model. The cap is 12 actual search attempts, not skipped candidates.
|
|
78
80
|
|
|
79
81
|
Fetch candidates use the same shape but include only adapters with
|
|
80
|
-
`supportsUrls` and a `fetch` implementation. The fetch cap is 6 attempts.
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
newest first
|
|
87
|
-
`
|
|
82
|
+
`supportsUrls` and a `fetch` implementation. The fetch cap is 6 actual attempts.
|
|
83
|
+
Cooldowns are applied to the full discovery set before either cap.
|
|
84
|
+
|
|
85
|
+
Within a family, models are ordered by brand first: DeepSeek, OpenAI, Claude,
|
|
86
|
+
Gemini/Gemma, then other gateway brands. Brands without named tiers use variant
|
|
87
|
+
order `flash → base → pro`, then version number, newest first. GPT and Claude
|
|
88
|
+
use version number first, newest first, with capability tier as a tiebreaker:
|
|
89
|
+
OpenAI uses `luna → terra → sol → astra` and Claude uses
|
|
90
|
+
`haiku → sonnet → opus → fable`. Ties fall back to the deterministic
|
|
91
|
+
`provider/id@baseUrl` order. Ranking only applies to models whose API is already
|
|
92
|
+
supported. For example, built-in `opencode-go` DeepSeek models use
|
|
93
|
+
`openai-completions` and are not eligible for Responses search.
|
|
88
94
|
A provider id is only retried with another model when the first failure was
|
|
89
95
|
model-specific; provider-wide failures (auth, balance, network, timeout,
|
|
90
|
-
malformed request) skip the rest of that provider.
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
96
|
+
malformed request) skip the rest of that provider. Provider failures and
|
|
97
|
+
model-specific failures are remembered per phase (search/fetch) for the life of
|
|
98
|
+
the process. On later calls the failed provider or model is moved behind healthy
|
|
99
|
+
candidates for a 60-second to 10-minute exponential cooldown. Concurrent
|
|
100
|
+
failures during an active cooldown count as one outage; a failed probe after
|
|
101
|
+
expiry increases the cooldown. A successful search or fetch with at least one
|
|
102
|
+
successful URL and no provider transport error clears it. Calls already in
|
|
103
|
+
flight are not cancelled or reordered.
|
|
104
|
+
|
|
105
|
+
The current model is preferred when it supports search and neither its provider
|
|
106
|
+
nor that model is cooling down. The cache is a fallback, not an override. When
|
|
107
|
+
the current model
|
|
108
|
+
is unsupported, the cached provider is tried first, which avoids repeating
|
|
109
|
+
discovery on every call.
|
|
95
110
|
|
|
96
111
|
## Cache and fingerprint
|
|
97
112
|
|
|
@@ -124,7 +139,10 @@ be used. A cached provider that is no longer available is ignored.
|
|
|
124
139
|
|
|
125
140
|
## Input validation
|
|
126
141
|
|
|
127
|
-
- `query` is trimmed
|
|
142
|
+
- `query` is trimmed. When DeepSeek is selected, queries over 128 Unicode
|
|
143
|
+
characters produce an actionable error before any DeepSeek request; no
|
|
144
|
+
automatic truncation, fallback, or health cooldown occurs. Other providers
|
|
145
|
+
are not subject to this limit.
|
|
128
146
|
- `urls` is an array of at most 20 strings.
|
|
129
147
|
- Each URL must be HTTP/HTTPS, have a host, omit username/password, and be at
|
|
130
148
|
most 8192 characters.
|
|
@@ -158,10 +176,11 @@ The result is a JSON wrapper:
|
|
|
158
176
|
}
|
|
159
177
|
```
|
|
160
178
|
|
|
161
|
-
Fields inside `search` and `fetched[].data` are provider data. The extension
|
|
162
|
-
not deduplicate,
|
|
163
|
-
|
|
164
|
-
|
|
179
|
+
Fields inside `search` and `fetched[].data` are provider data. The extension
|
|
180
|
+
does not deduplicate,
|
|
181
|
+
normalize, filter, re-rank, summarize, insert citation markers, or append source
|
|
182
|
+
sections. The final guard keeps model-facing results and errors within 96,000
|
|
183
|
+
Unicode code points by default (`PI_BETTER_WEB_SEARCH_MAX_CHARS`).
|
|
165
184
|
It preserves ordinary formatted JSON, or uses compact JSON if that alone fits.
|
|
166
185
|
Otherwise it budgets sibling fields and array entries independently. Recognized
|
|
167
186
|
link and identity fields stay whole; entries or branches that cannot fit them
|
|
@@ -171,8 +190,8 @@ rather than partially emitted. Unknown relative links or bare domains may not be
|
|
|
171
190
|
identifiable. Other strings can be shortened, and fields or trailing array entries
|
|
172
191
|
omitted. The JSON portion
|
|
173
192
|
stays valid, followed by one `[truncated]` line; the complete text is therefore
|
|
174
|
-
not valid JSON. No truncation metadata is injected into the
|
|
175
|
-
|
|
193
|
+
not valid JSON. No output-size truncation metadata is injected into the JSON;
|
|
194
|
+
`details.truncated` marks output-size data loss. When truncation is needed with a limit of 11–13 characters,
|
|
176
195
|
only the marker is returned; below 11, a minimal JSON value is returned instead.
|
|
177
196
|
This is a character guard, not a token or model-context limit; it does not
|
|
178
197
|
provide pagination or retain the complete provider payload for later use.
|
|
@@ -214,6 +233,7 @@ the abort signal and resolve credentials through `lib/auth.ts`.
|
|
|
214
233
|
| `extensions/index.ts` | Tool registration, exposure sync, lifecycle handlers |
|
|
215
234
|
| `lib/candidates.ts` | Current/available candidates, ordering, cache resolution |
|
|
216
235
|
| `lib/search.ts` | Input validation, search/fetch fallback, cache writes, output |
|
|
236
|
+
| `lib/health.ts` | Provider-wide failure cooldowns and candidate reordering |
|
|
217
237
|
| `lib/auth.ts` | Credential resolution, header merging, env fallback |
|
|
218
238
|
| `lib/cache.ts` | Preference cache and model-set fingerprint |
|
|
219
239
|
| `lib/families.ts` | Provider family detection |
|
package/docs/providers.md
CHANGED
|
@@ -20,8 +20,10 @@ stream parsing, and error behavior:
|
|
|
20
20
|
| * | **Anthropic Messages** | api `anthropic-messages` | Yes | No | Messages API `web_search_20260209` tool & OAuth |
|
|
21
21
|
|
|
22
22
|
A model whose API is `openai-completions` is not search-capable unless it is
|
|
23
|
-
served by DeepSeek or Ollama Cloud.
|
|
24
|
-
|
|
23
|
+
served by the native DeepSeek provider or Ollama Cloud. In particular, the
|
|
24
|
+
built-in `opencode-go` DeepSeek models use `openai-completions`; brand ranking
|
|
25
|
+
does not make them Responses-compatible or expose them as search candidates.
|
|
26
|
+
A local Ollama daemon is not supported; Ollama Cloud uses the hosted REST API.
|
|
25
27
|
|
|
26
28
|
## DeepSeek
|
|
27
29
|
|
|
@@ -54,8 +56,11 @@ POST https://api.deepseek.com/v1/tools/search
|
|
|
54
56
|
}
|
|
55
57
|
```
|
|
56
58
|
|
|
57
|
-
- `query` is 1–128 Unicode characters, not all whitespace.
|
|
58
|
-
|
|
59
|
+
- `query` is 1–128 Unicode characters, not all whitespace. Longer queries
|
|
60
|
+
return a model-facing error with the actual length and the 128-character
|
|
61
|
+
limit; the model should shorten the query and retry. No DeepSeek request is
|
|
62
|
+
sent, no automatic truncation or fallback occurs, and no failure cooldown is
|
|
63
|
+
recorded.
|
|
59
64
|
- `count` is within the documented 1–50 range; this package uses 10.
|
|
60
65
|
- `need_content` is `true`, so `content` can contain the page body. The output
|
|
61
66
|
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.9.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.9.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.9 -m "v0.1.9"
|
|
55
|
+
git push origin v0.1.9
|
|
56
|
+
gh release create v0.1.9 dist/pi-better-web-search-0.1.9.tgz \
|
|
57
|
+
--title "v0.1.9" \
|
|
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.9.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:
|