# Felo Search Provider 配置指南

本文档只讲“要配置哪些东西才能让 Pi 用上 `felo` provider”。方案背景见 `DESIGN.md`，改动清单见 `FELO-PROVIDER.md`。

配置分两部分：**环境变量**（endpoint / key / 超时，必须放在环境变量里，不支持写进配置文件）和 **两个 JSON 文件**（让 Pi 认到这个 fork 包、并把它设为默认 provider）。

## 1. 环境变量（必须）

```bash
export CLOUDS_WAY_SEARCH_ENDPOINT="https://searchapi.cloudsway.net/search/<workspace-token>/smart"
export CLOUDS_WAY_SEARCH_KEY="<你的 Bearer token>"
```

| 变量 | 必填 | 说明 |
|---|---|---|
| `CLOUDS_WAY_SEARCH_ENDPOINT` | 是 | 完整 URL，**必须带 `/search/` 前缀**，格式固定为 `https://searchapi.cloudsway.net/search/<workspace-token>/<product-suffix>`。产品线后缀例如 `smart`（SmartSearch，推荐，带语义相关性排序）、`serp`（Litesearch 文搜文）。少写 `/search/` 会直接 404，已实测确认。 |
| `CLOUDS_WAY_SEARCH_KEY` | 是 | Bearer token，鉴权按 workspace 而非按端点绑定，同一个 key 换产品线后缀也能用。 |
| `CLOUDS_WAY_SEARCH_TIMEOUT_MS` | 否 | 请求超时（毫秒）。不设置，或设置了非数字/负数，都会兜底为 `30000`（30 秒）。 |

**不要**把 endpoint/key 写进 `~/.pi/web-search.json` 或任何配置文件——这个 provider 的实现只读环境变量，写进配置文件不会生效。

写入你的 shell 配置（当前 shell 是 zsh）：

```bash
echo 'export CLOUDS_WAY_SEARCH_ENDPOINT="https://searchapi.cloudsway.net/search/<workspace-token>/smart"' >> ~/.zshrc
echo 'export CLOUDS_WAY_SEARCH_KEY="<你的 key>"' >> ~/.zshrc
source ~/.zshrc
```

或者只想在当前终端会话里临时生效，直接在终端执行上面两行 `export` 即可，不用写文件。

## 2. `~/.pi/web-search.json`（新建）

当前这个文件不存在。新建它，写入：

```json
{
  "provider": "felo"
}
```

作用：把 `provider` 显式设为 `felo` 后，Pi 的 `search()` 会直接调用 felo，跳过 auto 模式的整条回退链（不会因为你原来配了别的 provider 而被抢先命中）。

## 3. `~/.pi/agent/settings.json`（修改 `packages` 字段）

当前内容：

```json
{
  "lastChangelogVersion": "0.83.0",
  "theme": "dark",
  "defaultModel": "claude-sonnet-4-6",
  "defaultProvider": "anthropic",
  "packages": [
    "npm:pi-web-access"
  ]
}
```

把 `"packages"` 里的 `"npm:pi-web-access"` 改成本 fork 包的绝对路径：

```json
{
  "lastChangelogVersion": "0.83.0",
  "theme": "dark",
  "defaultModel": "claude-sonnet-4-6",
  "defaultProvider": "anthropic",
  "packages": [
    "/Users/liulong/workspace/felo/felo-pi-web-access"
  ]
}
```

本地路径不需要 `file:` 前缀，直接写绝对路径即可（已查阅 Pi 官方 `packages.md` 确认）。

## 4. 重启 Pi 并验证

改完以上三处，重启 Pi（包内容是直接跑 `.ts` 源码，改文件本身不需要额外 build，但 `packages`/环境变量的变更需要重启进程生效）。

验证顺序：

1. **确认 provider 被识别为可用**：正常发一次 `web_search` 工具调用，观察结果是否来自 CloudsWay（而不是其它 provider 的结果格式）。
2. **确认凭证缺失时报错清晰**：临时 `unset CLOUDS_WAY_SEARCH_KEY` 后再搜一次，应该直接报“未配置凭证”的错误，而不是静默切换到别的 provider（因为已经显式指定了 `provider: "felo"`，官方逻辑不会做 fallback）。验证完记得把 key 重新 `export` 回去。
3. **确认 curator 网页能显示这个 provider**：如果搜索触发了浏览器 curator 页面，页面上应该能看到 "Felo Search" 按钮，且手动点击切换不会被拒绝。

## 常见问题

- **改了环境变量但没生效**：环境变量是进程启动时读取的，改完 `~/.zshrc` 需要开一个新终端窗口（或 `source ~/.zshrc`）重新启动 Pi 进程，不是重启已经在跑的 Pi。
- **想切回官方包**：把 `settings.json` 的 `packages` 改回 `"npm:pi-web-access"`，并把 `web-search.json` 的 `provider` 改成 `"auto"` 或直接删掉这个文件。
- **测试额度**：CloudsWay 测试 key 额度有限（约 10 美金），且默认 qps=3。日常高频使用前建议找业务方确认是否需要切换到正式计费的 key，避免频繁触发 429。