如何用 check-update 与 update.md 升级 Agent Reach 并验证渠道与 active

如何用 check-update 与 update.md 升级 Agent Reach 并验证渠道与 active_backend 迁移

【免费下载链接】Agent-ReachGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Reach

你手上已经装好 Agent Reach，现在要把它升到最新版本、把上游工具同步到新版，并确认升级后每个渠道仍然可用、多后端平台（小红书/Reddit/B站/Twitter）路由到了预期的后端。官方更新指南 docs/update.md 定义了完整路径：agent-reach check-update判断是否需要升级 → 升级本体包 → 只刷新已安装的上游工具 → 按共存规则保留旧后端 → 用agent-reach version和agent-reach doctor验证渠道状态与active_backend。前提是你通过 pip、pipx 或 venv 安装过agent-reach，升级过程不会动你的渠道配置和 Cookie。

第 1 步：用 check-update 判断是否需要升级

agent-reach check-update

命令会先打印当前版本: vX.Y.Z，然后向 GitHub API 查询最新版本。输出分四种情况（实现见 cli.py）：

✅ 已是最新版本：跳过升级步骤，直接做第 4 步验证。
最新版本: vX.Y.Z ← 有更新！：随后附上 release notes 的前 20 行（更新内容：），并给出两种更新方式——推荐给 AI Agent 的完整更新一句话（会完整更新本体 + 上游工具 + skill，对应 docs/update.md）和仅更新本体的 pip 命令。
无法检查更新（GitHub API 速率限制，请稍后重试）：命令已带指数退避重试（默认 3 次），仍失败就稍后再跑。
仓库还没有 release 时，回退到显示最新提交: <sha> (<date>) <message>并给出同样的更新方式。

第 2 步：升级 Agent Reach 本体包

有更新时执行：

pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip

如果 pip 报externally-managed-environment（PEP 668），说明当初是用 pipx 或 venv 安装的，用对应的安装方式：

# 当初用 pipx 安装的情况 pipx install --force https://github.com/Panniantong/agent-reach/archive/main.zip # 或先激活更新指南指定的 venv 再用 pip source ~/.agent-reach-venv/bin/activate

第 3 步：刷新上游工具（只升级已装的，不新装）

docs/update.md 的 Step 3 给出了一段刷新脚本，核心原则是只升级用户已经安装的工具，不安装任何新工具（唯一例外见下文 OpenCLI 可选分支）：

# 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 install --force 'yt-dlp[default]' 2>/dev/null || uv tool install --force 'yt-dlp[default]' 2>/dev/null || python -m pip install -U 'yt-dlp[default]' 2>/dev/null; } # rdt-cli is pinned to a git source (PyPI lags upstream) — same pin as the code's _RDT_GIT_SOURCE which rdt >/dev/null 2>&1 && pipx install --force 'git+https://github.com/public-clis/rdt-cli.git@5e4fb3720d5c174e976cd425ccc3b879d52cac66' 2>/dev/null # 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

副作用说明：这些命令会覆盖升级你已存在的全局工具（pipx/uv 工具和 npm 全局包），不会删除文件。每条命令都有which X >/dev/null 2>&1 &&前置判断，工具没装过就整行跳过，所以不会引入新工具。rdt-cli特意固定到与代码内_RDT_GIT_SOURCE（cli.py）相同的 git 提交，因为 PyPI 上的版本落后于上游。

可选分支——桌面用户引入 OpenCLI：自 v1.5.0 起 OpenCLI 是小红书/Reddit 的首选后端（并新增 B站字幕）。只有当用户明确同意时才安装：

agent-reach install --system --channels opencli

安装后需要用户在 Chrome 商店点一次『添加扩展』——这是唯一必须由人完成的操作。小红书走 OpenCLI 时只使用用户已有的 Chrome 会话，更新流程不会代用户登录或读取浏览器 Cookie。用户拒绝也没关系，所有渠道继续在既有后端上工作。

第 4 步：共存规则——不要卸载旧后端

docs/update.md 明确写了Never uninstall tools the user already has。退役后端（例如 yt-dlp 已不再承担 Bilibili、xhs-cli 不再默认安装）在仍可用的地方继续作为 fallback 工作，Agent Reach 会自动绕开它们（routes around them）；删不删由用户决定，升级流程不替用户做这个选择。

第 5 步：验证版本、渠道状态与 active_backend

升级完成后跑两条验证命令：

agent-reach version agent-reach doctor

agent-reach version输出形如Agent Reach v1.x.x，与check-update报告的最新版一致即说明本体升级生效。

agent-reach doctor（文本模式）的图例是✅ 可用 / [!] 已装但需配置/登录 / [X] 未安装（报告结构见 doctor.py）。判断后端迁移是否生效看两处：

多后端渠道（小红书/Reddit/B站/Twitter）在可用时会在行尾标注（当前后端：…）——这来自每个渠道的active_backend（doctor.py），是"迁移到了哪个后端"的直接证据；
加--json得到机器可读的同款数据，每个渠道都带active_backend字段，方便脚本核对：

agent-reach doctor --json

doctor 还会确认已检测到的 agent skill 目录中存在 Agent Reach skill；如果用户本地已有自定义 skill，doctor 会保留而不覆盖，只有明确要刷新内置 skill 文件时才运行agent-reach skill --install。

升级后渠道状态异常的判断

每个渠道都应显示 ✅ 或 [!] 并附带清晰消息。
如果某个之前可用的渠道现在显示 [X]/error，消息里会包含精确的修复处方（例如 venv-reinstall 的具体命令）——按消息执行后再跑一次agent-reach doctor复查。
可选渠道未安装属于正常现象（提示"还有 N 个可选渠道可以解锁"），不是升级失败。