# pi-search-kit

[English](README.md)

为 [Pi](https://pi.dev) 打造的 LLM 驱动网络搜索与内容提取扩展。内置 Tavily、AnySearch 搜索与 Jina 内容提取。

## 功能

- **内置 Provider 覆盖**：Tavily 和 AnySearch 提供通用及垂直搜索；Tavily、AnySearch 和 Jina 提供内容提取。
- **LLM 驱动动态路由**：各 Provider 声明能力元数据（`searchHint`/`fetchHint`），大模型根据注入的 `promptGuidelines` 智能选择最佳 Provider，无需硬编码规则分类器。
- **零门槛配置与降级链**：Tavily、AnySearch 支持免 Key 搜索，Jina 支持免 Key 网页提取。当服务暂时不可用时，自动触发按成本优化的降级链。
- **SSRF 安全防护 Guard**：内置 DNS 校验与私有 IP 拦截，有效防御针对内网、回环地址及云服务元数据接口的 SSRF 攻击。
- **输出体积控制与去重**：自动合并去重搜索结果，超大网页内容自动切片截断并保存至本地临时文件。

## 环境要求

- Node.js 22.19.0 或更高版本
- `@earendil-works/pi-ai`、`@earendil-works/pi-coding-agent`、`@earendil-works/pi-tui` 以及 `typebox`
- 内置 Tavily、AnySearch 搜索和 Jina 提取均无需配置 API Key

## 安装

```sh
pi install npm:pi-search-kit
```

## 配置

内置 Tavily、AnySearch 和 Jina 均可在不配置 API Key 的情况下使用。要使用需要认证的 Provider 能力，请配置对应的环境变量：

| Provider | 环境变量 | 特长与说明 |
| --- | --- | --- |
| Tavily | `TAVILY_API_KEY`（可选） | 免 Key 通用搜索和提取；配置 Key 后可用 crawl/map/research |
| AnySearch | `ANYSEARCH_API_KEY`（可选） | 免 Key 通用、垂直搜索和提取 |
| Jina | `JINA_API_KEY`（可选） | 免 Key 网页与 PDF 内容提取 |

环境变量优先于已有 `~/.pi/pi-search-kit/config.json` 配置文件中的值。为兼容之前版本，扩展仍会读取该配置文件，格式如下：

```json
{
  "apiKeys": {
    "tavily": "your-tavily-key",
    "anysearch": "your-anysearch-key",
    "jina": "your-jina-key"
  }
}
```

## 使用

大模型可直接调用 `web_search` 或 `web_fetch` 工具：

```ts
// 使用 Tavily 进行通用搜索
web_search({ query: "React 19 features", provider: "tavily" })

// 使用内置 AnySearch 进行垂直搜索
web_search({ query: "AAPL stock price", provider: "anysearch", vertical: "finance.us_stock" })

// 使用 Jina 进行网页内容提取
web_fetch({ url: "https://example.com/article", provider: "jina" })
```

当未显式指定 `provider` 时，内置服务商按成本优先顺序尝试：
- **搜索**：`Tavily → AnySearch`
- **提取**：`Tavily → Jina → AnySearch`

显式指定 `provider` 后，扩展只使用该服务商；如果请求失败，会直接返回错误，不会静默切换到其他服务商。

## 安全

Pi 扩展以当前用户的系统权限运行。安装前请审查源代码，并且只配置你信任的服务。

本扩展向外部 Provider API 及用户请求的网页 URL 发起网络请求。扩展内置了 SSRF 防护 Guard（`assertSafeDns` 及 IP 校验），严禁访问私有 IP 段（`127.0.0.1`、`10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16` 以及 AWS 元数据地址 `169.254.169.254`）。API Key 从 `~/.pi/pi-search-kit/config.json` 或环境变量读取。

## 开发

```sh
git clone https://codeberg.org/huanghui/pi-search-kit.git
cd pi-search-kit
npm ci
npm run check
npm test
npm pack --dry-run --json
```

架构决策记录与术语词汇表请参阅 [CONTEXT.md](CONTEXT.md) 与 [docs/adr/](docs/adr/)。

## 参与贡献

欢迎通过 [Codeberg](https://codeberg.org/huanghui/pi-search-kit/issues) 提交 issue 和范围明确的拉取请求。提交前请运行 `npm run check` 和 `npm test`。

## 许可证

[MIT](LICENSE)