Bocha Web Search pi Extension

为 pi 开发的 Bocha AI 网页搜索扩展，注册一个 bocha_web_search 工具，用于搜索网页并返回 Markdown 格式的结果列表。

功能简介

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

安装

通过 pi 安装（推荐）

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

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

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

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

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

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

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 的场景。在项目根目录（或其任意上级目录）下手动创建：

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

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

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：

{
  "apiKey": "YOUR_BOCHA_API_KEY"
}

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

配置示例

{
  "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 文件；请按上述步骤手动准备配置文件。