# Pi Search Tools

[English](README.md)

为 [Pi](https://pi.dev) 打造的统一网页搜索与内容提取扩展包。

---

## 项目结构

```
pi-search-tools/
├── index.ts                           # Pi 扩展入口（转发至 src/index.ts）
├── src/
│   ├── index.ts                       # 扩展注册逻辑
│   ├── config.ts                      # 配置持久化与 Key 解析器 (~/.pi/pi-search-tools/config.json)
│   ├── commands.ts                    # 状态机循环控制的 /search-config 配置命令
│   ├── router.ts                      # 意图分类器与服务商路由分发器
│   ├── utils.ts                       # 并发检索结果 URL 去重核心算法
│   ├── web-search.ts                  # web_search 工具实现（含多角度并发查询分发）
│   ├── web-fetch.ts                   # web_fetch 网页文本提取工具（内置 SSRF 安全拦截）
│   └── providers/                     # 底层搜索引擎与阅读器 API 客户端
│       ├── index.ts                   # 静态工厂与服务商配置
│       ├── types.ts                   # 统一纯类型定义 (SearchResult, SearchProvider)
│       ├── tavily.ts                  # Tavily 客户端适配（支持搜索、crawl 与 research）
│       ├── exa.ts                     # Exa 客户端适配（时序敏感型抓取）
│       ├── anysearch.ts               # Anysearch 客户端适配（提供垂直分类结构化检索）
│       ├── serper.ts                  # Serper (Google Search) 客户端适配
│       └── jina.ts                    # Jina Reader 网页提取客户端
├── test/                              # 原生 TS 单元测试套件
│   ├── security.test.ts               # SSRF 与内网/回环地址阻断边界测试
│   ├── router.test.ts                 # 意图语义分类与主备路由测试
│   ├── config.test.ts                 # 敏感 Key 掩码遮蔽与环境变量加载优先级测试
│   └── dedup.test.ts                  # URL 去重纯逻辑断言测试
├── skills/                            # Pi Coding Agent 大模型检索策略指南
│   └── search/
│       └── SKILL.md                   # 引导 LLM 在不同场景下高效调用工具 of Skill 指南
└── package.json
```

---

## 安装

支持以下两种方式安装：

* **NPM 安装（推荐）**：
  ```bash
  pi install npm:pi-search-tools
  ```
* **GitHub 安装**：
  ```bash
  pi install https://github.com/huanghui-dev/pi-search-tools
  ```

---

## 配置与使用

### 命令行交互面板
在终端运行配置命令：
```bash
/search-config
```
在 API Key 输入框中按返回键或取消，将安全返回上一级服务商列表。

### 环境变量
可直接配置环境变量（优先级高于配置文件）：
- `TAVILY_API_KEY`
- `EXA_API_KEY`
- `ANYSEARCH_API_KEY`
- `SERPER_API_KEY`
- `JINA_API_KEY`

---

## 执行测试

运行内置的 TypeScript 单元测试（基于 Node.js 原生测试运行器）：
```bash
npm run test
```

---

## 安全与防御

为保证企业级沙箱运行安全，`pi-search-tools` 内置了严密的防 SSRF（服务端请求伪造）劫持策略：
1. **私有网络阻断**：严格拦截针对 `localhost`、IPv4 回环网段（`127.0.0.0/8`）、本地链路网段（`169.254.0.0/16`）以及私有局域网网段（`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`）的 HTTP 请求。
2. **DNS 重绑定防御**：在实际发出 HTTP 请求前，会进行异步 DNS 预解析校验，对解析出的 IP 地址再次进行私有网段强力拦截，全面防御 DNS 重绑定（DNS Rebinding）漏洞。

---

## 开发与规范

已严格对齐 `pi-main` 核心工程的质量与安全规范：
1. **格式化与语法检查**：使用 Biome 对项目代码进行统一格式化。缩进风格配置为 `tab`，缩进宽度为 `3`。
2. **常用指令**：
   - 运行风格与语法检测：`npm run check`（自动执行 `biome check --write .`）
   - 运行单元测试：`npm test`

---

## 许可证书

MIT