# Pi Search Tools

[English](README.md)

为 [Pi](https://pi.dev) 打造的 LLM 驱动式网页搜索与内容提取扩展。扩展本身**不做**查询分类或自动选服务商——每个服务商通过元数据（`searchHint`/`fetchHint`）声明其专长，调用方 LLM 根据动态生成的 `promptGuidelines` 通过 `provider` 参数选择最佳服务商。

---

## 服务商

| 服务商 | 搜索 | 提取 | 说明 |
|----------|------|------|------|
| **Tavily** | ✅ | ✅ | 通用网页搜索 + crawl/map/research（SimpleQA SOTA 93.3%） |
| **Exa** | ✅ | ✅ | 语义/学术搜索，强时效 |
| **Serper** | ✅ | — | 基于 Google 搜索的快速通用网页/新闻搜索 |
| **iFlow** | ✅ | ✅ | 针对中文查询和新闻优化的搜索与高净度内容提取 |
| **Anysearch** | ✅ | ✅ | 结构化垂直搜索（金融、学术、安全、旅行） |
| **Gemini** | ✅ | — | Google 官方搜索（基于 Grounding API） |
| **DeepSeek** | ✅ | — | 基于 DeepSeek 官方 Anthropic 兼容端点的服务端搜索工具 |
| **Jina** | — | ✅ | JS 渲染、原生 PDF、频率限制、**零门槛**（无需 API key） |
| **Firecrawl** | — | ✅ | 完整 Playwright 渲染，JS 能力最强，月度配额 |

## 项目结构

```
pi-search-tools/
├── index.ts                           # Pi 扩展入口（转发至 src/index.ts）
├── src/
│   ├── index.ts                       # 扩展注册逻辑
│   ├── config.ts                      # 配置文件解析 (~/.pi/pi-search-tools/config.json)
│   ├── commands.ts                    # 交互式 /search-tools API key 配置
│   ├── utils.ts                       # 结果去重、SSRF 防护、重试/超时、内存缓存
│   ├── web-search.ts                  # web_search 工具（动态服务商路由）
│   ├── web-fetch.ts                   # web_fetch 工具（SSRF 防护 + 内容提取）
│   └── providers/                     # REST API 客户端 + 服务商元数据
│       ├── index.ts                   # 工厂函数、动态辅助方法、promptGuidelines 聚合
│       ├── types.ts                   # Provider 接口 + META 类型定义
│       ├── tavily.ts                  # Tavily API 适配
│       ├── exa.ts                     # Exa API 适配
│       ├── serper.ts                  # Serper API 适配（Google 搜索封装）
│       ├── iflow.ts                   # iFlow API 适配（中文本地化优化）
│       ├── anysearch.ts               # Anysearch API 适配（垂直搜索）
│       ├── gemini.ts                  # Gemini API 适配（Google Search Grounding）
│       ├── deepseek.ts                # DeepSeek API 适配（服务端搜索 Grounding）
│       ├── jina.ts                    # Jina 提取适配（SSE 解析、零门槛）
│       └── firecrawl.ts              # Firecrawl API 适配
├── test/                              # 原生 TypeScript 单元测试（80 个）
│   ├── providers.test.ts              # META 一致性 + 动态枚举/链生成
│   ├── prompt-guidelines.test.ts      # promptGuidelines 聚合正确性
│   ├── factory.test.ts                # Provider 工厂 + apiKeyRequired 行为
│   ├── execute.test.ts                # 搜索/提取执行流程 + this 绑定回归测试
│   ├── gemini.test.ts                 # Gemini API 请求、响应解析、重定向超时
│   ├── deepseek.test.ts               # DeepSeek API 流式解析与自定义模型测试
│   ├── jina-fetch.test.ts            # Jina SSE 解析 + 去重
│   ├── config.test.ts                 # API key 掩码与解析优先级
│   ├── dedup.test.ts                  # URL 去重
│   └── utils.test.ts                  # SSRF、内存缓存、超时/重试
└── package.json
```

---

## 安装

```bash
pi install npm:pi-search-tools
```

---

## 配置

### 交互式设置
```bash
/search-tools
```
选择服务商并输入 API key。

### 环境变量
在环境中配置服务商 API key（优先级高于配置文件）：
- `TAVILY_API_KEY`
- `EXA_API_KEY`
- `SERPER_API_KEY`
- `IFLOW_API_KEY`
- `ANYSEARCH_API_KEY`
- `GEMINI_API_KEY`
- `DEEPSEEK_API_KEY`
- `DEEPSEEK_SEARCH_MODEL` （可选，自定义搜索所用的模型，默认为 `deepseek-v4-flash`）
- `JINA_API_KEY`
- `FIRECRAWL_API_KEY`

---

## 路由

### LLM 驱动路由
扩展**不做**查询分类。调用方 LLM 通过 `provider` 参数选择服务商：

```
# 通用搜索 → Tavily（最快）
web_search({ query: "React 19 features", provider: "tavily" })

# 学术搜索 → Exa（语义检索，强时效）
web_search({ query: "transformer architecture paper", provider: "exa" })

# 股票/CVE → Anysearch + vertical
web_search({ query: "AAPL", provider: "anysearch", vertical: "finance.us_stock" })
web_search({ query: "CVE-2025-12345", provider: "anysearch", vertical: "security.scan" })
```

如果不传 `provider`，自动走成本优先兜底链：
- 搜索链：`Tavily → Exa → Serper → iFlow → Anysearch → Gemini → Deepseek`
- 提取链：`Tavily → Jina → Exa → Anysearch → Firecrawl → iFlow`

当**显式指定**服务商且调用失败时，扩展**不会**回退——将错误直接返回给 LLM，尊重 LLM 的选择。

---

## 架构设计

设计决策文档位于仓库中：
- **[CONTEXT.md](https://codeberg.org/huanghui/pi-search-tools/src/branch/main/CONTEXT.md)** — 领域术语表和规范命名
- **[docs/adr/](https://codeberg.org/huanghui/pi-search-tools/src/branch/main/docs/adr/)** — 架构决策记录（LLM 路由、单接口、Jina 搜索排除、Anysearch 保留）

---

## 测试

```bash
npm run test
```

共 80 个测试，覆盖 META 一致性、链生成、promptGuidelines 聚合、工厂行为、执行流程、SSE 解析、配置解析、去重和 SSRF 防护。

---

## 开发

- **格式化与语法检查**: [Biome](https://biomejs.dev)，tab 缩进（宽度 3）
- **TypeScript**: 严格模式
- **检查**: `npm run check`
- **测试**: `npm test`

---

## 许可证书

MIT