---
slug: "bocha-web-search-pi-extension"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/Wolido/bocha-web-search-pi-extension@main/README.md"
repo: "https://github.com/Wolido/bocha-web-search-pi-extension"
source_file: "README.md"
branch: "main"
---
# Bocha Web Search pi Extension

为 [pi](https://github.com/earendil-works/pi) 开发的 Bocha AI 网页搜索扩展，注册一个 `bocha_web_search` 工具，用于搜索网页并返回 Markdown 格式的结果列表。

## 功能简介

- 调用 Bocha AI `/v1/web-search` 接口搜索网页。
- 支持设置返回结果数量、时间范围（freshness）以及是否返回 AI 摘要。
- 结果以 Markdown 列表形式返回，包含标题、链接、摘要/片段和发布日期。
- 当输出超过默认行数或字节限制时，会自动截断并将完整内容保存到临时文件。

## 安装

### 通过 pi 安装（推荐）

全局安装（对当前用户生效）：

```bash
pi install npm:bocha-web-search-pi-extension
```

项目级安装（写入当前项目的 `.pi/settings.json`）：

```bash
pi install npm:bocha-web-search-pi-extension -l
```

安装后，在 pi 中执行 `/reload` 即可加载扩展。

如果你想先试用再安装，可以使用本地路径加载：

```bash
pi -e /path/to/bocha-web-search
```

## 配置文件

配置文件固定保存在以下路径，**不会随 npm 包目录变化**：

```
~/.pi/agent/bocha-web-search/config.json
```

首次使用前，请按以下步骤准备配置文件（扩展会在首次调用工具时自动创建配置目录）：

```bash
mkdir -p ~/.pi/agent/bocha-web-search
cp /path/to/bocha-web-search/config.json.example ~/.pi/agent/bocha-web-search/config.json
```

将 `YOUR_BOCHA_API_KEY` 替换为你的真实 Bocha API Key：

```json
{
  "apiKey": "YOUR_BOCHA_API_KEY"
}
```

**注意**：`config.json` 包含敏感信息，请勿提交到 GitHub。本仓库的 `.gitignore` 已默认忽略相关文件，但仍需确保不会误传。

## 配置示例

```json
{
  "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

## 使用示例

在 pi 中调用 `bocha_web_search` 工具：

```
bocha_web_search(query: "pi coding agent 最新功能")
```

带参数调用：

```
bocha_web_search(
  query: "人工智能最新进展",
  count: 10,
  freshness: "oneWeek",
  summary: true
)
```

### 参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `query` | `string` | 是 | - | 搜索关键词 |
| `count` | `integer` | 否 | `5` | 返回结果数量，范围 `1~50` |
| `freshness` | `string` | 否 | `"noLimit"` | 时间范围，可选：`noLimit`、`oneDay`、`oneWeek`、`oneMonth`、`oneYear` |
| `summary` | `boolean` | 否 | `true` | 是否返回 AI 生成的摘要 |

## 注意事项

- 安装完成后请务必在 pi 中执行 `/reload` 重新加载扩展。
- 如果配置文件不存在或 API Key 未设置，调用工具时会抛出明确错误并提示配置文件路径。
- 扩展会自动创建 `~/.pi/agent/bocha-web-search/` 配置目录，但不会自动创建 `config.json` 文件；请按上述步骤手动准备配置文件。