From 65ff8d69d0cccb542c54a3d61f709d22f83663ec Mon Sep 17 00:00:00 2001 From: Pnant <73925474+Panniantong@users.noreply.github.com> Date: Tue, 31 Mar 2026 18:36:43 +0800 Subject: [PATCH] docs: rewrite update.md for v1.4.0 upstream migrations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit update.md now handles the full update lifecycle autonomously: - Installs new CLI tools (twitter-cli, rdt-cli, xhs-cli, bili-cli) - Removes deprecated bird CLI - Updates SKILL.md + references/ with fallback - Reports changes to user install.md: update tool references (bird→twitter-cli, Exa→rdt-cli). Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/install.md | 11 +++-- docs/update.md | 107 ++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 90 insertions(+), 28 deletions(-) diff --git a/docs/install.md b/docs/install.md index 296c03f..ced05fa 100644 --- a/docs/install.md +++ b/docs/install.md @@ -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 (bird 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 (twitter-cli, rdt-cli, xhs-cli, yt-dlp, mcporter, gh CLI, etc.) — Agent Reach is just the installer and health checker. ### ⚠️ Boundaries @@ -140,8 +140,7 @@ agent-reach configure twitter-cookies "PASTED_STRING" > **代理说明（中国大陆等需要翻墙的网络环境）：** > -> bird CLI 使用 Node.js，在需要代理的网络环境下可通过环境变量配置代理。 -> Agent Reach 安装时会自动安装 `undici`（`npm install -g undici`）以提供代理支持。 +> twitter-cli 和 rdt-cli 使用 Python，在需要代理的网络环境下可通过环境变量配置代理。 > > **你（Agent）需要做的：** > 1. 确认用户配了代理：`agent-reach configure proxy http://user:pass@ip:port` @@ -385,10 +384,10 @@ After installation, use upstream tools directly. See SKILL.md for the full comma | Platform | Upstream Tool | Example | |----------|--------------|---------| -| Twitter/X | `bird` | `bird search "query" -n 10` | +| Twitter/X | `twitter` | `twitter search "query" -n 10` | | YouTube | `yt-dlp` | `yt-dlp --dump-json URL` | -| Bilibili | `yt-dlp` | `yt-dlp --dump-json URL` | -| Reddit | `mcporter` (Exa) | `mcporter call 'exa.web_search_exa(query: "...", includeDomains: ["reddit.com"])'` | +| Bilibili | `yt-dlp` + `bili` | `bili hot` / `bili search "query" --type video` | +| Reddit | `rdt` | `rdt search "query"` / `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(...)'` | diff --git a/docs/update.md b/docs/update.md index d9c7789..30d630f 100644 --- a/docs/update.md +++ b/docs/update.md @@ -24,7 +24,7 @@ Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/ma ### Goal -Update Agent Reach to the latest version, then verify everything still works. +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. ### Step 1: Check current version @@ -32,44 +32,107 @@ Update Agent Reach to the latest version, then verify everything still works. agent-reach check-update ``` -If it says "已是最新版本", you're done — tell the user. +If it says "已是最新版本", skip to Step 5 (verify). Otherwise continue. -### Step 2: Update +### Step 2: Update Agent Reach package ```bash pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip ``` -### Step 3: Verify +### Step 3: Install / migrate upstream tools + +Run these commands to ensure all upstream CLI tools are installed. Skip any that are already installed. + +```bash +# === Required tools (core functionality) === + +# 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 + +# Reddit — rdt-cli (replaces Exa-based approach) +which rdt >/dev/null 2>&1 || pipx install rdt-cli 2>/dev/null || uv tool install 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" +``` + +### Step 4: Clean up deprecated tools + +```bash +# Remove bird CLI (repo deleted, replaced by twitter-cli) +which bird >/dev/null 2>&1 && npm uninstall -g @steipete/bird 2>/dev/null && echo "✅ Removed deprecated bird CLI" + +# Note: browser_cookie3 is still supported as fallback, no need to remove +# Note: miku_ai is no longer needed (WeChat now uses Exa), but no harm keeping it +``` + +### Step 5: Verify ```bash agent-reach version agent-reach doctor ``` -Report the new version and channel status to the user. If any channel changed status (was ✅ now ❌), investigate and fix. +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 4: Update SKILL.md (if installed) - -If the user has the Agent Reach skill installed, update it too: +### Step 6: Update SKILL.md (if installed) ```bash -agent-reach install --skill-only -``` +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' -If the `--skill-only` flag is not available, manually copy the latest SKILL.md: +skill_md = skill_pkg.joinpath('SKILL.md').read_text(encoding='utf-8') +refs_pkg = skill_pkg.joinpath('references') -```bash -python3 -c " -import importlib.resources, shutil, os -skill = importlib.resources.files('agent_reach').joinpath('skill', 'SKILL.md').read_text() -for d in [os.path.expanduser('~/.openclaw/skills/agent-reach'), - os.path.expanduser('~/.claude/skills/agent-reach')]: - if os.path.isdir(d): - with open(os.path.join(d, 'SKILL.md'), 'w') as f: - f.write(skill) - print(f'✅ Updated: {d}') +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}') " ``` -Done. Tell the user what version they're now on and how many channels are available. +### Step 7: 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) + +Done.