Agent Reach：让 AI Agent 读懂整个互联网——从日文版 README 看多后端路由与诊断机制

本文以 Agent Reach 仓库的日文版 README（docs/README_ja.md）为主体，完整梳理这个项目的定位、13+ 平台支持矩阵、安装与配置流程，并结合 agent_reach/channels/ 源码解析其"首选 + 备选"多后端路由与 agent-reach doctor 诊断的底层实现。读完后，你可以掌握如何用一条命令为 AI Agent 装上全网读取能力，并理解每个平台"当前到底在用哪个后端"的判定逻辑。

一、为什么需要 Agent Reach：每个平台都有一道墙

AI Agent 已经能访问互联网，但"连上网络"只是开始。日文 README 指出：最有价值的信息散落在 Twitter 的讨论、Reddit 的反馈、YouTube 的教程、小红书的测评、Bilibili 的视频和 GitHub 的动态里——这些恰恰是信息密度最高的地方，而每个平台都有自己的访问壁垒：

障碍	现实情况
Twitter API	按量计费，中度使用每月约 $215
Reddit	服务器 IP 被 403 封锁
小红书	必须登录才能浏览
Bilibili	封锁海外/服务器 IP

把这些平台逐一接通 Agent，意味着要逐个找工具、装依赖、调配置。Agent Reach 把这件事压缩成一条指令——把下面的话复制给任意能执行命令的 Agent（Claude Code、OpenClaw、Cursor、Windsurf 等）：

Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md

Agent 会自动完成安装、环境检测，并告诉你哪些渠道已经可用。已安装过的用户更新同样只需一句话（指向 更新指南）：

Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md

README 同时给出了项目承诺的五个要点，这些承诺都能在仓库中找到对应实现：

要点	说明
💰 完全免费	所有工具开源、所有 API 免费。唯一可能的花费是服务器代理（约 $1/月），本地电脑不需要
🔒 隐私安全	Cookie 只保存在本地，不上传。完全开源，随时可审计
🔄 持续换代	定期跟踪并更新上游工具（yt-dlp、twitter-cli、rdt-cli、Jina Reader 等）
🤖 兼容所有 Agent	任何能跑命令行（exec）的 Agent 都可以用
🩺 自带诊断	agent-reach doctor 一条命令告诉你哪个渠道通、哪个不通、怎么修

二、支持平台总览：13 类平台的配置分级

日文 README 的平台矩阵如下（这是文章的核心内容之一，完整保留）：

平台	能力	配置方式	备注
🌐 Web	浏览	无需配置	任意 URL → 干净的 Markdown（Jina Reader）
🐦 Twitter/X	浏览、搜索	无需配置 / Cookie	单条推文立即可看；配 Cookie 后解锁搜索、时间线、发帖（twitter-cli）
📕 小红书	浏览、搜索、评论	OpenCLI / Cookie	OpenCLI 只复用用户自己管理的既有 Chrome 会话；MCP/旧工具走 Cookie-Editor
💼 LinkedIn	Jina Reader（公开页面）	—	支持个人资料、公司、职位搜索；对 Agent 说"帮我配置 LinkedIn"
💬 微信文章	搜索 + 浏览	无需配置	公众号文章搜索与阅读（完整 Markdown），基于 Exa + Camoufox（可选）
💻 V2EX	热门帖、节点帖、帖子详情+回复、用户资料	无需配置	公开 JSON API，无需认证
📈 雪球	行情、搜索、热帖、热门股票	无需配置	公开 API 自动携带会话 Cookie，无需登录
🎙️ 小宇宙播客	文字转录	免费 API Key	播客音频 → Groq Whisper（免费）完整文字稿
🔍 Web 搜索	搜索	自动配置	安装时自动接入，免费、无需 API Key（Exa 经 mcporter 调用）
📦 GitHub	浏览、搜索	无需配置	基于 gh CLI，公开仓库开箱即用；gh auth login 后解锁 Fork、Issue、PR
📺 YouTube	浏览、搜索	无需配置	字幕提取 + 1800+ 视频站点搜索（yt-dlp）
📺 Bilibili	浏览、搜索	无需配置	bili-cli 搜索与视频信息（无需登录），字幕走 OpenCLI；yt-dlp 因 Bilibili 412 限制不再使用
📡 RSS	浏览	无需配置	任意 RSS/Atom 源（feedparser）
📖 Reddit	搜索、浏览	Cookie	2024 年起需要认证——安装后执行 rdt login（rdt-cli）

配置级别说明：无需配置 = 装完即用 · 自动配置 = 安装时自动处理 · Cookie = 从浏览器导出 · 代理 = 约 $1/月。

从源码结构看，当前仓库的渠道注册表 agent_reach/channels/__init__.py 中 ALL_CHANNELS 共注册了 15 个渠道实例（GitHub、Twitter、YouTube、Reddit、Facebook、Instagram、Bilibili、小红书、LinkedIn、小宇宙、V2EX、雪球、RSS、Exa 搜索、Web），其中 Facebook 与 Instagram 是日文 README 之后新增的渠道，而"微信文章"在注册表中没有独立的渠道文件，从源码结构看其读取路径是并入 Exa 搜索渠道处理的。也就是说，README 矩阵是"用户视角的能力清单"，而 ALL_CHANNELS 是"代码视角的实现清单"，两者互为印证。

三、快速上手：三种安装路径

3.1 交给 Agent 自动安装

复制给 AI Agent 的那句话指向 安装指南。该指南为 Agent 规定了明确的边界（不使用 sudo、不修改 ~/.agent-reach/ 之外的系统文件、不在 Agent 工作区里克隆仓库或建文件），流程是：

1. 安装 CLI（pipx install 或 venv + pip install 仓库压缩包）；
2. 默认只读检查系统基建（gh CLI、Node.js、mcporter、yt-dlp 等）；
3. 仅在用户显式批准后，用 --system 安装外部依赖并通过 MCP 接入 Exa 搜索；
4. 询问用户需要哪些可选渠道（--channels=opencli,xiaohongshu 等）；
5. 跑 agent-reach doctor 修复并汇报。

3.2 手动安装

日文 README 中的手动安装流程：

pip install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto           # 只读检查（默认行为）
agent-reach install --env=auto --system  # 仅在你显式允许系统变更时

agent-reach install 默认是安全检查：只检查环境、列出缺失项，不改机器；只有显式加 --system 才会安装外部工具和写入配置，--dry-run 可以先预览。这些参数在 agent_reach/cli.py 的 install 子命令解析逻辑中定义。包本身由 pyproject.toml 声明：Python ≥ 3.10，入口点 agent-reach = agent_reach.cli:main，依赖里自带 yt-dlp 与 feedparser（所以 YouTube 与 RSS 渠道零额外安装）。

3.3 作为 Skill 安装

对 Claude Code / OpenClaw 等支持 Skills 的 Agent：

npx skills add Panniantong/Agent-Reach@agent-reach

Skill 安装后，Agent 会自动检测 agent-reach CLI 是否可用并按需安装。Skill 的核心文件是 agent_reach/skill/SKILL.md，它规定了路由表（search / social / career / dev / web / video / finance 七类意图 → 对应 references/*.md），并写明常驻规则："动手前先体检"——多后端/登录态平台先跑 agent-reach doctor --json，active_backend 有值时按它选命令组。

注意：agent-reach install --system 显式许可后，Skill 才会自动注册；默认的 agent-reach install 是只读的，不写文件。

四、装好即用：自然语言请求如何落到上游命令

README 强调"不需要记命令"——Agent 读了 SKILL.md 之后自己知道该调什么。零配置场景的映射关系是：

• "帮我读这个链接" → curl https://r.jina.ai/URL 读任意网页
• "这个 GitHub 仓库是做什么的" → gh repo view owner/repo
• "这个 YouTube 视频讲了什么" → yt-dlp --dump-json URL 取字幕
• "读一下这条推文" → 设置 TWITTER_AUTH_TOKEN / TWITTER_CT0 后运行 twitter tweet URL
• "订阅这个 RSS" → feedparser 解析
• "搜一下 GitHub 上的 LLM 框架" → gh search repos "LLM framework"

以 Web 渠道为例，agent_reach/channels/web.py 中的 read() 方法展示了内置读取的实际做法：把 URL 规范化后拼成 https://r.jina.ai/{url}，用 urllib 请求并限制响应体 5MB，还会识别 Jina/Cloudflare 的反爬验证页（检测 "requiring captcha"、"Just a moment..." 等特征），命中时直接抛错提示"改用站点专用工具或浏览器读取"——而不是把验证码页面当作正文返回给 Agent。WebChannel.check() 则被设计为零开销兜底：它不做网络探测、恒返回 ok，因为"它是兜底渠道，doctor 里其他渠道已经触网了"（源码注释原意）。

五、按需解锁：Cookie 与代理，都是可选项

日文 README 的原则是"不用就不配，所有步骤都是可选的"。

5.1 Twitter Cookie：免费、约 2 分钟

对 Agent 说"帮我配 Twitter 的 Cookie"，它会引导你用 Cookie-Editor 插件手工导出。保存的凭据有一个明确的边界：只供 agent-reach doctor 检查"配置是否齐全"使用，doctor 不会执行 twitter status。真正调用上游命令时，需要在进程环境中显式设置变量：

export TWITTER_AUTH_TOKEN="..."
export TWITTER_CT0="..."
twitter search "query" -n 10

为什么 doctor 不代跑 twitter status？agent_reach/channels/twitter.py 的 _check_twitter_cli 注释给出了原因：上游 twitter status 在凭据缺失或无效时会自动回退去读浏览器 Cookie，而项目策略是"Twitter 只接受用户通过 Cookie-Editor 明确导出的内容"，所以 doctor 选择只检查显式凭据存在与否（shutil.which("twitter") + 环境变量/配置中是否有 TWITTER_AUTH_TOKEN 与 TWITTER_CT0），不做实时验证。该渠道的后端候选是 ["twitter-cli", "OpenCLI", "bird CLI (legacy)"]（见 twitter.py 的 backends 属性），按序探测、第一个完全可用的当选。

5.2 代理：约 $1/月，仅服务器需要

本地电脑通常不需要代理；只有当网络环境里 Reddit/Twitter 被封锁时才配置。Bilibili 走 bili-cli，不依赖代理路线。安装指南 中给出了代理配置命令：agent-reach configure proxy（隐藏输入保存代理地址），并明确"它不是自动解锁开关"——twitter-cli / rdt-cli 这类 Python 工具需要通过 HTTP_PROXY / HTTPS_PROXY 环境变量生效。

六、agent-reach doctor：一条命令看清全部渠道状态

README 给出了 doctor 的典型输出（保留原文示例）：

$ agent-reach doctor

👁️  Agent Reach 状态
========================================

✅ 可用:
  ✅ GitHub 仓库和代码 — 可浏览/搜索公开仓库
  ✅ YouTube 视频字幕 — yt-dlp
  ✅ Bilibili 搜索、视频信息 — bili-cli（字幕走 OpenCLI）
  ✅ RSS/Atom 源 — feedparser
  ✅ Web 页面（任意 URL）— Jina Reader API

🔍 搜索（配免费 Exa Key 后解锁）:
  ⬜ Web 语义搜索 — 去 exa.ai 获取免费 Key

🔧 可配置:
  ⚠️  Twitter/X — doctor 只确认显式凭据是否存在；上游 CLI 需要环境变量
  ✅ Reddit 帖子和评论 — rdt-cli 搜索+浏览（免费，无需代理）
  ⬜ 小红书笔记 — OpenCLI 仅用既有会话；其余用 Cookie-Editor 配置 MCP/旧工具

状态: 9 个渠道中 6 个可用

这份报告不是打印出来的模板，而是一次真实的环境体检。源码链路如下：

1. 逐渠道收集：agent_reach/doctor.py 的 check_all() 遍历 get_all_channels() 的 15 个渠道，逐一调用 ch.check(config)，并把结果整理成含 status、backends、active_backend 的字典。两个值得注意的防御：单个渠道抛异常只会把该渠道降级为 status="error"，不会拖垮整份报告（"doctor must survive any channel"）；所有输出在渲染前经过 scrub_url_credentials 清洗，防止上游探测输出回显配置里的 URL 凭据。

2. 真实执行探测，而非只看命令存在：这是本项目诊断机制的核心。agent_reach/probe.py 的 probe_command() 会真的执行 cmd --version 这样的无副作用命令，并把结果分为五类：missing（不在 PATH）、broken（命令存在但执行失败——最常见的是系统 Python 升级后 pipx/uv 的 venv shebang 失效，which() 能找到 shim 但 exec 抛 FileNotFoundError）、timeout、error、ok。对 broken 的情况它会直接给出修复处方（uv tool install --force <pkg> 或 pipx reinstall <pkg>）。base.py 的模块注释把这条原则写死为渠道契约："shutil.which() 单独不构成健康证明——过期的 venv shim 能通过 which() 但无法执行"。

3. 两级选型，避免"装了但没登录"挡住可用备选：以 Bilibili 渠道为例，agent_reach/channels/bilibili.py 的 check() 先按序收集所有候选后端的 (status, message)，然后第一轮找 ok，没有 ok 才找 warn——否则"装了但未登录"的候选会把排在后面、完整可用的备选后端挡在门外。当选者写入 self.active_backend，doctor 报告里就会显示"当前后端：bili-cli"。此外，即使别的候选兜底成功，断链候选的报错也会以 [备选后端异常] 附加在消息里带出来。

4. 按 tier 分组呈现：format_report()（doctor.py）按渠道的 tier 字段（0=零配置、1=需免费 Key、2=需较复杂配置）把渠道分成"装好即用"与"可选渠道"两组，并在结尾输出 N/Total 个渠道可用 以及"还有 X 个可选渠道可以解锁，告诉你的 Agent「帮我装 XXX」即可"的引导语——这正是 README 里那份报告的生成逻辑。

七、设计思想：脚手架工具，不是框架

日文 README 的核心论断是：Agent Reach 是脚手架工具（scaffolding），不是框架。它只做一件事——替你完成"选型、安装、体检、路由"的判断。安装之后，Agent 直接调用上游工具（twitter-cli、rdt-cli、bili-cli、yt-dlp、mcporter、gh CLI 等），中间没有包装层。

7.1 渠道即文件，全部可插拔

README 给出的 channels/ 目录图景如下（结合当前仓库实际文件列表整理）：

channels/
├── web.py          → Jina Reader     ← 可换成 Firecrawl、Crawl4AI…
├── twitter.py      → twitter-cli      ← 可换成官方 API…
├── youtube.py      → yt-dlp          ← 可换成 YouTube API、Whisper…
├── github.py       → gh CLI          ← 可换成 REST API、PyGithub…
├── bilibili.py     → bili-cli ▸ OpenCLI ▸ 搜索 API（yt-dlp 因 412 限制退役）
├── reddit.py       → OpenCLI ▸ rdt-cli（必须登录态）
├── xiaohongshu.py  → OpenCLI ▸ xiaohongshu-mcp ▸ xhs-cli
├── linkedin.py     → mcp-server-linkedin ← 可换成 LinkedIn API…
├── rss.py          → feedparser      ← 可换成 atoma…
├── exa_search.py   → mcporter MCP    ← 可换成 Tavily、SerpAPI…
└── __init__.py     → 渠道注册表（doctor 检测用）

每个渠道文件本质上只做两件事：can_handle(url) 判断某 URL 是否属于该平台，check(config) 检查上游工具是否安装且可用。实际读取与搜索由 Agent 直接调用上游工具完成。要新增一个平台，就新增一个独立的渠道文件并在 __init__.py 注册——这也是 贡献指南 鼓励的"单文件即一渠道"模式。

7.2 多后端路由：换后端 = 改列表顺序

这是"脚手架"思想在源码中最直接的体现。agent_reach/channels/base.py 定义了渠道契约：

• backends 是一个有序候选列表，backends[0] 是首选，其余是兜底。"切换某平台的后端"意味着重排这个列表，而不是重写代码；
• check() 必须把实际在服务的那个后端写入 self.active_backend（找不到则为 None）；
• 用户可以通过配置项 <channel>_backend（或环境变量 <CHANNEL>_BACKEND）强制置顶某个后端，ordered_backends() 会把它移到列表头部；未知值会被忽略，保证"过期配置永远不会把可用的后端挡掉"。

这个机制有两个真实的换代案例：

Bilibili：agent_reach/channels/bilibili.py 的模块注释记录了 2026 年 6 月的实测结论——Bilibili 风控对 yt-dlp 返回 412（最新版本、直连、走代理、预热 Cookie 各种配置都试过），而 bili-cli 无需登录即可搜索/看热门/视频详情，OpenCLI 通过浏览器会话补齐字幕。于是 yt-dlp 从 B 站渠道退役（它仍是 YouTube 后端），候选列表固化为 ["bili-cli", "OpenCLI", "B站搜索 API"]，最后一档甚至是一个零依赖的 curl 直连搜索 API（_search_api_ok() 检测 code == 0）。

小红书：agent_reach/channels/xiaohongshu.py 的注释解释了候选顺序如何"自动完成环境分流"——OpenCLI 依赖桌面 Chrome，在服务器上自然探测不到，于是自包含无头浏览器的 xiaohongshu-mcp 接棒；上游 2026-03 起停更的 xhs-cli 则作为存量用户的最后一档候选保留。同一份代码，在桌面与服务器上会路由到不同后端，用户无感知。

7.3 当前工具选型（README 原表）

场景	工具	理由
网页浏览	Jina Reader	免费、无需 API Key
读推文	twitter-cli	Cookie 认证，支持搜索/浏览/时间线/长文
YouTube 字幕 + 搜索	yt-dlp	面向 YouTube 与支持的 1800+ 视频站点（不用于 B 站）
Bilibili	bili-cli ▸ OpenCLI ▸ 搜索 API	yt-dlp 因 412 退役；bili-cli 无需登录即可搜索/浏览
Web 搜索	Exa（经 mcporter）	AI 语义搜索、MCP 接入、免 Key
GitHub	gh CLI	官方工具，认证后完整 API
RSS	feedparser	Python 生态标准选择
小红书	OpenCLI（桌面）▸ xiaohongshu-mcp（服务器）▸ xhs-cli	OpenCLI 只用既有会话；其余走 Cookie-Editor 手工配置
LinkedIn	mcp-server-linkedin	MCP 服务，浏览器自动化
微信文章	Exa（搜索+阅读）+ Camoufox（可选）	零配置搜索+全文阅读
小宇宙播客	transcribe.sh	bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh <URL>，脚本见 agent_reach/scripts/transcribe_xiaoyuzhou.sh

README 提醒：这些是"当前选型"。不满意就替换对应的渠道文件——这正是脚手架的意义。

八、FAQ（来自日文 README，面向 AI 检索）

• 不付费 Twitter API，如何让 Agent 搜索 Twitter？ 用 twitter-cli + Cookie 认证。Cookie-Editor 手工导出，经 agent-reach configure twitter-cookies 隐藏输入保存（仅供 doctor 配置检查）。直接运行 twitter search "query" -n 10 的进程需显式传入 TWITTER_AUTH_TOKEN 与 TWITTER_CT0。
• 如何获取 YouTube 字幕？ yt-dlp --dump-json "URL" 提取元数据，yt-dlp --write-sub --skip-download "URL" 提取字幕，多语言、无需 API Key。
• 服务器/数据中心 IP 访问 Reddit 返回 403？ 2024 年起 Reddit 要求所有 API 请求认证。pipx install rdt-cli 后执行 rdt login（自动从浏览器提取 Cookie），之后 rdt search "query" 搜索、rdt read POST_ID 读帖+评论。
• 兼容 Claude Code / Cursor / Windsurf / OpenClaw 吗？ 兼容。Agent Reach 是安装器 + 配置工具，任何能执行 shell 命令的编码 Agent 都能用。先 pip install 仓库压缩包，再 agent-reach install（只读检查），显式许可后才 --system。注意 PyPI 上的同名包是另一个项目。
• 免费吗？有 API 成本吗？ 100% 免费开源。所有后端（twitter-cli、rdt-cli、OpenCLI、bili-cli、yt-dlp、Jina Reader、Exa）都不需要付费 API Key；只有网络封锁场景才可能产生代理费用。
• 小红书内容如何程序化读取？ Agent Reach 不代用户登录小红书、不读取浏览器 Cookie。OpenCLI 只使用用户已有且明确控制的 Chrome 会话；没有现成会话时不会自动登录，而是引导用 Cookie-Editor 手工导出配置 xiaohongshu-mcp 或旧工具。agent-reach configure xhs-cookies 不会把 Cookie 注入 OpenCLI/Chrome。

九、结语与延伸阅读

Agent Reach 把"给 Agent 接一个平台"从一次性的踩坑工程，变成了一条可诊断、可路由、可换代的流水线：install 装好即用，doctor 报告每个渠道当前走哪条后端，check-update / 更新指南 负责换代，退役后端（如 B 站的 yt-dlp）自动让位而不影响用户。对希望在自己的 Agent 里复用这套模式的开发者，建议按以下路径深入本仓库：

• 渠道契约与多后端路由：agent_reach/channels/base.py、agent_reach/channels/__init__.py
• 真实健康探测：agent_reach/probe.py
• 诊断报告生成：agent_reach/doctor.py
• 代表性渠道实现：twitter.py（凭据边界）、bilibili.py（后端换代）、xiaohongshu.py（桌面/服务器自动分流）
• 面向 Agent 的操作手册：安装指南、更新指南、SKILL.md
• 测试覆盖：tests/test_channel_contracts.py、tests/test_doctor.py、tests/test_probe.py

上游工具致谢（与 README 一致）：twitter-cli、rdt-cli、xhs-cli、Jina Reader、yt-dlp、Exa、feedparser、mcp-server-linkedin。项目采用 MIT 许可（LICENSE）。