From 80a08c8c105c514389b7dfa759a4dfe4746e222d Mon Sep 17 00:00:00 2001 From: Panniantong Date: Thu, 26 Feb 2026 08:25:06 +0100 Subject: [PATCH] docs: update all remaining references to use upstream tools directly - docs/README_en.md: update FAQ, Works Out of the Box, Design Philosophy - docs/troubleshooting.md: Exa fallback uses mcporter directly - agent_reach/guides/setup-exa.md: test with mcporter call - agent_reach/guides/setup-wechat.md: test with Jina Reader --- README.md | 16 +++++++------ agent_reach/guides/setup-exa.md | 4 ++-- agent_reach/guides/setup-wechat.md | 2 +- docs/README_en.md | 38 +++++++++++++++++------------- docs/troubleshooting.md | 5 ++-- 5 files changed, 35 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index cf322a0..85c115e 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@

- 快速开始 · English · 支持平台 · 设计理念 + 快速开始 · English · 支持平台 · 设计理念

--- @@ -104,7 +104,7 @@ AI Agent 已经能帮你写代码、改文档、管项目——但你让它去 2. **安装系统依赖** — 自动检测并安装 Node.js、gh CLI、mcporter、bird 等 3. **配置搜索引擎** — 通过 MCP 接入 Exa（免费，无需 API Key） 4. **检测环境** — 判断是本地电脑还是服务器，给出对应的配置建议 -5. **注册 Skill** — 在 Agent 的 skills 目录安装 SKILL.md，以后 Agent 遇到"搜推特"、"看视频"这类需求，会自动知道调用 Agent Reach +5. **注册 SKILL.md** — 在 Agent 的 skills 目录安装使用指南，以后 Agent 遇到"搜推特"、"看视频"这类需求，会自动知道该调哪个上游工具 安装完之后，`agent-reach doctor` 一条命令告诉你每个渠道的状态。 @@ -143,19 +143,21 @@ Agent Reach 做的事情很简单：**帮你把这些选型和配置的活儿做 ``` channels/ ├── web.py → Jina Reader ← 可以换成 Firecrawl、Crawl4AI…… -├── twitter.py → bird ← 可以换成 Nitter、官方 API…… -├── youtube.py → yt-dlp ← 可以换成 YouTube API、Whisper…… +├── twitter.py → bird ← 可以换成 Nitter、官方 API…… +├── youtube.py → yt-dlp ← 可以换成 YouTube API、Whisper…… ├── github.py → gh CLI ← 可以换成 REST API、PyGithub…… -├── bilibili.py → yt-dlp ← 可以换成 bilibili-api…… +├── bilibili.py → yt-dlp ← 可以换成 bilibili-api…… ├── reddit.py → JSON API + Exa ← 可以换成 PRAW、Pushshift…… ├── xiaohongshu.py → mcporter MCP ← 可以换成其他 XHS 工具…… ├── linkedin.py → linkedin-mcp ← 可以换成 LinkedIn API…… ├── bosszhipin.py → mcp-bosszp ← 可以换成其他招聘工具…… -├── rss.py → feedparser ← 可以换成 atoma…… +├── rss.py → feedparser ← 可以换成 atoma…… ├── exa_search.py → mcporter MCP ← 可以换成 Tavily、SerpAPI…… -└── __init__.py → 渠道注册 +└── __init__.py → 渠道注册（doctor 检测用） ``` +每个渠道文件只负责检测对应上游工具是否可用（`check()` 方法），给 `agent-reach doctor` 提供状态信息。实际的读取和搜索由 Agent 直接调用上游工具完成。 + ### 当前选型 | 场景 | 选型 | 为什么选它 | diff --git a/agent_reach/guides/setup-exa.md b/agent_reach/guides/setup-exa.md index c0349d5..2d027ed 100644 --- a/agent_reach/guides/setup-exa.md +++ b/agent_reach/guides/setup-exa.md @@ -22,8 +22,8 @@ mcporter config add exa https://mcp.exa.ai/mcp ### 3. 验证 ```bash -agent-reach doctor | grep "Web Search" -agent-reach search "test" -n 1 +agent-reach doctor | grep "Search" +mcporter call 'exa.web_search_exa(query: "test", numResults: 1)' ``` ## 需要用户手动做的步骤 diff --git a/agent_reach/guides/setup-wechat.md b/agent_reach/guides/setup-wechat.md index 0af3bdf..a55d00b 100644 --- a/agent_reach/guides/setup-wechat.md +++ b/agent_reach/guides/setup-wechat.md @@ -18,7 +18,7 @@ playwright install chromium 3. 安装完成后测试： ```bash -agent-reach read "https://mp.weixin.qq.com/s/一个测试链接" +curl -s "https://r.jina.ai/https://mp.weixin.qq.com/s/一个测试链接" -H "Accept: text/markdown" ``` ## 需要用户手动做的步骤 diff --git a/docs/README_en.md b/docs/README_en.md index d636e16..53877ab 100644 --- a/docs/README_en.md +++ b/docs/README_en.md @@ -108,14 +108,14 @@ After the Skill is installed, the Agent will auto-detect whether `agent-reach` C No configuration needed — just tell your Agent: -- "Read this link" → any web page -- "What's this GitHub repo about?" → repos, issues, code -- "What does this video cover?" → YouTube / Bilibili subtitles -- "Read this tweet" → Twitter posts -- "Subscribe to this RSS" → RSS / Atom feeds -- "Search GitHub for LLM frameworks" → GitHub search +- "Read this link" → `curl https://r.jina.ai/URL` for any web page +- "What's this GitHub repo about?" → `gh repo view owner/repo` +- "What does this video cover?" → `yt-dlp --dump-json URL` for subtitles +- "Read this tweet" → `bird read URL --json` +- "Subscribe to this RSS" → `feedparser` to parse feeds +- "Search GitHub for LLM frameworks" → `gh search repos "LLM framework"` -**No commands to remember.** The Agent knows what to call. +**No commands to remember.** The Agent reads SKILL.md and knows what to call. --- @@ -171,26 +171,30 @@ Every time you spin up a new Agent, you spend time finding tools, installing dep Agent Reach does one simple thing: **it makes those tool selection and configuration decisions for you.** +After installation, your Agent calls the upstream tools directly (bird CLI, yt-dlp, mcporter, gh CLI, etc.) — no wrapper layer in between. + ### 🔌 Every Channel is Pluggable -Each platform is a single Python file implementing a unified interface. **Backends can be swapped anytime** — when a better tool comes along, change one file and nothing else breaks. +Each platform maps to an upstream tool. **Don't like one? Swap it out.** ``` channels/ ├── web.py → Jina Reader ← swap to Firecrawl, Crawl4AI… -├── twitter.py → bird ← swap to Nitter, official API… -├── youtube.py → yt-dlp ← swap to YouTube API, Whisper… +├── twitter.py → bird ← swap to Nitter, 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… +├── bilibili.py → yt-dlp ← swap to bilibili-api… ├── reddit.py → JSON API + Exa ← swap to PRAW, Pushshift… ├── xiaohongshu.py → mcporter MCP ← swap to other XHS tools… ├── linkedin.py → linkedin-mcp ← swap to LinkedIn API… ├── bosszhipin.py → mcp-bosszp ← swap to other job tools… -├── rss.py → feedparser ← swap to atoma… +├── rss.py → feedparser ← swap to atoma… ├── exa_search.py → mcporter MCP ← swap to Tavily, SerpAPI… -└── __init__.py → Channel registry +└── __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. + ### Current Tool Choices | Scenario | Tool | Why | @@ -226,13 +230,13 @@ This project was entirely vibe-coded 🎸 There might be rough edges here and th
How to search Twitter/X with AI agent without paying for API? -Agent Reach uses the [bird CLI](https://www.npmjs.com/package/@steipete/bird) with cookie-based authentication — completely free, no Twitter API subscription needed. After installing Agent Reach, export your Twitter cookies using the Cookie-Editor Chrome extension, run `agent-reach configure twitter-cookies "your_cookies"`, and your agent can search with `agent-reach search-twitter "query"`. +Agent Reach uses the [bird CLI](https://www.npmjs.com/package/@steipete/bird) with cookie-based authentication — completely free, no Twitter API subscription needed. After installing Agent Reach, export your Twitter cookies using the Cookie-Editor Chrome extension, run `agent-reach configure twitter-cookies "your_cookies"`, and your agent can search with `bird search "query" --json`.
How to get YouTube video transcripts / subtitles for AI agent? -Simply run `agent-reach read https://youtube.com/watch?v=xxx`. It automatically extracts transcripts using yt-dlp. Supports multiple languages, no API key required. +`yt-dlp --dump-json "https://youtube.com/watch?v=xxx"` extracts video metadata; `yt-dlp --write-sub --skip-download "URL"` extracts subtitles. Supports multiple languages, no API key required.
@@ -244,7 +248,7 @@ Reddit blocks datacenter IPs. Configure a residential proxy: `agent-reach config
Does Agent Reach work with Claude Code / Cursor / Windsurf / OpenClaw? -Yes! Agent Reach is a standard CLI tool. Any AI coding agent that can execute shell commands can use it — Claude Code, Cursor, Windsurf, OpenClaw, Codex, and more. Just `pip install agent-reach` and start using it. +Yes! Agent Reach is an installer + configuration tool. Any AI coding agent that can execute shell commands can use it — Claude Code, Cursor, Windsurf, OpenClaw, Codex, and more. Just `pip install agent-reach`, run `agent-reach install`, and the agent can start using the upstream tools immediately.
@@ -262,7 +266,7 @@ Agent Reach uses bird CLI which accesses Twitter via cookie auth — same as you
How to read XiaoHongShu / 小红书 content programmatically? -Agent Reach integrates with xiaohongshu-mcp (runs in Docker). After setup, use `agent-reach read ` or `agent-reach search-xhs "query"` to search and read XiaoHongShu notes. +Agent Reach integrates with xiaohongshu-mcp (runs in Docker). After setup, use `mcporter call 'xiaohongshu.get_feed_detail(...)'` to read notes or `mcporter call 'xiaohongshu.search_feeds(keyword: "query")'` to search.
--- diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d69e8b8..b6a934e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -26,11 +26,10 @@ ### 方案 3：不用 bird，用 Exa 搜索替代 -Agent Reach 在 bird 失败时会自动 fallback 到 Exa 搜索。Exa 支持搜索 x.com 上的内容，虽然不如 bird 实时，但不受代理限制： +bird 不可用时，可以直接用 Exa 搜索 Twitter 内容： ```bash -agent-reach search-twitter "query" # bird 失败时自动用 Exa -agent-reach search "site:x.com query" # 直接用 Exa 搜索 +mcporter call 'exa.web_search_exa(query: "site:x.com query", numResults: 10)' ``` ### 方案 4：配置 Node.js 全局代理（高级）