Agent Reach 技术原理

v1.5.0 · 安装器 + 健康检查器 + Skill 文档的三合一工具包

Agent Reach 是一个面向 AI Agent 的"互联网平台接入框架"——它本身不是运行时中间层，而是安装器 + 健康检查器 + Skill 文档的三合一工具包。AI Agent 直接调用上游 CLI 工具（如 opencli、yt-dlp、gh），Agent Reach 只负责把这些工具装好、配好、告诉 Agent 该用什么命令。

一、三层架构总览

Agent Reach 三层架构总览 能力层 — AI Agent AI Agent (LLM) SKILL.md references/*.md 路由表 + 命令参考 + 分类文档 框架层 — Agent Reach (v1.5.0) 安装器 install --channels 健康检查 doctor --json 配置管理 config.yaml Skill 注册 skill --install 运行时层 — 上游 CLI 工具（Agent 直接调用） OpenCLI 浏览器桥接 yt-dlp 视频/字幕 gh GitHub mcporter MCP 中间层 Jina 网页读取 Agent Reach 本身不参与数据流——Agent 读 SKILL.md 后直接调上游工具 Agent Reach 只负责"装好、配好、告诉 Agent 怎么用"
图 1 · Agent Reach 三层架构总览

核心要点：Agent Reach 不在数据路径上。Agent 读 SKILL.md 知道该调什么命令，然后直接调 opencli、yt-dlp 这些上游工具。Agent Reach 只负责把它们装好、检查健康状态、管理配置。

二、Channel 与 Backend 多对多映射

每个 Channel 代表一个互联网平台（如小红书），每个 Backend 是一个底层运行时（如 OpenCLI），一个 Backend 可以服务多个 Channel。Channel 的 backends 列表是有序的，表示优先级——首选不可用时自动降级。

Channel 与 Backend 多对多映射 Channel（平台渠道） Backend（运行时后端） 小红书 Xiaohongshu backends: OpenCLI, mcp, xhs-cli Twitter / X backends: twitter-cli, OpenCLI, bird Bilibili backends: bili-cli, OpenCLI, API Reddit backends: OpenCLI, rdt-cli Facebook backends: OpenCLI only Instagram backends: OpenCLI only YouTube backends: yt-dlp (tier 0) GitHub backends: gh CLI (tier 0) OpenCLI 浏览器桥接，复用登录态 yt-dlp 视频下载 + 字幕提取 gh CLI GitHub API 封装 mcporter MCP 协议中间层 Jina Reader 通用网页读取兜底
图 2 · Channel 与 Backend 多对多映射

可以看到 OpenCLI（橙色）一个后端覆盖了 6 个社交平台——这是 Agent Reach 最核心的设计。以小红书为例，backends = ["OpenCLI", "xiaohongshu-mcp", "xhs-cli"] 意味着优先用 OpenCLI，不行再降级到 MCP，最后才用 xhs-cli。

三、OpenCLI 浏览器桥接工作原理

这是整个技术栈中最精巧的部分。OpenCLI 的核心思路：不创建新的浏览器实例，而是"搭便车"在用户已经登录的 Chrome 上。通过 Chrome 扩展的 WebSocket 连接，Agent 发出的命令直接在用户的浏览器中执行——网站看到的就是一个正常登录用户的操作，不需要任何额外的认证配置。

OpenCLI 浏览器桥接工作原理 AI Agent 读 SKILL.md 后调用 opencli CLI v1.8.6 (Node.js) OpenCLI Daemon 本地常驻进程 1 2 Chrome 扩展 ws://localhost:19825/ext 3 WebSocket Chrome 浏览器 用户已登录的会话 4 目标网站 小红书/Reddit/Twitter... 5 6 YAML 数据返回 关键优势 零配置认证 — 复用 Chrome 已有登录态，无需 API Key / Cookie 配置 / 扫码登录 一个 OpenCLI 安装 = 6 个社交平台全覆盖（小红书/Reddit/B站/Twitter/FB/IG）
图 3 · OpenCLI 浏览器桥接工作原理
1AI Agent 读 SKILL.md 中的路由表，确定该调用 opencli xiaohongshu search "..."
2命令传递给 OpenCLI Daemon（本地常驻 Node.js 进程）
3Daemon 通过 WebSocket（ws://localhost:19825/ext）连接 Chrome 扩展
4扩展在已登录的 Chrome 中执行操作（发请求、读 DOM）
5Chrome 向目标网站发送请求——网站看到的是正常登录用户
6数据沿原路返回，最终以 YAML 格式交给 Agent

四、后端探活与自动降级机制

probe_command() 不只做 shutil.which() 文件检查，而是真实执行命令来验证健康状态。然后 check() 按 ok > warn > error > off 优先级选择第一个可用后端。

后端探活与自动降级机制 以小红书为例 — check() 探活流程 OpenCLI 优先级 1 — 首选 xiaohongshu-mcp 优先级 2 — 降级 xhs-cli 优先级 3 降级 降级 探活逻辑（真实执行命令，而非 which 检查） _check_opencli() opencli daemon status 检查扩展 WebSocket 连接 检查 Chrome 磁盘扩展目录 _check_mcp() HTTP GET localhost:18060 mcporter config list 检查 xiaohongshu 是否接入 _check_xhs xhs status 检查输出中 ok: true 选择优先级 — 第一个 ok 获胜，没有 ok 则第一个 warn ok 完全可用 warn 已安装待配置 error 已安装但损坏 off / None 未安装 probe_command() 的精细区分 missing — 命令不在 PATH（shutil.which 找不到） broken — 命令存在但无法执行（通常是 venv 断链，需 reinstall） timeout/error — 命令运行但行为异常（可重试）
图 4 · 后端探活与自动降级机制

五、渠道覆盖一览

渠道 后端列表 Tier 实现模式
GitHubgh CLItier 0简单单后端，probe_command 探活
YouTubeyt-dlptier 0单后端 + JS runtime 检查 + 转写能力
WebJina Readertier 0恒可用兜底渠道，can_handle 始终 True
Twitter / Xtwitter-cli → OpenCLI → birdtier 1多后端两段式选择 (ok > warn)
RedditOpenCLI → rdt-clitier 1多后端，手写 subprocess
Bilibilibili-cli → OpenCLI → APItier 1多后端 + broken 备选提示
小红书OpenCLI → xiaohongshu-mcp → xhs-clitier 1三后端，含 MCP HTTP 探测
FacebookOpenCLItier 1OpenCLISiteChannel (12 行)
InstagramOpenCLItier 1OpenCLISiteChannel (12 行)
LinkedInlinkedin-scraper-mcptier 2MCP + Jina Reader 兜底

Tier 含义：tier 0 零配置即用 tier 1 需免费密钥或登录 tier 2 需复杂配置

六、Skill 注册机制

agent-reach skill --install 的流程

按优先级查找 AI Agent 的技能目录：

  1. $OPENCLAW_HOME/.openclaw/skills/
  2. ~/.agents/skills/ — 通用 Agent，最高优先级
  3. ~/.openclaw/skills/ — OpenClaw
  4. ~/.claude/skills/ — Claude Code

对每个存在的目录，创建 agent-reach/ 子目录，从包资源复制 SKILL.md（根据 locale 选择中/英文）和 references/*.md 分类文档。

安装和 doctor 命令完成时会自动触发 Skill 安装（确保首次运行后 skill 一定存在）。

SKILL.md 的内容结构
  1. 触发条件（triggers）— 定义何时必须使用此 skill：调研/搜索/社交平台/招聘/GitHub/网页/视频/金融
  2. 路由表 — 用户意图 → 分类 → 详细文档引用
  3. 零配置快速命令 — Exa 搜索、Jina Reader、GitHub 搜索、YouTube 字幕、V2EX、B 站搜索
  4. 需登录态的命令 — Twitter 搜索、Reddit、小红书、Facebook、Instagram
  5. 环境检查 — agent-reach doctor --json
  6. 分类引用 — 指向 references/ 目录下的详细文档

七、关键设计模式总结

1. 安装器而非中间层

Agent Reach 本身是安装器 + 健康检查器，不是运行时中间层。Agent 直接调用上游 CLI 工具。

2. 渠道注册表模式

channels/__init__.py 中的 ALL_CHANNELS 列表是单一事实来源，doctor 遍历它生成健康报告。

3. 后端优先 + 回退

多后端渠道使用 ordered_backends() 排序候选，check() 按 ok > warn > error > off 选择第一个可用后端。

4. 真实探活而非文件检查

probe_command() 实际执行命令来验证健康状态，能区分 missing、broken、timeout、error 四种失败模式。

5. Skill 即文档

SKILL.md 直接作为 AI Agent 的运行时参考，包含路由表、命令参考和详细分类文档。

6. 浏览器桥接零配置认证

OpenCLI 通过 Chrome 扩展复用已有登录态，无需 API Key / Cookie 配置 / 扫码登录。

Agent Reach v1.5.0 技术原理文档 · 基于源码分析生成 · 2026-07-23