Agent Reach 技能体系详解：让 AI Agent 拥有 15 平台的互联网能力路由器

Agent Reach 通过一个标准的 Agent Skill 文件（SKILL.md）把自己的「互联网能力」注入到 Claude Code、OpenCode、OpenClaw 等支持技能机制的 Agent 中。本文以仓库中的 SKILL_en.md 为骨架，完整拆解这套技能的工作方式：意图路由表、零配置快速命令、登录态平台的安全边界、agent-reach doctor 环境体检，以及 7 份 references 文档中沉淀的重试链与验收标准，并结合 doctor.py、base.py、cli.py 的源码，讲清每个规则背后的实现依据。

技能本质：一份 frontmatter + 路由表 + 七份参考手册

SKILL_en.md 采用 Agent Skills 标准格式，开头是 YAML frontmatter，核心字段是触发式 description：

name: agent-reach
description: >
  MUST USE when user wants to research/search/look up/find anything on the
  internet — e.g. "research this topic", "do a deep dive on X", "search the
  web for X", "see what people say about X", "look this up".

  Also MUST USE when user mentions any platform or shares any URL/link:
  Twitter/X, Reddit, Facebook, Instagram, YouTube, GitHub, Bilibili, XiaoHongShu,
  Xiaoyuzhou Podcast, LinkedIn/jobs/recruiting, V2EX, Xueqiu (stocks), RSS.

  15 platforms, multi-backend routing (OpenCLI / per-platform CLIs / APIs).
  Zero config for 6 channels. Run `agent-reach doctor --json` to see which
  backend serves each platform right now.

  NOT for: writing reports/analysis/translation (this skill only FETCHES
  internet content); posting/commenting/liking (write operations); platforms
  that already have a dedicated skill installed (prefer that skill).

这段 description 定义了技能的两个边界：何时必须使用（用户想搜索/调研/查证任何网络信息，或消息中出现上述任一平台/URL），以及何时不该使用（写报告/分析/翻译——技能只负责抓取内容不负责写作；发帖/评论/点赞等写操作；已安装专用技能的场景优先专用技能）。中文版本见 SKILL.md，命令通用，参考文档为中文。

从源码结构看，这份 SKILL 文件不是手写维护的独立文件，而是随包分发：cli.py 中的 _install_skill() 在安装阶段把 skill/ 目录整体复制到各 Agent 的技能根目录。语言选择逻辑在 _skill_resource_name()（cli.py）中：依次检查 AGENT_REACH_LANG、LC_ALL、LC_MESSAGES、LANG 环境变量，若任一值以 en 开头则安装英文 SKILL_en.md，否则安装中文 SKILL.md。扫描的技能目录包括 ~/.agents/skills、~/.config/opencode/skills、~/.openclaw/skills、~/.claude/skills（cli.py），设置 OPENCLAW_HOME 时还会优先插入其下的 .openclaw/skills。未安装过技能时可用 agent-reach skill --install / agent-reach skill --uninstall 单独管理（子命令定义见 cli.py）。

五条常驻规则（Standing rules）

技能正文为整个会话定义了 5 条必须遵守的规则，理解它们是正确使用该技能的前提：

1. 动手前先体检（Health-check before acting）：对多后端/依赖登录态的平台（XiaoHongShu / Reddit / Bilibili / Twitter / Facebook / Instagram），先跑 agent-reach doctor --json，以有值的 active_backend 为准。active_backend: null 表示 Doctor 故意跳过了实时探测（避免读取浏览器 Cookie 或产生远程写入），并不代表没有可用后端；只有当任务确实需要该平台时，才运行对应参考文档里的只读命令做验证。
2. 宣布你的选择：开始前声明 "using agent-reach, platform X via backend Y"，让用户知道走了哪条链路。
3. 失败时按 references/ 中的重试链处理，绝不凭空猜测命令。
4. 宽调研任务要组合平台：Exa 做网页搜索 + Twitter/Reddit 抓讨论 + XiaoHongShu/Bilibili 抓中文视角，并行收集后统一综合。
5. 为用户盯版本：完成一个较大的多平台任务后运行 agent-reach check-update（很快，一次 API 调用）。若存在新版本，在收尾时附加一行提示（例如 "Agent Reach vX.Y.Z is available"）并附上更新指引（对应仓库内 update.md 的更新流程）；不要中断当前任务去更新，也不要对同一版本反复唠叨。

doctor 命令的实现在 doctor.py 的 check_all()：遍历所有渠道的 check(config)，单个渠道异常不会拖垮整份报告（降级为 status="error"），且每条消息在输出前都会经过 scrub_url_credentials() 清洗，防止上游探测输出回显已配置的含凭据 URL。每个渠道的结果包含 status、name、message、tier、backends、active_backend 六个字段——这正是规则 1 中要求 Agent 检查 active_backend 的数据来源。

意图路由表（Routing table）

技能的核心是一张「用户意图 → 分类 → 参考文档」的路由表：

用户意图	分类	参考文档
网页 / 代码搜索	search	references/search.md
小红书 / Twitter / B站 / V2EX / Reddit / Facebook / Instagram	social	references/social.md
求职 / LinkedIn	career	references/career.md
GitHub / 代码	dev	references/dev.md
网页 / 文章 / RSS	web	references/web.md
YouTube / B站 / 播客转录	video	references/video.md
雪球 / 股票行情	finance	references/finance.md

规则很明确：只要技能存在，涉及这些平台就按路由表执行，不要自创方法。参考文档覆盖各后端命令组、注意事项与重试链（命令通用，中文环境为中文文档）。

零配置快速命令（Zero-config quick commands）

以下 6 组命令无需登录、开箱即用，覆盖最常见的调研场景：

# Exa 网页搜索（经 mcporter 调用 Exa MCP）
mcporter call exa.web_search_exa query="query" numResults=5

# 读取任意网页
curl -s "https://r.jina.ai/URL"

# GitHub 搜索
gh search repos "query" --sort stars --limit 10

# YouTube 字幕（B站绝不要用 yt-dlp；重试链见 video 参考文档）
yt-dlp --write-sub --write-auto-sub --skip-download -o "/tmp/%(id)s" "URL"

# V2EX 热门主题
curl -s "https://www.v2ex.com/api/topics/hot.json" -H "User-Agent: agent-reach/1.0"

# B站搜索（bili-cli，只读无需登录）
bili search "query" --type video -n 5

结合仓库可以补充几点实现细节：

• Exa 搜索通过 mcporter 渠道调用，MCP 服务器的注册配置见 config/mcporter.json。search.md 特别提示：Exa MCP 的 get_code_context_exa 已弃用且默认不注册，代码问题也统一用 web_search_exa，精确仓库搜索改用 GitHub 搜索。
• YouTube 字幕走 yt-dlp。安装器会探测 yt-dlp 版本，满足条件时自动向 yt-dlp 配置追加 --js-runtimes node（cli.py），因为新版 yt-dlp 处理 YouTube 需要外部 JS 运行时（Deno 或 Node）。注意 doctor 只确认 yt-dlp 本体与 JS runtime 能执行，active_backend: yt-dlp 不等于目标视频字幕已实时验证——验收标准是实际拿到非空字幕内容。
• V2EX 直接调用公开 JSON API（无需认证），social.md 还给出了节点主题、主题详情、回复、用户信息的完整端点，以及 V2EXChannel 的 Python 调用示例（get_hot_topics / get_node_topics / get_topic / get_user）。
• B站 强制走 bili-cli（bili search/hot/video/audio），social.md 与 video.md 都明确警告：不要用 yt-dlp 读 B站（风控已全面 412 拦截）；字幕用 opencli bilibili subtitle BVxxx，无字幕时 bili audio BVxxx 下载音频再配合 agent-reach transcribe 转写。

登录态平台：命令组与安全边界

多后端平台必须先跑 agent-reach doctor --json 看对应平台的 active_backend，再用对应命令组：

# Twitter 搜索（twitter-cli 优先；重试链见 social 参考文档）
twitter search "query" -n 10

# Reddit（无零配置路径——OpenCLI 或 rdt-cli，均需登录态）
opencli reddit search "query" -f yaml   # 桌面
rdt search "query" --limit 10            # 存量/服务器

# 小红书（桌面优先 OpenCLI）
opencli xiaohongshu search "query" -f yaml

# Facebook / Instagram（桌面 OpenCLI，复用浏览器会话）
opencli facebook search "query" -f yaml
opencli facebook groups -f yaml
opencli instagram search "query" -f yaml       # 用户搜索
opencli instagram user USERNAME -f yaml        # 单用户近期帖子

技能文档为两个平台写了明确的安全边界，这些边界在 CLI 校验中有对应实现：

Twitter 边界：agent-reach configure twitter-cookies 保存的 Cookie 仅供 doctor 检查显式凭据是否存在；doctor 不执行 twitter status，也不会配置当前 Shell。直接调用 twitter 命令前，必须在子进程环境中显式提供 TWITTER_AUTH_TOKEN 与 TWITTER_CT0，且不得打印其值。

小红书边界：Agent Reach 不得替用户登录、不得读取浏览器 Cookie。OpenCLI 只能使用用户已存在且明确控制的 Chrome 会话；没有现成会话时不要自动化登录，改走手工 Cookie-Editor 导出流程（xiaohongshu-mcp 或存量工具）。

从源码看，这套边界是强制执行的：cli.py 中，configure --from-browser --platform 对 twitter 和 xiaohongshu 直接报错，强制走 configure twitter-cookies / configure xhs-cookies 的手工导出路径；install 阶段也只打印需要用户显式授权的 Cookie 命令，从不自动读取浏览器凭据。多后端的选择机制则定义在 base.py 的 ordered_backends()：backends 是有序候选列表（backends[0] 为首选），用户可以通过配置键 <channel>_backend（或环境变量 <CHANNEL>_BACKEND）把指定后端提到列表最前面，未知值会被忽略，防止过期的覆盖项遮蔽可用后端。

各平台的完整命令组、已知不稳定点与重试链在 references 中，重点摘录：

• Twitter（social.md）：稳定命令为 twitter feed / twitter tweet / twitter article / twitter user-posts / twitter user；search 可能因 GraphQL 端点变动而 404，失败时按序执行重试链：① 直接重试一次 → ② pipx upgrade twitter-cli 后再试 → ③ 换 opencli twitter search "query" -f yaml → ④ 改走 feed/user-posts 等稳定命令绕路。要求 twitter-cli v0.8.5+，且不要在 VPS/数据中心 IP 上频繁调用（封号风险）。
• 小红书（social.md）：三个后端——A：OpenCLI（桌面首选，opencli xiaohongshu search/note/comments/feed/user）；B：xiaohongshu-mcp（服务器场景，首次调用会自动下载约 150MB 无头浏览器，命令务必带 --timeout 120000，认证只走 Cookie-Editor 手工导出）；C：xhs-cli（存量备选，上游 2026-03 起停更）。通用限制：小红书强制 xsec_token，不能直接用裸 note_id 读笔记，必须先搜索/feed 拿结果再用结果中的完整 URL/ID 去读；高频请求会触发验证码，每次操作间隔 2-3 秒。
• Reddit（social.md）：匿名 .json 端点已封（403），官方 API 自 2025-11 起人工审批基本不批，因此没有零配置路径。后端 A 为 OpenCLI（opencli reddit search/read/subreddit/hot/popular/subreddit-info，要求 Chrome 已登录 reddit.com）；后端 B 为 rdt-cli（需 rdt login 后才能搜索和阅读，服务器无浏览器时手动写 Cookie）。持有 2025-11 前 script app 凭证的存量用户可走官方 API + PRAW（100 QPM 免费），但不建议推荐新用户。
• Facebook / Instagram（social.md）：均走 OpenCLI 复用 Chrome 登录态。Facebook 支持 search/profile/feed/groups（Groups 只承诺当前账号可见的群组列表/最近动态）；Instagram 的 search 是用户搜索而非全站帖子搜索，读帖子需先确定 username 再用 instagram user USERNAME；遇 429 / login required 先让用户在 Chrome 重新登录并降频。
• 雪球（finance.md）：xueqiu.active_backend 有值才按该后端使用，null 只表示 Doctor 未完成实时内容验证。优先 opencli xueqiu whoami/search/stock/hot/hot-stock；验收标准是返回股票名称、代码、价格或非空内容列表，退出码 0 但字段为空不算成功；HTTP 400 通常是会话/Cookie 问题，不表示代码不存在；whoami 成功而 stock 失败时按适配器问题报告，不要误诊成未登录。

环境检查：agent-reach doctor

# 渠道可用性 + 每个平台当前由哪个后端服务
agent-reach doctor --json

--json 输出机器可读格式（供 Agent 解析），不带 --json 时输出文本报告，按 tier 分组渲染（doctor.py 的 format_report()）：tier 0 为「装好即用」，tier 1 为「需要免费 key/登录」，tier 2 为「可选的复杂配置」；结尾汇总 N/M 个渠道可用，并列明还有哪些可选渠道可解锁。tier 的语义定义在 base.py：0=zero-config, 1=needs free key, 2=needs setup。报告还会在 Unix 上检查 ~/.agent-reach/config.yaml 的文件权限，若组/其他用户可读会给出 chmod 600 的修复提示——因为该文件存放 API key 等敏感配置。

发现 OpenCLI 适配器

路由表里没有需要的平台或命令时，技能给出固定的发现流程：

1. 运行 opencli list 列出全部已安装适配器；
2. 用 opencli <platform> --help 查看该平台的可用命令。

技能特别强调：发现只证明适配器存在，不证明认证或目标内容可用；只有当用户任务确实需要该平台时才运行只读命令，且必须以拿到非空内容为准。OpenCLI 作为跨平台后端的安装器定义在 cli.py（facebook、instagram、opencli 共用 _install_opencli_deps），且属于「仅桌面」渠道——服务器环境（无桌面 Chrome）下 install 会自动跳过（cli.py 中 OPENCLI_ONLY_CHANNELS 在 server 环境被剔除并打印提示）。

工作区规则（Workspace rules）

绝不在 Agent 工作区创建文件。临时输出一律放 /tmp/，持久化数据放 ~/.agent-reach/。这条规则贯穿所有参考文档：YouTube 字幕下载用 -o "/tmp/%(id)s"，小宇宙播客转录的 Markdown 默认输出到 /tmp/，bili 的 Cookie jar 也写在 /tmp/bili_ck.txt。

七份参考文档速览：每份解决什么问题

参考文档	覆盖范围	关键实战点
search.md	Exa AI 搜索	web_search_exa(query, numResults=5)；擅长英文/技术/代码资料；get_code_context_exa 已弃用
social.md	小红书/Twitter/B站/V2EX/Reddit/Facebook/Instagram	多后端命令组、xsec_token 限制、Twitter 重试链、频率控制建议
career.md	LinkedIn	mcporter call linkedin.search_people / search_jobs / get_person_profile / get_company_profile；需先 --login 保存登录态；MCP 不可用时 fallback 到 Jina Reader
dev.md	GitHub CLI	认证、搜索、仓库、Issue、PR、Actions 日志（gh run view <run-id> --log-failed）、Release、gh api，以及 --json + --jq 结构化输出
web.md	网页/RSS	Jina Reader（curl r.jina.ai/URL）、web-reader MCP（可 retain_images=true / return_format="text"）、feedparser 读 RSS
video.md	YouTube/B站/小宇宙	字幕重试链、Whisper 转写兜底、B站 bili-cli 命令组、小宇宙 transcribe.sh（可选 --polish 用 Llama 3.3 70B 补标点分段）
finance.md	雪球行情	opencli xueqiu 命令组、Cookie 边界、验收与失败处理标准

其中两条重试链值得单独记住，因为它们定义了「成功的验收标准」：

YouTube 字幕重试链（按序执行，拿到实质内容即停）：① yt-dlp --write-sub --write-auto-sub ...；② 出现 bot 校验或字幕为空且 OpenCLI 已连接时，opencli youtube transcript "URL" -f yaml；③ OpenCLI 返回 Caption URL returned empty response 时最多重试 3 次（带过期时间的字幕 URL 偶发失效，不能把空响应当成视频没有字幕）；④ 仍失败或视频本来就没有字幕，agent-reach transcribe "URL" 下载音频用 Whisper 转写。成功标准是实际得到非空字幕/转录内容，不是命令退出码或 doctor 的探测结果（video.md）。

转写服务商策略：agent-reach transcribe 只接收公开 http(s) URL 或本地音频文件；需要先 agent-reach configure groq-key（免费 key）或 agent-reach configure openai-key。默认 auto 模式只用第一个已配置服务商（优先 Groq，否则 OpenAI），失败即停止，不会把音频自动转给另一家；--allow-provider-fallback 才是显式授权跨服务商降级——且该参数只在 --provider auto 时合法（cli.py 有参数校验），使用时应确认音频内容可以分享给两家服务商。

配置与更新流程

技能规定：某渠道需要 setup 时，去取安装指引（对应仓库内 install.md）——「用户只负责提供 cookies / 一次扩展点击，Agent 负责其余步骤」。CLI 侧对应的能力：

• agent-reach configure <key>：支持 proxy、github-token、groq-key、openai-key、twitter-cookies、youtube-cookies、xhs-cookies，敏感 key 走隐藏输入（cli.py）；
• agent-reach install --env=auto --channels=...：一键安装可选渠道，--system 显式授权系统级变更，--dry-run 预览（如小宇宙渠道需要：agent-reach install --env=auto --system --channels=xiaoyuzhou，需用户明确授权）；
• agent-reach check-update：完成较大任务后的快速版本检查（一次 API 调用），新版本提示对应 update.md 的更新流程；
• agent-reach watch：健康检查 + 更新检查的组合，适合放进定时任务。

小结

SKILL_en.md 的设计范式可以概括为三点：先体检后动手（doctor --json 的 active_backend 是唯一路由依据，null 不等于不可用）、意图驱动路由（7 类意图各有一份带重试链的参考文档，命令可复制、验收标准明确）、严格的能力边界（只读抓取、不替用户登录、不读浏览器 Cookie、不在工作区落文件）。配合 doctor.py 的容错体检、base.py 的有序后端路由与用户覆盖机制，这套技能让 Agent 在多平台调研时有确定性的执行路径，而不是每次即兴发挥。