feat(experience): one-liner install/update docs catch up + version-watching skill
The one-liner entry docs were untouched by the backend upgrade — new users following "帮我安装 Agent Reach" would still get the old world. Now: - docs/install.md: xiaohongshu section rewritten (desktop OpenCLI with the one manual extension click / server xiaohongshu-mcp with QR + 150MB first-run warning / legacy xhs-cli kept as fallback); Reddit section says plainly there is no zero-config path; optional-channel menu gains OpenCLI; upstream table matches the new routing with a doctor --json pointer - docs/update.md: full rewrite — upgrade-only-what-exists tool refresh (incl. npm update for OpenCLI/mcporter, pinned git source for rdt-cli), one-time OpenCLI offer for desktops, skill sync now rides doctor's auto-sync instead of an inline python blob, WeChat-era content removed - check-update / watch: "update available" now leads with the one-liner (帮我更新 Agent Reach：<update.md>) which updates package + tools + skill; bare pip stays as the package-only alternative - fix: version compare was `!=` — a local build AHEAD of the latest release (installed from main during a release window) was told to "update" into a downgrade; now semantic tuple compare with fallback (+4 tests) - skill (zh+en): description gains a NOT-for boundary (fetch-only, no write ops, defer to dedicated skills); new standing rule — after substantial tasks run check-update and append a one-liner update hint to the wrap-up, never interrupting or nagging - SKILL_en.md restructured to the same three-layer skeleton as the Chinese version (124-line body, shared references/) instead of a 263-line everything-inline page Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Pnant
@@ -14,6 +14,9 @@ description: >
|
||||
Zero config for 6 channels. Run `agent-reach doctor --json` to see which
|
||||
backend serves each platform right now.
|
||||
|
||||
NOT for: 写报告/数据分析/翻译等内容加工（本 skill 只负责从互联网获取内容）；
|
||||
发帖/评论/点赞等写操作；已有专门 skill 的平台（先用专门 skill）。
|
||||
|
||||
【路由方式】SKILL.md 包含路由表和常用命令，复杂场景需按需阅读对应分类的 references/*.md。
|
||||
分类：search / social (小红书/推特/B站/V2EX/Reddit) / career(LinkedIn) / dev(github) / web(网页/文章/RSS) / video(YouTube/B站/播客)。
|
||||
triggers:
|
||||
@@ -46,6 +49,11 @@ metadata:
|
||||
2. **声明你在用什么**：开始干活前说一句「使用 agent-reach 的 X 平台 / Y 后端」。
|
||||
3. **失败按 references 里的重试链处理**，不要瞎猜命令。
|
||||
4. **全网调研类任务**：组合多平台（Exa 搜索 + Twitter/Reddit 看讨论 + 小红书/B站看中文场景），并行收集再汇总。
|
||||
5. **替用户盯版本**：完成一次较大的调研/多平台任务后，顺手跑
|
||||
`agent-reach check-update`（很快，一个 API 调用）。有新版就在收尾汇报里附一句：
|
||||
「Agent Reach 有新版 vX.Y.Z，复制这句话给我即可更新：帮我更新 Agent Reach：
|
||||
https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md」。
|
||||
不要中断当前任务去更新，也不要重复提醒同一个版本。
|
||||
|
||||
## 路由表
|
||||
|
||||
|
||||
+72
-210
@@ -13,251 +13,113 @@ description: >
|
||||
Zero config for 6 channels. Run `agent-reach doctor --json` to see which
|
||||
backend serves each platform right now.
|
||||
|
||||
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", "雪球", "股票".
|
||||
NOT for: writing reports/analysis/translation (this skill only FETCHES
|
||||
internet content); posting/commenting/liking (write operations); platforms
|
||||
that already have a dedicated skill installed (prefer that skill).
|
||||
metadata:
|
||||
openclaw:
|
||||
homepage: https://github.com/Panniantong/Agent-Reach
|
||||
---
|
||||
|
||||
# Agent Reach — Usage Guide
|
||||
# Agent Reach — internet capability router
|
||||
|
||||
Upstream tools for 13 platforms. Call them directly.
|
||||
13 platforms, multiple backends each. **When this skill exists, use it for
|
||||
these platforms — do not invent your own approach.**
|
||||
|
||||
Run `agent-reach doctor` to check which channels are available.
|
||||
## Standing rules (apply for the whole session)
|
||||
|
||||
## ⚠️ Workspace Rules
|
||||
1. **Health-check before acting**: for multi-backend platforms (XiaoHongShu /
|
||||
Reddit / Bilibili / Twitter), run `agent-reach doctor --json` first and
|
||||
pick the command group matching each platform's `active_backend`.
|
||||
2. **Announce what you use**: say "using agent-reach, platform X via backend Y"
|
||||
before starting.
|
||||
3. **On failure, follow the retry chains in references/** — never guess
|
||||
commands.
|
||||
4. **For broad research tasks**: combine platforms (Exa for web search +
|
||||
Twitter/Reddit for discussions + XiaoHongShu/Bilibili for Chinese
|
||||
perspectives), collect in parallel, then synthesize.
|
||||
5. **Watch versions for the user**: after finishing a substantial
|
||||
multi-platform task, run `agent-reach check-update` (fast, one API call).
|
||||
If a new version exists, append one line to your wrap-up: "Agent Reach
|
||||
vX.Y.Z is available — paste this to me to update: 帮我更新 Agent Reach：
|
||||
https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md".
|
||||
Never interrupt the current task to update; never nag about the same version twice.
|
||||
|
||||
**Never create files in the agent workspace.** Use `/tmp/` for temporary output and `~/.agent-reach/` for persistent data.
|
||||
## Routing table
|
||||
|
||||
## Web — Any URL
|
||||
|
||||
```bash
|
||||
curl -s "https://r.jina.ai/URL"
|
||||
```
|
||||
|
||||
## Web Search (Exa)
|
||||
| User intent | Category | Details |
|
||||
|---------|------|---------|
|
||||
| Web / code search | search | [references/search.md](references/search.md) |
|
||||
| XiaoHongShu / Twitter / Bilibili / V2EX / Reddit | social | [references/social.md](references/social.md) |
|
||||
| Jobs / LinkedIn | career | [references/career.md](references/career.md) |
|
||||
| GitHub / code | dev | [references/dev.md](references/dev.md) |
|
||||
| Web pages / articles / RSS | web | [references/web.md](references/web.md) |
|
||||
| YouTube / Bilibili / podcast transcripts | video | [references/video.md](references/video.md) |
|
||||
|
||||
## Zero-config quick commands
|
||||
|
||||
```bash
|
||||
# Exa web search
|
||||
mcporter call 'exa.web_search_exa(query: "query", numResults: 5)'
|
||||
mcporter call 'exa.get_code_context_exa(query: "code question", tokensNum: 3000)'
|
||||
```
|
||||
|
||||
## Twitter/X (twitter-cli)
|
||||
# Read any web page
|
||||
curl -s "https://r.jina.ai/URL"
|
||||
|
||||
```bash
|
||||
twitter -c search "query" -n 10 # search (-c = compact JSON, LLM-friendly)
|
||||
twitter -c tweet URL_OR_ID # read tweet + replies (supports /status/ URLs)
|
||||
twitter -c article URL_OR_ID # read a Twitter Article
|
||||
twitter -c user-posts @username -n 20 # user timeline
|
||||
twitter -c feed -n 20 # home timeline
|
||||
```
|
||||
|
||||
> Binary is `twitter` (`pipx install twitter-cli`, ≥ 0.8.5). The `bird` name in older docs has been retired. If `search` returns 404, run `pipx upgrade twitter-cli`.
|
||||
|
||||
## YouTube (yt-dlp)
|
||||
|
||||
```bash
|
||||
yt-dlp --dump-json "URL" # video metadata
|
||||
yt-dlp --write-sub --write-auto-sub --sub-lang "zh-Hans,zh,en" --skip-download -o "/tmp/%(id)s" "URL"
|
||||
# download subtitles, then read the .vtt file
|
||||
yt-dlp --dump-json "ytsearch5:query" # search
|
||||
```
|
||||
|
||||
## 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
|
||||
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)
|
||||
```
|
||||
|
||||
## Reddit (login required — no zero-config path)
|
||||
|
||||
> 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
|
||||
opencli reddit search "query" -f yaml # desktop, browser session
|
||||
rdt search "query" --limit 10 # legacy/server, cookie login
|
||||
rdt read POST_ID # post + comments
|
||||
```
|
||||
|
||||
## GitHub (gh CLI)
|
||||
|
||||
```bash
|
||||
# GitHub search
|
||||
gh search repos "query" --sort stars --limit 10
|
||||
gh repo view owner/repo
|
||||
gh search code "query" --language python
|
||||
gh issue list -R owner/repo --state open
|
||||
gh issue view 123 -R owner/repo
|
||||
```
|
||||
|
||||
## XiaoHongShu (multi-backend — check doctor for active backend)
|
||||
# YouTube subtitles (NOTE: never use yt-dlp for Bilibili — see video.md)
|
||||
yt-dlp --write-sub --skip-download -o "/tmp/%(id)s" "URL"
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
> **Tip: Clean bloated output.** The XHS API returns large JSON with many unused fields.
|
||||
> Pipe through the formatter to save context:
|
||||
> ```bash
|
||||
> mcporter call 'xiaohongshu.search_feeds(keyword: "query")' | agent-reach format xhs
|
||||
> ```
|
||||
> This keeps only: title, content, author, engagement counts, image URLs, and tags.
|
||||
|
||||
## Xiaoyuzhou Podcast (groq-whisper + ffmpeg)
|
||||
|
||||
```bash
|
||||
# Transcribe a single podcast episode (outputs text to /tmp/)
|
||||
~/.agent-reach/tools/xiaoyuzhou/transcribe.sh "https://www.xiaoyuzhoufm.com/episode/EPISODE_ID"
|
||||
```
|
||||
|
||||
> Requires `ffmpeg` and a Groq API key (free).
|
||||
> Configure the key with `agent-reach configure groq-key YOUR_KEY`.
|
||||
> On first run, install the tools with `agent-reach install --env=auto`.
|
||||
> Run `agent-reach doctor` to check status.
|
||||
> Output Markdown files are saved to `/tmp/` by default.
|
||||
|
||||
## LinkedIn (mcporter)
|
||||
|
||||
```bash
|
||||
mcporter call 'linkedin.get_person_profile(linkedin_url: "https://linkedin.com/in/username")'
|
||||
mcporter call 'linkedin.search_people(keyword: "AI engineer", limit: 10)'
|
||||
```
|
||||
|
||||
Fallback: `curl -s "https://r.jina.ai/https://linkedin.com/in/username"`
|
||||
|
||||
## V2EX (public API)
|
||||
|
||||
```bash
|
||||
# Hot topics
|
||||
# V2EX hot topics
|
||||
curl -s "https://www.v2ex.com/api/topics/hot.json" -H "User-Agent: agent-reach/1.0"
|
||||
|
||||
# Topics in a node (node_name examples: python, tech, jobs, qna)
|
||||
curl -s "https://www.v2ex.com/api/topics/show.json?node_name=python&page=1" -H "User-Agent: agent-reach/1.0"
|
||||
|
||||
# Topic details (extract topic_id from URLs like 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"
|
||||
|
||||
# Topic replies
|
||||
curl -s "https://www.v2ex.com/api/replies/show.json?topic_id=TOPIC_ID&page=1" -H "User-Agent: agent-reach/1.0"
|
||||
|
||||
# User profile
|
||||
curl -s "https://www.v2ex.com/api/members/show.json?username=USERNAME" -H "User-Agent: agent-reach/1.0"
|
||||
# Bilibili search (bili-cli, no login needed)
|
||||
bili search "query" --type video -n 5
|
||||
```
|
||||
|
||||
Python example (`V2EXChannel`):
|
||||
## Login-backed platforms (pick by doctor's active_backend)
|
||||
|
||||
```python
|
||||
from agent_reach.channels.v2ex import V2EXChannel
|
||||
```bash
|
||||
# Twitter search (twitter-cli preferred; retry chain in social.md)
|
||||
twitter search "query" -n 10
|
||||
|
||||
ch = V2EXChannel()
|
||||
# Reddit (NO zero-config path — OpenCLI or rdt-cli, login required)
|
||||
opencli reddit search "query" -f yaml # desktop
|
||||
rdt search "query" --limit 10 # legacy/server
|
||||
|
||||
# Get hot topics (default 20 items)
|
||||
# Returned fields: id, title, url, replies, node_name, node_title, content(first 200 chars), created
|
||||
topics = ch.get_hot_topics(limit=10)
|
||||
for t in topics:
|
||||
print(f"[{t['node_title']}] {t['title']} ({t['replies']} replies) {t['url']}")
|
||||
print(f" id={t['id']} created={t['created']}")
|
||||
|
||||
# Get latest topics for a specific node
|
||||
# Returned fields: id, title, url, replies, node_name, node_title, content(first 200 chars), created
|
||||
node_topics = ch.get_node_topics("python", limit=5)
|
||||
for t in node_topics:
|
||||
print(t["id"], t["title"], t["url"])
|
||||
|
||||
# Get one topic plus replies
|
||||
# Returned fields: id, title, url, content, replies_count, node_name, node_title,
|
||||
# author, created, replies (list of {author, content, created})
|
||||
topic = ch.get_topic(1234567)
|
||||
print(topic["title"], "—", topic["author"])
|
||||
for r in topic["replies"]:
|
||||
print(f" {r['author']}: {r['content'][:80]}")
|
||||
|
||||
# Get user info
|
||||
# Returned fields: id, username, url, website, twitter, psn, github, btc, location, bio, avatar, created
|
||||
user = ch.get_user("Livid")
|
||||
print(user["username"], user["bio"], user["github"])
|
||||
|
||||
# Search (not supported by the public V2EX API; returns guidance instead)
|
||||
result = ch.search("asyncio")
|
||||
print(result[0]["error"]) # Use built-in site search or the Exa channel instead
|
||||
# XiaoHongShu (desktop prefers OpenCLI)
|
||||
opencli xiaohongshu search "query" -f yaml
|
||||
```
|
||||
|
||||
> No auth required. Results are public JSON. V2EX node names are listed at https://www.v2ex.com/planes
|
||||
## Environment check
|
||||
|
||||
## Xueqiu (public API)
|
||||
|
||||
```python
|
||||
from agent_reach.channels.xueqiu import XueqiuChannel
|
||||
|
||||
ch = XueqiuChannel()
|
||||
|
||||
# Get stock quotes (symbol examples: SH600519 mainland China, SZ000858 Shenzhen, AAPL US, 00700 HK)
|
||||
# Returned fields: symbol, name, current, percent, chg, high, low, open, last_close,
|
||||
# volume, amount, market_capital, turnover_rate, pe_ttm, timestamp
|
||||
quote = ch.get_stock_quote("AAPL")
|
||||
print(f"{quote['name']} ({quote['symbol']}): {quote['current']} ({quote['percent']}%)")
|
||||
|
||||
# Search stocks
|
||||
# Returned fields: symbol, name, exchange
|
||||
stocks = ch.search_stock("Apple", limit=5)
|
||||
for s in stocks:
|
||||
print(f"{s['name']} ({s['symbol']}) - {s['exchange']}")
|
||||
|
||||
# Hot posts
|
||||
# Returned fields: id, title, text(first 200 chars), author, likes, url
|
||||
posts = ch.get_hot_posts(limit=10)
|
||||
for p in posts:
|
||||
print(f"{p['author']}: {p['text'][:50]}... ({p['likes']} likes)")
|
||||
|
||||
# Hot stocks (stock_type=10 popularity ranking, stock_type=12 watchlist ranking)
|
||||
# Returned fields: symbol, name, current, percent, rank
|
||||
hot = ch.get_hot_stocks(limit=10, stock_type=10)
|
||||
for s in hot:
|
||||
print(f"#{s['rank']} {s['name']} ({s['symbol']}): {s['current']} ({s['percent']}%)")
|
||||
```bash
|
||||
# Channel availability + which backend serves each platform
|
||||
agent-reach doctor --json
|
||||
```
|
||||
|
||||
> No login required. Agent Reach auto-fetches session cookies, and all public APIs can be used directly.
|
||||
## Workspace rules
|
||||
|
||||
## RSS (feedparser)
|
||||
**Never create files in the agent workspace.** Use `/tmp/` for temporary
|
||||
output and `~/.agent-reach/` for persistent data.
|
||||
|
||||
```python
|
||||
python3 -c "
|
||||
import feedparser
|
||||
for e in feedparser.parse('FEED_URL').entries[:5]:
|
||||
print(f'{e.title} — {e.link}')
|
||||
"
|
||||
```
|
||||
## Detailed references
|
||||
|
||||
## Troubleshooting
|
||||
Read the matching file when you need specifics (commands above cover the
|
||||
common cases; references hold per-backend command groups, caveats, retry
|
||||
chains — note: reference docs are written in Chinese, commands are universal):
|
||||
|
||||
- **Channel not working?** Run `agent-reach doctor` — it shows status and fix instructions.
|
||||
- **Twitter fetch failed?** Ensure `undici` is installed: `npm install -g undici`. Configure a proxy if needed: `agent-reach configure proxy URL`.
|
||||
- [Search](references/search.md) — Exa AI search
|
||||
- [Social](references/social.md) — XiaoHongShu, Twitter, Bilibili, V2EX, Reddit (multi-backend groups)
|
||||
- [Career](references/career.md) — LinkedIn
|
||||
- [Dev](references/dev.md) — GitHub CLI
|
||||
- [Web](references/web.md) — Jina Reader, RSS
|
||||
- [Video](references/video.md) — YouTube, Bilibili, Xiaoyuzhou
|
||||
|
||||
## Setting Up a Channel ("help me configure XXX")
|
||||
## Configure a channel
|
||||
|
||||
If a channel needs setup (cookies, Docker, etc.), fetch the install guide:
|
||||
If a channel needs setup, fetch the install guide:
|
||||
https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
|
||||
|
||||
The user only provides cookies. Everything else is your job.
|
||||
The user only provides cookies / one extension click; the agent does the rest.
|
||||
|
||||
Reference in New Issue
Block a user