内容
# fetchira
免费的网络搜索、页面读取、深度研究和图像生成，适用于您的编码代理 —— 一个二进制文件，零月度账单。
## 问题
您的代理需要不断访问网络，而付费搜索 API 需要按调用次数计费。同时，每月有大量的免费搜索未被使用：Serper、Tavily、Exa 和 Parallel 提供免费搜索积分，Firecrawl 读取页面，Steel 驱动无头浏览器 —— 而您的登录的 Gemini、Grok 和 ChatGPT 账户在顶部添加搜索、多步骤深度研究、图像生成和文件问答。它们共同涵盖了大部分代理的研究需求，而且是免费的。
问题在于记账。每个提供商都有自己的 API、自己的密钥、自己的配额和自己的重置窗口。要使用免费层，您必须记住哪个密钥在哪里，跟踪哪些提供商已经用完这个月的配额，并在其中一个提供商开始返回 `429` 时切换到另一个提供商。没有人愿意手动执行此操作，代理也不能。
## 解决方案
fetchira 就是这个记账问题的程序化解决方案。它是一个单独的 Rust 二进制文件，与您的编码代理使用 **MCP**（模型上下文协议）。代理请求一个通用功能 —— *搜索此内容*、*读取此 URL*、*执行深度研究*、*驱动浏览器* —— fetchira 按照该功能的提供商顺序（内置或使用 `fetchira priority` 设置）进行路由，选择每个提供商中剩余配额最少的账户，并在其中一个提供商出现错误或用完配额时自动切换到下一个提供商。
它还附带一个 **本地仪表盘**，允许人类实时监控相同的内容并在不编辑配置文件的情况下管理账户。
## 快速开始
```sh
brew install ImmuneFOMO/tap/fetchira # 或：curl -fsSL https://raw.githubusercontent.com/ImmuneFOMO/fetchira/main/install.sh | sh
fetchira # 打开仪表盘：连接提供商、尝试搜索、注册您的编码工具
```
更喜欢终端吗？`fetchira setup`（引导式 TUI）+ `fetchira install` 可以完成相同的事情。
重启您的编码工具并要求它搜索网络 —— fetchira 会接管。
## 功能
| 功能 | 代理调用 | fetchira 路由到（默认顺序 —— 可以使用 `fetchira priority` 重订） |
|---|---|---|
| **搜索** | `search` | tavily → serper → exa → parallel → gemini_web → grok_web → chatgpt_web |
| **读取** | `read` | firecrawl → tavily → serper → exa（然后自动升级到无头浏览器） |
| **深度研究** | `deep_research` | gemini_web → chatgpt_web → parallel → exa → grok_web → tavily |
| **图像** | `create_image` | chatgpt_web → gemini_web → grok_web |
| **文件问答** | `search` / `deep_research` + `file` | 将本地文件附加到 grok / gemini / chatgpt 调用中并询问它们 |
| **浏览器** | `browser` | steel |
| **使用情况** | `usage` | 实时余额 + 每层限制 + 模型/模式目录，和每个提供商的功能表 |
- **配额感知路由**。每个调用都会路由到具有该功能剩余配额最多的账户。当提供商返回 `429`/`402` 时，该预算将被耗尽，路由器将在窗口重置之前停止发送请求。
- **自动故障转移**。如果选择的账户发生错误，fetchira 将移至下一个具有相同功能的账户，代理不会看到任何中断。
- **每个提供商的多个账户**。添加 `exa-1`、`exa-2` 等，路由器将根据剩余配额在它们之间进行负载均衡。
- **每个账户的粘性代理**。为每个账户提供自己的出口 IP（来自 Webshare 池的 `proxy = "pool"` 或固定的 URL），以便多个免费账户不会共享一个地址。
- **实时余额**。在提供商公开余额的情况下，fetchira 从账户中读取实际余额，而不是根据名义上限进行猜测 —— serper / tavily / firecrawl 的积分，exa / parallel / steel 的实际美元余额（显示为 `$balance · ≈N requests`）。
## 仪表盘
```sh
fetchira ui # 打开 http://127.0.0.1:7878 在您的浏览器中
```
路由器仪表盘。**概览** 将每个提供商按功能分组，并显示每个账户剩余的免费配额和重置时间 —— 同时显示实时调用日志。
**路由优先级** 面板在同一选项卡中重新排序每个功能首先尝试的提供商（与 `fetchira priority` 相同的顺序）。
**账户** 是管理界面：每个账户都有其配额条、重置窗口、代理、密钥/会话状态和健康状态。添加、删除、重新登录或向任何账户发送真正的“测试”探测，所有操作都在此处进行 —— 它写入与 CLI 相同的配置文件。机密信息永远不会发送到浏览器（密钥显示为 `•••• key set`，代理凭证被掩盖）。
**活动** 是完整的路由日志，带有过滤器、每个提供商的健康状态和故障转移故事 —— `exa-1 429 → tavily-1`，每个提供商的最后成功和最后错误。单击任何调用以打开它发送的内容和返回的内容；**调试** 选项卡保留相同的每个请求的详细信息，带有原始 HTTP 头和正文，机密信息被遮蔽。
## 安装和设置
**Homebrew** （macOS + Linux）：
```sh
brew install ImmuneFOMO/tap/fetchira
```
**或 `curl | sh`** —— 将适用于您平台的预构建二进制文件下载到 `~/.local/bin`：
```sh
curl -fsSL https://raw.githubusercontent.com/ImmuneFOMO/fetchira/main/install.sh | sh
```
**从源代码** （在checkout中构建，使用cargo）：
```sh
./install.sh # 构建，将二进制文件安装到 ~/.local/bin
```
然后配置提供商：
```sh
fetchira setup # 引导：选择提供商，粘贴 API 密钥，登录网络提供商
```
## CLI
```sh
fetchira ui # 打开本地仪表盘（实时配额，账户，路由日志）
fetchira providers # 列出所有可用的提供商及其功能
fetchira list # 您的账户 + 剩余配额 + 登录状态
fetchira add <provider> # 添加账户（提示输入密钥，或登录如果为网络提供商）
# 标志：--label L --key K --proxy pool|URL
fetchira remove <label> # 删除账户（及其会话/使用情况）
fetchira login <provider> # （重新）捕获网络会话登录通过浏览器
fetchira session <label> # 手动附加网络会话（从标准输入或 --file 读取 cookie JSON）
fetchira priority [cap] # 显示或设置每个功能的提供商顺序
# 例如：fetchira priority search grok_web,serper （重置：… search reset）
fetchira install # 向您的编码工具注册 fetchira
fetchira update # 下载并安装最新版本（或 `brew upgrade`）
fetchira --version # 打印已安装的版本
fetchira help
```
`fetchira add tavily` 请求密钥；`fetchira add gemini_web` 打开浏览器登录（或在没有浏览器的情况下回退到 `fetchira session` —— 参见[网络会话](#网络会话)）。每个提供商可以有多个账户（ `--label tavily-2` ）；路由器根据剩余配额进行负载均衡。
## 与您的编码工具注册
二进制文件 **是** MCP 服务器（标准输入/输出）。简单的方法是让它写入每个工具的配置文件：
```sh
fetchira install
```
它检测并支持 Claude Code、Codex CLI、OpenCode、Gemini CLI、Cursor、Windsurf、VS Code 和 Claude Desktop —— 多选，然后为每个工具编写正确的文件格式（合并，永远不会覆盖现有的服务器）。重启工具以获取。
手动注册也很简单 —— 将任何 MCP 客户端指向二进制文件：
```sh
claude mcp add fetchira -s user -- ~/.local/bin/fetchira # Claude Code
```
```jsonc
// generic mcp.json（Cursor, Windsurf, Gemini CLI, Claude Desktop）
{ "mcpServers": { "fetchira": { "command": "/Users/you/.local/bin/fetchira" } } }
```
标准输出是 MCP 通道；日志输出到标准错误（`RUST_LOG=debug` 获取更多）。对于 Claude Code，还有一个 `skills/fetchira/SKILL.md` 中的技能 —— 将其复制到 `~/.claude/skills/fetchira/SKILL.md`，以便代理知道何时以及如何使用工具。
## 网络会话
`gemini_web`、`grok_web` 和 `chatgpt_web` 使用您的 **登录浏览器 cookie** 而不是 API 密钥，通过伪装成 Chrome 的客户端。每个提供商只需一次性设置：
```sh
fetchira login gemini_web # 打开浏览器；登录，然后它会捕获会话
fetchira login grok_web
fetchira login chatgpt_web
```
`fetchira login <provider>` 启动一个真正的浏览器，对抗一个专用的配置文件，等待您完成登录，捕获 cookie（包括 HttpOnly）并将其存储在 `usage.db` 中。如果存在，它使用 **Chrome/Chromium/Edge/Brave**（通过 DevTools 协议），否则使用 **Firefox**（直接从其纯文本 `cookies.sqlite` 读取，因为 Firefox 放弃了 CDP）。设置 `FETCHIRA_BROWSER=chrome|firefox` 以强制使用其中之一。这些帐户获得与 API 帐户相同的粘性代理支持。
**无头浏览器/无浏览器？** 在没有 GUI 的服务器上，在其他任何机器（或任何浏览器）上登录，导出 cookie 为 JSON，然后手动附加它们 - 在运行 fetchira 的盒子上不需要浏览器：
```sh
fetchira add gemini_web --label gemini_web-1 # 即使跳过浏览器登录也已保存
fetchira session gemini_web-1 --file cookies.json # 或：在 stdin 上粘贴/管道 JSON
```
JSON 是一个 cookie 数组 (`[{"name":"sso","value":"…","domain":".grok.com"}]`) 或 `{"cookies":[…]}` — "Cookie 编辑器"浏览器扩展导出的形状。仪表板有相同的粘贴框（添加帐户 → *或粘贴会话*，或任何网络帐户上的 **会话** 按钮）。
**对话、模型、模式。** 网络结果以 `⟦session: …⟧` 令牌结尾；将其作为 `session` 传回以继续使用完整的历史记录继续相同的聊天。可选的 `model` 和 `mode` 为每个提供商选择（尽力而为；订阅功能可能被锁定）：
```jsonc
search { "query": "...", "provider": "gemini_web" } // -> 答案 + 会话令牌
search { "query": "follow-up", "session": "gemini_web:c_…,r_…" } // 继续聊天
```
**深度研究。** Gemini 和 ChatGPT 运行真正的基于计划的流程 - `deep_research` 返回一个计划和一个 `session`；在该会话上发送 `"start"` 以运行它（或替换计划的修订请求）。Gemini 在同一个调用中返回报告（~1-3 分钟）；ChatGPT 然后运行 ~5-30 分钟，因此它返回一个 `session`，您再次调用它以获取完成的报告。Grok 直接在其重型层运行深度研究（无计划步骤），而 exa / parallel 通过 API 进行真正的多轮研究。
**图像和文件问答。** `create_image` 从文本提示生成 - grok 和 gemini 在 HTTP 上进行渲染，chatgpt 驱动浏览器；它返回图像字节，而不是链接。要询问本地文件或图像，请在 `search` 或 `deep_research` 上将它们的路径作为 `file`（数组）传递（默认为 grok）。两者都采用可选的 `provider`，如果失败则像其他所有情况一样。
**实时限制。** `usage` 为每个网络会话轮询其真正的逐级限制和可以选择的模型/模式目录（带有思考级别）- 您的订阅锁定的模式（例如 Grok Expert/Heavy 在过期计划上）显示为 `0/0`。
**注意事项，固有的反向工程网络访问：**
- **会话过期。** Cloudflare 的 `cf_clearance` 有效期为 ~30 分钟至几个小时，无法在无头浏览器中生成。当提供商返回 session/403 错误时，请重新运行 `fetchira login <provider>`（或使用 `fetchira session` 重新附加）；同时，路由器故障转移到 API 提供商。
- **Grok 是间歇性的。** fetchira 伪造每个请求的反-bot `x-statsig-id`，这可以绕过 grok.com，但 grok 对 IP 声誉和速率是激进的。更好的机会：新的登录，一个住宅 `proxy`，并且没有突发。路由器在 grok 阻止时故障转移。
- **ChatGPT 驱动真正的浏览器。** chatgpt.com 在每次发送后都有一个 Turnstile 挑战，纯 HTTP 无法通过，因此 chatgpt_web 通过登录的浏览器配置文件提交（阅读限制保持纯 HTTP）。它需要 Chrome/Chromium 可用；深度研究轮询在纯 HTTP 上恢复。
## 配置
所有内容都位于 fetchira 主目录中 - `$FETCHIRA_HOME`，默认为 `~/.config/fetchira`：`fetchira.toml`（帐户 + 设置），`.env`（引用为 `env:VAR` 的机密），`usage.db`（配额计数器，网络会话，路由/调试日志）。`setup`、`add`、`priority` 和仪表板都写入相同的 `fetchira.toml`，因此不需要手动编辑 - 但它是纯 TOML，如果您愿意（请参见 `fetchira.toml.example` 和 `.env.example`）：
```toml
db_path = "usage.db" # 相对路径相对于 fetchira 主目录
[debug_log] # 完整的请求/响应捕获（调试选项卡）
enabled = true # 默认启用；受保留 + 行/大小上限限制
retention_hours = 24
[proxy_pool] # 可选：具有 proxy = "pool" 的帐户在此处抽取一个粘性 IP
webshare_url = "https://proxy.webshare.io/api/v2/proxy/list/download/<token>/…"
# proxies = ["http://user:pass@host:port"] # 或静态列表
[priority] # 可选：每个功能的提供商顺序
search = ["grok_web", "serper"] # 列出的提供商按此顺序尝试；未列出的提供商按内置顺序。
# 功能：search, read, deep_research, image
[[account]]
provider = "tavily"
label = "tavily-1" # 唯一名称；在仪表板和路由日志中显示
api_key = "env:TAVILY_API_KEY" # 字面密钥，或从 .env / 环境中解析的 env:VAR
proxy = "pool" # "pool" | "http://user:pass@host:port" | 省略直接
[[account]]
provider = "gemini_web" # 网络会话不携带 api_key - cookie 位于 usage.db 中
label = "gemini-1"
quota = 5000 # 名义聊天/搜索预算（网络提供商没有余额终点）
reset = "monthly" # monthly | daily | once
dr_quota = 100 # 单独的深度研究预算 - 设置为匹配您的计划
dr_reset = "daily"
```
**配额数字。** API 提供商实时报告其实际余额，因此其行不需要调整。网络会话没有余额终点 - `quota`/`dr_quota` 是软故障转移保护，并且提供商自己的 `429` 始终是真相来源。
**环境变量。** `FETCHIRA_HOME` - 配置目录覆盖。`FETCHIRA_BROWSER=chrome|firefox` - 强制登录捕获浏览器。`FETCHIRA_NO_UI=1` - 裸 `fetchira` 在终端中为 MCP 提供服务，而不是打开仪表板。`FETCHIRA_NO_OPEN=1` - `fetchira ui` 打印 URL 而不打开浏览器。`RUST_LOG` - 日志详细程度（日志输出到 stderr）。
## 构建和验证
```sh
cargo build --release
cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test
```
影响设计的研究笔记位于 [`research/`](research/) 中。
