Agent Reach

Agent Reach — Router

17 platform toolset. Route by user intent to the matching category reference.

Upstream: Panniantong/Agent-Reach

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

Preflight (Auto-Update)

Run this before every use. It ensures Agent Reach is installed and up-to-date.

#!/usr/bin/env bash
set -euo pipefail

PASS=true

# 1. Check if agent-reach CLI exists
if ! command -v agent-reach &>/dev/null; then
    echo "  MISSING  agent-reach CLI"
    echo "  Installing via pipx..."
    if command -v pipx &>/dev/null; then
        pipx install https://github.com/Panniantong/agent-reach/archive/main.zip --python python3.14 2>&1
        agent-reach install --env=auto 2>&1
        echo "  OK  agent-reach installed"
    else
        echo "  FAIL  pipx not found. Install: brew install pipx"
        PASS=false
    fi
else
    INSTALLED=$(agent-reach --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || echo "0.0.0")
    echo "  OK  agent-reach v${INSTALLED}"

    # 2. Check for updates (non-blocking: 5s timeout, failures are non-fatal)
    LATEST=$(curl -sf --max-time 5 https://api.github.com/repos/Panniantong/Agent-Reach/releases/latest 2>/dev/null \
        | python3 -c "import sys,json; print(json.load(sys.stdin).get('tag_name','').lstrip('v'))" 2>/dev/null || echo "")

    if [[ -n "$LATEST" && "$LATEST" != "$INSTALLED" ]]; then
        echo "  UPDATE  v${INSTALLED} → v${LATEST}"
        echo "  Upgrading..."
        pipx upgrade agent-reach 2>&1 | tail -1
        # Re-run install to update tools and SKILL.md
        agent-reach install --env=auto 2>&1 | grep -E '^\s*(✅|--|✗|\[)' | head -20
        echo "  OK  Updated to v${LATEST}"
    fi
fi

# 3. Quick health check (which channels are active?)
if command -v agent-reach &>/dev/null; then
    DOCTOR_OUTPUT=$(agent-reach doctor 2>&1)
    ACTIVE=$(echo "$DOCTOR_OUTPUT" | grep -c '✅' || true)
    TOTAL=$(echo "$DOCTOR_OUTPUT" | grep -cE '(✅|--)' || true)
    echo "  OK  ${ACTIVE}/${TOTAL} channels active"
fi

if ! $PASS; then
    echo "FAIL: Agent Reach not available."
    exit 1
fi
echo "Preflight passed."

If the version check fails (no network, GitHub rate-limited), it silently continues with the installed version. Updates are best-effort, never blocking.

Routing Table

Zero-Config Quick Commands

# Exa web search
mcporter call 'exa.web_search_exa(query: "query", numResults: 5)'

# Read any web page
curl -s "https://r.jina.ai/URL"

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

# Twitter search
twitter search "query" --limit 10

# YouTube / Bilibili subtitles
yt-dlp --write-sub --skip-download -o "/tmp/%(id)s" "URL"

# Reddit search + read
rdt search "query" --limit 10
rdt read POST_ID

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

Environment Check

# Check available channels
agent-reach doctor

# List all MCP services
mcporter_list_servers()

Configuration

agent-reach configure proxy http://user:pass@ip:port     # Reddit/Bilibili proxy
agent-reach configure twitter-cookies "auth_token=xxx; ct0=yyy"
agent-reach configure groq-key gsk_xxxxx                 # Xiaoyuzhou podcasts
agent-reach configure xhs-cookies "key1=val1; key2=val2" # XiaoHongShu
agent-reach configure --from-browser chrome              # Auto-extract all cookies

For channel-specific setup details, see references/setup-channels.md.

Workspace Rules

Never create files in the agent workspace. Use /tmp/ for temporary output and ~/.agent-reach/ for persistent data.

Troubleshooting

• Channel not working? Run agent-reach doctor
• Update manually: pipx upgrade agent-reach && agent-reach install --env=auto
• Full reinstall: pipx reinstall agent-reach && agent-reach install --env=auto

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure. 2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

职场招聘

LinkedIn。

LinkedIn

# 获取个人资料
mcporter call 'linkedin-scraper.get_person_profile(linkedin_url: "https://linkedin.com/in/username")'

# 搜索人才
mcporter call 'linkedin-scraper.search_people(keyword: "AI engineer", limit: 10)'

# 获取公司资料
mcporter call 'linkedin-scraper.get_company_profile(linkedin_url: "https://linkedin.com/company/xxx")'

# 搜索职位
mcporter call 'linkedin-scraper.search_jobs(keyword: "software engineer", limit: 10)'

需要登录: LinkedIn scraper 需要有效的登录态。

Fallback 方案

如果 MCP 不可用，可以用 Jina Reader：

curl -s "https://r.jina.ai/https://linkedin.com/in/username"

<!-- # SSoT-OK — version below is a gh CLI example placeholder, not our package -->

开发工具

GitHub CLI

GitHub (gh CLI)

GitHub 官方命令行工具，用于仓库、Issue、PR、Actions、Release 以及 API 访问。

# 认证
gh auth login
gh auth status

# 搜索
gh search repos "query" --sort stars --limit 10
gh search code "query" --language python

# 仓库
gh repo view owner/repo
gh repo clone owner/repo
gh repo create my-repo --private
gh repo fork owner/repo
gh repo fork owner/repo --clone
gh repo sync owner/repo

# Issues
gh issue list -R owner/repo --state open
gh issue view 123 -R owner/repo
gh issue create -R owner/repo --title "Title" --body "Body"

# Pull Requests
gh pr list -R owner/repo --state open
gh pr view 123 -R owner/repo
gh pr create -R owner/repo --title "Title" --body "Body"
gh pr checks 123 --repo owner/repo

# Actions / CI
gh run list --repo owner/repo --limit 10
gh run view <run-id> --repo owner/repo
gh run view <run-id> --repo owner/repo --log-failed
gh workflow list --repo owner/repo

# Releases
gh release list -R owner/repo
gh release create v1.0.0

# API
gh api /user
gh api repos/owner/repo

# JSON 输出
gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'

选择指南

搜索工具

Exa AI 搜索引擎。

Exa AI 搜索

高质量 AI 搜索引擎，擅长技术和代码搜索。

mcporter call 'exa.web_search_exa(query: "query", numResults: 5)'
mcporter call 'exa.get_code_context_exa(query: "code question", tokensNum: 3000)'

使用场景

特点

• 擅长英文内容和技术文档
• 支持代码上下文搜索
• 结果质量高

与其他搜索工具对比

Channel Setup Reference

Optional channels that require additional configuration beyond the base install.

Reddit (Proxy Required)

Reddit blocks many IP ranges. Configure a residential proxy:

agent-reach configure proxy http://user:pass@ip:port

Alternative: Search via Exa (free, no proxy needed) — mcporter call 'exa.web_search_exa(query: "site:reddit.com topic")'

XiaoHongShu (Docker + Cookies)

# Start the MCP server
docker run -d --name xiaohongshu-mcp -p 18060:18060 xpzouying/xiaohongshu-mcp

# Register with mcporter
mcporter config add xiaohongshu http://localhost:18060/mcp

# Import cookies (from browser Cookie-Editor export)
agent-reach configure xhs-cookies '<JSON array or header string>'

ARM64 (Apple Silicon): Build from source at <https://github.com/xpzouying/xiaohongshu-mcp>

Douyin

pip install douyin-mcp-server
# Start the HTTP server on port 18070, then:
mcporter config add douyin http://localhost:18070/mcp

No login needed.

LinkedIn (Chromium Required)

pip install linkedin-scraper-mcp
mcporter config add linkedin http://localhost:3000/mcp

Requires Chromium browser with UI (desktop) or VNC (server).

Xiaoyuzhou Podcasts (Groq API Key)

Free Groq account for Whisper speech-to-text:

1. Register at <https://console.groq.com> 2. Run: agent-reach configure groq-key gsk_xxxxx

Weibo (mcporter)

pip install git+https://github.com/Panniantong/mcp-server-weibo.git
mcporter config add weibo --command 'mcp-server-weibo'

Auto-Extract Browser Cookies

Extract cookies for all platforms from your browser in one command:

agent-reach configure --from-browser chrome
# Also supports: firefox, edge, brave, opera

<!-- # SSoT-OK — versions below refer to upstream third-party CLIs, not our packages -->

社交媒体 & 社区

小红书、抖音、Twitter/X、微博、B站、V2EX、Reddit。

小红书 / XiaoHongShu (xhs-cli)

稳定可用的命令

# 搜索笔记（推荐入口）
xhs search "query"

# 阅读笔记详情（必须用搜索结果中的 URL 或 ID，不能裸 note_id）
xhs read NOTE_ID_OR_URL

# 查看评论
xhs comments NOTE_ID_OR_URL

# 浏览热门
xhs hot

# 推荐 feed
xhs feed

已知不稳定的命令（v0.6.4）

# 以下命令当前可能返回 API error，谨慎使用：
xhs user USER_ID          # 可能返回 {code: -1}
xhs user-posts USER_ID    # 可能返回 {code: -1}
xhs favorites              # 可能返回 API error

重要注意事项

安装: pipx install xiaohongshu-cli，然后 xhs login（自动从浏览器提取 Cookie）。

>

xsec_token 限制: 小红书强制 xsec_token 机制，不能直接用裸 note_id 去读。正确流程是：先 xhs search 或 xhs feed 获取结果，再用结果中的 URL/ID 去 xhs read。直接构造 note_id 会被拦截。

>

频率控制: 高频请求（批量搜索、深翻评论）会触发验证码，这是平台限制无法绕过。建议每次操作间隔 2-3 秒。

>

POST 操作风险: 发帖(post)、评论(comment)、点赞(like) 等写操作在 v0.6.x 可能因签名问题返回 406。如需使用，建议降级到 v0.3.5 (pipx install xiaohongshu-cli==0.3.5)。

抖音 / Douyin

# 解析视频信息
mcporter call 'douyin.parse_douyin_video_info(share_link: "https://v.douyin.com/xxx/")'

# 获取无水印下载链接
mcporter call 'douyin.get_douyin_download_link(share_link: "https://v.douyin.com/xxx/")'

# 提取视频文案
mcporter call 'douyin.extract_douyin_text(share_link: "https://v.douyin.com/xxx/")'

无需登录

Twitter/X (twitter-cli)

稳定命令

# 首页时间线（最稳定）
twitter feed -n 20

# 读取单条推文（含回复）
twitter tweet URL_OR_ID

# 读取长文 / X Article
twitter article URL_OR_ID

# 用户时间线
twitter user-posts @username -n 20

# 用户资料
twitter user @username

可能不稳定的命令

# 搜索推文（Twitter 频繁改 GraphQL 端点，可能 404）
twitter search "query" -n 10
# 如果 search 返回 404，升级 twitter-cli：pipx upgrade twitter-cli

# likes（2024 年后只能看自己的，平台限制）
twitter likes

重要注意事项

安装: pipx install twitter-cli（确保 v0.8.5+）

>

认证: 推荐用 Cookie-Editor 导出后设置环境变量 TWITTER_AUTH_TOKEN + TWITTER_CT0。自动提取在 SSH/Docker/无头环境不可用。

>

IP 风控: 不要在 VPS/数据中心 IP 上频繁调用，尤其是 followers/following，有封号风险。使用住宅代理或本地环境。

>

search 可能失效: Twitter 频繁修改 GraphQL API，search 命令可能随时返回 404。如遇到，先 pipx upgrade twitter-cli。如果最新版仍不行，说明上游还没跟上 Twitter 的改动，用 twitter feed 替代。

>

输出格式: 建议用 --yaml 或 --json 获得结构化输出，对 AI agent 更友好。

微博 / Weibo

# 使用 Jina Reader 读取
curl -s "https://r.jina.ai/https://weibo.com/USER_ID/POST_ID"

微博主要通过网页抓取，推荐使用通用网页读取方式。

B站 / Bilibili

# 获取视频元数据
yt-dlp --dump-json "https://www.bilibili.com/video/BVxxx"

# 下载字幕
yt-dlp --write-sub --write-auto-sub --sub-lang "zh-Hans,zh,en" --convert-subs vtt --skip-download -o "/tmp/%(id)s" "URL"

注意: 服务器 IP 可能遇到 412 错误。使用 --cookies-from-browser chrome 或配置代理。

V2EX (公开 API)

无需认证，直接调用公开 API。

热门主题

curl -s "https://www.v2ex.com/api/topics/hot.json" -H "User-Agent: agent-reach/1.0"

节点主题

# node_name 如: python, tech, jobs, qna, programmers
curl -s "https://www.v2ex.com/api/topics/show.json?node_name=python&page=1" -H "User-Agent: agent-reach/1.0"

主题详情

# topic_id 从 URL 获取，如 https://www.v2ex.com/t/1234567
curl -s "https://www.v2ex.com/api/topics/show.json?id=TOPIC_ID" -H "User-Agent: agent-reach/1.0"

主题回复

curl -s "https://www.v2ex.com/api/replies/show.json?topic_id=TOPIC_ID&page=1" -H "User-Agent: agent-reach/1.0"

用户信息

curl -s "https://www.v2ex.com/api/members/show.json?username=USERNAME" -H "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']} 回复)")

# 获取节点帖子
node_topics = ch.get_node_topics("python", limit=5)

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

# 获取用户信息
user = ch.get_user("Livid")

节点列表: <https://www.v2ex.com/planes>

Reddit (rdt-cli)

# 搜索帖子
rdt search "query" --limit 10

# 读帖子全文 + 评论
rdt read POST_ID

# 浏览 subreddit
rdt sub python --limit 20

# 浏览热门
rdt popular --limit 10

# 浏览 /r/all
rdt all --limit 10

安装: pipx install rdt-cli（确保 v0.4.2+）。无需登录即可搜索和阅读。

需要登录的功能：rdt feed --subs-only（订阅列表）、rdt saved（收藏）。

建议使用 --yaml 输出，对 AI agent 更友好。

视频/播客

YouTube、B站、小宇宙播客的字幕和转录。

YouTube (yt-dlp)

获取视频元数据

yt-dlp --dump-json "URL"

下载字幕

# 下载字幕 (不下载视频)
yt-dlp --write-sub --write-auto-sub --sub-lang "zh-Hans,zh,en" --skip-download -o "/tmp/%(id)s" "URL"

# 然后读取 .vtt 文件
cat /tmp/VIDEO_ID.*.vtt

获取评论

# 提取评论（best-effort，不保证完整）
yt-dlp --write-comments --skip-download --write-info-json \
  --extractor-args "youtube:max_comments=20" \
  -o "/tmp/%(id)s" "URL"
# 评论在 .info.json 的 comments 字段中

搜索视频

yt-dlp --dump-json "ytsearch5:query"

字幕注意: 手动上传的字幕提取可靠；自动生成字幕可能存在行间重复，需后处理。

评论注意: --write-comments 基于网页抓取（非 YouTube Data API），部分评论可能丢失。

B站 / Bilibili (yt-dlp + bili-cli)

视频元数据 (yt-dlp)

yt-dlp --dump-json "https://www.bilibili.com/video/BVxxx"

字幕 (yt-dlp)

yt-dlp --write-sub --write-auto-sub --sub-lang "zh-Hans,zh,en" --convert-subs vtt --skip-download -o "/tmp/%(id)s" "URL"

搜索/热门/排行 (bili-cli)

# 搜索视频
bili search "query" --type video -n 5

# 热门视频
bili hot -n 10

# 排行榜
bili rank -n 10

412 风控: 海外 IP 必须提供 Cookie（--cookies-from-browser chrome 或 --cookies /path/to/cookies.txt），国内 IP 一般不受影响。

安装 bili-cli: pipx install bilibili-cli，然后 bili login 扫码登录。

小宇宙播客 / Xiaoyuzhou Podcast

转录单集播客

# 输出 Markdown 文件到 /tmp/
~/.agent-reach/tools/xiaoyuzhou/transcribe.sh "https://www.xiaoyuzhoufm.com/episode/EPISODE_ID"

前置要求

1. ffmpeg: brew install ffmpeg 2. Groq API Key (免费): <https://console.groq.com/keys> 3. 配置 Key: agent-reach configure groq-key YOUR_KEY 4. 首次运行: agent-reach install --env=auto 安装工具

检查状态

agent-reach doctor

输出 Markdown 文件默认保存到 /tmp/。

抖音视频解析

# 解析视频信息
mcporter call 'douyin.parse_douyin_video_info(share_link: "https://v.douyin.com/xxx/")'

# 获取无水印下载链接
mcporter call 'douyin.get_douyin_download_link(share_link: "https://v.douyin.com/xxx/")'

详见 social.md

选择指南

网页阅读

通用网页、微信公众号、RSS。

通用网页 (Jina Reader)

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

# 示例
curl -s "https://r.jina.ai/https://example.com/article"

适用场景: 大多数网页可以直接用 Jina Reader 读取。

Web Reader (MCP)

# 读取网页内容 (Markdown 格式)
mcporter call 'web-reader.webReader(url: "https://example.com")'

# 保留图片
mcporter call 'web-reader.webReader(url: "https://example.com", retain_images: true)'

# 纯文本格式
mcporter call 'web-reader.webReader(url: "https://example.com", return_format: "text")'

适用场景: 需要更精确控制输出格式时使用。

微信公众号 / WeChat Articles

搜索公众号文章（通过 Exa）

# 搜索微信公众号文章
mcporter call 'exa.web_search_exa(query: "搜索关键词", numResults: 5, includeDomains: ["mp.weixin.qq.com"])'

阅读公众号文章全文（通过 Exa）

# 抓取文章全文
mcporter call 'exa.crawling_exa(urls: ["https://mp.weixin.qq.com/s/ARTICLE_ID"], maxCharacters: 10000)'

可选：Camoufox 阅读（反爬更强）

cd ~/.agent-reach/tools/wechat-article-for-ai && python3 main.py "https://mp.weixin.qq.com/s/ARTICLE_ID"

注意: Jina Reader 无法读取微信文章（被 CAPTCHA 拦截），推荐用 Exa。

RSS (feedparser)

python3 -c "
import feedparser
for e in feedparser.parse('FEED_URL').entries[:5]:
    print(f'{e.title} — {e.link}')
"

适用场景: 订阅博客、新闻源、播客等 RSS feed。

选择指南