From 380cfd565db5711e3678556bd86e3b8e5fa51727 Mon Sep 17 00:00:00 2001 From: Pnant <73925474+Panniantong@users.noreply.github.com> Date: Thu, 11 Jun 2026 16:30:56 +0800 Subject: [PATCH] feat(identity): capability-layer positioning + skill rewrite, v1.5.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SKILL.md (per the skill-writing guide): - description rewritten trigger-first: 调研/全网调研/帮我调研/research lead the text (the owner's own phrasing "去全网调研" previously had NO matching trigger word — the exact undertrigger the guide warns about); platform keywords front-loaded against the 1536-char truncation - standing rules added: probe `doctor --json` active_backend before acting on multi-backend platforms, announce which skill/backend is in use, follow the documented retry chains, compose multi-platform research - quick commands updated to the new reality: bili-cli for bilibili search, Reddit/xiaohongshu moved to a "login-backed platforms" section - SKILL_en.md: same description surgery + the actively harmful stale advice removed (anonymous reddit .json curl, yt-dlp for bilibili) README / README_en: - tagline gains the capability-layer subline: backends are chosen, installed and health-checked for us to swap — the user never notices - "设计理念" reframed from scaffolding to capability layer (selection / install / doctor / routing); channels diagram now shows ordered backend lists; selection table split into primary + fallback columns with the live-test rationale per row - platform table: honest rows for bilibili (bili-cli, yt-dlp retired), Reddit (no zero-config path), xiaohongshu (OpenCLI / mcp / legacy) Version 1.5.0 across pyproject / __init__ / CLAUDE.md / test fixture. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 2 +- README.md | 72 +++++++++++++++--------------- agent_reach/__init__.py | 2 +- agent_reach/skill/SKILL.md | 70 +++++++++++++++++++----------- agent_reach/skill/SKILL_en.md | 59 ++++++++++++++++--------- docs/README_en.md | 82 ++++++++++++++++++----------------- pyproject.toml | 2 +- tests/test_cli.py | 2 +- 8 files changed, 165 insertions(+), 126 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 60d0aa9..ce2492f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,7 +3,7 @@ ## Project Agent Reach — Python CLI + library that gives AI agents read/search access to 13 internet platforms. Positioning: installer + doctor + config tool. NOT a wrapper — after install, agents call upstream tools directly. -Repo: github.com/Panniantong/Agent-Reach | License: MIT | Version: 1.4.2 +Repo: github.com/Panniantong/Agent-Reach | License: MIT | Version: 1.5.0 ## Commands - `pip install -e .` — Dev install diff --git a/README.md b/README.md index 072b2df..e5d7204 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,10 @@ 给你的 AI Agent 一键装上互联网能力

+

+ 当下最稳的接入方式，替你选好、装好、体检好——接入方式会换代，你不用操心 +

+

MIT License Python 3.10+ @@ -56,7 +60,7 @@ AI Agent 已经能帮你写代码、改文档、管项目——但你让它去 |---|---| | 💰 **完全免费** | 所有工具开源、所有 API 免费。唯一可能花钱的是服务器代理（$1/月），本地电脑不需要 | | 🔒 **隐私安全** | Cookie 只存在你本地，不上传不外传。代码完全开源，随时可审查 | -| 🔄 **持续更新** | 底层工具（yt-dlp、twitter-cli、rdt-cli、Jina Reader 等）定期追踪更新到最新版，你不用自己盯 | +| 🔄 **持续换代** | 每个平台都是「首选 + 备选」多后端路由。某个接入方式失效了，我们换下一个，你无感（2026-06 实例：yt-dlp 被 B站风控封死 → 已切换 bili-cli，用户零操作） | | 🤖 **兼容所有 Agent** | Claude Code、OpenClaw、Cursor、Windsurf……任何能跑命令行的 Agent 都能用 | | 🩺 **自带诊断** | `agent-reach doctor` 一条命令告诉你哪个通、哪个不通、怎么修 | @@ -72,9 +76,9 @@ AI Agent 已经能帮你写代码、改文档、管项目——但你让它去 | 🔍 **全网搜索** | — | 全网语义搜索 | 自动配置（MCP 接入，免费无需 Key） | | 📦 **GitHub** | 读公开仓库 + 搜索 | 私有仓库、提 Issue/PR、Fork | 告诉 Agent「帮我登录 GitHub」 | | 🐦 **Twitter/X** | 读单条推文 | 搜索推文、浏览时间线、发推 | 告诉 Agent「帮我配 Twitter」 | -| 📺 **B站** | 本地：字幕提取 + 搜索 | 服务器也能用 | 告诉 Agent「帮我配代理」 | -| 📖 **Reddit** | 搜索 + 读帖子和评论（通过 rdt-cli） | Cookie | 需要登录认证（`rdt login`），详见 [rdt-cli](https://github.com/public-clis/rdt-cli) | -| 📕 **小红书** | — | 阅读、搜索、发帖、评论、点赞 | 告诉 Agent「帮我配小红书」 | +| 📺 **B站** | 搜索 + 视频详情（bili-cli，无需登录） | 字幕（OpenCLI） | 告诉 Agent「帮我配 B站」 | +| 📖 **Reddit** | —（没有零配置路径：匿名接口已被封） | 搜索 + 读帖子和评论 | 桌面装 OpenCLI 用浏览器登录态；或 rdt-cli + Cookie | +| 📕 **小红书** | — | 搜索、阅读、评论 | 桌面装 OpenCLI（刷过小红书即可用）；服务器用 xiaohongshu-mcp 扫码 | | 💼 **LinkedIn** | Jina Reader 读公开页面 | Profile 详情、公司页面、职位搜索 | 告诉 Agent「帮我配 LinkedIn」 | | 💻 **V2EX** | 热门帖子、节点帖子、帖子详情+回复、用户信息 | — | 无需配置 | | 📈 **雪球** | 股票行情、搜索股票、热门帖子、热门股票排行 | — | 告诉 Agent「帮我配雪球」 | @@ -151,51 +155,49 @@ AI Agent 已经能帮你写代码、改文档、管项目——但你让它去 ## 设计理念 -**Agent Reach 是一个脚手架（scaffolding），不是框架。** +**Agent Reach 是一个能力层（capability layer），不是又一个工具。** -你给一个新 Agent 装环境的时候，总要花时间去找工具、装依赖、调配置——Twitter 用什么读？Reddit 怎么绕封？YouTube 字幕怎么提取？每次都要重新踩一遍。 +它比任何具体实现高一层——负责**选型、安装、体检、路由**，不负责底层读取本身。读取由 Agent 直接调用上游工具完成，没有包装层。 -Agent Reach 做的事情很简单：**帮你把这些选型和配置的活儿做完了。** +你给一个新 Agent 装环境的时候，总要花时间去找工具、装依赖、调配置——Twitter 用什么读？Reddit 怎么登录？小红书的 CLI 停更了换什么？每次都要重新踩一遍。Agent Reach 做的事情很简单：**当下最稳的接入方式，我们替你选好、装好、体检好。接入方式会换代（2026 年 3 月一批单平台 CLI 集体停更，我们换了路由），你不用操心。** -安装完成后，Agent 直接调用上游工具（twitter-cli、rdt-cli、xhs-cli、yt-dlp、mcporter、gh CLI 等），不需要经过 Agent Reach 的包装层。 +### 🔌 每个平台 = 首选 + 备选的有序后端列表 -### 🔌 每个渠道都是可插拔的 - -每个平台背后是一个独立的上游工具。**不满意？换掉就行。** +换接入方式 = 调整列表顺序，不是重写代码。`agent-reach doctor` 会告诉你每个平台**当前在用哪个后端**。 ``` channels/ -├── web.py → Jina Reader ← 可以换成 Firecrawl、Crawl4AI…… -├── twitter.py → twitter-cli ← 可以换成官方 API…… -├── youtube.py → yt-dlp ← 可以换成 YouTube API、Whisper…… -├── github.py → gh CLI ← 可以换成 REST API、PyGithub…… -├── bilibili.py → yt-dlp ← 可以换成 bilibili-api…… -├── reddit.py → rdt-cli ← 搜索+阅读，需 Cookie 认证 -├── xiaohongshu.py → mcporter MCP ← 可以换成其他 XHS 工具…… -├── linkedin.py → linkedin-mcp ← 可以换成 LinkedIn API…… -├── rss.py → feedparser ← 可以换成 atoma…… -├── exa_search.py → mcporter MCP ← 可以换成 Tavily、SerpAPI…… +├── web.py → Jina Reader +├── twitter.py → twitter-cli ▸ OpenCLI ▸ bird +├── youtube.py → yt-dlp +├── github.py → gh CLI +├── bilibili.py → bili-cli ▸ OpenCLI ▸ 搜索 API（yt-dlp 已被 B站风控封死，退役） +├── reddit.py → OpenCLI ▸ rdt-cli（无零配置路径，必须登录态） +├── xiaohongshu.py → OpenCLI ▸ xiaohongshu-mcp ▸ xhs-cli +├── linkedin.py → linkedin-mcp ▸ Jina Reader +├── rss.py → feedparser +├── exa_search.py → Exa via mcporter └── __init__.py → 渠道注册（doctor 检测用） ``` -每个渠道文件只负责检测对应上游工具是否可用（`check()` 方法），给 `agent-reach doctor` 提供状态信息。实际的读取和搜索由 Agent 直接调用上游工具完成。 +每个渠道文件按序**真实探测**各候选后端（不只是看命令存不存在），第一个完整可用的当选；坏掉的会给出修复处方。实际的读取和搜索由 Agent 直接调用上游工具完成。 ### 当前选型 -| 场景 | 选型 | 为什么选它 | -|------|------|-----------| -| 读网页 | [Jina Reader](https://github.com/jina-ai/reader) | 9.8K Star，免费，不需要 API Key | -| 读推特 | [twitter-cli](https://github.com/public-clis/twitter-cli) | 2.1K Star，Cookie 登录，搜索/读推文/时间线/长文 | -| Reddit | [rdt-cli](https://github.com/public-clis/rdt-cli) | 304 Star，Cookie 认证，搜索+全文+评论 | -| 视频字幕 + 搜索 | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | 154K Star，YouTube + B站 + 1800 站通吃 | -| B站增强 | [bili-cli](https://github.com/public-clis/bilibili-cli) | 590 Star，热门/排行/搜索/动态 | -| 搜全网 | [Exa](https://exa.ai) via [mcporter](https://github.com/nicobailon/mcporter) | AI 语义搜索，MCP 接入免 Key | -| GitHub | [gh CLI](https://cli.github.com) | 官方工具，认证后完整 API 能力 | -| 读 RSS | [feedparser](https://github.com/kurtmckee/feedparser) | Python 生态标准选择，2.3K Star | -| 小红书 | [xhs-cli](https://github.com/jackwener/xiaohongshu-cli) | 1.5K Star，pipx 一行安装，搜索/阅读/评论/发帖 | -| LinkedIn | [linkedin-scraper-mcp](https://github.com/stickerdaniel/linkedin-mcp-server) | ⭐1.2K，MCP 服务，浏览器自动化 | +| 场景 | 首选 | 备选 | 为什么这么选 | +|------|------|------|-----------| +| 读网页 | [Jina Reader](https://github.com/jina-ai/reader) | — | 免费，不需要 API Key | +| 读推特 | [twitter-cli](https://github.com/public-clis/twitter-cli) | [OpenCLI](https://github.com/jackwener/opencli) | 实测搜索稳定；OpenCLI 走浏览器登录态兜底 | +| Reddit | [OpenCLI](https://github.com/jackwener/opencli)（桌面） | [rdt-cli](https://github.com/public-clis/rdt-cli) | 匿名接口已被封、官方 API 审批制——只剩登录态路线 | +| YouTube 字幕 + 搜索 | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | — | 154K Star，YouTube 仍是最佳（注意：不再用于 B站） | +| B站 | [bili-cli](https://github.com/public-clis/bilibili-cli) | OpenCLI ▸ 搜索 API | yt-dlp 被 B站风控 412 封死（2026-06 实测），bili-cli 无登录可搜可读 | +| 搜全网 | [Exa](https://exa.ai) via [mcporter](https://github.com/nicobailon/mcporter) | — | AI 语义搜索，MCP 接入免 Key | +| GitHub | [gh CLI](https://cli.github.com) | — | 官方工具，认证后完整 API 能力 | +| 读 RSS | [feedparser](https://github.com/kurtmckee/feedparser) | — | Python 生态标准选择 | +| 小红书 | [OpenCLI](https://github.com/jackwener/opencli)（桌面） | [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)（服务器）▸ xhs-cli | xhs-cli 作者已转投 OpenCLI（24K Star）；浏览器登录态零摩擦 | +| LinkedIn | [linkedin-scraper-mcp](https://github.com/stickerdaniel/linkedin-mcp-server) | Jina Reader | MCP 服务，浏览器自动化 | -> 📌 这些都是「当前选型」。不满意？换掉对应文件就行。这正是脚手架的意义。 +> 📌 这些都是「当前选型」，基于真机实测定期复核。某条路失效了我们换下一条——`agent-reach doctor` 永远告诉你现在走的是哪条。 --- diff --git a/agent_reach/__init__.py b/agent_reach/__init__.py index ce3a33b..f60634a 100644 --- a/agent_reach/__init__.py +++ b/agent_reach/__init__.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- """Agent Reach — Give your AI Agent eyes to see the entire internet.""" -__version__ = "1.4.2" +__version__ = "1.5.0" __author__ = "Neo Reid" from agent_reach.core import AgentReach diff --git a/agent_reach/skill/SKILL.md b/agent_reach/skill/SKILL.md index e6c0c82..24e4912 100644 --- a/agent_reach/skill/SKILL.md +++ b/agent_reach/skill/SKILL.md @@ -1,19 +1,24 @@ --- name: agent-reach description: > - MUST USE when user asks to search, browse, read, or interact with content from any of these platforms: - 小红书/xiaohongshu/xhs, Twitter/推特/X, B站/bilibili, - V2EX, Reddit, LinkedIn/领英, YouTube, GitHub code search, - 小宇宙播客, 雪球/股票行情, RSS feeds, or any web URL. + MUST USE when user wants to 调研/research/搜索/search/查/找/look up anything + on the internet — e.g. 全网调研 X / 帮我调研一下 X / 查一下 X / 搜搜 X / + 看看大家怎么评价 X / X 上有什么讨论 / research this topic。 - Also MUST USE for: web搜索/搜/查/找/look up/research, 招聘/求职/jobs, 分享的链接/URL. - Routes to CLI tools: xhs-cli, twitter-cli, rdt-cli, gh, yt-dlp, curl+Jina, mcporter. - 13 platforms. Zero config for 6 channels. + Also MUST USE when user mentions any platform or shares any URL/链接: + 小红书/xiaohongshu/xhs, Twitter/推特/X, B站/bilibili, Reddit, V2EX, + LinkedIn/领英/招聘/求职/jobs, YouTube, GitHub code search, 小宇宙播客, + 雪球/股票行情, RSS feeds, or any web URL. + + 13 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. 【路由方式】SKILL.md 包含路由表和常用命令，复杂场景需按需阅读对应分类的 references/*.md。 分类：search / social (小红书/推特/B站/V2EX/Reddit) / career(LinkedIn) / dev(github) / web(网页/文章/RSS) / video(YouTube/B站/播客)。 triggers: - - search: 搜/查/找/search/搜索/查一下/帮我搜 + - research: 调研/全网调研/帮我调研/研究一下/research/深入了解 + - search: 搜/查/找/search/搜索/查一下/帮我搜/看看大家怎么说 - social: - 小红书: xiaohongshu/xhs/小红书/红书 - Twitter: twitter/推特/x.com/推文 @@ -30,9 +35,17 @@ metadata: homepage: https://github.com/Panniantong/Agent-Reach --- -# Agent Reach — 路由器 +# Agent Reach — 互联网能力路由器 -13 平台工具集合。根据用户意图选择对应分类。 +13 平台、多后端。**本 skill 存在时必须用它访问这些平台，不要自己发明方案。** + +## 常驻规则（全程适用） + +1. **动手前先体检**：多后端平台（小红书/Reddit/B站/Twitter）先跑 + `agent-reach doctor --json`，按各平台 `active_backend` 字段选命令组。 +2. **声明你在用什么**：开始干活前说一句「使用 agent-reach 的 X 平台 / Y 后端」。 +3. **失败按 references 里的重试链处理**，不要瞎猜命令。 +4. **全网调研类任务**：组合多平台（Exa 搜索 + Twitter/Reddit 看讨论 + 小红书/B站看中文场景），并行收集再汇总。 ## 路由表 @@ -57,30 +70,35 @@ curl -s "https://r.jina.ai/URL" # GitHub 搜索 gh search repos "query" --sort stars --limit 10 -# Twitter 搜索 -twitter search "query" -n 10 - -# YouTube/B站字幕 +# YouTube 字幕（注意：B站不要用 yt-dlp，见 video.md） yt-dlp --write-sub --skip-download -o "/tmp/%(id)s" "URL" -# Reddit 搜索 -rdt search "query" --limit 10 - -# Reddit 读帖 + 评论 -rdt read POST_ID - # 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 +``` + +## 需登录态的平台（按 doctor 的 active_backend 选命令） + +```bash +# 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 ``` ## 环境检查 ```bash -# 检查可用 channel -agent-reach doctor - -# 查看所有 MCP 服务 -mcporter_list_servers() +# 检查可用 channel 与每个平台当前激活的后端 +agent-reach doctor --json ``` ## 工作区规则 @@ -92,7 +110,7 @@ mcporter_list_servers() 根据用户需求，阅读对应的详细文档： - [搜索工具](references/search.md) — Exa AI 搜索 -- [社交媒体](references/social.md) — 小红书, Twitter, B站, V2EX, Reddit +- [社交媒体](references/social.md) — 小红书, Twitter, B站, V2EX, Reddit（多后端命令组） - [职场招聘](references/career.md) — LinkedIn - [开发工具](references/dev.md) — GitHub CLI - [网页阅读](references/web.md) — Jina Reader, RSS diff --git a/agent_reach/skill/SKILL_en.md b/agent_reach/skill/SKILL_en.md index 5768d78..2f533c7 100644 --- a/agent_reach/skill/SKILL_en.md +++ b/agent_reach/skill/SKILL_en.md @@ -1,16 +1,20 @@ --- name: agent-reach description: > - MUST USE when user asks to search, browse, read, or interact with content from any supported platform: + 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, YouTube, GitHub, Bilibili, XiaoHongShu, - Xiaoyuzhou Podcast, LinkedIn, V2EX, Xueqiu (stocks), RSS, or any web URL. + Xiaoyuzhou Podcast, LinkedIn/jobs/recruiting, V2EX, Xueqiu (stocks), RSS. - Also MUST USE for: web search, look up, research, find, share a URL/link, jobs/recruiting. - Routes to CLI tools: xhs-cli, twitter-cli, rdt-cli, gh, yt-dlp, curl+Jina, mcporter. - 13 platforms, zero config for 6 channels. + 13 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. - Triggers: "search twitter", "search xiaohongshu", "watch this video", - "search the web", "look this up", "research", "youtube transcript", + Triggers: "research", "deep dive", "search twitter", "search xiaohongshu", + "watch this video", "search the web", "look this up", "youtube transcript", "search reddit", "read this link", "bilibili", "V2EX", "xiaoyuzhou", "podcast", "xueqiu", "stock quote", "雪球", "股票". metadata: @@ -62,24 +66,30 @@ yt-dlp --write-sub --write-auto-sub --sub-lang "zh-Hans,zh,en" --skip-download - yt-dlp --dump-json "ytsearch5:query" # search ``` -## Bilibili (yt-dlp) +## Bilibili (bili-cli / OpenCLI) + +> ⚠️ Do NOT use yt-dlp for bilibili — its risk control 412-blocks yt-dlp in +> every configuration (verified 2026-06). yt-dlp is for YouTube only. ```bash -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" +bili video BVxxx # video detail, no login needed +bili search "query" --type video -n 5 # search +bili hot -n 10 # trending +opencli bilibili subtitle BVxxx # subtitles (desktop Chrome) ``` -> Server IPs may get 412. Use `--cookies-from-browser chrome` or configure a proxy. +## Reddit (login required — no zero-config path) -## Reddit +> Anonymous .json endpoints are 403-blocked and official API registration is +> approval-gated (2025-11). Every backend needs a logged-in session. +> Check `agent-reach doctor --json` for the active backend. ```bash -curl -s "https://www.reddit.com/r/SUBREDDIT/hot.json?limit=10" -H "User-Agent: agent-reach/1.0" -curl -s "https://www.reddit.com/search.json?q=QUERY&limit=10" -H "User-Agent: agent-reach/1.0" +opencli reddit search "query" -f yaml # desktop, browser session +rdt search "query" --limit 10 # legacy/server, cookie login +rdt read POST_ID # post + comments ``` -> Server IPs may get 403. Search via Exa instead, or configure a proxy. - ## GitHub (gh CLI) ```bash @@ -90,13 +100,20 @@ gh issue list -R owner/repo --state open gh issue view 123 -R owner/repo ``` -## XiaoHongShu (mcporter) +## XiaoHongShu (multi-backend — check doctor for active backend) ```bash -mcporter call 'xiaohongshu.search_feeds(keyword: "query")' -mcporter call 'xiaohongshu.get_feed_detail(feed_id: "xxx", xsec_token: "yyy")' -mcporter call 'xiaohongshu.get_feed_detail(feed_id: "xxx", xsec_token: "yyy", load_all_comments: true)' -mcporter call 'xiaohongshu.publish_content(title: "Title", content: "Body text", images: ["/path/img.jpg"], tags: ["tag"])' +# Desktop preferred: OpenCLI (reuses browser session, zero config) +opencli xiaohongshu search "query" -f yaml +opencli xiaohongshu note "NOTE_URL" -f yaml + +# Server: xiaohongshu-mcp via mcporter (QR login; always pass --timeout 120000) +mcporter call 'xiaohongshu.search_feeds(keyword: "query")' --timeout 120000 +mcporter call 'xiaohongshu.get_feed_detail(feed_id: "xxx", xsec_token: "yyy")' --timeout 120000 + +# Legacy fallback: xhs-cli (upstream unmaintained since 2026-03) +xhs search "query" +xhs read NOTE_ID_OR_URL ``` > Requires login. Use Cookie-Editor to import cookies. diff --git a/docs/README_en.md b/docs/README_en.md index b669f2a..f87b513 100644 --- a/docs/README_en.md +++ b/docs/README_en.md @@ -4,6 +4,10 @@ Give your AI Agent one-click access to the entire internet

+

+ The most reliable access path for each platform — chosen, installed, and health-checked for you. Backends come and go; you won't notice. +

+

MIT License Python 3.10+ @@ -51,7 +55,7 @@ Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/ma |---|---| | 💰 **Completely free** | All tools are open source, all APIs are free. The only possible cost is a server proxy ($1/month) — local computers don't need one | | 🔒 **Privacy safe** | Cookies stay local. Never uploaded. Fully open source — audit anytime | -| 🔄 **Kept up to date** | Upstream tools (yt-dlp, twitter-cli, rdt-cli, Jina Reader, etc.) are tracked and updated regularly | +| 🔄 **Kept up to date** | Every platform routes through a primary + fallback backend list. When an access path dies, we switch to the next — you won't notice (June 2026: Bilibili 412-blocked yt-dlp → switched to bili-cli, zero action on your side) | | 🤖 **Works with any Agent** | Claude Code, OpenClaw, Cursor, Windsurf… any Agent that can run commands | | 🩺 **Built-in diagnostics** | `agent-reach doctor` — one command shows what works, what doesn't, and how to fix it | @@ -63,7 +67,7 @@ Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/ma |----------|-------------|:-----:|-------| | 🌐 **Web** | Read | Zero config | Any URL → clean Markdown ([Jina Reader](https://github.com/jina-ai/reader) ⭐9.8K) | | 🐦 **Twitter/X** | Read · Search | Cookie | Cookie unlocks search, timeline, tweet reading, articles ([twitter-cli](https://github.com/public-clis/twitter-cli)) | -| 📕 **XiaoHongShu** | Read · Search · **Post · Comment · Like** | Cookie | `pipx install xiaohongshu-cli` + `xhs login` ([xhs-cli](https://github.com/jackwener/xiaohongshu-cli)) | +| 📕 **XiaoHongShu** | Read · Search · **Post · Comment · Like** | OpenCLI / MCP | Desktop: [OpenCLI](https://github.com/jackwener/opencli) (reuses browser session); Server: [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) (QR login); legacy xhs-cli still works | | 💼 **LinkedIn** | Jina Reader (public pages) | Full profiles, companies, job search | Tell your Agent "help me set up LinkedIn" | | 💻 **V2EX** | Hot topics · Node topics · Topic detail + replies · User profile | Zero config | Public JSON API, no auth required. Great for tech community content | | 📈 **Xueqiu (雪球)** | Stock quotes · Search · Hot posts · Hot stocks | Browser cookie | Tell your Agent "help me set up Xueqiu" | @@ -71,9 +75,9 @@ Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/ma | 🔍 **Web Search** | Search | Auto-configured | Auto-configured during install, free, no API key ([Exa](https://exa.ai) via [mcporter](https://github.com/nicepkg/mcporter)) | | 📦 **GitHub** | Read · Search | Zero config | [gh CLI](https://cli.github.com) powered. Public repos work immediately. `gh auth login` unlocks Fork, Issue, PR | | 📺 **YouTube** | Read · **Search** | Zero config | Subtitles + search across 1800+ video sites ([yt-dlp](https://github.com/yt-dlp/yt-dlp) ⭐148K) | -| 📺 **Bilibili** | Read · **Search** | Zero config / Proxy | Video info + subtitles + search. Local works directly, servers need a proxy ([yt-dlp](https://github.com/yt-dlp/yt-dlp)) | +| 📺 **Bilibili** | Read · **Search** | Zero config | Search + video detail via [bili-cli](https://github.com/public-clis/bilibili-cli) (no login needed); subtitles via [OpenCLI](https://github.com/jackwener/opencli). yt-dlp is 412-blocked by Bilibili and no longer used here | | 📡 **RSS** | Read | Zero config | Any RSS/Atom feed ([feedparser](https://github.com/kurtmckee/feedparser) ⭐2.3K) | -| 📖 **Reddit** | Search · Read | Cookie | Requires auth since 2024 — `rdt login` after install ([rdt-cli](https://github.com/public-clis/rdt-cli)) | +| 📖 **Reddit** | Search · Read | OpenCLI / Cookie | No zero-config path (anonymous endpoints blocked). Desktop: [OpenCLI](https://github.com/jackwener/opencli) via browser session; or [rdt-cli](https://github.com/public-clis/rdt-cli) + cookie | > **Setup levels:** Zero config = install and go · Auto-configured = handled during install · mcporter = needs MCP service · Cookie = export from browser · Proxy = $1/month @@ -164,7 +168,7 @@ Tell your Agent "help me configure Twitter cookies" — it'll guide you through Bilibili blocks server IPs. Get a proxy ([Webshare](https://webshare.io) recommended, $1/month) and send the address to your Agent. -> Reddit now works free via rdt-cli without any proxy. Local computers don't need a proxy for Bilibili either. +> Reddit needs a logged-in session — rdt-cli works after `rdt login` (still free, no proxy needed). Local computers don't need a proxy for Bilibili either. --- @@ -188,7 +192,7 @@ $ agent-reach doctor ⬜ Web semantic search — sign up at exa.ai for free key 🔧 Configurable: - ✅ Reddit posts and comments — search and read via rdt-cli (free, no proxy) + ⬜ Reddit posts and comments — needs login: rdt-cli after `rdt login`, or OpenCLI browser session ⬜ XiaoHongShu notes — needs cookie. Export from browser Status: 6/9 channels available @@ -198,52 +202,50 @@ Status: 6/9 channels available ## Design Philosophy -**Agent Reach is a scaffolding tool, not a framework.** +**Agent Reach is a capability layer, not yet another tool.** -Every time you spin up a new Agent, you spend time finding tools, installing deps, and debugging configs — what reads Twitter? How do you bypass Reddit blocks? How do you extract YouTube subtitles? Every time, you re-do the same work. +It sits one level above any specific implementation — it handles **selection, installation, health checks, and routing**, not the reading itself. Reading is done by your Agent calling upstream tools directly; there is no wrapper layer. -Agent Reach does one simple thing: **it makes those tool selection and configuration decisions for you.** +Every time you spin up a new Agent, you spend time finding tools, installing deps, and debugging configs — what reads Twitter? How do you log into Reddit? What replaces a discontinued XiaoHongShu CLI? Every time, you re-do the same work. Agent Reach does one simple thing: **the most reliable access path for each platform, chosen, installed, and health-checked for you. Access paths come and go (in March 2026 a batch of single-platform CLIs went unmaintained — we re-routed), so you don't have to care.** -After installation, your Agent calls the upstream tools directly (twitter-cli, rdt-cli, xhs-cli, yt-dlp, mcporter, gh CLI, etc.) — no wrapper layer in between. +### 🔌 Every platform = an ordered backend list (primary + fallbacks) -### 🔌 Every Channel is Pluggable - -Each platform maps to an upstream tool. **Don't like one? Swap it out.** +Switching access paths means reordering the list, not rewriting code. `agent-reach doctor` tells you **which backend each platform is currently using**. ``` channels/ -├── web.py → Jina Reader ← swap to Firecrawl, Crawl4AI… -├── twitter.py → twitter-cli ← swap to official API… -├── youtube.py → yt-dlp ← swap to YouTube API, Whisper… -├── github.py → gh CLI ← swap to REST API, PyGithub… -├── bilibili.py → yt-dlp ← swap to bilibili-api… -├── reddit.py → rdt-cli ← search + read, cookie auth required -├── xiaohongshu.py → mcporter MCP ← swap to other XHS tools… -├── linkedin.py → linkedin-mcp ← swap to LinkedIn API… -├── rss.py → feedparser ← swap to atoma… -├── exa_search.py → mcporter MCP ← swap to Tavily, SerpAPI… +├── web.py → Jina Reader +├── twitter.py → twitter-cli ▸ OpenCLI ▸ bird +├── youtube.py → yt-dlp +├── github.py → gh CLI +├── bilibili.py → bili-cli ▸ OpenCLI ▸ search API (yt-dlp retired, 412-blocked) +├── reddit.py → OpenCLI ▸ rdt-cli (no zero-config path, login required) +├── xiaohongshu.py → OpenCLI ▸ xiaohongshu-mcp ▸ xhs-cli +├── linkedin.py → linkedin-mcp ▸ Jina Reader +├── rss.py → feedparser +├── exa_search.py → Exa via mcporter └── __init__.py → Channel registry (for doctor checks) ``` -Each channel file only checks whether its upstream tool is installed and working (`check()` method for `agent-reach doctor`). The actual reading and searching is done by calling the upstream tools directly. +Each channel file **actually probes** its candidate backends in order (not just checking that a command exists) — the first fully working one becomes the active backend, and broken ones come with a fix prescription. The actual reading and searching is done by the Agent calling the upstream tools directly. ### Current Tool Choices -| Scenario | Tool | Why | -|----------|------|-----| -| Read web pages | [Jina Reader](https://github.com/jina-ai/reader) | 9.8K stars, free, no API key needed | -| Read tweets | [twitter-cli](https://github.com/public-clis/twitter-cli) | 2.1K stars, cookie auth, search/read/timeline/articles | -| Reddit | [rdt-cli](https://github.com/public-clis/rdt-cli) | 304 stars, cookie auth, search + full posts + comments | -| Video subtitles + search | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | 154K stars, YouTube + Bilibili + 1800 sites | -| Bilibili enhanced | [bili-cli](https://github.com/public-clis/bilibili-cli) | 590 stars, hot/rank/search/feed | -| Search the web | [Exa](https://exa.ai) via [mcporter](https://github.com/nicobailon/mcporter) | AI semantic search, MCP integration, no API key | -| GitHub | [gh CLI](https://cli.github.com) | Official tool, full API after auth | -| Read RSS | [feedparser](https://github.com/kurtmckee/feedparser) | Python ecosystem standard, 2.3K stars | -| XiaoHongShu | [xhs-cli](https://github.com/jackwener/xiaohongshu-cli) | 1.5K stars, pipx install, search/read/comment/post | -| LinkedIn | [linkedin-scraper-mcp](https://github.com/stickerdaniel/linkedin-mcp-server) | 1.2K stars, MCP server, browser automation | -| Xiaoyuzhou Podcast | `transcribe.sh` | `bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh ` | +| Scenario | Primary | Fallback | Why | +|----------|---------|----------|-----| +| Read web pages | [Jina Reader](https://github.com/jina-ai/reader) | — | Free, no API key needed | +| Read tweets | [twitter-cli](https://github.com/public-clis/twitter-cli) | [OpenCLI](https://github.com/jackwener/opencli) | Reliable search in real-world tests; OpenCLI falls back on your browser session | +| Reddit | [OpenCLI](https://github.com/jackwener/opencli) (desktop) | [rdt-cli](https://github.com/public-clis/rdt-cli) | Anonymous endpoints blocked, official API gated — logged-in sessions are the only route left | +| YouTube subtitles + search | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | — | 154K stars, still the best for YouTube (no longer used for Bilibili) | +| Bilibili | [bili-cli](https://github.com/public-clis/bilibili-cli) | OpenCLI ▸ search API | yt-dlp is 412-blocked by Bilibili (verified June 2026); bili-cli searches and reads without login | +| Search the web | [Exa](https://exa.ai) via [mcporter](https://github.com/nicobailon/mcporter) | — | AI semantic search, MCP integration, no API key | +| GitHub | [gh CLI](https://cli.github.com) | — | Official tool, full API after auth | +| Read RSS | [feedparser](https://github.com/kurtmckee/feedparser) | — | Python ecosystem standard | +| XiaoHongShu | [OpenCLI](https://github.com/jackwener/opencli) (desktop) | [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) (server) ▸ xhs-cli | The xhs-cli author moved to OpenCLI (24K stars); browser sessions mean zero friction | +| LinkedIn | [linkedin-scraper-mcp](https://github.com/stickerdaniel/linkedin-mcp-server) | Jina Reader | MCP server, browser automation | +| Xiaoyuzhou Podcast | `transcribe.sh` | — | `bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh ` | -> 📌 These are the *current* choices. Don't like one? Swap out the file. That's the whole point of scaffolding. +> 📌 These are the *current* choices, re-verified regularly on real machines. When a path dies we switch to the next — `agent-reach doctor` always tells you which one is active. --- @@ -276,7 +278,7 @@ Agent Reach uses [twitter-cli](https://github.com/public-clis/twitter-cli) with

Reddit returns 403 from server / datacenter IP blocked? -Agent Reach uses [rdt-cli](https://github.com/public-clis/rdt-cli) for Reddit. Since 2024, Reddit requires authentication for all API requests. Install with `pipx install rdt-cli`, then run `rdt login` (auto-extracts cookies from your browser). Your agent can then search with `rdt search "query"` and read full posts + comments with `rdt read POST_ID`. +Reddit requires a logged-in session for everything (anonymous endpoints are blocked, and official API registration has been approval-gated since 2025-11). On desktop, the preferred path is OpenCLI riding your browser's reddit.com session. Otherwise install rdt-cli from the pinned git source (`pipx install 'git+https://github.com/public-clis/rdt-cli.git'` — PyPI lags), then `rdt login`. Your agent can then search with `rdt search "query"` and read full posts + comments with `rdt read POST_ID`.
@@ -288,7 +290,7 @@ Yes! Agent Reach is an installer + configuration tool. Any AI coding agent that
Is Agent Reach free? Any API costs? -100% free and open source. All backends (twitter-cli, rdt-cli, xhs-cli, yt-dlp, Jina Reader, Exa) are free tools that don't require paid API keys. The only optional cost is a residential proxy (~$1/month) if you need Bilibili access from a server. Reddit works free via rdt-cli without any proxy. +100% free and open source. All backends (twitter-cli, rdt-cli, xhs-cli, yt-dlp, Jina Reader, Exa) are free tools that don't require paid API keys. The only optional cost is a residential proxy (~$1/month) for some server scenarios. Reddit costs nothing but needs a logged-in session (rdt-cli after `rdt login`, or OpenCLI reusing your browser session).
diff --git a/pyproject.toml b/pyproject.toml index 1826345..12c769a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "agent-reach" -version = "1.4.2" +version = "1.5.0" description = "Give your AI Agent eyes to see the entire internet. Search + Read 10+ platforms." readme = "README.md" license = {text = "MIT"} diff --git a/tests/test_cli.py b/tests/test_cli.py index bb8c71e..b99b059 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -148,7 +148,7 @@ class TestCheckUpdateRetry: sequence = [ R(429, headers={"Retry-After": "3"}), - R(200, payload={"tag_name": "v1.4.2"}), + R(200, payload={"tag_name": "v1.5.0"}), ] with patch("requests.get", side_effect=sequence):