pi-better-web-search 0.1.0 → 0.1.2
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 +16 -0
- package/CONTRIBUTING.md +2 -2
- package/README.md +22 -20
- package/assets/architecture.svg +68 -40
- package/docs/README.zh-CN.md +22 -20
- package/docs/architecture.md +10 -14
- package/docs/providers.md +22 -16
- package/docs/publishing.md +6 -6
- package/docs/testing.md +1 -1
- package/{src → extensions}/index.ts +4 -4
- package/{src → lib}/format.ts +0 -5
- package/{src → lib}/search.ts +1 -7
- package/package.json +4 -3
- /package/{src → lib}/auth.ts +0 -0
- /package/{src → lib}/cache.ts +0 -0
- /package/{src → lib}/candidates.ts +0 -0
- /package/{src → lib}/families.ts +0 -0
- /package/{src → lib}/providers/anthropic.ts +0 -0
- /package/{src → lib}/providers/deepseek.ts +0 -0
- /package/{src → lib}/providers/google.ts +0 -0
- /package/{src → lib}/providers/http.ts +0 -0
- /package/{src → lib}/providers/index.ts +0 -0
- /package/{src → lib}/providers/ollama.ts +0 -0
- /package/{src → lib}/providers/openai.ts +0 -0
- /package/{src → lib}/providers/sse.ts +0 -0
- /package/{src → lib}/providers/types.ts +0 -0
- /package/{src → lib}/schema.ts +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,21 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.2
|
|
4
|
+
|
|
5
|
+
- Remove provider/model routing metadata from the model-facing JSON output
|
|
6
|
+
(`search` and `fetched[]`). Routing metadata remains in `details` for UI and
|
|
7
|
+
logs and is not sent to the model.
|
|
8
|
+
- Update the architecture diagram to show all 10 supported provider classes
|
|
9
|
+
plus Anthropic Messages.
|
|
10
|
+
- Refresh the README, Chinese README, design notes, and architecture docs for the
|
|
11
|
+
new output shape.
|
|
12
|
+
- Verification: 116 tests pass, and the package contents pass verification.
|
|
13
|
+
|
|
14
|
+
## 0.1.1
|
|
15
|
+
|
|
16
|
+
- Align directory structure with Pi extension conventions (`extensions/index.ts` and `lib/`), eliminating the `:src` suffix in Pi's startup banner.
|
|
17
|
+
- Highlight and expand documentation for all 10 supported provider classes: DeepSeek, Google Gemini, Google Antigravity, Ollama Cloud, OpenAI, Azure OpenAI, OpenAI Codex, GitHub Copilot, OpenCode, and xAI Grok (plus Anthropic Messages).
|
|
18
|
+
|
|
3
19
|
## 0.1.0
|
|
4
20
|
|
|
5
21
|
Initial release of `pi-better-web-search`.
|
package/CONTRIBUTING.md
CHANGED
|
@@ -37,8 +37,8 @@ step and no runtime dependency to bundle.
|
|
|
37
37
|
|
|
38
38
|
## Provider work
|
|
39
39
|
|
|
40
|
-
A provider adapter lives in `
|
|
41
|
-
`ProviderAdapter` contract in `
|
|
40
|
+
A provider adapter lives in `lib/providers/<family>.ts` and follows the
|
|
41
|
+
`ProviderAdapter` contract in `lib/providers/types.ts`. Return provider data
|
|
42
42
|
unchanged. `search()` should throw when the provider did not perform a search;
|
|
43
43
|
`fetch()` should return one entry per URL and put per-URL failures in
|
|
44
44
|
`entry.error`.
|
package/README.md
CHANGED
|
@@ -8,12 +8,12 @@ provider supports it, automatically falls back across authenticated providers,
|
|
|
8
8
|
and returns provider data as-is.
|
|
9
9
|
|
|
10
10
|
[](https://github.com/zhexusun10/pi-better-web-search/actions/workflows/ci.yml)
|
|
11
|
-
[](https://www.npmjs.com/package/pi-better-web-search)
|
|
12
12
|
[](LICENSE)
|
|
13
13
|
[](https://pi.dev)
|
|
14
14
|
[](https://nodejs.org)
|
|
15
15
|
|
|
16
|
-
[简体中文](docs/README.zh-CN.md) · [Architecture](docs/architecture.md) · [Providers](docs/providers.md) · [Testing](docs/testing.md) · [Source](
|
|
16
|
+
[简体中文](docs/README.zh-CN.md) · [Architecture](docs/architecture.md) · [Providers](docs/providers.md) · [Testing](docs/testing.md) · [Source](extensions/index.ts)
|
|
17
17
|
|
|
18
18
|

|
|
19
19
|
|
|
@@ -99,14 +99,21 @@ invalid URLs alongside valid work are reported in the `fetched` entries.
|
|
|
99
99
|
|
|
100
100
|
## Provider support
|
|
101
101
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
|
105
|
-
|
|
106
|
-
|
|
|
107
|
-
|
|
|
108
|
-
|
|
|
109
|
-
|
|
|
102
|
+
`pi-better-web-search` natively supports **10 distinct provider classes** (plus Anthropic Messages), automatically detecting authenticated credentials and routing each call through native provider protocols:
|
|
103
|
+
|
|
104
|
+
| # | Provider Class | Web Search | URL Analysis | Native Protocol & Endpoint |
|
|
105
|
+
|:---:|---|:---:|:---:|---|
|
|
106
|
+
| 1 | **DeepSeek** | Yes | Yes | Native REST `/v1/tools/search` & `/v1/tools/fetch` |
|
|
107
|
+
| 2 | **Google Gemini** | Yes | Yes | `google-generative-ai` SSE `google_search` grounding & `url_context` |
|
|
108
|
+
| 3 | **Google Antigravity** | Yes | Yes | Antigravity enterprise Vertex endpoint & wrapper body |
|
|
109
|
+
| 4 | **Ollama Cloud** | Yes | Yes | Hosted REST `/api/web_search` & `/api/web_fetch` (`ollama.com`) |
|
|
110
|
+
| 5 | **OpenAI** | Yes | No | Official Responses API `web_search` tool (`openai-responses`) |
|
|
111
|
+
| 6 | **Azure OpenAI** | Yes | No | Azure Responses API (`azure-openai-responses`) |
|
|
112
|
+
| 7 | **OpenAI Codex** | Yes | No | Specialized `/codex/responses` with Codex account tokens & headers |
|
|
113
|
+
| 8 | **GitHub Copilot** | Yes | No | Responses routing with Copilot auth tokens & proxy endpoints |
|
|
114
|
+
| 9 | **OpenCode** | Yes | No | Responses routing with Pi session tracking headers |
|
|
115
|
+
| 10 | **xAI (Grok)** | Yes | No | Grok dialect Responses API (`web_search_call.action.sources`) |
|
|
116
|
+
| * | **Anthropic Messages** | Yes | No | Messages API `web_search_20260209` tool & Claude Code OAuth |
|
|
110
117
|
|
|
111
118
|
URL analysis is only exposed when at least one usable interface supports it.
|
|
112
119
|
For example, a current OpenAI model with only OpenAI credentials gets a
|
|
@@ -115,13 +122,12 @@ credentials also gets `urls`.
|
|
|
115
122
|
|
|
116
123
|
Provider detection follows the authenticated model's provider/API:
|
|
117
124
|
|
|
118
|
-
1. `deepseek` provider
|
|
119
|
-
2. Antigravity or Google Generative AI
|
|
125
|
+
1. `deepseek` provider (DeepSeek native search/fetch)
|
|
126
|
+
2. Antigravity or Google Generative AI (Google Gemini & Google Antigravity)
|
|
120
127
|
3. Ollama Cloud (`ollama-cloud` provider or exact `ollama.com` host)
|
|
121
|
-
4. xAI with `openai-responses`
|
|
122
|
-
5. OpenAI-compatible Responses APIs (
|
|
123
|
-
|
|
124
|
-
6. Anthropic Messages
|
|
128
|
+
4. xAI with `openai-responses` (xAI Grok)
|
|
129
|
+
5. OpenAI-compatible Responses APIs (OpenAI, Azure OpenAI, OpenAI Codex, GitHub Copilot, OpenCode)
|
|
130
|
+
6. Anthropic Messages (Claude)
|
|
125
131
|
|
|
126
132
|
See [Providers](docs/providers.md) for request shapes, auth quirks, and URL
|
|
127
133
|
support per family.
|
|
@@ -216,8 +222,6 @@ this:
|
|
|
216
222
|
{
|
|
217
223
|
"query": "the query",
|
|
218
224
|
"search": {
|
|
219
|
-
"provider": "deepseek",
|
|
220
|
-
"model": "deepseek-chat",
|
|
221
225
|
"answer": "provider text when available",
|
|
222
226
|
"results": "the provider's raw results",
|
|
223
227
|
"citations": "the provider's raw citations",
|
|
@@ -227,8 +231,6 @@ this:
|
|
|
227
231
|
"fetched": [
|
|
228
232
|
{
|
|
229
233
|
"url": "https://example.com",
|
|
230
|
-
"provider": "deepseek",
|
|
231
|
-
"model": "deepseek-chat",
|
|
232
234
|
"data": "the provider's raw fetch payload"
|
|
233
235
|
}
|
|
234
236
|
]
|
package/assets/architecture.svg
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img" aria-labelledby="title desc">
|
|
2
2
|
<title id="title">pi-better-web-search architecture</title>
|
|
3
|
-
<desc id="desc">One web_search tool routes
|
|
3
|
+
<desc id="desc">One web_search tool routes across ten provider classes, falls back across authenticated providers, and returns raw provider JSON with a size guard.</desc>
|
|
4
4
|
<defs>
|
|
5
5
|
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
|
6
6
|
<path d="M 0 0 L 10 5 L 0 10 z" fill="#52525b"/>
|
|
@@ -16,8 +16,13 @@
|
|
|
16
16
|
.h { font: 700 18px Arial, Helvetica, sans-serif; fill: #18181b; }
|
|
17
17
|
.t { font: 400 15px Arial, Helvetica, sans-serif; fill: #3f3f46; }
|
|
18
18
|
.muted { font: 400 14px Arial, Helvetica, sans-serif; fill: #71717a; }
|
|
19
|
+
.p { font: 700 13px Arial, Helvetica, sans-serif; fill: #18181b; }
|
|
20
|
+
.d { font: 400 10.5px Arial, Helvetica, sans-serif; fill: #71717a; }
|
|
19
21
|
.inv-h { font: 700 18px Arial, Helvetica, sans-serif; fill: #ffffff; }
|
|
20
22
|
.inv-t { font: 400 14px Arial, Helvetica, sans-serif; fill: #e4e4e7; }
|
|
23
|
+
.inv-p { font: 700 13px Arial, Helvetica, sans-serif; fill: #ffffff; }
|
|
24
|
+
.inv-d { font: 400 10.5px Arial, Helvetica, sans-serif; fill: #e4e4e7; }
|
|
25
|
+
.note { font: 400 11px Arial, Helvetica, sans-serif; fill: #71717a; }
|
|
21
26
|
.arrow { stroke: #52525b; stroke-width: 2; fill: none; marker-end: url(#arrow); }
|
|
22
27
|
.label { font: 600 13px Arial, Helvetica, sans-serif; fill: #52525b; }
|
|
23
28
|
.footer { font: 400 14px Arial, Helvetica, sans-serif; fill: #71717a; }
|
|
@@ -28,57 +33,80 @@
|
|
|
28
33
|
<rect class="panel" x="20" y="20" width="1160" height="600" rx="22"/>
|
|
29
34
|
|
|
30
35
|
<text class="title" x="56" y="82">pi-better-web-search</text>
|
|
31
|
-
<text class="subtitle" x="56" y="116">one tool · provider
|
|
36
|
+
<text class="subtitle" x="56" y="116">one tool · 10 provider classes · raw results</text>
|
|
32
37
|
|
|
33
|
-
<rect class="box" x="56" y="
|
|
34
|
-
<text class="h" x="
|
|
35
|
-
<text class="t" x="
|
|
36
|
-
<text class="muted" x="
|
|
37
|
-
<text class="muted" x="
|
|
38
|
+
<rect class="box" x="56" y="150" width="220" height="124" rx="16"/>
|
|
39
|
+
<text class="h" x="76" y="180">Current pi model</text>
|
|
40
|
+
<text class="t" x="76" y="208">supports search?</text>
|
|
41
|
+
<text class="muted" x="76" y="234">yes → use it first</text>
|
|
42
|
+
<text class="muted" x="76" y="256">no → fallback</text>
|
|
38
43
|
|
|
39
|
-
<path class="arrow" d="M
|
|
40
|
-
<text class="label" x="
|
|
44
|
+
<path class="arrow" d="M 276 212 L 306 212"/>
|
|
45
|
+
<text class="label" x="280" y="200">route</text>
|
|
41
46
|
|
|
42
|
-
<rect class="box" x="
|
|
43
|
-
<text class="h" x="
|
|
44
|
-
<text class="t" x="
|
|
45
|
-
<text class="t" x="
|
|
46
|
-
<text class="muted" x="
|
|
47
|
+
<rect class="box" x="312" y="150" width="250" height="124" rx="16"/>
|
|
48
|
+
<text class="h" x="332" y="180">Candidate router</text>
|
|
49
|
+
<text class="t" x="332" y="208">current → cached →</text>
|
|
50
|
+
<text class="t" x="332" y="230">family priority</text>
|
|
51
|
+
<text class="muted" x="332" y="256">fingerprint-aware cache</text>
|
|
47
52
|
|
|
48
|
-
<path class="arrow" d="M
|
|
49
|
-
<text class="label" x="
|
|
53
|
+
<path class="arrow" d="M 562 212 L 598 212"/>
|
|
54
|
+
<text class="label" x="568" y="200">try in order</text>
|
|
50
55
|
|
|
51
|
-
<
|
|
52
|
-
<
|
|
56
|
+
<rect class="dash" x="604" y="112" width="340" height="350" rx="18"/>
|
|
57
|
+
<text class="h" x="624" y="142">provider adapters</text>
|
|
58
|
+
<text class="muted" x="920" y="142" text-anchor="end">10 classes</text>
|
|
53
59
|
|
|
54
|
-
<rect class="accent" x="
|
|
55
|
-
<text class="inv-
|
|
56
|
-
<text class="inv-
|
|
60
|
+
<rect class="accent" x="616" y="154" width="152" height="46" rx="10"/>
|
|
61
|
+
<text class="inv-p" x="630" y="172">DeepSeek</text>
|
|
62
|
+
<text class="inv-d" x="630" y="187">native search + fetch</text>
|
|
57
63
|
|
|
58
|
-
<rect class="box" x="
|
|
59
|
-
<text class="
|
|
60
|
-
<text class="
|
|
64
|
+
<rect class="box" x="616" y="208" width="152" height="46" rx="10"/>
|
|
65
|
+
<text class="p" x="630" y="226">Google Gemini</text>
|
|
66
|
+
<text class="d" x="630" y="241">search + URL context</text>
|
|
61
67
|
|
|
62
|
-
<rect class="box" x="
|
|
63
|
-
<text class="
|
|
64
|
-
<text class="
|
|
68
|
+
<rect class="box" x="616" y="262" width="152" height="46" rx="10"/>
|
|
69
|
+
<text class="p" x="630" y="280">Google Antigravity</text>
|
|
70
|
+
<text class="d" x="630" y="295">search + URL context</text>
|
|
65
71
|
|
|
66
|
-
<rect class="box" x="
|
|
67
|
-
<text class="
|
|
68
|
-
<text class="
|
|
72
|
+
<rect class="box" x="616" y="316" width="152" height="46" rx="10"/>
|
|
73
|
+
<text class="p" x="630" y="334">Ollama Cloud</text>
|
|
74
|
+
<text class="d" x="630" y="349">search + fetch</text>
|
|
69
75
|
|
|
70
|
-
<rect class="box" x="
|
|
71
|
-
<text class="
|
|
72
|
-
<text class="
|
|
76
|
+
<rect class="box" x="616" y="370" width="152" height="46" rx="10"/>
|
|
77
|
+
<text class="p" x="630" y="388">OpenAI</text>
|
|
78
|
+
<text class="d" x="630" y="403">Responses web search</text>
|
|
73
79
|
|
|
74
|
-
<
|
|
75
|
-
<text class="
|
|
80
|
+
<rect class="box" x="776" y="154" width="152" height="46" rx="10"/>
|
|
81
|
+
<text class="p" x="790" y="172">Azure OpenAI</text>
|
|
82
|
+
<text class="d" x="790" y="187">Azure Responses</text>
|
|
76
83
|
|
|
77
|
-
<rect class="box" x="
|
|
78
|
-
<text class="
|
|
79
|
-
<text class="
|
|
80
|
-
|
|
81
|
-
<
|
|
84
|
+
<rect class="box" x="776" y="208" width="152" height="46" rx="10"/>
|
|
85
|
+
<text class="p" x="790" y="226">OpenAI Codex</text>
|
|
86
|
+
<text class="d" x="790" y="241">Codex Responses</text>
|
|
87
|
+
|
|
88
|
+
<rect class="box" x="776" y="262" width="152" height="46" rx="10"/>
|
|
89
|
+
<text class="p" x="790" y="280">GitHub Copilot</text>
|
|
90
|
+
<text class="d" x="790" y="295">Copilot Responses</text>
|
|
91
|
+
|
|
92
|
+
<rect class="box" x="776" y="316" width="152" height="46" rx="10"/>
|
|
93
|
+
<text class="p" x="790" y="334">OpenCode</text>
|
|
94
|
+
<text class="d" x="790" y="349">OpenCode Responses</text>
|
|
95
|
+
|
|
96
|
+
<rect class="box" x="776" y="370" width="152" height="46" rx="10"/>
|
|
97
|
+
<text class="p" x="790" y="388">xAI Grok</text>
|
|
98
|
+
<text class="d" x="790" y="403">Grok Responses</text>
|
|
99
|
+
|
|
100
|
+
<text class="note" x="624" y="446">plus Anthropic Messages · native Messages web search</text>
|
|
101
|
+
|
|
102
|
+
<path class="arrow" d="M 944 212 L 974 212"/>
|
|
103
|
+
<text class="label" x="948" y="200">raw</text>
|
|
104
|
+
|
|
105
|
+
<rect class="box" x="980" y="150" width="160" height="124" rx="16"/>
|
|
106
|
+
<text class="h" x="1000" y="180">Tool result</text>
|
|
107
|
+
<text class="t" x="1000" y="208">raw JSON</text>
|
|
108
|
+
<text class="muted" x="1000" y="234">no cleanup</text>
|
|
109
|
+
<text class="muted" x="1000" y="256">64k char guard</text>
|
|
82
110
|
|
|
83
111
|
<rect class="panel" x="56" y="492" width="1084" height="94" rx="16"/>
|
|
84
112
|
<text class="h" x="78" y="522">Exposure & memory</text>
|
package/docs/README.zh-CN.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
`web_search`。它使用各家 provider 的原生搜索接口,在可用 provider 支持时
|
|
7
7
|
分析 URL,自动在已登录的 provider 之间切换,并把 provider 数据原样返回。
|
|
8
8
|
|
|
9
|
-
[English](../README.md) · [架构说明](architecture.md) · [Provider 细节](providers.md) · [测试](testing.md) · [源码](../
|
|
9
|
+
[English](../README.md) · [架构说明](architecture.md) · [Provider 细节](providers.md) · [测试](testing.md) · [源码](../extensions/index.ts)
|
|
10
10
|
|
|
11
11
|

|
|
12
12
|
|
|
@@ -81,28 +81,34 @@ provider 都失败时,工具返回错误(`isError: true`),不会静默
|
|
|
81
81
|
|
|
82
82
|
## Provider 支持
|
|
83
83
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
|
87
|
-
|
|
88
|
-
|
|
|
89
|
-
|
|
|
90
|
-
|
|
|
91
|
-
|
|
|
84
|
+
`pi-better-web-search` 原生支持 **10 类主流 Provider**(及 Anthropic Messages),通过各家原生 API 协议接入,兼具最原汁原味的模型能力与极速体验:
|
|
85
|
+
|
|
86
|
+
| # | Provider 类别 | 网页搜索 | URL 分析 | 原生协议与端点接口 |
|
|
87
|
+
|:---:|---|:---:|:---:|---|
|
|
88
|
+
| 1 | **DeepSeek** | 是 | 是 | 原生 REST `/v1/tools/search` 与 `/v1/tools/fetch` |
|
|
89
|
+
| 2 | **Google Gemini** | 是 | 是 | `google-generative-ai` SSE `google_search` 与 `url_context` |
|
|
90
|
+
| 3 | **Google Antigravity** | 是 | 是 | Antigravity 企业级 Vertex 端点与专属包装体 |
|
|
91
|
+
| 4 | **Ollama Cloud** | 是 | 是 | 托管独立 REST `/api/web_search` 与 `/api/web_fetch`(`ollama.com`) |
|
|
92
|
+
| 5 | **OpenAI** | 是 | 否 | 官方 Responses API `web_search` 工具(`openai-responses`) |
|
|
93
|
+
| 6 | **Azure OpenAI** | 是 | 否 | Azure Responses API 专用端点(`azure-openai-responses`) |
|
|
94
|
+
| 7 | **OpenAI Codex** | 是 | 否 | 专有 `/codex/responses` 端点,支持 Codex 账号 Token 与 Originator 协议 |
|
|
95
|
+
| 8 | **GitHub Copilot** | 是 | 否 | Copilot 鉴权凭证路由与兼容代理端点 Responses 搜索 |
|
|
96
|
+
| 9 | **OpenCode** | 是 | 否 | 携带 Pi 会话追踪请求头的 Responses 搜索 |
|
|
97
|
+
| 10 | **xAI (Grok)** | 是 | 否 | 原生 Grok 方言 Responses API(`web_search_call.action.sources`) |
|
|
98
|
+
| * | **Anthropic Messages** | 是 | 否 | Messages API `web_search_20260209` 工具及 Claude Code OAuth 凭据 |
|
|
92
99
|
|
|
93
100
|
只有至少一个可用接口支持 URL 分析时,`urls` 才会暴露。例如:当前模型是
|
|
94
101
|
OpenAI 且只有 OpenAI 凭据时,schema 只有 `query`;同一会话只要还有
|
|
95
|
-
DeepSeek、
|
|
102
|
+
DeepSeek、Google Gemini、Antigravity 或 Ollama Cloud 凭据,就会出现 `urls`。
|
|
96
103
|
|
|
97
104
|
Provider 识别顺序:
|
|
98
105
|
|
|
99
|
-
1. `deepseek` provider
|
|
100
|
-
2. Antigravity 或 Google Generative AI
|
|
106
|
+
1. `deepseek` provider(DeepSeek 原生 search/fetch)
|
|
107
|
+
2. Antigravity 或 Google Generative AI(Google Gemini 与 Google Antigravity)
|
|
101
108
|
3. Ollama Cloud(`ollama-cloud` provider,或 host 精确为 `ollama.com`)
|
|
102
|
-
4. xAI + `openai-responses
|
|
103
|
-
5. OpenAI-compatible Responses API
|
|
104
|
-
|
|
105
|
-
6. Anthropic Messages
|
|
109
|
+
4. xAI + `openai-responses`(xAI Grok)
|
|
110
|
+
5. OpenAI-compatible Responses API(OpenAI、Azure OpenAI、OpenAI Codex、GitHub Copilot、OpenCode)
|
|
111
|
+
6. Anthropic Messages(Claude)
|
|
106
112
|
|
|
107
113
|
各 provider 的请求形状、鉴权细节和 URL 支持见 [Provider 细节](providers.md)。
|
|
108
114
|
|
|
@@ -183,8 +189,6 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
|
|
|
183
189
|
{
|
|
184
190
|
"query": "the query",
|
|
185
191
|
"search": {
|
|
186
|
-
"provider": "deepseek",
|
|
187
|
-
"model": "deepseek-chat",
|
|
188
192
|
"answer": "provider text when available",
|
|
189
193
|
"results": "the provider's raw results",
|
|
190
194
|
"citations": "the provider's raw citations",
|
|
@@ -194,8 +198,6 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
|
|
|
194
198
|
"fetched": [
|
|
195
199
|
{
|
|
196
200
|
"url": "https://example.com",
|
|
197
|
-
"provider": "deepseek",
|
|
198
|
-
"model": "deepseek-chat",
|
|
199
201
|
"data": "the provider's raw fetch payload"
|
|
200
202
|
}
|
|
201
203
|
]
|
package/docs/architecture.md
CHANGED
|
@@ -136,8 +136,6 @@ The result is a JSON wrapper:
|
|
|
136
136
|
{
|
|
137
137
|
query?: string;
|
|
138
138
|
search?: {
|
|
139
|
-
provider: ProviderFamily;
|
|
140
|
-
model: string;
|
|
141
139
|
answer?: string;
|
|
142
140
|
results?: unknown;
|
|
143
141
|
citations?: unknown;
|
|
@@ -147,8 +145,6 @@ The result is a JSON wrapper:
|
|
|
147
145
|
};
|
|
148
146
|
fetched?: Array<{
|
|
149
147
|
url: string;
|
|
150
|
-
provider?: ProviderFamily;
|
|
151
|
-
model?: string;
|
|
152
148
|
data?: unknown;
|
|
153
149
|
error?: string;
|
|
154
150
|
}>;
|
|
@@ -189,21 +185,21 @@ interface ProviderAdapter {
|
|
|
189
185
|
|
|
190
186
|
`search()` throws when the provider did not perform a search. `fetch()` returns
|
|
191
187
|
one entry per requested URL; per-URL failures go in `entry.error`. Both honor
|
|
192
|
-
the abort signal and resolve credentials through `
|
|
188
|
+
the abort signal and resolve credentials through `lib/auth.ts`.
|
|
193
189
|
|
|
194
190
|
## File map
|
|
195
191
|
|
|
196
192
|
| Path | Responsibility |
|
|
197
193
|
| --- | --- |
|
|
198
|
-
| `
|
|
199
|
-
| `
|
|
200
|
-
| `
|
|
201
|
-
| `
|
|
202
|
-
| `
|
|
203
|
-
| `
|
|
204
|
-
| `
|
|
205
|
-
| `
|
|
206
|
-
| `
|
|
194
|
+
| `extensions/index.ts` | Tool registration, exposure sync, lifecycle handlers |
|
|
195
|
+
| `lib/candidates.ts` | Current/available candidates, ordering, cache resolution |
|
|
196
|
+
| `lib/search.ts` | Input validation, search/fetch fallback, cache writes, output |
|
|
197
|
+
| `lib/auth.ts` | Credential resolution, header merging, env fallback |
|
|
198
|
+
| `lib/cache.ts` | Preference cache and model-set fingerprint |
|
|
199
|
+
| `lib/families.ts` | Provider family detection |
|
|
200
|
+
| `lib/schema.ts` | Query-only and query+urls schema variants |
|
|
201
|
+
| `lib/format.ts` | JSON wrapper, output guard, success/error results |
|
|
202
|
+
| `lib/providers/` | Provider adapters, SSE reader, HTTP helpers |
|
|
207
203
|
|
|
208
204
|
## Non-goals
|
|
209
205
|
|
package/docs/providers.md
CHANGED
|
@@ -1,17 +1,23 @@
|
|
|
1
1
|
# Providers
|
|
2
2
|
|
|
3
|
-
The extension selects
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
|
9
|
-
|
|
10
|
-
|
|
|
11
|
-
| Google | api `google-generative-ai
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
3
|
+
The extension selects an adapter from the authenticated model's provider id,
|
|
4
|
+
API id, and base URL. We natively support **10 distinct provider classes** (plus
|
|
5
|
+
Anthropic Messages), each mapped to its native request shape, authentication,
|
|
6
|
+
stream parsing, and error behavior:
|
|
7
|
+
|
|
8
|
+
| # | Provider Class | Detection | Search | URL Analysis | Interface & Endpoint |
|
|
9
|
+
|:---:|---|---|:---:|:---:|---|
|
|
10
|
+
| 1 | **DeepSeek** | provider `deepseek` | Yes | Yes | Native REST `/v1/tools/search`, `/v1/tools/fetch` |
|
|
11
|
+
| 2 | **Google Gemini** | api `google-generative-ai` | Yes | Yes | SSE `google_search`, `url_context` |
|
|
12
|
+
| 3 | **Google Antigravity** | provider/api `antigravity` | Yes | Yes | Antigravity enterprise Vertex endpoint & wrapper |
|
|
13
|
+
| 4 | **Ollama Cloud** | provider `ollama-cloud` or host `ollama.com` | Yes | Yes | Hosted REST `/api/web_search`, `/api/web_fetch` |
|
|
14
|
+
| 5 | **OpenAI** | api `openai-responses` | Yes | No | Responses API `web_search` |
|
|
15
|
+
| 6 | **Azure OpenAI** | api `azure-openai-responses` | Yes | No | Azure Responses API `/responses` |
|
|
16
|
+
| 7 | **OpenAI Codex** | api `openai-codex-responses` | Yes | No | Codex `/codex/responses` & account tokens |
|
|
17
|
+
| 8 | **GitHub Copilot** | Copilot provider/token with Responses | Yes | No | Copilot Responses with token routing & proxy endpoints |
|
|
18
|
+
| 9 | **OpenCode** | OpenCode provider with Responses | Yes | No | Responses API with Pi session tracking headers |
|
|
19
|
+
| 10 | **xAI (Grok)** | provider `xai` or model `grok*` with Responses | Yes | No | Grok dialect Responses (`action.sources`) |
|
|
20
|
+
| * | **Anthropic Messages** | api `anthropic-messages` | Yes | No | Messages API `web_search_20260209` tool & OAuth |
|
|
15
21
|
|
|
16
22
|
A model whose API is `openai-completions` is not search-capable unless it is
|
|
17
23
|
served by DeepSeek or Ollama Cloud. A local Ollama daemon is not supported;
|
|
@@ -207,10 +213,10 @@ a per-URL error.
|
|
|
207
213
|
|
|
208
214
|
## Adding a provider
|
|
209
215
|
|
|
210
|
-
1. Add a family to `
|
|
211
|
-
2. Create `
|
|
212
|
-
3. Register it in `
|
|
213
|
-
4. Add family detection in `
|
|
216
|
+
1. Add a family to `lib/providers/types.ts` if it is genuinely new.
|
|
217
|
+
2. Create `lib/providers/<family>.ts` exporting a `ProviderAdapter`.
|
|
218
|
+
3. Register it in `lib/providers/index.ts`.
|
|
219
|
+
4. Add family detection in `lib/families.ts`.
|
|
214
220
|
5. Add tests for request shape, auth/header preservation, raw result
|
|
215
221
|
preservation, search evidence, errors, aborts, and URL behavior.
|
|
216
222
|
6. Update this document, `README.md`, and `CHANGELOG.md`.
|
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.2.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.2.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.2 -m "v0.1.2"
|
|
55
|
+
git push origin v0.1.2
|
|
56
|
+
gh release create v0.1.2 dist/pi-better-web-search-0.1.2.tgz \
|
|
57
|
+
--title "v0.1.2" \
|
|
58
58
|
--notes-file /path/to/release-notes.md
|
|
59
59
|
```
|
|
60
60
|
|
package/docs/testing.md
CHANGED
|
@@ -80,7 +80,7 @@ search and a real DeepSeek credential:
|
|
|
80
80
|
PI_BETTER_WEB_SEARCH_CACHE=/tmp/pi-bws-e2e/cache.json \
|
|
81
81
|
pi --no-session --print --mode json \
|
|
82
82
|
--provider mock-chat --model mock-chat/mock-chat-model \
|
|
83
|
-
-e ./
|
|
83
|
+
-e ./extensions/index.ts "please search the web"
|
|
84
84
|
```
|
|
85
85
|
|
|
86
86
|
5. Inspect the second model request. The tool result must be valid raw JSON with
|
|
@@ -4,11 +4,11 @@ import {
|
|
|
4
4
|
hasExposedCandidate,
|
|
5
5
|
hasUrlCandidate,
|
|
6
6
|
resolveResolutionContext,
|
|
7
|
-
} from "
|
|
8
|
-
import { buildWebSearchSchema, buildWebSearchToolDescription, WEB_SEARCH_TOOL_NAME } from "
|
|
9
|
-
import { runWebSearch } from "
|
|
7
|
+
} from "../lib/candidates.ts";
|
|
8
|
+
import { buildWebSearchSchema, buildWebSearchToolDescription, WEB_SEARCH_TOOL_NAME } from "../lib/schema.ts";
|
|
9
|
+
import { runWebSearch } from "../lib/search.ts";
|
|
10
10
|
|
|
11
|
-
export { WEB_SEARCH_TOOL_NAME } from "
|
|
11
|
+
export { WEB_SEARCH_TOOL_NAME } from "../lib/schema.ts";
|
|
12
12
|
|
|
13
13
|
export function createWebSearchToolManager(
|
|
14
14
|
pi: Pick<ExtensionAPI, "registerTool" | "getActiveTools" | "setActiveTools">,
|
package/{src → lib}/format.ts
RENAMED
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
|
|
2
|
-
import type { ProviderFamily } from "./providers/types.ts";
|
|
3
2
|
|
|
4
3
|
const configuredOutputLimit = Number(process.env.PI_BETTER_WEB_SEARCH_MAX_CHARS);
|
|
5
4
|
export const MAX_OUTPUT_CHARS =
|
|
@@ -10,8 +9,6 @@ export const MAX_OUTPUT_CHARS =
|
|
|
10
9
|
export interface WebSearchOutput {
|
|
11
10
|
query?: string;
|
|
12
11
|
search?: {
|
|
13
|
-
provider: ProviderFamily;
|
|
14
|
-
model: string;
|
|
15
12
|
answer?: string;
|
|
16
13
|
results?: unknown;
|
|
17
14
|
citations?: unknown;
|
|
@@ -21,8 +18,6 @@ export interface WebSearchOutput {
|
|
|
21
18
|
};
|
|
22
19
|
fetched?: Array<{
|
|
23
20
|
url: string;
|
|
24
|
-
provider?: ProviderFamily;
|
|
25
|
-
model?: string;
|
|
26
21
|
data?: unknown;
|
|
27
22
|
error?: string;
|
|
28
23
|
}>;
|
package/{src → lib}/search.ts
RENAMED
|
@@ -377,8 +377,6 @@ function fetchOutput(states: FetchState[], urlErrors: UrlValidationError[]): Non
|
|
|
377
377
|
if (state.data !== undefined && state.provider) {
|
|
378
378
|
return {
|
|
379
379
|
url: state.url,
|
|
380
|
-
provider: state.provider.family,
|
|
381
|
-
model: state.provider.model.id,
|
|
382
380
|
data: state.data,
|
|
383
381
|
};
|
|
384
382
|
}
|
|
@@ -474,11 +472,7 @@ export async function runWebSearch(
|
|
|
474
472
|
const output: WebSearchOutput = {};
|
|
475
473
|
if (query) output.query = query;
|
|
476
474
|
if (searchSuccess) {
|
|
477
|
-
output.search = {
|
|
478
|
-
...searchSuccess.result,
|
|
479
|
-
provider: searchSuccess.candidate.family,
|
|
480
|
-
model: searchSuccess.candidate.model.id,
|
|
481
|
-
};
|
|
475
|
+
output.search = { ...searchSuccess.result };
|
|
482
476
|
}
|
|
483
477
|
if (fetchRequested) {
|
|
484
478
|
output.fetched = fetchOutput(states, urlErrors);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-better-web-search",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "A better provider-native web_search tool for pi: raw results, automatic provider fallback, URL analysis, and native DeepSeek Search/Fetch.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -30,7 +30,8 @@
|
|
|
30
30
|
"url-context"
|
|
31
31
|
],
|
|
32
32
|
"files": [
|
|
33
|
-
"
|
|
33
|
+
"extensions/",
|
|
34
|
+
"lib/",
|
|
34
35
|
"docs/",
|
|
35
36
|
"assets/",
|
|
36
37
|
"README.md",
|
|
@@ -41,7 +42,7 @@
|
|
|
41
42
|
],
|
|
42
43
|
"pi": {
|
|
43
44
|
"extensions": [
|
|
44
|
-
"./
|
|
45
|
+
"./extensions/index.ts"
|
|
45
46
|
],
|
|
46
47
|
"image": "https://raw.githubusercontent.com/zhexusun10/pi-better-web-search/main/assets/architecture.svg"
|
|
47
48
|
},
|
/package/{src → lib}/auth.ts
RENAMED
|
File without changes
|
/package/{src → lib}/cache.ts
RENAMED
|
File without changes
|
|
File without changes
|
/package/{src → lib}/families.ts
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
/package/{src → lib}/schema.ts
RENAMED
|
File without changes
|