FATSEARCH

Agent 读取每个页面都要付出这样的代价

Agent 会获得一份简短的大纲。需要深入了解时，它只读取一个章节，而不是整页。
菜单、Cookie 横幅、导航、页脚链接、跟踪脚本：统统移除。
价格、日期、数字：保留 _{（损失保护机制会逐一统计）}。

提示

“免费”抓取在模型端的成本会高出约 100 倍。而且之后的每一轮对话中，它都会留在上下文里。

你的密钥永远不会进入聊天内容

fats setup <provider> 会在 127.0.0.1 上打开一次性密钥表单，并通过随机令牌保护，有效期为 30 分钟。
你可以在浏览器中粘贴密钥，确保它不会进入聊天内容、模型上下文或 Agent 日志。
表单会拒绝来自其他来源的 POST；密钥会进行实时验证，以 mode 0600 保存，并且只发送给对应的服务商。

$ fats setup decodo
= setup decodo · waiting for the key at http://127.0.0.1:59802/k/e0c8baba7a5b058947f4fdab97dabb05/decodo · 30 min · $0
tell the user (never ask for the key in chat):
1. open https://dashboard.decodo.com/web-data/playground  (no account yet: https://dashboard.decodo.com/register)
2. Copy the API key shown on the Web Data playground. Do NOT paste it in this chat.
3. open http://127.0.0.1:59802/k/e0c8baba7a5b058947f4fdab97dabb05/decodo , paste the key, press Save
then: fats setup   (when the user says done; end your turn, do not poll · checks it, $0)
link dead (30 min passed)? run fats setup decodo again and give the user the new line 3

fats setup 会显示仍在等待填写的表单（! form_waiting decodo · 23 min left · <its URL>），或已过期的表单（! form_expired decodo · the link the user got is dead → fats setup decodo · new link, same 3 steps）。 通过 SSH 连接时（设置了 SSH_CONNECTION 或 SSH_TTY），还会多显示一行，说明如何在终端中粘贴密钥。

## 应对难访问的页面

fats 会先尝试普通 HTTP 请求（免费）。如果页面是 JS 外壳、验证码或访问墙， 它就会启用你的服务商：优先选择最便宜的，采用对冲策略，并跟踪每次调用的成本。

$ fats https://www.nytimes.com/ dry:true
nytimes.com/ fetch plain → oxy (after a captcha) → bd ∥ oxyjs after 5s → new u1 · up to $0.0040

$ fats stats
u1 rust-lang.org · Rust Programming Language · plain 230ms $0.0000 · 1.2ktok
u2 en.wikipedia.org · Rust (programming language… · plain 558ms $0.0000 · 40.9ktok

_{fats stats 就是宣传依据：展示真实数据，而非空口声称。}

38 个难访问的页面 _{社交 · 新闻 · 商店 · 旅行 · 分类信息 · 搜索 · 每个页面运行一次}

在返回文本中找到答案的用时	1 s	10 s	20 s	60 s
FATSEARCH 0.2.0 2026-10-21	12	19	19	35 /38
Firecrawl 2026-10-16	0	22	24	24
Tavily 2026-10-16	9	17	18	19

_{FATSEARCH 能读取更多难访问的页面；Firecrawl 和 Tavily 在成功读取的页面上速度更快（同一批页面，中位数：23.7 s vs 4.9 s、23.7 s vs 1.0 s）。各读取器在不同日期运行。方法和所有数据行 → · 上表对应：一个页面，六个读取器 →}

在 Agent 中测试 _{FATSEARCH 0.1.3 · Claude Code 2.1.280，每项运行一次，2026-10-19}

• 51 项任务，FATSEARCH MCP vs Firecrawl MCP：正确率 50/51 vs 51/51 · 每 1k 项任务费用 $15.06 vs $53.48 · 中位数 5.3 s vs 6.7 s · 用时最慢的 10% 为 43.8 s vs 21.5 s。详情 →
• Claude Code 的 WebFetch 在 npm、Medium 和 G2 上收到 403；FATSEARCH 则成功读取了这三个网站。详情 →
• 同一个 Wikipedia 页面，开源读取器：FATSEARCH 用 1,384 个 token 找到答案；mcp-server-fetch、Crawl4AI、mcp-searxng 和可自托管的 Firecrawl 读取整个页面则用了 75k–117k 个 token。详情 →
• 完整表格（包括失败项）：docs/benchmarks.md

开始使用

说明

软件包名是 fatsearch；命令名是 fats（类似于 ripgrep → rg）。Homebrew、npm 和安装 脚本也会添加 fatsearch 作为第二个名称；cargo install 只会添加 fats。 无需账户。 不配置服务商密钥时，fats 只能读取普通请求能获取的内容；网页搜索需要 Oxylabs 或 Bright Data 密钥。 配置任意一个密钥（Oxylabs、Bright Data 或 Decodo）后，它就能通过对应服务商渲染页面并解除访问限制。

## 设置

你在终端中： 运行 fats setup。这是一个菜单（↑↓ Enter）：免费抓取和各个服务商及其状态，然后是设置（Agent 连接、缓存、统计、遥测）。选择一个服务商，粘贴其密钥（显示为 • 和字符数），fats 会先实时验证密钥，再保存。运行 fats setup oxy 可直接跳到某个服务商（也支持 bd、decodo、gh）。

你的 Agent 操作，或没有终端： Agent 运行 fats setup oxy（或 bd、decodo、gh）。它会显示服务商的控制台链接，以及一个在 127.0.0.1 上开放 30 分钟的一次性表单。Agent 会把 URL 发给你；你在浏览器中将密钥粘贴到表单里，而不是聊天中（查看输出内容）。然后 Agent 运行 fats setup 来验证密钥（$0）。

密钥保存在密钥目录中的 auth.json（模式 0600）里，且只会发送给对应的服务商。auth.json 是唯一的密钥来源： fats 绝不会发送环境变量中的密钥，因此你保存的密钥就是每次调用使用的密钥（fats 会显示每个密钥的末 4 个字符：keys oxy …6XBR · bd none · decodo none · gh none · auth.json）。在没有浏览器的计算机上（CI、SSH），可以通过管道传入密钥：printf %s "$KEY" | fats setup oxy 会验证并保存密钥。已导出密钥的情况：运行一次 fats setup import-env，它会验证密钥，在尚未保存密钥时将其复制到密钥目录，且绝不会替换已保存的密钥。替换密钥时，旧文件会保留为 auth.json.bak（0600）。

服务商	密钥	页面，未运行 JS	页面，已渲染	网络搜索
免费（普通 HTTP，使用你的 IP）	无	$0	—	—
Oxylabs Web API	fats setup oxy（导入：OXYLABS_WEB_API_KEY）	$0.0010	$0.0015	$0.0010
Bright Data Web Unlocker	fats setup bd（导入：BRIGHTDATA_API_KEY；zone BRIGHTDATA_UNLOCKER_ZONE）	—	$0.0015	$0.0015
Decodo Web Data API	fats setup decodo（导入：DECODO_AUTH_TOKEN）	$0.0010	$0.0015	—
GitHub（fats gh）	fats setup gh 会复制 gh CLI 的令牌（导入：GH_TOKEN）	$0	—	—

_{每页标价，dry:true 和 fats stats 使用此价格。Oxylabs 和 Bright Data 的支出可通过 fats account 查看；Decodo 无法读取此密钥的用量，因此其 $ 为标价，绝不会与实际支出核对。}

关闭某个服务商而不丢失其密钥：fats setup oxy off；恢复使用：fats setup oxy on。

免费抓取使用你自己的连接： 每页通过你的 IP 发起一个请求；每个站点每秒最多开始一次抓取。页面会等待轮到自己，而不是购买服务商调用。服务商使用自己的 IP，且没有速率限制。fats setup free off 会将所有页面都交给服务商，因此每个页面都会产生费用。

MCP

一个工具。一段字符串。同样的命令。

claude mcp add --scope user fats -- fats mcp                      # Claude Code
codex mcp add fats -- fats mcp                                    # Codex
{"mcpServers": {"fats": {"command": "fats", "args": ["mcp"]}}}   # Cursor, Desktop, …

_{该工具为 fats(cmd)，其工具卡约占 60 个令牌。知道 fats u1#3 的 Agent 就知道如何使用整个工具。
MCP Registry：mcp-name: io.github.fatsearch/fats}

命令

命令	作用
fats <url>	抓取 → 清理 → 生成大纲，并缓存为 u1
fats u1#3	阅读第 3 节
fats u1 price	筛选页面内容
fats u1 links · fats l4	列出编号链接 · 跟进一个链接
fats rust async runtime	网络搜索 → 结果以 ID 显示
fats gh rust markdown	按星标数搜索 GitHub 仓库
fats ./report.pdf	本地文件，每页一个章节
fats stats	每次抓取的服务商、毫秒数、费用和令牌数
… dry:true	查看将要执行的操作及费用

_{选项  limit:20  country:de  js:true  wait:30  fresh:true  ·  一屏查看所有内容：fats help  ·  了解如何高效使用：fats guide}

## 面向 Agent

Agent 技能在此仓库中进行版本管理（skills/fatsearch/SKILL.md）：介绍如何读取页面而不占满上下文，以及缺少 fats 时如何安装、连接并验证。

npx skills add fatsearch/fatsearch        # Agent Skills standard: Claude Code, Codex, Cursor, Copilot, Gemini CLI, …
gh skill install fatsearch/fatsearch      # the same through GitHub CLI ≥ 2.90

没有这两种 CLI 的 Agent 会读取固定到某个版本的文档： https://raw.githubusercontent.com/fatsearch/fatsearch/v0.2.4/skills/fatsearch/SKILL.md。 这样，Agent 看到的是可供审查的版本化文本，且它运行的所有内容都不会来自网站。

供 Agent 阅读的纯 Markdown 文档：fatsearch.com/llms.txt。

遥测

FATSEARCH 会分享匿名使用统计数据，以便我们修复问题。它绝不会分享你阅读或搜索的内容。

• 绝不发送： URL、搜索内容、页面文本、文件、API 密钥、你的 IP 地址或任何 ID。
• 会发送： fatsearch 版本、操作系统、使用的程序包（npm、Homebrew、cargo……）、执行的命令、错误、 哪些提供商正常工作、我们代码中的崩溃。

使用 fats telemetry show 查看确切的发送内容。你可以在 fats setup → Settings → Telemetry 中关闭遥测， 也可以使用 fats setup telemetry off、FATS_TELEMETRY=0 或 DO_NOT_TRACK=1 关闭。详情：docs/telemetry.md

目前还不能做什么

• match:near / match:topic：需要本地模型
• 扫描版 PDF 的 OCR → ! no_text
• DOCX / XLSX → ! not_in_v1 zip
• 操作系统密钥链：密钥保存在 auth.json 中（权限模式 0600）
• 远程 MCP：仅支持 stdio
• 登录：需要登录才能访问的页面仍然需要登录才能访问

每项都会打印一行 !，说明缺少什么以及该怎么做。绝不静默处理。