Agent-Reach SKILL.md 解析：为 AI Agent 设计 15 平台互联网能力路由器

本文以 agent_reach/skill/SKILL.md 为主体，剖析 Agent-Reach 项目如何把一个"Skill 文件"写成 AI Agent 可直接执行的互联网访问路由协议：从触发条件与元数据、五条常驻规则，到 7 类 15 平台的路由表、零配置快速命令组、登录态平台的认证边界、doctor --json 环境体检与 OpenCLI 适配器发现机制。读完后你能理解该项目"多后端路由 + 只读优先 + 重试链兜底"的完整设计，并掌握把平台能力组装成 Agent 工作流的实操方法。

SKILL.md 是什么：一个写给 Agent 的路由协议

agent_reach/skill/SKILL.md 不是给人看的说明书，而是一份注入 AI Agent（Claude 类工具）上下文的 Skill 定义文件。文件开头的 YAML front matter 声明了触发协议，其核心内容是三条"MUST USE"规则：

• 用户想要调研/research/搜索/查/找互联网上任何内容时（"全网调研 X"、"查一下 X"、"看看大家怎么评价 X"）必须使用本 skill；
• 用户提及任何平台（小红书/xiaohongshu/xhs、Twitter/推特/X、B站/bilibili、Reddit、Facebook、Instagram、V2EX、LinkedIn、YouTube、GitHub code search、小宇宙播客、雪球、RSS 或任意网页 URL）时必须使用本 skill；
• 文件同时明确"NOT for"边界：写报告/数据分析/翻译等内容加工不属于本 skill（它只负责从互联网获取内容）；发帖/评论/点赞等写操作不属于本 skill；已有专门 skill 的平台优先用专门 skill。

front matter 还声明了能力概览："15 platforms, multi-backend routing (OpenCLI / per-platform CLIs / APIs). Zero config for 6 channels"，并给出自检命令 agent-reach doctor --json。整个文件的定位一句话概括：本 skill 存在时必须用它访问这些平台，不要自己发明方案。

常驻规则：五条贯穿全程的执行纪律

SKILL.md 的"常驻规则"一节定义了 Agent 每次执行任务时都必须遵守的五条纪律，这是整个路由协议的骨架：

1. 动手前先体检：多后端/登录态平台（小红书/Reddit/B站/Twitter/Facebook/Instagram）先跑 agent-reach doctor --json。active_backend 有值时按它选命令组；active_backend: null 表示 Doctor 为避免触发浏览器 Cookie 读取或远端写入而没有做实时验证，不代表后端不存在。只有用户任务明确需要该平台时，才按对应 reference 的只读命令手动验证。
2. 声明你在用什么：开始干活前说一句"使用 agent-reach 的 X 平台 / Y 后端"，保证用户对 Agent 行为有知情权。
3. 失败按 references 里的重试链处理，不要瞎猜命令。
4. 全网调研类任务：组合多平台（Exa 搜索 + Twitter/Reddit 看讨论 + 小红书/B站看中文场景），并行收集再汇总。
5. 替用户盯版本：完成一次较大的调研/多平台任务后，顺手跑 agent-reach check-update（很快，一个 API 调用）。有新版就在收尾汇报里附一句更新指引；不要中断当前任务去更新，也不要重复提醒同一个版本。

这些命令在仓库源码中都有对应实现。agent_reach/cli.py 的 main() 中注册了 setup、install、configure、doctor、transcribe、check-update 等子命令；其中 check-update 的帮助文本即 "Check for new versions and changes"，doctor 的帮助文本即 "Check platform availability"，与 SKILL.md 中的描述一一对应。

路由表：7 个分类覆盖 15 个平台

SKILL.md 的路由表是"意图 → 分类 → 详细文档"的三级结构，复杂场景按需阅读对应分类的 references 文档：

用户意图	分类	详细文档
网页搜索/代码搜索	search	references/search.md
小红书/推特/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

这种"主文件只做路由、细节下沉到 references"的设计是控制 Agent 上下文开销的常见做法：SKILL.md 本身只有 142 行，而最重的 social.md 有 301 行，只有真正碰到小红书/Twitter/Reddit 任务时才需要加载。

零配置快速命令：6 个免登录通道的命令组

SKILL.md 给出了一组"零配置"命令，覆盖搜索、网页阅读、GitHub、YouTube、V2EX、B站六类无需登录即可工作的通道：

# Exa 网页搜索
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.md）
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

references/search.md 把 mcporter call exa.web_search_exa 展开为具体用法：web_search_exa(query: "...", numResults: 5) 用于网页搜索，web_search_exa(query: "框架名 API 示例", numResults: 5) 用于技术/代码资料。该文档还明确：Exa MCP 的 get_code_context_exa 已弃用且默认不注册，代码问题也使用 web_search_exa；需要精确搜索仓库内容时改用 GitHub 搜索。在"与其他搜索工具对比"表中，Exa 定位于英文/技术/代码搜索，中文搜索留给智谱搜索，仓库/代码搜索留给 GitHub 搜索——每个工具只占一个明确的生态位。

从配置文件看，Exa 是通过 MCP 协议接入的：config/mcporter.json 中声明了 "exa": { "baseUrl": "https://mcp.exa.ai/mcp" }，即 exa 是远程 MCP 服务，由 mcporter 负责本地统一调用。同一文件还注册了 "xiaohongshu": { "baseUrl": "http://localhost:18060/mcp" }，说明小红书 MCP 后端走本地回环地址——这也解释了 social.md 里为什么小红书后端 B 的 mcporter call xiaohongshu.* 命令要求 --timeout 120000。

V2EX：公开 API 直连 + Python 通道封装

V2EX 是零配置通道的典型代表，references/social.md 给出了完整 API 命令组（热门主题、节点主题、主题详情、主题回复、用户信息，均带 User-Agent: agent-reach/1.0 头），并附 Python 调用示例：

from agent_reach.channels.v2ex import V2EXChannel

ch = V2EXChannel()

# 获取热门帖子
topics = ch.get_hot_topics(limit=10)
for t in topics:
    print(f"[{t['node_title']}] {t['title']} ({t['replies']} 回复)")

# 获取帖子详情 + 回复
topic = ch.get_topic(1234567)
print(topic["title"], "—", topic["author"])

这段示例与仓库源码结构吻合：agent_reach/channels/v2ex.py 实现了 V2EXChannel，提供 get_hot_topics、get_node_topics、get_topic、get_user 等方法。也就是说 V2EX 通道有"curl 直连 API"和"Python 库调用"两条路径，前者给 Agent 在 Shell 里用，后者给程序化集成用。

YouTube 与 B站的分工边界

零配置命令组里特意用注释警告："B站不要用 yt-dlp"。references/video.md 解释了原因并给出完整重试链：yt-dlp 只用于 YouTube（下载字幕 --write-sub --write-auto-sub --sub-lang "zh-Hans,zh,en"、搜索用 ytsearch5:query、评论为 best-effort 网页抓取）；B站因风控已全面 412 拦截 yt-dlp（实测直连/代理/带 Cookie 全部无效），必须走 bili-cli（bili video BVxxx / bili search / bili hot / bili rank，只读无需登录）与 OpenCLI（opencli bilibili subtitle BVxxx 取带时间轴字幕）。YouTube 字幕失败时的重试链是：yt-dlp → opencli youtube transcript（空响应最多重试 3 次）→ agent-reach transcribe 音频转写，"成功标准是实际得到非空字幕/转录内容，不是命令退出码"。

agent-reach transcribe 在 cli.py 中注册，帮助文本为 "Transcribe a URL or local audio file (Whisper via Groq/OpenAI)"；video.md 补充了关键安全语义：默认 auto 模式只使用第一个已配置服务商（优先 Groq，否则 OpenAI），失败即停止，不会把音频自动发给另一家；--allow-provider-fallback 会显式授权跨服务商降级，只应在确认内容可分享给两家后使用。

需登录态的平台：命令组与认证边界

SKILL.md 对登录态平台的第一原则是"按 doctor 的 active_backend 选命令"，然后逐平台划定认证边界——这部分是文档中最有实战价值的约束条款：

# Twitter 搜索（twitter-cli 首选；失败重试链见 social.md）
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        # 读指定用户最近帖子

Twitter：Cookie 只供 doctor 检查，不供命令执行

SKILL.md 特别澄清了一个极易被 Agent 误解的语义：agent-reach configure twitter-cookies 保存的 Cookie 只供 doctor 检查配置是否齐全；doctor 不执行 twitter status，也不会设置当前 Shell。直接运行 twitter 前，必须在子进程环境中显式提供 TWITTER_AUTH_TOKEN 和 TWITTER_CT0，且不得在日志或命令回显中暴露值。

references/social.md 进一步区分了 Twitter 命令的稳定区与不稳定区：稳定命令有 twitter feed -n 20（首页时间线，最稳定）、twitter tweet URL_OR_ID（含回复）、twitter article（X Article）、twitter user-posts @username、twitter user @username；不稳定命令有 twitter search（Twitter 频繁改 GraphQL 端点，可能 404）和 twitter likes（2024 年后平台限制只能看自己的）。搜索失败时的重试链按序执行、成功即停：

1. 直接重试一次（偶发失败常见）；
2. pipx upgrade twitter-cli 升级后再试；
3. 换 OpenCLI 备选：opencli twitter search "query" -f yaml（复用浏览器登录态）；
4. 都不行就改用 twitter feed / twitter user-posts 等稳定命令绕路。

文档还给出风控约束：不要在 VPS/数据中心 IP 上频繁调用（尤其 followers/following，有封号风险），输出建议用 --yaml/--json 结构化格式对 Agent 更友好。

小红书：三后端与"不替用户登录"的边界

social.md 为小红书定义了 A/B/C 三个后端，先跑 agent-reach doctor --json 看 active_backend 再选命令组：

• 后端 A：OpenCLI（桌面首选）——opencli xiaohongshu search "query" -f yaml、opencli xiaohongshu note "NOTE_URL" -f yaml（读正文+互动数据）、opencli xiaohongshu comments NOTE_ID（支持楼中楼）、opencli xiaohongshu feed、opencli xiaohongshu user USER_ID。要求 Chrome 打开且装了 OpenCLI 扩展。
• 后端 B：xiaohongshu-mcp（服务器场景）——先 agent-reach configure xhs-cookies（用户用 Cookie-Editor 手工导出后显式导入），只读检查 mcporter call xiaohongshu.check_login_status --timeout 120000，搜索 mcporter call xiaohongshu.search_feeds keyword="query" --timeout 120000，详情 mcporter call xiaohongshu.get_feed_detail feed_id="..." xsec_token="..."。首次调用自动下载约 150MB 无头浏览器，务必带 --timeout 120000。
• 后端 C：xhs-cli（存量备选）——xhs search / xhs read NOTE_ID_OR_URL / xhs comments / xhs hot / xhs feed；上游 2026-03 起停更，xhs user 等命令可能返回 API error，新装用户建议直接走 A/B。

三个后端共享两条硬约束。xsec_token 限制：小红书强制 xsec_token 机制，不能直接用裸 note_id 去读，正确流程是先搜索/feed 拿结果、再用结果中的完整 URL/ID 去读。认证边界：Agent Reach 不得替用户执行登录，也不得读取浏览器 Cookie；OpenCLI 只能使用用户已有且明确控制的 Chrome 会话；agent-reach configure xhs-cookies 不会把 Cookie 注入 OpenCLI，它保存的是 xiaohongshu.com 同域 Cookie 集，非该域 Cookie 会被忽略。另有频率控制建议：高频请求会触发验证码，每次操作间隔 2-3 秒。

Reddit：无零配置路径的双后端

social.md 对 Reddit 的定性是"没有零配置路径"：匿名 .json 端点已被封（403），官方 API 自 2025-11 起人工审批基本不批，两个后端都靠登录态。后端 A 是 OpenCLI（opencli reddit search/read/subreddit/hot/popular/subreddit-info，要求 Chrome 已登录 reddit.com）；后端 B 是 rdt-cli（rdt search "query" --limit 10、rdt read POST_ID、rdt sub python --limit 20），安装命令为 pipx install 'git+https://github.com/public-clis/rdt-cli.git'（PyPI 版本落后，需从 GitHub 装 v0.4.2+），先 rdt login 才能使用。

这个"从 git 装"的要求在源码里有直接佐证：agent_reach/cli.py 顶部定义了 _RDT_GIT_SOURCE = "git+https://github.com/public-clis/rdt-cli.git@5e4fb37..."，注释说明 "Pinned to the 0.4.2 state — PyPI still only has 0.4.1 (upstream issue #10)"，即安装器直接钉死到 0.4.2 对应的 git 提交，与 SKILL.md 的叙述一致。

Facebook 与 Instagram：统一收敛到 OpenCLI

两个平台都走 OpenCLI 复用 Chrome 登录态，正常 active_backend 应为 OpenCLI。Facebook 命令组为 search / profile / feed / groups（Groups 只承诺读取当前账号可见的群组列表/最近动态，不承诺任意群帖子和评论 API）；Instagram 命令组为 search（注意是搜用户而非全站帖子搜索）、profile、user USERNAME（读指定用户最近帖子）、explore、saved。文档明确不要默认恢复 instaloader（历史 cookies/401/429 不稳定），也不要推荐 Jina/Exa/Graph API 作为默认路径；若出现 429 / login required，先让用户在 Chrome 里重新登录并降低频率。

环境检查：doctor --json 与 active_backend 语义

SKILL.md 的环境检查一节只有一行命令，但语义在"常驻规则"中完整定义：

# 检查可用 channel 与每个平台当前激活的后端
agent-reach doctor --json

active_backend 三个字段的语义值得单独强调，因为它直接决定 Agent 该不该信任体检结果：

• active_backend 有值 → 按它选对应后端的命令组；
• active_backend: null → 不代表后端不存在，只表示 Doctor 为避免触发浏览器 Cookie 读取或远端写入而没有做实时验证；
• 只有用户任务明确需要该平台时，才按对应 reference 的只读命令手动验证。

从源码看，这一语义由 agent_reach/doctor.py 实现：它遍历各 channel 的注册单例，读取 ch.active_backend 属性组装 JSON 结果（源码注释特别说明 "Channels are registry singletons: a stale active_backend from a..."，即注意单例上残留的旧状态）。video.md 还用 YouTube 给出了一个反面例子：doctor 只确认 yt-dlp 本体与 JS runtime 能执行，不会请求具体视频，因此 active_backend: yt-dlp 不等于目标视频的字幕已通过实时验证——doctor 验证的是"通道可用"，不是"内容可达"。

finance.md 进一步给出了登录态平台的验收标准，可视为全局方法论：以返回股票名称、代码、价格或非空内容列表为成功；退出码 0 但字段为空不算成功；HTTP 400 通常是会话/Cookie 问题，不能把 400 当成"股票不存在"；whoami 成功而 stock/hot 失败时按适配器解析或平台接口问题报告，不要误诊成未登录。

OpenCLI 适配器发现：路由表之外的兜底协议

SKILL.md 定义了一个优雅降级协议：路由表没有覆盖用户需要的平台或命令时，先用 opencli list 查已有适配器，再用 opencli <平台> --help 查看公开命令。同时划出两条验收线：发现适配器只证明命令存在，不证明登录态或目标内容可用；仅在用户任务明确需要该平台时执行只读命令，并以实际非空内容验收。

这与仓库中 OpenCLI 后端的角色相印证：agent_reach/backends/opencli.py 实现了 OpenCLI 后端的封装，各 channel（如 channels/xiaohongshu.py、channels/reddit.py）通过它选择是否走 OpenCLI 命令组。doctor.py 输出的 active_backend 正是这一选择的结果记录。

工作区规则与配置渠道

SKILL.md 最后两节是 Agent 行为的空间边界与配置协议：

• 工作区规则：不要在 agent workspace 创建文件。使用 /tmp/ 存放临时输出，~/.agent-reach/ 存放持久数据。这条规则同时解释了为什么前文所有 yt-dlp 命令都用 -o "/tmp/%(id)s" 模板、小宇宙转写输出也默认保存到 /tmp/——全文档的命令示例都遵守这一约定。
• 配置渠道：如果某个 channel 需要配置，获取安装指南后由 agent 完成其余配置，用户只需提供 cookies。仓库内的 docs/install.md 与 docs/cookie-export.md 对应了这份指南与 Cookie 导出流程。

敏感配置项的边界在源码中同样有定义：cli.py 维护了 _SENSITIVE_CONFIG_KEYS = {"proxy", "github-token", "groq-key", "openai-key", "twitter-cookies", "xhs-cookies"} 与 _MAX_CONFIGURE_VALUE_CHARS = 1024 * 1024 的值长度上限，即 SKILL.md 中"隐藏输入""不得在日志暴露值"等约束在 configure 命令的实现层有对应的敏感键集合与限额保护。

小结：Skill 文件的三层结构

回看 SKILL.md 全文，它实际上是一份三层结构的路由协议：

1. 触发层（front matter）：MUST USE / NOT for 声明，解决"什么时候该用"；
2. 路由层（路由表 + 常驻规则 + 零配置命令组）：解决"用什么命令组、先跑什么检查、失败怎么办"；
3. 下沉层（references 七篇分类文档）：解决"每平台完整命令组、重试链、认证边界与验收标准"。

三层之间用 doctor --json 的 active_backend 作为运行时锚点衔接：Agent 不预知用户机器上哪个后端可用，而是"先体检、按结果选组、以非空内容验收"。配合 agent_reach/skill/references/ 下 7 篇分类文档（social.md 301 行、video.md 148 行等）以及仓库源码中 cli.py / doctor.py / backends/opencli.py 的实现佐证，这套"只读优先、多后端路由、重试链兜底"的设计完整回答了"如何让 AI Agent 用零 API 费用的方式读取 15 个平台内容"这一工程问题。