fetchmux

FetchMux

为 AI Agent 提供一个搜索端点。 在 Brave、Tavily、Exa、Firecrawl 和 Crossref 前面放置一个路由器。每个请求都带有严格的费用上限和截止时间；每个响应都会附带一份回执，说明使用了哪个提供商、原因以及费用。

你的 Agent 不必再在提示词和应用代码中硬编码提供商。它们只需发送一种请求格式；网关便会根据你控制的策略，选择符合条件的提供商，在调用前执行预算和截止时间限制，在失败时安全重试，并返回规范化结果和完整追踪记录。提供商密钥由你保管——它们永远不会离开你的网关。

回执

一切都清晰可见。每个 /v1/search 响应都会附带路由决策：

"route": {
  "selectedProvider": "brave",
  "attemptedProviders": ["brave"],
  "reasonCodes": ["TASK_MATCH", "WITHIN_BUDGET", "RELIABILITY_WEIGHT"],
  "attempts": [
    { "provider": "brave", "outcome": "success", "latencyMs": 640, "estimatedCostUsd": 0.005 }
  ],
  "estimatedCostUsd": 0.005,
  "latencyMs": 640,
  "fallbackUsed": false,
  "traceId": "rt_b400e7c8"
}

路由方式

  agent  ──▶  { query · task · maxCostUsd · maxLatencyMs }
                             │
                             ▼
                      ┌──────────────┐        your keys
                      │   FetchMux    │ ─────▶ Brave · Tavily · Exa
                      │    policy     │        Firecrawl · Crossref
                      └──────────────┘ ◀─────  (bring your own)
                             │
                             ▼
  agent  ◀──  evidence[]  +  route receipt

只有在凭据、任务匹配度、电路状态、支出和截止时间均符合要求时，提供商才符合条件。预算和截止时间是资格规则，而非尽力而为的提示。只有发生可重试的故障时才会回退。

快速开始

无需提供商账号——公共 Crossref 路由开箱即用：

git clone https://github.com/krutftw/fetchmux
cd fetchmux
npm install
npm run build

export FETCHMUX_API_KEY="a-long-random-key"
export CROSSREF_ENABLED=true
export CROSSREF_CONTACT_EMAIL="[email protected]"
npm run dev:gateway

在另一个 Shell 中：

curl http://127.0.0.1:8787/v1/search \
  -H "Authorization: Bearer a-long-random-key" \
  -H "Content-Type: application/json" \
  -d '{ "query": "retrieval augmented generation", "task": "scholarly", "maxLatencyMs": 8000 }'

要进行实际的网页搜索，请设置提供商密钥，并改用网页搜索任务：

export FETCHMUX_API_KEY="a-long-random-key"
export BRAVE_API_KEY="your-brave-key"
export BRAVE_COST_PER_REQUEST_USD="0.005"   # from your provider plan
npm run dev:gateway

刚开始使用 Firecrawl？新账号通过此链接可在首月享受 10% 折扣（推荐链接——FetchMux 会获得少量佣金，你无需支付额外费用）。

在 Agent 中使用

将任意 MCP 客户端（Claude、Cursor 等）指向已发布的服务：

{
  "mcpServers": {
    "fetchmux": {
      "command": "npx",
      "args": ["-y", "@fetchmux/mcp"],
      "env": {
        "FETCHMUX_BASE_URL": "http://127.0.0.1:8787/",
        "FETCHMUX_API_KEY": "your-gateway-key"
      }
    }
  }
}

提供两个只读工具：search_web 和 preview_search_route。

或者使用类型化 SDK @fetchmux/sdk：

import { FetchMux } from "@fetchmux/sdk";

const client = new FetchMux({
  baseUrl: "http://127.0.0.1:8787/",
  apiKey: process.env.FETCHMUX_API_KEY,
  fetch: globalThis.fetch.bind(globalThis),
});

const res = await client.search({
  query: "latest stable Node.js release",
  task: "fresh_facts",
  maxCostUsd: 0.02,
});

提供商

每个提供商都需要使用你自己的密钥。设置对应的 *_API_KEY；如果希望强制执行美元预算，还可选择设置 *_COST_PER_REQUEST_USD。

提供商	用途	密钥
Brave	网页搜索	BRAVE_API_KEY
Tavily	网页搜索、研究	TAVILY_API_KEY
Exa	网页搜索、文档	EXA_API_KEY
Firecrawl	页面内容	FIRECRAWL_API_KEY
Crossref	学术元数据	无（CROSSREF_ENABLED=true）

REST 端点

方法	路径	认证	行为
GET	/health	公开	进程健康状态和版本
GET	/ready	公开	提供商就绪状态
GET	/v1/providers	bearer	提供商配置状态
POST	/v1/route/preview	bearer	排序后的候选项，不调用提供商
POST	/v1/search	bearer	路由检索和路由回执

完整规范：docs/openapi.yaml。

所有配置变量

本地 Node 开发时，进程不会自动加载 .env；请在 shell 或进程管理器中设置变量。Docker Compose 会读取被忽略的 .env 文件。

变量	默认值	用途
FETCHMUX_API_KEY	无	受保护路由的 bearer 密钥
FETCHMUX_API_KEYS	无	以逗号分隔的轮换密钥
FETCHMUX_AUTH_DISABLED	false	精确设为 true 时绕过认证（仅限可信的本地使用）
FETCHMUX_ALLOWED_ORIGINS	无	以逗号分隔的浏览器来源；为空时不启用 CORS
FETCHMUX_HOST	127.0.0.1	绑定地址
FETCHMUX_PORT	8787	TCP 端口
BRAVE_API_KEY / TAVILY_API_KEY / EXA_API_KEY / FIRECRAWL_API_KEY	无	提供商凭据
CROSSREF_ENABLED	false	精确设为 true 时启用无需凭据的学术路由
CROSSREF_CONTACT_EMAIL	无	Crossref 礼貌池使用的受监控联系邮箱
*_COST_PER_REQUEST_USD	无	用于美元预算的各提供商单次请求成本估算

启用 maxCostUsd 前，请参阅提供商配置。

在 Docker 中运行

cp .env.example .env    # add your keys, never commit it
docker compose up --build -d
curl http://127.0.0.1:8787/health

非 root Distroless 镜像：已移除 Linux 功能、根文件系统为只读，提供商凭据仅在容器启动时传入。

基准测试

无需网络调用或消耗额度，即可验证每种情况和提供商组合：

npm run benchmark -- --workload benchmarks/workloads/founding-v1.json --mode dry-run

实时模式需要提供商密钥，并且必须显式指定 --confirm-live。发布结果前，请检查各提供商的条款——参阅基准测试方法。

它是什么（以及不是什么）

开源、可自托管、单租户、BYOK。路由事件以 JSON 格式输出到 stdout，默认不包含你的查询文本、密钥和结果内容。无数据库、无遥测。

它不是托管服务、共享额度转售商，也不声称这些提供商可以互换。提供商名称指的是它内置的适配器，而非合作关系。托管版本已列入路线图——为仓库加星以获取进展。

开发

npm test          # 232 tests
npm run typecheck
npm run lint
npm run build
npm run dev:gateway
npm run dev:site

更多文档：产品设计 · 本地开发 · 部署 · 提供商配置 · 数据处理 · 事件响应

安全问题：[email protected]。

许可证

Apache-2.0。可免费自托管、修改和再分发。