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
+42
-40
@@ -20,7 +20,7 @@ Copy this to your AI Agent:
|
||||
|
||||
### Goal
|
||||
|
||||
Install Agent Reach and all upstream tools so your user's agent has full internet access. After installation, you'll use the upstream tools directly (twitter-cli, rdt-cli, xhs-cli, yt-dlp, mcporter, gh CLI, etc.) — Agent Reach is just the installer and health checker.
|
||||
Install Agent Reach and all upstream tools so your user's agent has full internet access. After installation, you'll use the upstream tools directly (OpenCLI, twitter-cli, bili-cli, rdt-cli, yt-dlp, mcporter, gh CLI, etc.) — Agent Reach is the selector, installer, health checker and router, never a wrapper.
|
||||
|
||||
### ⚠️ Boundaries
|
||||
|
||||
@@ -96,12 +96,13 @@ After installing the basics, **ask the user** which additional channels they nee
|
||||
>
|
||||
> 还有这些可选渠道，你需要哪些？
|
||||
>
|
||||
> - 🌟 **OpenCLI**（桌面推荐）— 一次安装，小红书/Reddit/B站字幕/Twitter 备选全解锁（复用浏览器登录态，零配置；只需在 Chrome 商店点一次"添加扩展"）
|
||||
> - 🐦 **Twitter/X** — 搜推文、看时间线（需要登录 Cookie）
|
||||
> - 📈 **雪球** — 股票行情、热门帖子（需要登录 Cookie）
|
||||
> - 🎙️ **小宇宙播客** — 音频转文字（需要免费 Groq Key）
|
||||
> - 📕 **小红书** — 阅读、搜索、发帖（需要登录）
|
||||
> - 📖 **Reddit** — 搜索和阅读帖子
|
||||
> - 📺 **B站完整版** — 热门、排行、搜索
|
||||
> - 📕 **小红书** — 搜索、阅读、评论（桌面走 OpenCLI；服务器用 xiaohongshu-mcp 扫码）
|
||||
> - 📖 **Reddit** — 搜索和阅读帖子（必须登录态：桌面 OpenCLI 或 rdt-cli + Cookie）
|
||||
> - 📺 **B站完整版** — 热门、排行、搜索、视频详情（bili-cli，无需登录）
|
||||
> - 💼 **LinkedIn** — Profile、职位搜索
|
||||
>
|
||||
> 告诉我你要哪些，比如"帮我装小红书和 Twitter"。或者说"全部装"。
|
||||
@@ -109,11 +110,11 @@ After installing the basics, **ask the user** which additional channels they nee
|
||||
Based on the user's choice, run:
|
||||
|
||||
```bash
|
||||
agent-reach install --env=auto --channels=twitter,xiaohongshu # Example: user chose Twitter + XHS
|
||||
agent-reach install --env=auto --channels=opencli,xiaohongshu # Example: desktop user chose XHS (OpenCLI-backed)
|
||||
agent-reach install --env=auto --channels=all # User wants everything
|
||||
```
|
||||
|
||||
Supported channel names: `twitter`, `xiaoyuzhou`, `xueqiu`, `xiaohongshu`, `reddit`, `bilibili`, `linkedin`, `all`
|
||||
Supported channel names: `opencli`, `twitter`, `xiaoyuzhou`, `xueqiu`, `xiaohongshu`, `reddit`, `bilibili`, `linkedin`, `all`
|
||||
|
||||
### Step 3: Fix what's broken
|
||||
|
||||
@@ -159,44 +160,43 @@ agent-reach configure twitter-cookies "PASTED_STRING"
|
||||
>
|
||||
> 如果用户报告 "fetch failed"，参考 [troubleshooting.md](troubleshooting.md)
|
||||
|
||||
**Reddit & Bilibili full access (server users):**
|
||||
> "Reddit and Bilibili block server IPs. To unlock full access, I need a residential proxy. You can get one at https://webshare.io ($1/month). Send me the proxy address."
|
||||
**Reddit (login is mandatory — no zero-config path):**
|
||||
> Reddit 的匿名接口已被封、官方 API 需人工审批。桌面用户首选 OpenCLI（浏览器里登录过 reddit.com 即可用）；服务器/存量用户用 rdt-cli：
|
||||
|
||||
```bash
|
||||
agent-reach configure proxy http://user:pass@ip:port
|
||||
pipx install 'git+https://github.com/public-clis/rdt-cli.git' # PyPI 落后，从 GitHub 装
|
||||
rdt login # 自动提取浏览器 Cookie；服务器无浏览器时按 doctor 提示手动写 Cookie
|
||||
```
|
||||
|
||||
**XiaoHongShu / 小红书 (xhs-cli):**
|
||||
> "小红书通过 xhs-cli 访问，pipx 一行安装，不需要 Docker。"
|
||||
|
||||
```bash
|
||||
pipx install xiaohongshu-cli
|
||||
xhs login
|
||||
```
|
||||
|
||||
> `xhs login` 会自动从浏览器提取 Cookie。如果自动提取失败，可以手动导入：
|
||||
>
|
||||
> **手动导入 Cookie（Cookie-Editor 方式）：**
|
||||
> 1. 用户在自己的浏览器登录小红书 (xiaohongshu.com)
|
||||
> 2. 用 [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) 插件导出 Cookie（JSON 或 Header String 格式均可）
|
||||
> 3. 把 Cookie 字符串发给 Agent
|
||||
> 4. Agent 运行命令完成登录：
|
||||
>
|
||||
> 中国大陆访问 Reddit 需要代理；服务器 IP 被风控时可配住宅代理（如 https://webshare.io，约 $1/月）：
|
||||
> ```bash
|
||||
> # JSON 格式（Cookie-Editor → Export → JSON）
|
||||
> agent-reach configure xhs-cookies '[{"name":"web_session","value":"xxx","domain":".xiaohongshu.com",...}]'
|
||||
>
|
||||
> # 或 Header String 格式（Cookie-Editor → Export → Header String）
|
||||
> agent-reach configure xhs-cookies "key1=val1; key2=val2; ..."
|
||||
> agent-reach configure proxy http://user:pass@ip:port
|
||||
> ```
|
||||
|
||||
**XiaoHongShu / 小红书（多后端，按环境选）:**
|
||||
|
||||
> **桌面电脑（推荐 OpenCLI）：**
|
||||
> "小红书走 OpenCLI——复用你浏览器里的登录态，平时刷过小红书就直接能用，零配置。"
|
||||
|
||||
```bash
|
||||
agent-reach install --channels opencli
|
||||
```
|
||||
|
||||
> 装完后引导用户做唯一一步手动操作（Chrome 安全限制，无法代劳）：
|
||||
> 1. 打开 https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk
|
||||
> 2. 点「添加至 Chrome」
|
||||
> 3. 运行 `opencli doctor` 验证（显示 Extension: connected 即成功）
|
||||
>
|
||||
> **注意：** 推荐使用 Cookie-Editor 导出方式，不要依赖 QR 扫码登录。
|
||||
> **服务器 / 无桌面环境（xiaohongshu-mcp）：**
|
||||
> 1. 从 https://github.com/xpzouying/xiaohongshu-mcp/releases 下载对应平台 binary 到 `~/.agent-reach/tools/`
|
||||
> 2. 启动服务（首次运行会自动下载约 150MB 无头浏览器，耐心等完成）
|
||||
> 3. 让用户扫码登录（agent 调 `get_login_qrcode` 工具取二维码）
|
||||
> 4. 接入：`mcporter config add xiaohongshu http://localhost:18060/mcp`
|
||||
> 5. 调用时务必带 `--timeout 120000`
|
||||
>
|
||||
> **备选方案：Docker MCP**
|
||||
> 如果你已经在使用 [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) Docker 方案，它也能正常工作：
|
||||
> **存量用户（xhs-cli）：** 已装好的 xhs-cli 继续作为备选后端工作（上游 2026-03 起停更，不推荐新装）。`xhs login` 自动提取浏览器 Cookie；失败时用 Cookie-Editor 导出后：
|
||||
> ```bash
|
||||
> docker run -d --name xiaohongshu-mcp -p 18060:18060 xpzouying/xiaohongshu-mcp
|
||||
> mcporter config add xiaohongshu http://localhost:18060/mcp
|
||||
> agent-reach configure xhs-cookies "key1=val1; key2=val2; ..."
|
||||
> ```
|
||||
|
||||
**雪球 / Xueqiu (股票行情 + 热门帖子):**
|
||||
@@ -292,7 +292,7 @@ If the user agrees, create a **cron job** (daily, `sessionTarget: "isolated"`, `
|
||||
运行 agent-reach watch 命令。
|
||||
如果输出包含"全部正常"，不需要通知用户，静默结束。
|
||||
如果输出包含问题（❌ ⚠️）或新版本（🆕），把完整报告发给用户，并建议修复方案。
|
||||
如果有新版本可用，问用户是否要升级（升级命令：pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip）。
|
||||
如果有新版本可用，问用户是否要升级（把这句话发给用户的 Agent 即可完整更新：帮我更新 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md）。
|
||||
```
|
||||
|
||||
If the user wants a different agent to handle it, let them choose.
|
||||
@@ -319,14 +319,16 @@ After installation, use upstream tools directly. See SKILL.md for the full comma
|
||||
|
||||
| Platform | Upstream Tool | Example |
|
||||
|----------|--------------|---------|
|
||||
| Twitter/X | `twitter` | `twitter search "query" -n 10` |
|
||||
| Twitter/X | `twitter`（备选 `opencli`） | `twitter search "query" -n 10` |
|
||||
| YouTube | `yt-dlp` | `yt-dlp --dump-json URL` |
|
||||
| Bilibili | `yt-dlp` + `bili` | `bili hot` / `bili search "query" --type video` |
|
||||
| Reddit | `rdt` | `rdt search "query"` / `rdt read POST_ID` |
|
||||
| Bilibili | `bili`（字幕走 `opencli`） | `bili search "query" --type video` / `opencli bilibili subtitle BVxxx` |
|
||||
| Reddit | `opencli`（备选 `rdt`） | `opencli reddit search "query" -f yaml` / `rdt read POST_ID` |
|
||||
| GitHub | `gh` | `gh search repos "query"` |
|
||||
| Web | `curl` + Jina | `curl -s "https://r.jina.ai/URL"` |
|
||||
| Exa Search | `mcporter` | `mcporter call 'exa.web_search_exa(...)'` |
|
||||
| 小红书 | `mcporter` | `mcporter call 'xiaohongshu.search_feeds(...)'` |
|
||||
| 小红书 | `opencli`（服务器 `mcporter`） | `opencli xiaohongshu search "query" -f yaml` |
|
||||
| 小宇宙播客 | `transcribe.sh` | `bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh <URL>` |
|
||||
| LinkedIn | `mcporter` | `mcporter call 'linkedin.get_person_profile(...)'` |
|
||||
| RSS | `feedparser` | `python3 -c "import feedparser; ..."` |
|
||||
|
||||
> 多后端平台以 `agent-reach doctor --json` 的 `active_backend` 为准。
|
||||
|
||||
+51
-68
@@ -24,7 +24,7 @@ Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/ma
|
||||
|
||||
### Goal
|
||||
|
||||
Update Agent Reach to the latest version, install any new upstream tools, migrate from deprecated tools, and verify everything works. The user should not need to do anything manually.
|
||||
Update Agent Reach to the latest version, refresh upstream tools, migrate from retired backends, and verify everything works. The user should not need to do anything manually (except things only a human can do, like clicking a browser-extension install button).
|
||||
|
||||
### Step 1: Check current version
|
||||
|
||||
@@ -32,7 +32,7 @@ Update Agent Reach to the latest version, install any new upstream tools, migrat
|
||||
agent-reach check-update
|
||||
```
|
||||
|
||||
If it says "已是最新版本", skip to Step 5 (verify). Otherwise continue.
|
||||
If it says "已是最新版本", skip to Step 4 (verify). Otherwise continue.
|
||||
|
||||
### Step 2: Update Agent Reach package
|
||||
|
||||
@@ -40,40 +40,47 @@ If it says "已是最新版本", skip to Step 5 (verify). Otherwise continue.
|
||||
pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip
|
||||
```
|
||||
|
||||
### Step 3: Install / migrate upstream tools
|
||||
> If pip complains about `externally-managed-environment` (PEP 668), the user
|
||||
> originally installed via pipx or a venv — use the matching command:
|
||||
> `pipx install --force https://github.com/Panniantong/agent-reach/archive/main.zip`
|
||||
> or activate `~/.agent-reach-venv` first.
|
||||
|
||||
Run these commands to ensure all upstream CLI tools are installed. Skip any that are already installed.
|
||||
### Step 3: Refresh upstream tools
|
||||
|
||||
Run these to keep installed tools current. **Only upgrade what is already
|
||||
installed — do not install new tools the user never asked for** (the one
|
||||
exception: OpenCLI on desktop, see below).
|
||||
|
||||
```bash
|
||||
# === Required tools (core functionality) ===
|
||||
# Python-based CLIs the user already has (upgrade keeps signatures fresh)
|
||||
which twitter >/dev/null 2>&1 && { pipx upgrade twitter-cli 2>/dev/null || uv tool upgrade twitter-cli 2>/dev/null; }
|
||||
which bili >/dev/null 2>&1 && { pipx upgrade bilibili-cli 2>/dev/null || uv tool upgrade bilibili-cli 2>/dev/null; }
|
||||
which xhs >/dev/null 2>&1 && { pipx upgrade xiaohongshu-cli 2>/dev/null || uv tool upgrade xiaohongshu-cli 2>/dev/null; }
|
||||
which yt-dlp >/dev/null 2>&1 && { pipx upgrade yt-dlp 2>/dev/null || uv tool upgrade yt-dlp 2>/dev/null || pip install -U yt-dlp 2>/dev/null; }
|
||||
|
||||
# Twitter/X — twitter-cli (replaces deprecated bird CLI)
|
||||
which twitter >/dev/null 2>&1 || pipx install twitter-cli 2>/dev/null || uv tool install twitter-cli 2>/dev/null
|
||||
# rdt-cli is pinned to a git source (PyPI lags upstream)
|
||||
which rdt >/dev/null 2>&1 && pipx install --force 'git+https://github.com/public-clis/rdt-cli.git' 2>/dev/null
|
||||
|
||||
# Reddit — rdt-cli (replaces Exa-based approach; PyPI lags, install from GitHub)
|
||||
which rdt >/dev/null 2>&1 || pipx install 'git+https://github.com/public-clis/rdt-cli.git' 2>/dev/null || uv tool install --from 'git+https://github.com/public-clis/rdt-cli.git' rdt-cli 2>/dev/null
|
||||
|
||||
# XiaoHongShu — xhs-cli (replaces Docker MCP)
|
||||
which xhs >/dev/null 2>&1 || pipx install xiaohongshu-cli 2>/dev/null || uv tool install xiaohongshu-cli 2>/dev/null
|
||||
|
||||
# === Optional enhancements ===
|
||||
|
||||
# Bilibili — bili-cli (adds hot/rank/search on top of yt-dlp)
|
||||
which bili >/dev/null 2>&1 || pipx install bilibili-cli 2>/dev/null || uv tool install bilibili-cli 2>/dev/null
|
||||
|
||||
# mcporter + Exa (for WeChat, web search)
|
||||
which mcporter >/dev/null 2>&1 || npm install -g mcporter 2>/dev/null
|
||||
|
||||
# yt-dlp (YouTube + Bilibili video)
|
||||
which yt-dlp >/dev/null 2>&1 || pip install yt-dlp 2>/dev/null
|
||||
|
||||
# gh CLI (GitHub)
|
||||
which gh >/dev/null 2>&1 || echo "GitHub CLI not installed — see https://cli.github.com"
|
||||
# npm-based
|
||||
which mcporter >/dev/null 2>&1 && npm update -g mcporter 2>/dev/null
|
||||
which opencli >/dev/null 2>&1 && npm update -g @jackwener/opencli 2>/dev/null
|
||||
```
|
||||
|
||||
**Desktop users without OpenCLI**: since v1.5.0 OpenCLI is the preferred
|
||||
backend for 小红书/Reddit (and adds B站 subtitles) by riding the user's
|
||||
browser session. Offer it once:
|
||||
|
||||
> "这次更新引入了 OpenCLI 后端（复用你的浏览器登录态，小红书/Reddit 零配置）。要装吗？装完只需你在 Chrome 商店点一次『添加扩展』。"
|
||||
|
||||
If yes: `agent-reach install --channels opencli` and guide them through the
|
||||
extension click. If no, everything keeps working on existing backends.
|
||||
|
||||
### Step 4: Coexistence (DO NOT uninstall old tools)
|
||||
|
||||
**IMPORTANT: Never uninstall any existing tools the user already has installed.** Old tools (bird, browser_cookie3, miku_ai, etc.) may still be working on the user's machine even if their upstream repos are archived or deleted. Agent Reach supports both old and new tools as fallback. Only install new tools alongside existing ones.
|
||||
**Never uninstall tools the user already has.** Retired backends (e.g. yt-dlp
|
||||
no longer serves Bilibili; xhs-cli is no longer installed by default) keep
|
||||
working as fallbacks where they still function. Agent Reach routes around
|
||||
them automatically — removal is the user's call, not yours.
|
||||
|
||||
### Step 5: Verify
|
||||
|
||||
@@ -82,51 +89,27 @@ agent-reach version
|
||||
agent-reach doctor
|
||||
```
|
||||
|
||||
Running `agent-reach doctor` (text mode) also auto-syncs the bundled skill
|
||||
(SKILL.md + references) into every detected agent skill directory — no
|
||||
separate skill-update step is needed.
|
||||
|
||||
Check the doctor output:
|
||||
- All channels should show ✅ or ⚠️ (with clear instructions)
|
||||
- If any channel that was working before now shows ❌, investigate:
|
||||
- Twitter: needs `twitter-cli` + browser cookies (run `xhs login` pattern)
|
||||
- Reddit: needs `rdt-cli` (should be installed in Step 3)
|
||||
- XiaoHongShu: needs `xhs-cli` + login (run `xhs login`)
|
||||
- WeChat: should work via Exa (zero config)
|
||||
|
||||
### Step 6: Update SKILL.md (if installed)
|
||||
- Every channel shows ✅ / [!] with a clear message, and multi-backend
|
||||
channels (小红书/Reddit/B站/Twitter) report `当前后端：…`
|
||||
- If a previously-working channel now shows [X]/error, the message contains
|
||||
the exact fix (e.g. a venv-reinstall prescription) — run it, then re-check
|
||||
- `--json` gives the same data machine-readably (`active_backend` per channel)
|
||||
|
||||
```bash
|
||||
agent-reach install --skill-only 2>/dev/null || python3 -c "
|
||||
import importlib.resources, os
|
||||
try:
|
||||
skill_pkg = importlib.resources.files('agent_reach').joinpath('skill')
|
||||
except Exception:
|
||||
from pathlib import Path
|
||||
skill_pkg = Path(os.path.dirname(os.path.abspath(__file__))).parent / 'agent_reach' / 'skill'
|
||||
|
||||
skill_md = skill_pkg.joinpath('SKILL.md').read_text(encoding='utf-8')
|
||||
refs_pkg = skill_pkg.joinpath('references')
|
||||
|
||||
for base in [os.path.expanduser('~/.openclaw/skills/agent-reach'),
|
||||
os.path.expanduser('~/.claude/skills/agent-reach'),
|
||||
os.path.expanduser('~/.agents/skills/agent-reach')]:
|
||||
if os.path.isdir(base):
|
||||
with open(os.path.join(base, 'SKILL.md'), 'w', encoding='utf-8') as f:
|
||||
f.write(skill_md)
|
||||
refs_dir = os.path.join(base, 'references')
|
||||
os.makedirs(refs_dir, exist_ok=True)
|
||||
for ref in refs_pkg.iterdir():
|
||||
name = ref.name if hasattr(ref, 'name') else str(ref).split('/')[-1]
|
||||
if name.endswith('.md'):
|
||||
with open(os.path.join(refs_dir, name), 'w', encoding='utf-8') as f:
|
||||
f.write(ref.read_text(encoding='utf-8'))
|
||||
print(f'✅ Updated skill: {base}')
|
||||
"
|
||||
```
|
||||
|
||||
### Step 7: Report to user
|
||||
### Step 6: Report to user
|
||||
|
||||
Tell the user:
|
||||
1. What version they're now on (`agent-reach version`)
|
||||
2. How many channels are available (count ✅ in doctor output)
|
||||
3. Any channels that need their action (e.g., `xhs login` for XiaoHongShu, browser cookies for Twitter)
|
||||
4. What changed in this update (major: Twitter/Reddit/XiaoHongShu upstream tools migrated for better stability)
|
||||
|
||||
1. What version they're on now (`agent-reach version`)
|
||||
2. How many channels are available, and which backend each multi-backend
|
||||
platform is using (from doctor)
|
||||
3. Anything that needs their action (e.g. Chrome extension click, `xhs login`,
|
||||
QR scan for xiaohongshu-mcp on servers)
|
||||
4. What changed in this update (release notes shown by `check-update`)
|
||||
|
||||
Done.
|
||||
|
||||
Reference in New Issue
Block a user