# @gagansd/pi-web-search 中文文档 规范地址：https://npmcn.com/package/%40gagansd/pi-web-search/ 版本：0\.4\.0 npm 元数据更新时间：2026-10-25T20:11:10.405Z 中文译文更新时间：2026-11-15T21:01:06.240Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40gagansd/pi-web-search 原文对照：https://npmcn.com/package/%40gagansd/pi-web-search/?lang=original 项目主页：https://github.com/GaganSD/pi-extensions/tree/main/pi-web-search 源码仓库：https://github.com/GaganSD/pi-extensions ## 关键信息（来自 npm 元数据） - 包体积（解压后）：299 kB，34 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=22\.19\.0 - 运行依赖：0 个 - peer 依赖：typebox \*，@earendil-works/pi-ai \*，@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \* - 首次发布：2026-10-01T18:19:55.600Z - 最新版本发布：2026-10-25T20:11:10.012Z - 近 30 天下载量：3670（2026-10-16 至 2026-11-14，npm 官方下载统计） - 已发布版本数：7（近 12 个月 7 个） ## 中文简介 一个搜索工具,用于公共网络/代码,URL提取,以及本地证据的续作. 引用,上下文高效,默认无密钥. ## 安装 ```sh npm install @gagansd/pi-web-search ``` 也可以使用：`pnpm add @gagansd/pi-web-search`、`yarn add @gagansd/pi-web-search`、`bun add @gagansd/pi-web-search` ## README # pi-web-搜索 **Pi 统一网络和公共编码搜索: 1 `search` 用于查询、URL提取和本地证据的继续的工具.** - **默认无密钥 :** Exa,相通,Jina Reader(只取URL),grep.app,和Sourcegraph. 可选 Jev 过滤重用您的 Pi 登录/ key . - **一个平面图:** 完全一个 `query`, (中文(简体) ), `urls`,或 `ref`附加可选 `scope`, (中文(简体) ), `effort`, (中文(简体) ), `find`,以及 `cursor`。没有选择提供者的参数. - **两项努力:** `fast` (默认)使用一个配置的提供者加倒计时; `thorough` 粉丝横跨合格来源 由 `research.enabled`。 。 。 . - 可选 Pi-native Jev 排名,过滤,和安全分类. 默认关闭. ## 安装 需要皮条 **0.99.0或更新**。 。 。 . 1. 安装 : `pi install npm:@gagansd/pi-web-search` 2. 第一个互动会话显示了一个一次性的设置,即为已有的Exa,GitHub和并行的证书. 对于密钥和设置, 随时运行 `/web-search`。 。 。 . > 无密钥配置有 Exa 和 并行 设定的限制 . | 命令 | 它会做什么 | | --- | --- | | `/web-search` | 菜单:状态,提供者密钥,分类器. 无头指印状态. | | `/web-search status` | 提供商、证书存在(从未有密钥)和分类针. | | `/web-search provider [name]` | 添加或修改检索密钥。 采取器为色码:无键,可选,或需要;有或缺失. | | `/web-search classifier [none|provider/model]` | 从列表中选择或禁用 `none`。 。 。 . | ## 分类器 API 可选分类法增加了判决 `effort: "thorough"` 电话; 快速 `search` 电话从不运行. - **等级:** 倾向于相关、自成一体的摘录并惩罚非专题结果. - **过滤器 :** 抑制有自信地标出即时注射、钓鱼或有害内容. - **检查覆盖范围 :** 判断获取的证据是否足以回答询问. ### 结构和模型支助 `Retrieval → Pi classifier API → ranking/filtering policy → cited results` 分类器接收查询和候选标题,URL,以及作为状态的节选,加上打出布尔和选择问题. 它返回概率;代码应用权重和阈值. Pi拥有目录,认证,以及 `classify()`。这个包裹针出一个精确 `provider`编号 :`model`。 。 。 . | 分类符 | 支助 | | --- | --- | | **杰维** 通过 TypeSafe、Vercel AI Gateway 或 OpenRouter 访问 | 现在可用; 重复使用 Pi 认证 . | | **任意 Pi 分类器** 包括马拉马.cpp | 把它钉住 `provider`编号 :`model`。 。 。 . | | **OpenAI 决定和其他决定模式** | 在 Pi 中注册为分类器时支持; 给确切的提供者/ 模型打针 . | 提供者-独立边界使得其他分类者可以不重写检索或排名. 将任何注册的 Pi 分类器按下 `/web-search classifier`。 。 。 . ### 用您已有的 Pi 登录尝试 Jev 对于 OpenRouter : 1. 运行 `/login openrouter` **只有Pi还没有被认证**。 。 。 . 2. 运行 `/web-search classifier` 选择 `openrouter/~typesafe/jev-latest`,或 `/web-search classifier openrouter/~typesafe/jev-latest`。 。 。 . 3. 运行 `/reload`。 。 。 . 4. 问:“用彻底的搜索来搜索网页以中止Signal.timeout。” | 使用 | 设置命令 | 默认模式 | | --- | --- | --- | | 类型安全 | `/web-search classifier typesafe/jev-latest` | `jev-latest` | | Vercel AI 网关 | `/web-search classifier vercel-ai-gateway/typesafe-ai/jev` | `typesafe-ai/jev` | | 打开路透社 | `/web-search classifier openrouter/~typesafe/jev-latest` | `~typesafe/jev-latest` | | 打开代码 | `/web-search classifier opencode/jev-1.13` | `jev-1.13` | | OpenAI 决定 | `/web-search classifier vercel-ai-gateway/openai/gpt-6-luna-decisions` | `openai/gpt-6-luna-decisions` | | 大赦国际 | `/web-search classifier` 并选择列出的克拉夫/杰夫型号 | 目录 | `/web-search classifier` 列出当前每个分类器 Pi 注册,加 **无**分类符不出现在 `/model`;这个取取器是搜索专用的接针. Pinning 允许多源搜索和判断 `web-search.json`,保留您的其他设置. **不需要第二个 API 键 .** Pi重新使用其存储,环境,运行时间,或模型认证. 如果需要的话,请用Pi的 `/login` 给那个供货商. `/web-search classifier none` 禁用判断; 继续搜索 。 托管的分类费用记入固定账户. 默认取消分类。 如果启用时没有明确的提供者/模型对,则使用 **杰维** (单位:千美元)`vercel-ai-gateway/typesafe-ai/jev`) (中文(简体) ). 其他 Pi 分类器可以被明确固定. 配置用途 `classifier`旧的 `jev` 块和 `backend` 字段被拒绝,而不是迁移。 失败者会以警告方式获取证据。 主机分类器在输出剪接前收到节录;安全判断不是安全边界. 见 [所有设置和限制](https://npmcn.com/package/%40gagansd/pi-web-search/docs/research.md)。 。 。 . ## 工具和实例 使用 `search` 用于公共文档、当前信息、文字公共编码模式、已知的URL以及所储存的证据: > `search` 是唯一注册的工具。 直接和代码调用器使用相同的接口. | 投入 | 使用 | | --- | --- | | `query` | 搜索条款或问题。 与 `scope: "code"`,使用文字标识符或片段. | | `urls` | 在不请求搜索的情况下提取一个或多个已知的 HTTP( S) 页面 . | | `ref` | 本地读取存储的证据 。 接受手柄( 列表) 或 `:` (读). | | `scope` | `web` (违约), `code`,或 `both`。 。 。 . `both` 默认为 `effort: "thorough"`。 。 。 . | | `effort` | `fast` (默认;一个提供者加倒置)或 `thorough` (当前来源;需要) `research.enabled`) (中文(简体) ). | | `find` 编号 : `cursor` | 改进a `ref` 读取时使用文字上的通道搜索或继续光标. | 就是其中一个 `query`, (中文(简体) ), `urls`,或 `ref` 需要时间。 冲突、不适当的字段和未知参数都以短暂的错误而失败,而不是被默默地忽略. 实例: ```json { "query": "AbortSignal.timeout", "scope": "web" } ``` ```json { "query": "useSyncExternalStore repo:vercel/next.js", "scope": "code" } ``` ```json { "query": "AbortSignal.timeout", "scope": "both", "effort": "thorough" } ``` ```json { "urls": ["https://example.com/docs"] } ``` 使用 `repo:` 财务报告和审定财务报表 `language:` 用于常见的代码-过滤子集;其他 GitHub 修饰语是依赖提供者的。 仅当您想要提取时才提供 URL 字符串; 它们不能与 `query` 或者说 `ref`。 。 。 . `urls` 接受最多20个字符串;空白被忽略,无效/非HTTP(S) URL生成警告. 只使用 URL 调用需要至少一个有效的 URL 。 提取返回提供者选择的证据,而非完整浏览器页面 。 未声明的工具参数,例如 `limit`, (中文(简体) ), `provider`,或 `path` 在错误中拒绝并命名. ### 无需其他网络请求即可读取更多信息 搜索返回已绑定的预览外加会话本地 `resultId` 当证据可以存储。 传出手柄作为 `ref` 通过同一工具列出或读取证据: ```js const index = await tools.search({ ref: "" }); text(index); const passage = await tools.search({ ref: ":1", find: "timeout" }); text(passage); ``` 参考书系单行线(`:1` 是第一个存储结果。 奥米 `find` 和使用情况 `cursor` 继续读取。 处理在闲置了10分钟后过期(成功读取更新,最多60分钟),驱逐、关闭或重新装入。 没有写到磁盘上。 所储存的证据是有限度的,而且可能已被提供者截断 **未保证全页内容**。直接呼叫者可以复制返回的 `search({ref, cursor})` 继续调用; 不需要代码 。 见 [效率和限制](https://npmcn.com/package/%40gagansd/pi-web-search/docs/efficiency.md)。 。 。 . ### 代码修饰符 `repo:` 财务报告和审定财务报表 `language:` 是文件的常见子集。 在grep.app和Sourcegraph上,这些被取入过滤器;引出含有空格的限定值. 第一个不空地 `repo:` 值被使用,重复的语言被去除. **grep.app 语言过滤不可靠** 并总是在使用时添加警告;避免用于第一次搜索,并将零点击视为没有定论. 其他限定词依赖提供者:grep.app叶 `path:`, (中文(简体) ), `filename:`,而字形图案中的类似语法,而GitHub接收原始查询时没有改变并解释自己的语法. 零重击警告意味着可能的补救办法,而不是确认不存在代码的原因或证明. grep.app和公用源代码并非每个 GitHub 寄存器索引; `repo:facebook/react` 经常错过这些来源. ## 完整配置 配置路径是 `/web-search.json`,通常情况下 `~/.pi/agent/web-search.json`。 。 。 . `PI_WEB_SEARCH_CONFIG` 覆盖此路径 . `PI_CODING_AGENT_DIR` 更改 Pi 代理目录 . 扩展不会自动读取工程 `.pi/web-search.json` 或将 Pi 合并 `settings.json`。工程本地安装不会改变配置位置. 缺失文件使用这些默认 : ```json { "web": { "provider": "exa", "fallback": ["parallel"] }, "code": { "provider": "grep", "fallback": ["sourcegraph", "github"] }, "research": { "enabled": false }, "timeoutMs": 20000, "maxResults": 8 } ``` 所有字段都是可选的. 将更改合并到已有文件 。 网络操作每次读取配置;即使配置不正确,Ref读取仍停留在本地. 在本地 MCP 注册或证书更改后重新加载 . - `web` 接受 `exa`, (中文(简体) ), `parallel`,以及 `brave`. Jina是只提取的,不是搜索链供应商. `code` 接受 `grep`, (中文(简体) ), `sourcegraph`,以及 `github`。 。 。 . - `maxResults` 切到整数,然后夹到 **1–20 (中文(简体) )**它既限制了提供者的请求,也限制了 **全局返回的预览数**,包括URL摘录. 所请求的 URL 摘录被优先排序; 可通过 `search({ref})`. 提供者可能返回较少的结果或忽略所要求的限制. - `timeoutMs` 切换为整数毫秒。 积极价值有: **最低1,000毫秒**使用的非正值 **20 000毫瓦时**。这些数值调整不会发出警告. - 无效的 JSON, 未知字段/ 提供者, 以及形状错误的块生成 `invalid_config`。错误的家庭提供者触发警告和违约或删除。 一些无效的分类器值触发带有警告的默认值. 仅字面 `true` 启用 `classifier.enabled`。 。 。 . 见 [配置解析器](https://npmcn.com/package/%40gagansd/pi-web-search/src/providers/config.ts) 用于验证细节. ### 可选彻底搜索和Jev 1. 运行 `/web-search` 以识别配置路径. 2. 合并 `{"research":{"enabled":true}}` 进入文件. 3. 运行 `/reload`。 。 。 . `effort: "thorough"` 将相同的查询同时发送到 `scope`. Fan-out 被限制:最多 **每个家庭两次实际运输** 按配置顺序,最多4个 `both`; 缺失的运输不消耗一个槽. `fallback: []` 不排除来源。 它不检查协议或发起进一步搜查. `scope: "both"` 默认为彻底; 明确 `effort: "fast"` 与 `both` 被拒绝,以及 `research.enabled` 一定是事实 快来电从不刻意打出去. 捷夫需要单独的选入. 匿名检索不需要分类证书 。 见 [分类器设置](https://npmcn.com/package/%40gagansd/pi-web-search/docs/research.md#enable-external-judgment), (中文(简体) ), [调音](https://npmcn.com/package/%40gagansd/pi-web-search/docs/research.md#all-classifier-settings),以及 [失败行为](https://npmcn.com/package/%40gagansd/pi-web-search/docs/research.md#outcomes-and-limits)。 。 。 . ## 全权证书 Exa MCP,并列原生MCP,grep.app,和Sourcegraph不需要搜索密钥. Jina Reader以匿名方式处理只取URL;勇者搜索需要自己的密钥. 匿名并行有较低的服务器控制率限制. 平行密钥是可选的 . 搜索证书使用之前的第一个非空白环境别名 `/auth.json`GitHub 然后尝试已有的 `gh auth login` 符号 . | 存储的ID | 环境别名,优先 | 行为 | | --- | --- | --- | | `exa` | `EXA_API_KEY` | 选择 REST 而不是无密钥 MCP . | | `parallel` | `PARALLEL_API_KEY` | 为更高的限制添加一个 Bearer 头. | | `github` | `GITHUB_TOKEN`, (中文(简体) ), `GH_TOKEN` | 需要一个标志。 返回只核实公开结果. | | `brave` | `BRAVE_API_KEY`, (中文(简体) ), `BRAVE_SEARCH_API_KEY` | 可选的 REST 搜索提供者; 需要密钥 . | - 设置环境变量 **启动 Pi 之前**。在另一个外壳中导出不能改变运行中的 Pi 进程。 随着环境的改变,Pi重新开始. - 扩展读取 Exa/GitHub 存储每个操作的密钥. - 同时在MCP注册时捕捉到它的"熊"(Bearer)头. 运行 `/reload` 更改其键后. 合并此条目为已存在的 `auth.json` 不替换其他全权证书: ```json { "parallel": { "type": "api_key", "key": "" } } ``` - 私下替换占位符 . - 从版本控制中排除认证文件 . - 使用窄范围密钥/托盘 . 这个 [检索证书解析器](https://npmcn.com/package/%40gagansd/pi-web-search/src/env.ts) 读取正文 `.key` 字符串,而不是 shell 命令,嵌入环境引用,或者 OAuth 刷新证书 。 无法读取/ malform auth 表示没有存储的密钥 . `/web-search provider` 在 `auth.json` 并显示创建地点。 密钥从不命令参数, 也从不写给 `web-search.json`,然后在键入后从不显示。 环境化名仍然能赢得存储值. Pi 提供可选的主机对等器. 此软件包没有安装另一个 Pi 副本 。 见 [npm 咨询说明](https://npmcn.com/package/%40gagansd/pi-web-search/docs/release-validation.md#npm-advisory-and-host-dependencies)。 。 。 . Pi单独解决判断时的分类认证. Jev不需要单独的钥匙. 每个供应商都控制配额和账单。 钥匙不能保证配额或价格变化。 其他来源不能保证结果或可获得性. `/web-search` 显示认证快照,而不是活键有效性测试 。 它从来不显示钥匙. ### 可选勇士搜索 运行 `/web-search provider brave` 并合并到 `web-search.json`数字 : ```json { "web": { "provider": "brave", "fallback": ["exa", "parallel"] } } ``` 勇者号使用一个 REST 请求并返回排序片段,而不是生成答案或额外片段. 它的查询仅限于400个字符和50个单词;较长的查询明显失败,而不是默默地被缩短. 没有钥匙,勇者就跳过了。 彻底 `search` 在出示证书时考虑这一点,但须遵守配置的供应商命令和每家双向运输的限制。 被应用的URL被无密钥的Jina取出,从不与查询结合. 仅限 URL `search({ urls })` 使用 Jina Reader ,而不论搜索提供者的选择,现有网页提取作为可重试倒计时. Jina不是一个搜索引擎,不需要设置,只接收请求的URL,而不是搜索查询. Jina Markdown省略了图像和链接目的地,以减少输出噪音。 新提供者共享现有的预览和本地续作预算;不添加新的LLM指令或工具. ## 提供者的行为和限制 - 默认链 : **Exa − 平行** 财务报告和审定财务报表 **grep.app – sourcegraph – GitHub 页面存档备份,存于互联网档案馆 Grep.app – sourcegraph – GitHub**。 。 。 . - 空的网络结果不会触发回落 。 空代码结果或可重试失败继续通过 [供应商链](https://npmcn.com/package/%40gagansd/pi-web-search/src/providers/index.ts)。 。 。 . - 结果包含链接和摘录,不保证完整页。 确切的重复证据已经倒塌,而不同的段落和代码锚仍然保留。 搜索片段在直接输出和结构输出中被封为400个字符. 每条产出路径都有8 000个特点的全球预算;过多的引用被全部省去,并附有通知,从未缩短。 所储存的通道可以在有指针和光标的有约束的窗口中被读取. 见 [结构化产出](https://npmcn.com/package/%40gagansd/pi-web-search/src/format.ts)。 。 。 . - HTTP直接取回已限定30秒会话再用和飞行中分解. 限速供应商输入一个短冷却. 平行的嵌入式呼叫总是通过 Pi 执行,所以权限检查永远不会被再利用. 见 [效率和限制](https://npmcn.com/package/%40gagansd/pi-web-search/docs/efficiency.md)。 。 。 . ## 超时、倒计时和错误 检索和判决分担违约 **20秒钟** 预算。 清净能取更久. Jev 失败后会带着警告返回未经判断的证据. 检索截止日期已过,或呼叫者取消呼叫失败. 检查警告和 `/web-search`启用 `/mcp` 平行连接问题. ## 数据处理 **不要发送秘密或私人密码.** 外部提供者接受查询和URL. 可选Jev在输出剪接前接收候选标题,URL,和提供者节选. 获取的内容是不信任的. Jev不是快速注射防火墙或真相保障. 扩展不会将工作空间文件或会话历史作为搜索有效载荷发送. Pi可以在会话历史中保留工具调用. 查询,URL,出错,和摘录可以包含敏感文本. ## 开发和包装检查 1. 运行 `cd pi-web-search`。 。 。 . 2. 运行 `npm ci --ignore-scripts --no-audit --no-fund`。 。 。 . 3. 运行 `npm test`。 。 。 . 4. 运行 `npm run typecheck`。 。 。 . 5. 运行 `npm run audit:prod`。 。 。 . 6. 运行 `npm run pack:check`。 。 。 . 7. 运行 `npm run bench:context` 用于离线上下文脚印测量(特征-代用估计,而不是计费的代用计数). 可选检索检查 : `npm run smoke:live`。它会发出公开的测试询问,没有您的全权证书。 可选决定模式检查 : `npm run smoke:classifier` 使用您的 Pi 认证( billing application) 给默认的 Jev 模式进行四个直播。 它验证排名,注射抑制,证据不足,以及普通代码. 测试另一对,使用 `npm run smoke:classifier -- `。见 [释放检查和限制](https://npmcn.com/package/%40gagansd/pi-web-search/docs/release-validation.md)。 。 。 . SDK 用户必须装入 Pi 的 MCP 扩展名,用于本地并行呼叫和呼叫 `bindExtensions()`代码是可选的;直接 `search` 要求继续支持。 见 [SDK 实例](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/sdk/14-codemode-mcp.ts)。 。 。 . ## 许可证 [麻省理工学院](https://npmcn.com/package/%40gagansd/pi-web-search/LICENSE) - 加根・德瓦吉里 ## 常见问题 ### @gagansd/pi-web-search 是什么？ 一个搜索工具,用于公共网络/代码,URL提取,以及本地证据的续作\. 引用,上下文高效,默认无密钥\. ### 如何安装 @gagansd/pi-web-search？ 在项目目录运行 npm install @gagansd/pi-web-search，或使用 pnpm add / yarn add / bun add。 ### @gagansd/pi-web-search 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/gagansd\_\_pi-web-search 是否存在。 ### @gagansd/pi-web-search 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @gagansd/pi-web-search 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @gagansd/pi-web-search 可以商用吗？ @gagansd/pi-web-search 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @gagansd/pi-web-search 的下载量有多少？ 根据 npm 官方下载统计，@gagansd/pi-web-search 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,670 次，日均约 122 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @gagansd/pi-web-search 还在维护吗？ 最新版本 0\.4\.0 发布于 2026/10/26（21 天前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/10/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。