技术架构 - 可插拔渠道设计与数据流分析

核心设计理念

脚手架而非框架

Agent-Reach 的核心设计哲学是scaffolding（脚手架）而非framework（框架）：

实现方式：

• 安装后，Agent 直接调用 xreach、yt-dlp、gh 等上游工具
• Agent-Reach 仅提供检测、配置、诊断功能
• 不包装、不代理、不拦截调用

可插拔渠道架构

channels/
├── web.py          → Jina Reader     (网页阅读)
├── twitter.py      → xreach CLI      (Twitter 访问)
├── youtube.py      → yt-dlp          (视频字幕)
├── github.py       → gh CLI          (GitHub 操作)
├── bilibili.py     → yt-dlp          (B 站视频)
├── reddit.py       → JSON API + Exa  (Reddit 搜索)
├── xiaohongshu.py  → mcporter MCP    (小红书)
├── douyin.py       → mcporter MCP    (抖音)
├── linkedin.py     → linkedin-mcp    (LinkedIn)
├── bosszhipin.py   → mcp-bosszp      (Boss 直聘)
├── wechat.py       → camoufox+miku   (微信公众号)
├── rss.py          → feedparser      (RSS 订阅)
├── exa_search.py   → mcporter MCP    (全网搜索)
└── __init__.py     → 渠道注册表

每个渠道文件职责：

1. 实现 check() 方法：检测上游工具是否可用
2. 提供配置指引：告诉用户如何配置
3. 注册到渠道表：供 doctor 命令查询

系统架构总览

架构图

flowchart TB
    subgraph Agent["AI Agent 层"]
        A1[Claude Code]
        A2[Cursor]
        A3[Windsurf]
    end
    
    subgraph CLI["Agent-Reach CLI 层"]
        B1[安装命令]
        B2[配置命令]
        B3[doctor 诊断]
        B4[卸载命令]
    end
    
    subgraph Channels["渠道检测层"]
        C1[web.py]
        C2[twitter.py]
        C3[youtube.py]
        C4[其他渠道...]
    end
    
    subgraph Tools["上游工具层"]
        D1[Jina Reader API]
        D2[xreach CLI]
        D3[yt-dlp]
        D4[gh CLI]
        D5[mcporter MCP]
        D6[feedparser]
    end
    
    subgraph Platforms["目标平台"]
        E1[任意网页]
        E2[Twitter/X]
        E3[YouTube/B 站]
        E4[GitHub]
        E5[小红书/抖音]
        E6[RSS 源]
    end
    
    A1 & A2 & A3 --> B1 & B2 & B3
    B1 & B2 & B3 --> C1 & C2 & C3 & C4
    C1 --> D1
    C2 --> D2
    C3 --> D3
    C4 --> D4 & D5 & D6
    D1 --> E1
    D2 --> E2
    D3 --> E3
    D4 --> E4
    D5 --> E5
    D6 --> E6

数据流分析

安装流程

sequenceDiagram
    participant U as 用户
    participant A as AI Agent
    participant AR as Agent-Reach CLI
    participant S as 系统
    participant T as 上游工具
    
    U->>A: "帮我安装 Agent-Reach"
    A->>S: pip install agent-reach
    S-->>A: 安装完成
    A->>AR: agent-reach install --env=auto
    AR->>S: 检测环境（本地/服务器）
    AR->>S: 检测 Node.js、gh CLI 等
    AR->>S: 安装缺失依赖
    AR->>T: 配置 MCP 服务（mcporter）
    AR->>A: 注册 SKILL.md 使用指南
    AR-->>A: 安装完成，运行 doctor
    A->>AR: agent-reach doctor
    AR-->>A: 返回各渠道状态

渠道检测流程（doctor 命令）

flowchart LR
    Start[开始] --> Loop[遍历渠道列表]
    Loop --> Check[调用 channel.check]
    Check --> Result{检测结果}
    Result -->|可用 | Green[标记✅]
    Result -->|需配置 | Yellow[标记⚠️]
    Result -->|不可用 | Red[标记❌]
    Green --> Next[下一个渠道]
    Yellow --> Next
    Red --> Next
    Next --> More{还有渠道？}
    More -->|是 | Loop
    More -->|否 | Report[生成状态报告]
    Report --> End[结束]

核心组件详解

1. CLI 入口（agent_reach/cli.py）

职责：解析命令行参数，分发到对应命令处理器

# 概念性代码结构
def main():
    parser = argparse.ArgumentParser("agent-reach")
    subparsers = parser.add_subparsers()
    
    # 安装命令
    install_parser = subparsers.add_parser("install")
    install_parser.add_argument("--env", choices=["auto", "local", "server"])
    install_parser.add_argument("--safe", action="store_true")
    install_parser.add_argument("--dry-run", action="store_true")
    
    # 配置命令
    config_parser = subparsers.add_parser("configure")
    config_parser.add_argument("channel")  # twitter-cookies, proxy, etc.
    config_parser.add_argument("value")
    
    # 诊断命令
    doctor_parser = subparsers.add_parser("doctor")
    
    # 卸载命令
    uninstall_parser = subparsers.add_parser("uninstall")
    uninstall_parser.add_argument("--keep-config", action="store_true")
    
    args = parser.parse_args()
    dispatch(args)

2. 渠道检测器（channels/*.py）

通用接口：

# 每个渠道文件的抽象接口
class Channel(Protocol):
    def check(self) -> CheckResult:
        """检测上游工具是否可用"""
        ...
    
    def configure(self, config: dict) -> None:
        """配置渠道（如设置 Cookie）"""
        ...
    
    def get_status(self) -> str:
        """获取人类可读的状态描述"""
        ...

Twitter 渠道示例：

# agent_reach/channels/twitter.py
import subprocess

def check() -> CheckResult:
    """检查 xreach CLI 是否安装"""
    try:
        result = subprocess.run(
            ["xreach", "--version"],
            capture_output=True,
            text=True
        )
        if result.returncode == 0:
            return CheckResult(
                status="ready",
                message="xreach CLI 已安装"
            )
        else:
            return CheckResult(
                status="missing",
                message="xreach CLI 未安装"
            )
    except FileNotFoundError:
        return CheckResult(
            status="missing",
            message="xreach CLI 未找到"
        )

3. 配置管理器（~/.agent-reach/config.yaml）

存储内容：

• Cookie（Twitter、小红书等）
• 代理配置
• Token（GitHub、Exa 等）
• 用户偏好设置

安全措施：

# 文件权限设置为 600（仅所有者可读写）
chmod 600 ~/.agent-reach/config.yaml

# 文件内容示例（概念性）
twitter:
  cookies: "加密后的 Cookie 字符串"
proxy:
  http: "http://user:pass@ip:port"
github:
  token: "ghp_xxx"

4. 技能注册器（SKILL.md）

作用：安装到 Agent 的 skills 目录，指导 Agent 如何使用各渠道

内容结构：

# Agent-Reach Skills

## Twitter/X
当用户需要搜索或阅读推文时：
1. 使用 `xreach tweet <URL> --json` 读取单条推文
2. 使用 `xreach search "<query>" --json` 搜索推文
3. 如果返回 403，运行 `agent-reach configure twitter-cookies "<cookies>"`

## YouTube
当用户需要提取视频字幕时：
1. 使用 `yt-dlp --dump-json "<URL>"` 获取元数据
2. 使用 `yt-dlp --write-sub --skip-download "<URL>"` 提取字幕

## GitHub
当用户需要查看仓库信息时：
1. 使用 `gh repo view <owner>/<repo>` 查看基本信息
2. 使用 `gh search repos "<query>"` 搜索仓库

渠道-工具映射表

MCP 集成详解

Model Context Protocol（MCP）

什么是 MCP：

• 标准化协议，用于连接 AI 模型与外部工具
• 类似”USB-C for AI tools”
• 允许 Agent 通过统一接口调用不同服务

Agent-Reach 的 MCP 使用：

┌─────────────────┐
│   AI Agent      │
│ (Claude/Cursor) │
└────────┬────────┘
         │ MCP 调用
         ▼
┌─────────────────┐
│   mcporter      │ ← MCP 客户端
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ xiaohongshu-mcp │ ← MCP 服务端（Docker）
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   小红书 API     │
└─────────────────┘

配置流程：

1. 安装 Docker
2. agent-reach install 自动拉取并运行 MCP 服务容器
3. mcporter 注册服务到 Agent
4. Agent 通过 mcporter call 'xiaohongshu.get_feed_detail(...)' 调用

诊断机制（doctor 命令）

实现原理

# 概念性实现
def doctor():
    channels = discover_channels()  # 从 channels/ 目录加载
    results = []
    
    for channel in channels:
        result = channel.check()
        results.append({
            "name": channel.name,
            "status": result.status,  # ready, missing, misconfigured
            "message": result.message
        })
    
    # 生成报告
    print_report(results)

输出示例

$ agent-reach doctor

👁️  Agent Reach Status
========================================

✅ Ready to use:
  ✅ GitHub repos and code — public repos readable and searchable
  ✅ Twitter/X tweets — readable. Cookie unlocks search and posting
  ✅ YouTube video subtitles — yt-dlp
  ⚠️  Bilibili video info — server IPs may be blocked, configure proxy
  ✅ RSS/Atom feeds — feedparser
  ✅ Web pages (any URL) — Jina Reader API

🔍 Search (free Exa key to unlock):
  ⬜ Web semantic search — sign up at exa.ai for free key

🔧 Configurable:
  ⬜ Reddit posts and comments — search via Exa (free). Reading needs proxy
  ⬜ XiaoHongShu notes — needs cookie. Export from browser

Status: 6/9 channels available

安装策略

环境检测逻辑

def detect_environment():
    """检测运行环境"""
    if is_local_machine():
        return "local"
    elif is_server():
        return "server"
    else:
        return "auto"

def is_local_machine():
    """检测是否是本地电脑"""
    # 检查是否有桌面环境
    # 检查是否有浏览器
    # 检查 IP 是否是住宅 IP
    ...

def is_server():
    """检测是否是服务器"""
    # 检查云厂商元数据
    # 检查 IP 是否是数据中心 IP
    ...

安全模式

# 安全模式：只列出需要什么，不实际安装
agent-reach install --safe

# 输出示例：
需要安装以下依赖：
1. Node.js 18+ (当前未安装)
2. gh CLI (当前未安装)
3. xreach CLI (当前未安装)

请手动安装或移除 --safe 参数自动安装

结论

Agent-Reach 的技术架构核心是可插拔渠道 + 上游工具集成：

1. 渠道层：负责检测和配置，不负责实际调用
2. 工具层：现有开源工具，各领域最佳选择
3. 诊断层：统一接口检测所有渠道状态

这种设计实现了零包装开销、可单独替换、持续可维护的目标。

下一章将通过对比分析，展示该方案相对于其他方案的优劣势。