# @amaster\.ai/pi-web-access 中文文档

规范地址：https://npmcn.com/package/%40amaster.ai/pi-web-access/

版本：0\.1\.37
npm 元数据更新时间：2026-11-09T02:51:46.988Z
中文译文更新时间：2026-11-09T05:47:36.271Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40amaster.ai/pi-web-access
原文对照：https://npmcn.com/package/%40amaster.ai/pi-web-access/?lang=original
项目主页：https://github.com/TGYD-helige/pi#readme
源码仓库：https://github.com/TGYD-helige/pi

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.1 MB，112 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \>=0\.80\.10，@earendil-works/pi-coding-agent \>=0\.79\.1
- 首次发布：2026-06-09T08:17:50.481Z
- 最新版本发布：2026-11-09T02:51:46.775Z
- 近 30 天下载量：5929（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：106（近 12 个月 106 个）

## 中文简介

用于网页搜索、URL内容提取和图像搜索的 Pi 扩展名( Cloudflare, Tavily, Kimi, DeepSeek, Mimo, Z.AI, DashScope, Unsplash等)

## 安装

```sh
npm install @amaster.ai/pi-web-access
```

也可以使用：`pnpm add @amaster.ai/pi-web-access`、`yarn add @amaster.ai/pi-web-access`、`bun add @amaster.ai/pi-web-access`

## README

# pi-web-访问

![pi-web-access preview](https://raw.githubusercontent.com/TGYD-helige/pi/master/packages/pi-web-access/preview.png)

Pi扩展用于网页搜索和URL内容提取.

## 工具

### `web_search`

腾讯网. 也可通过 `/web-search <query>`。当键盘搜索提供者可用或当无键时注册 `parallel` 明确选择提供者.

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | :-: | :-: |
| `query` | 字符串 | 对 | 搜索查询 |
| `maxResults` | 编号 | 没有 | 返回的最大结果( 默认 5) |
| `topic` | `"general"` | `"news"` | 没有 | 专题类别 |
| `timeRange` | `"day"` | `"week"` | `"month"` | `"year"` | 没有 | 紧急过滤器 |
| `includeDomains` | 字符串 \[\] | 没有 | 只包括这些领域的成果 |
| `excludeDomains` | 字符串 \[\] | 没有 | 排除这些领域的结果 |

### `web_fetch`

获取一个 URL并返回其内容 。 也可通过 `/web-fetch <url> [extraction instructions]`;省略时,指示默认“放大本页”。 何时 `fetch.summary` 配置,摘要模型将使用 `prompt`; 否则直接返回取回的内容 `prompt` 为相容性而保留,但被忽略。 仅在 `fetch.provider` 或者说 `fetch.summary` 已配置.

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | :-: | :-: |
| `url` | 字符串 | 对 | 公共 HTTP( S) URL; 拒绝私有、 回回、 链接本地、 元数据、 认证和不安全的重定向目的地 |
| `prompt` | 字符串 | 对 | 关于已配置摘要模型的说明; 为兼容性而保留, 但当 `fetch.summary` 未配置 |

### `x_search`

Search X (Twitter) 为帖子和社交媒体内容. 仅在xai 提供者有 API 密钥时注册 .

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | :-: | :-: |
| `query` | 字符串 | 对 | X 上的搜索查询 |
| `allowedHandles` | 字符串 \[\] | 没有 | 仅包括这些手柄的员额(最多20个) |
| `excludedHandles` | 字符串 \[\] | 没有 | 从这些手柄中不包括员额(最多20个) |
| `fromDate` | 字符串 | 没有 | 开始日期( YYYY- MM- DD) |
| `toDate` | 字符串 | 没有 | 结束日期( YYYY- MM- DD) |

### `image_search`

搜索网络图像 。 仅在图像搜索提供者时注册( E)`dashscope` 或者说 `unsplash`)有API键. 也可以直接通过 `/image-search <query>` 命令.

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | :-: | :-: |
| `query` | 字符串 | 对 | 要搜索的图像描述 |

## 结构化工具成果

在有结构化工具支持的 Pi 运行时,代码代号接收来自这些工具的对象,而不是解析它们的Markdown. `web_search`, (中文(简体) ), `x_search`,以及 `image_search` 返回时 `{ provider, query, answer?, results, truncated }`,其中每个来源有 `title`, (中文(简体) ), `url`, (中文(简体) ), `content`,可选 `score`。 。 。 . `web_fetch` 返回时 `{ url, title, content, truncated }`; 内容是配置摘要模型时的摘要。 可读工具结果仍然可用.

结果有限度 `truncated` 表示缩短的文本或省略的源;保留源 URL从不缩短。 调用失败返回 `{ error }` 与 `isError: true`,所以脚本必须检查 `error` 在读取结果字段之前。 取消仍然中止通话 。 年长的Pi 运行时间保持他们的文本结果行为.

## 供应商

| 提供者 | 搜索 | 获取 | X 搜索 | 图像搜索 | 默认基址 | 信封瓦尔 | 默认模式 |
| --- | --- | :-: | :-: | :-: | --- | --- | --- |
| `cloudflare` | ✓ | ✗ | ✗ | ✗ | `https://api.cloudflare.com/client/v4` | `CLOUDFLARE_API_TOKEN` | \- 说吧 |
| `parallel` | ✓ | ✗ | ✗ | ✗ | `https://search.parallel.ai/mcp` | 无密钥 | \- 说吧 |
| `tavily` | ✓ | ✓ | ✗ | ✗ | `https://api.tavily.com` | `TAVILY_API_KEY` | \- 说吧 |
| `brave` | ✓ | ✗ | ✗ | ✗ | `https://api.search.brave.com` | `BRAVE_API_KEY` | \- 说吧 |
| `firecrawl` | ✓ | ✓ | ✗ | ✗ | `https://api.firecrawl.dev` | `FIRECRAWL_API_KEY` | \- 说吧 |
| `kimi` | ✓ | ✗ | ✗ | ✗ | `https://api.moonshot.cn/v1` | `MOONSHOT_API_KEY` | `kimi-k3` |
| `mimo` | ✓ | ✗ | ✗ | ✗ | `https://api.xiaomimimo.com/v1` | `MIMO_API_KEY` | `mimo-v2.5-pro` |
| `zai` | ✓ | ✓ | ✗ | ✗ | `https://api.z.ai` | `ZAI_API_KEY` | \- 说吧 |
| `gemini` | ✓ | ✗ | ✗ | ✗ | `https://generativelanguage.googleapis.com/v1beta` | `GEMINI_API_KEY` | `gemini-2.5-flash` |
| `perplexity` | ✓ | ✓ | ✗ | ✗ | `https://api.perplexity.ai` | `PERPLEXITY_API_KEY` | `openai/gpt-5.5` |
| `deepseek` | ✓ | ✓ | ✗ | ✗ | `https://api.deepseek.com` | `DEEPSEEK_API_KEY` | \- 说吧 |
| `openrouter` | ✓ | ✓ | ✗ | ✗ | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` | `openai/gpt-4.1-mini` |
| `xai` | ✓ | ✗ | ✓ | ✗ | `https://api.x.ai/v1` | `XAI_API_KEY` | `grok-4.3` |
| `openai` | ✓ | ✗ | ✗ | ✗ | `https://api.openai.com/v1` | `OPENAI_API_KEY` | `gpt-5.5` |
| `anthropic` | ✓ | ✓ | ✗ | ✗ | `https://api.anthropic.com/v1` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
| `dashscope` | ✓ | ✓ | ✗ | ✓ | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `DASHSCOPE_API_KEY` | `qwen3.8-flash` |
| `unsplash` | ✗ | ✗ | ✗ | ✓ | `https://api.unsplash.com` | `UNSPLASH_ACCESS_KEY` | \- 说吧 |
| `you` | ✓ | ✓ | ✗ | ✗ | `https://ydc-index.io` | `YDC_API_KEY` | \- 说吧 |

### 深搜索和获取

深层搜索使用 [搜索和获取 API](https://api-docs.deepseek.com/zh-cn/guides/search/)数字 : `POST /v1/tools/search` 返回带有长摘要的排序来源,以及 `POST /v1/tools/fetch` 返回 Markdown。 设定 `search.provider` 和(或) `fetch.provider` 改为 `"deepseek"` 供应 `DEEPSEEK_API_KEY` 或者说 `providers.deepseek.apiKey`现有 " 深搜索 " 设置继续发挥作用; `model` 被忽略, 搜索不再返回合成 `answer`根和根 `/v1` 支持基础 URL.

搜索请求的使用 `count` (违约5,API限制50)和 `need_content: false`; 获取其全体的结果 URL。 域过滤器变为 `site:` 编号 : `-site:` 语法,以及 `timeRange` 成为 `after:YYYY-MM-DD` 过滤器 (1/7/30/365天,协调世界时). 包括过滤器在内的完整查询必须包含1–128个Unicode字符. `topic` 忽略; 使用查询术语搜索新闻。 Raw DeepSeek搜索语法也可以直接包含在查询中.

### 云浮网络搜索

设定 `search.provider` 改为 `"cloudflare"`编辑 [Cloudflare 网络搜索 REST API](https://developers.cloudflare.com/web-search/how-to-use/) 需要账户标识, API 令牌, 与 **工人AI:阅读** 财务报告和审定财务报表 **AI 网关: 已读** ,以及带有信用或存储提供者密钥的AI Gateway. 默认网关是 `default`; 默认搜索提供者是 `ceramic`。 。 。 .

```json
{
  "pi-web-access": {
    "search": { "provider": "cloudflare" },
    "providers": {
      "cloudflare": {
        "apiKey": "${CLOUDFLARE_API_TOKEN}",
        "accountId": "${CLOUDFLARE_ACCOUNT_ID}",
        "gatewayId": "default",
        "searchProvider": "ceramic"
      }
    }
  }
}
```

`apiKey` 财务报告和审定财务报表 `accountId` 倒计时 `CLOUDFLARE_API_TOKEN` 财务报告和审定财务报表 `CLOUDFLARE_ACCOUNT_ID`. Cloudflare 在现有搜索提供者之后,也可以自动选择两者。 在用户或代理设置中配置插值;信任的项目设置不会扩展环境变量.

Cloudflare 唯一的提供者设置 :

| 外地 | 说明 |
| --- | --- |
| `accountId` | Cloudflare 账户 ID( 需要; 支持环境回落) . |
| `gatewayId` | AI 网关 ID( 默认) `default`) (中文(简体) ). |
| `searchProvider` | `ceramic`, (中文(简体) ), `exa`,或 `linkup` (默认) `ceramic`) (中文(简体) ). |
| `byokAlias` | AI Gateway中存储的提供者密钥的可选别名. 如果在网关上缺失,API会失败,而不是回到信用. |

请求使用 `POST {baseUrl}/accounts/{accountId}/ai/websearch/`。查询必须包含1–1024个字符. `maxResults` 默认为5并上限为10; `topic`, (中文(简体) ), `timeRange`, (中文(简体) ), `includeDomains`,以及 `excludeDomains` 被忽略,因为该 API 不支持它们。 结果包含标题,URL,和描述片段,没有被合成的答案;大片段被截取. Cloudflare 只支持搜索 .

自定义 Kimi 基础 URL 必须支持两者 `/chat/completions` 财务报告和审定财务报表 `/formulas/*`。 。 。 .

You.com search return web and news results in one call; 中文网 中文网 中文网; `topic: "news"` 更喜欢新闻结果并应用一周的新鲜度窗口。 内容 API`/v1/contents`返回干净的Markdown for `web_fetch`。获取密钥到 [api- keys (中文(简体) )](https://you.com/platform/api-keys)。 。 。 .

自定义 DashScope 基址必须指向一个与 OpenAI 兼容的响应 API 根 —— `${baseUrl}/responses` 需要所有的能力。 对于国际站点或专用的工作空间端点,例如使用. `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`中 `web_extractor` 工具和图像搜索用途 `web_search_image`; 两者都是代理式工具,每次呼叫需要几分钟时间(默认超时5分钟,调制通过 `timeoutMs`) (中文(简体) ). DashScope搜索只支持基本的网络搜索—— `includeDomains`编号 :`excludeDomains` 过滤器被忽略 .

**获取倒计时** (当 `fetch.provider` 未设置 :`r.jina.ai`\- 本地HTTP + 关闭。 两个阶段,包括目的地和重新定位DNS验证,共享一个 `timeoutMs` 截止时间(默认为30秒),Jina得到的预算最多一半,因此阅读者缓慢,仍然留有时间回落。 Jina和本地响应机构在文本/HTML转换前被封顶为2 MiB,超大小的响应返回了标记为部分的前缀. 部分旗能活过总和;使用有重点的搜索或浏览器检查来取回缺失的证据,而不是重复同样的全取. 配置的提供者适配器保留自己的响应和超时政策.

## 配置

设置密钥 : `pi-web-access`

项目 `.pi/settings.json` 数值只有在项目信任被接受之后才被加载,而不是环境插入。 用户和代理设置保留了环境插值.

```json
{
  "pi-web-access": {
    "search": {
      "provider": "kimi"
    },
    "fetch": {
      "provider": "zai",
      "summary": {
        "provider": "amaster",
        "model": "deepseek-v4-flash"
      }
    },
    "providers": {
      "kimi": {
        "apiKey": "AMASTER_API_KEY",
        "baseUrl": "https://credits.amaster.ai/v1"
      },
      "zai": {
        "apiKey": "${ZAI_API_KEY}"
      },
      "xai": {
        "apiKey": "${XAI_API_KEY}"
      }
    }
  }
}
```

### `search`

| 外地 | 说明 |
| --- | --- |
| `provider` | 用于网页搜索的哪个提供者 。 不设置 = 用密钥自动选择第一个提供者 。 明确选择 `parallel` 启用无密钥搜索; 否则没有密钥表示工具没有注册 . |

### `fetch`

| 外地 | 说明 |
| --- | --- |
| `provider` | 用于获取 URL 的哪个提供者 。 未设置=jina Reader = 本地倒计时. |
| `summary` | 用于摘要抓取内容的模型配置 . |
| `summary.provider` | 模式提供者名称(通过pi模式注册解决). |
| `summary.model` | 型号编号. |

如果没有 `fetch.provider` 也没有 `fetch.summary` 已配置, `web_fetch` 未注册.

### `imageSearch`

| 外地 | 说明 |
| --- | --- |
| `provider` | 用于图像搜索的哪个提供者( E)`dashscope` 或者说 `unsplash`) (中文(简体) ). 不设置 = 用密钥自动选择第一个提供者 。 没有密钥 = 工具未注册 . |

### `providers`

提供方配置 。 每个提供者支持:

| 外地 | 说明 |
| --- | --- |
| `apiKey` | API密钥. 用户和代理设置支持 `$ENV_VAR` 财务报告和审定财务报表 `${ENV_VAR}`; 仅支持带括号的窗体 `:-fallback`。项目设置保留占位符文字. |
| `baseUrl` | 覆盖默认 API 终点 . |
| `model` | 覆盖默认模式 . |
| `headers` | 额外的信头合并到每个请求中. |

环境变量在 `apiKey` 未设置在配置中.

平行是选入, 只支持搜索 : 它从未启用图像搜索或 `web_fetch`,它不进行 URL 获取或提取。 当选中时, 搜索目标和查询会离开机器 `https://search.parallel.ai/mcp`;这可以包括代理生成的寄存器上下文和这些目标或查询中包含的用户提供的URL. 现有的自动提供者选择,提供者命令,以及按键提供者行为不变.

## 建筑

每个提供者执行 `WebProvider` 接口通过 `BaseProvider`数字 :

```typescript
// providers/base.ts
export interface WebProvider {
  readonly id: BuiltInProviderId;
  search(params: SearchParams, provider: ResolvedProvider): Promise<SearchResponse>;
  fetch(url: string, provider: ResolvedProvider): Promise<FetchResponse>;
  imageSearch(params: ImageSearchParams, provider: ResolvedProvider): Promise<SearchResponse>;
}

export abstract class BaseProvider implements WebProvider {
  abstract readonly id: BuiltInProviderId;
  // Default implementations throw "not supported"
  async search(...) { throw new Error(`${this.id} does not support web_search.`); }
  async fetch(...) { throw new Error(`${this.id} does not support web_fetch.`); }
  async imageSearch(...) { throw new Error(`${this.id} does not support image_search.`); }
}
```

提供者只超越他们所支持的方法。 供应商专用能力(如: `XaiProvider.xsearch`)作为课上的额外方法被曝光.

## 工具登记规则

-   `web_search` 财务报告和审定财务报表 `/web-search <query>` ——当搜索提供者拥有 API 密钥,或者当无密钥时注册 `parallel` 明确选择.
-   `web_fetch` 财务报告和审定财务报表 `/web-fetch <url> [extraction instructions]` 登记时间: `fetch.provider` 或者说 `fetch.summary` 已配置.
-   `x_search` ——xai供应商拥有API密钥时注册.
-   `image_search` ——当图像搜索提供者(dashscope, unsplash)拥有API密钥时注册; `/image-search` 命令与它一起注册。 一个 `imageSearch.provider` 不支持图像搜索(例如). `"openai"`)作为未配置处理.
-   如果没有配置, 扩展加载将默默无声, 没有注册工具 .

## 安装

```bash
pi install npm:@amaster.ai/pi-web-access
```

## 发展

```bash
pnpm build      # tsc -b
pnpm typecheck  # tsc -b --pretty false
pnpm test       # vitest run src
```

### 工具失败

`web_search`, (中文(简体) ), `web_fetch`, (中文(简体) ), `x_search`,以及 `image_search` 返回时 `isError: true` 有保险箱 `error` 信息、信息和 `errorCategory`数字 : `timeout` 请求截止日期, `http_error` 用于识别的 HTTP 失败( 有数字) `httpStatus`, (中文(简体) ), `network_error` 对公认的运输故障, `cancelled` 为上游取消, `configuration_error` 编号 : `invalid_request` 编号 : `invalid_response` 用于经审查的本地验证失败,或 `request_failed` 对未分类的失败。 原始提供者出错,响应机构,URL,和资质被排除在这些故障结果和诊断日志之外. 呼叫取消会传播到运行时间. 这个 `/web-search`, (中文(简体) ), `/web-fetch`,以及 `/image-search` 命令使用相同的安全信息和日志分类。 超时并不意味着提供者配置无效 .

## 常见问题

### @amaster\.ai/pi-web-access 是什么？

用于网页搜索、URL内容提取和图像搜索的 Pi 扩展名\( Cloudflare, Tavily, Kimi, DeepSeek, Mimo, Z\.AI, DashScope, Unsplash等\)

### 如何安装 @amaster\.ai/pi-web-access？

在项目目录运行 npm install @amaster\.ai/pi-web-access，或使用 pnpm add / yarn add / bun add。

### @amaster\.ai/pi-web-access 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @amaster\.ai/pi-web-access 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @amaster\.ai/pi-web-access 可以商用吗？

@amaster\.ai/pi-web-access 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @amaster\.ai/pi-web-access 的下载量有多少？

根据 npm 官方下载统计，@amaster\.ai/pi-web-access 在 2026/10/06 – 2026/11/04 这 30 天内被下载 5,929 次，日均约 198 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @amaster\.ai/pi-web-access 还在维护吗？

最新版本 0\.1\.37 发布于 2026/11/09（今天）；至今共发布 106 个版本，其中过去 12 个月发布了 106 个；首次发布于 2026/06/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。