pi-better-web-search 0.1.0 → 0.1.1
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 +5 -0
- package/CONTRIBUTING.md +2 -2
- package/README.md +22 -16
- package/docs/README.zh-CN.md +22 -16
- package/docs/architecture.md +10 -10
- package/docs/providers.md +22 -16
- package/docs/testing.md +1 -1
- package/{src → extensions}/index.ts +4 -4
- 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}/format.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/{src → lib}/search.ts +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
- Align directory structure with Pi extension conventions (`extensions/index.ts` and `lib/`), eliminating the `:src` suffix in Pi's startup banner.
|
|
6
|
+
- 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).
|
|
7
|
+
|
|
3
8
|
## 0.1.0
|
|
4
9
|
|
|
5
10
|
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.
|
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
|
|
package/docs/architecture.md
CHANGED
|
@@ -189,21 +189,21 @@ interface ProviderAdapter {
|
|
|
189
189
|
|
|
190
190
|
`search()` throws when the provider did not perform a search. `fetch()` returns
|
|
191
191
|
one entry per requested URL; per-URL failures go in `entry.error`. Both honor
|
|
192
|
-
the abort signal and resolve credentials through `
|
|
192
|
+
the abort signal and resolve credentials through `lib/auth.ts`.
|
|
193
193
|
|
|
194
194
|
## File map
|
|
195
195
|
|
|
196
196
|
| Path | Responsibility |
|
|
197
197
|
| --- | --- |
|
|
198
|
-
| `
|
|
199
|
-
| `
|
|
200
|
-
| `
|
|
201
|
-
| `
|
|
202
|
-
| `
|
|
203
|
-
| `
|
|
204
|
-
| `
|
|
205
|
-
| `
|
|
206
|
-
| `
|
|
198
|
+
| `extensions/index.ts` | Tool registration, exposure sync, lifecycle handlers |
|
|
199
|
+
| `lib/candidates.ts` | Current/available candidates, ordering, cache resolution |
|
|
200
|
+
| `lib/search.ts` | Input validation, search/fetch fallback, cache writes, output |
|
|
201
|
+
| `lib/auth.ts` | Credential resolution, header merging, env fallback |
|
|
202
|
+
| `lib/cache.ts` | Preference cache and model-set fingerprint |
|
|
203
|
+
| `lib/families.ts` | Provider family detection |
|
|
204
|
+
| `lib/schema.ts` | Query-only and query+urls schema variants |
|
|
205
|
+
| `lib/format.ts` | JSON wrapper, output guard, success/error results |
|
|
206
|
+
| `lib/providers/` | Provider adapters, SSE reader, HTTP helpers |
|
|
207
207
|
|
|
208
208
|
## Non-goals
|
|
209
209
|
|
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/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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-better-web-search",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
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
|
/package/{src → lib}/format.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
|
/package/{src → lib}/search.ts
RENAMED
|
File without changes
|