docs: rewrite update.md for v1.4.0 upstream migrations

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) <noreply@anthropic.com>
2026-03-31 18:36:43 +08:00
parent 0f9cfe66ec
commit 65ff8d69d0
2 changed files with 90 additions and 28 deletions
@@ -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(...)'` |
@@ -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.