# 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 包目录变化**，扩展按以下优先级查找：

```
查找顺序：
1. 项目级：.pi/bocha-web-search/config.json（从当前目录向上搜索）
2. 用户级：~/.pi/agent/bocha-web-search/config.json（兜底）
```

即：从当前工作目录开始逐级向上查找 `.pi/bocha-web-search/config.json`，命中即用；一直找到根目录都没有时，回退到用户级配置。

### 项目级配置（可选，优先）

适用于某个项目需要使用独立 API Key 的场景。在项目根目录（或其任意上级目录）下手动创建：

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

注意：项目级配置目录**不会被自动创建**，需要按上述步骤手动准备。

### 用户级配置（兜底）

未提供项目级配置时，使用用户级配置：

```
~/.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/` 配置目录，不会自动创建项目级 `.pi/bocha-web-search/` 目录或任何 `config.json` 文件；请按上述步骤手动准备配置文件。