人工智能AI AgentMCP 服务AI 技能CLI【免费下载链接】Agent-Reach给你的 AI Agent 一键装上互联网能力。13 个平台网页/GitHub/YouTube/小红书/B站/Twitter/Reddit 等多后端路由当下最稳的接入方式替你选好、装好、体检好。GitHub 主仓库同步镜像。项目地址https://gitcode.com/Panniantong/Agent-Reach点击查看免费下载本篇指南以 Agent Reach 的官方更新文档docs/update.md为核心骨架系统讲解该项目面向 AI Agent 的完整升级流程如何检测新版本、升级 Python 包本体、刷新上游工具链twitter-cli / bili-cli / yt-dlp / rdt-cli / mcporter / OpenCLI、迁移退役后端以及通过doctor体检确认升级结果。读完你将掌握一套人工零干预、Agent 可自主执行的更新方法论并理解其背后的源码级设计语义化版本比较、带退避重试的 GitHub API 探测、多后端路由与共存策略。一、文档定位给人与给Agent的双通道指南Agent Reach 的更新指南是一个双通道文档前半部分面向人类用户后半部分## For AI Agents是写给 AI Agent 的结构化任务书。它刻意设计成复制一句话给 Agent 即可执行的形态例如帮我更新 Agent Reachhttps://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md这句话同时也是 agent_reach/cli.py 中_UPDATE_INSTRUCTIONS内置的推荐更新方式——源码注释明确说明这条一句话会让 Agent 完整更新本体 上游工具 skill三个部分而裸pip install只更新本体。该文档的实战价值在于它不只是一个命令清单而是一套完整的升级策略先探测、再升级、后体检、最后汇报任何一步出错都有明确的降级或修复路径。二、升级前置约束Workspace 与目录红线更新文档开篇### ⚠️ Workspace Rules立下了两条不可逾越的红线这是 Agent 在执行更新任务时的行为边界绝不在 Agent 工作区workspace内创建文件、克隆仓库或运行命令临时工作一律使用/tmp/持久化数据一律放在~/.agent-reach/。这与 docs/install.md 的 Directory Rules 一脉相承所有配置、Token、上游工具仓库都收敛在专用目录~/.agent-reach/、~/.agent-reach/tools/避免污染用户的项目目录。更新的最终目标也很明确——用户不需要手动做任何事除浏览器扩展安装这类只有人能完成的点击操作。三、Step 1检测当前版本——check-update的源码级拆解更新流程的第一步是运行agent-reach check-update如果输出已是最新版本直接跳到验证环节Step 5否则继续后续步骤。这个命令背后的实现非常值得展开在 agent_reach/cli.py 中_cmd_check_update()会先打印当前版本v{__version__}然后通过_github_get_with_retry()请求 GitHub Releases API 获取最新 release 标签tag_name并展示 release notes 的前 20 行作为更新内容预览随后输出内置的更新指引。几个源码级的关键设计语义化版本比较防降级提示_is_newer_version()cli.py不是简单的!比较而是解析x.y.z逐段比较大小。测试用例tests/test_cli.py明确验证了四种场景远端更新触发提示、版本相等不提示、本地领先于远端 release 时不提示降级避免发版窗口期本地装了main却被诱导降级、无法解析的版本回退到不等比较。带指数退避的重试_github_get_with_retry()cli.py默认重试 3 次每次退避2^(attempt-1)秒遇到 GitHub 速率限制429/403 X-RateLimit-Remaining: 0时还会读取Retry-After头作为延长等待。错误会被分类为timeout/dns/rate_limit/server_error等并映射为中文提示如网络超时、DNS 解析失败测试 test_check_update_reports_classified_error 验证了超时场景下输出已重试 3 次的诊断信息。无 release 时回退到 main 提交若仓库尚未发布任何 release则查询最新main提交展示短 SHA、日期与提交信息保证检测逻辑在任何阶段都可用。四、Step 2升级 Agent Reach 本体检测到新版本后升级 Python 包本体pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip文档特别标注了一个高频坑位如果pip报externally-managed-environment即 PEP 668 环境说明用户当初是通过 pipx 或虚拟环境安装的应改用对应命令pipx install --force https://github.com/Panniantong/agent-reach/archive/main.zip或先激活~/.agent-reach-venv安装指南 docs/install.md 中提供了python3 -m venv ~/.agent-reach-venv的创建方式五、Step 3刷新上游工具——只升级、不新装Agent Reach 的架构哲学是选择器、安装器、体检器和路由器而不是包装器安装完成后Agent 直接调用上游工具OpenCLI、twitter-cli、bili-cli、rdt-cli、yt-dlp、mcporter、gh CLI 等。因此更新时刷新上游工具签名至关重要。更新文档给出了一条黄金原则只升级用户已有的工具绝不安装用户没要求过的新工具唯一例外是桌面端的 OpenCLI见下文。完整命令如下# Python-based CLIs the user already has (upgrade keeps signatures fresh) which twitter /dev/null 21 { pipx upgrade twitter-cli 2/dev/null || uv tool upgrade twitter-cli 2/dev/null; } which bili /dev/null 21 { pipx upgrade bilibili-cli 2/dev/null || uv tool upgrade bilibili-cli 2/dev/null; } which xhs /dev/null 21 { pipx upgrade xiaohongshu-cli 2/dev/null || uv tool upgrade xiaohongshu-cli 2/dev/null; } which yt-dlp /dev/null 21 { 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 codes _RDT_GIT_SOURCE which rdt /dev/null 21 pipx install --force githttps://github.com/public-clis/rdt-cli.git5e4fb3720d5c174e976cd425ccc3b879d52cac66 2/dev/null # npm-based which mcporter /dev/null 21 npm update -g mcporter 2/dev/null which opencli /dev/null 21 npm update -g jackwener/opencli 2/dev/null这套命令的工程智慧在于每一条都以which tool为前置守卫只有已安装的工具才会被升级天然满足不新装约束同时 pipx / uv / pip 三级回退保证了不同安装方式的兼容性。关于 rdt-cli 的 git 源码 pin源码给出了权威解释在 agent_reach/cli.py 中_RDT_GIT_SOURCE被 pin 到5e4fb3720d5c174e976cd425ccc3b879d52cac66这一固定提交注释说明PyPI 仍停留在 0.4.1上游 issue #10即 PyPI 版本滞后于上游因此安装/升级必须以固定 git 提交为准。同理boss-agent-cli 也被 pin 到包含 PR #403-#407 的固定提交cli.py并明确绝不指向移动分支。5.1 桌面端 OpenCLI 的一次性邀约自 v1.5.0 起OpenCLI 成为小红书 / Reddit 的首选后端并为 B 站补充字幕能力但更新过程绝不代用户登录、绝不读取浏览器 Cookie——因为 Chrome 扩展只能由用户手动点击安装。因此更新指南要求 Agent 用一段固定话术向用户提出一次性邀约这次更新引入了 OpenCLI 后端。要装吗装完只需你在 Chrome 商店点一次『添加扩展』。小红书 OpenCLI 只使用你已有的 Chrome 会话如果没有现成会话我不会自动登录会改用 Cookie-Editor 配置 MCP / 存量工具。若用户同意则执行agent-reach install --system --channels opencli并引导用户完成扩展点击若拒绝一切继续在既有后端上运行不做任何破坏性操作。这一设计的源码支撑在 cli.py 的_install_opencli_deps()npm 包可以自动安装但扩展安装被注释明确标记为必须手动Chrome 安全限制安装完成后打印扩展 URL 与添加至 Chrome操作指引。六、Step 4共存策略——绝不卸载旧工具更新文档在Coexistence一节立下了一条重要纪律绝不卸载用户已有的工具。退役后端例如 yt-dlp 已不再服务 Bilibilixhs-cli 不再默认安装只要还能工作就继续作为 fallback 存在Agent Reach 会自动路由绕过它们——是否卸载由用户决定而不是由升级流程决定。这正是多后端路由机制的实际体现。从 agent_reach/channels/base.py 的类注释可以推断出核心语义backends是有序候选列表backends[0]为首选其余为后备切换后端就是重排此列表或应用用户覆盖而非重写代码check()必须把实际正在服务的后端写入self.active_backend无可用时置None用户可通过配置键channel_backend或环境变量CHANNEL_BACKEND强制指定后端ordered_backends()会将其移到队首未知值被静默忽略防止过时覆盖隐藏掉可用后端。以小红书为例agent_reach/channels/xiaohongshu.py其backends [OpenCLI, xiaohongshu-mcp, xhs-cli (xiaohongshu-cli)]探测顺序让环境差异自动生效OpenCLI 需要桌面 Chrome在服务器上永远不会探测成功此时 xiaohongshu-mcp 接管而 xhs-cli上游自 2026-03 起停止维护对存量安装仍是最后一位候选。这就是退役后端继续作为 fallback的落地实现。七、Step 5验证升级——doctor 体检与 skill 同步升级完成后执行双命令验证agent-reach version agent-reach doctor7.1 doctor 的附加职责skill 同步运行agent-reach doctor文本模式还会顺带确保 Agent 技能目录中存在 Agent Reach skill若用户已有 skilldoctor 会保留而非覆盖本地定制。只有当你明确想刷新内置 skill 文件时才使用agent-reach skill --install对应源码是 cli.py 的_install_skill()它会向所有已存在的技能根目录~/.agents/skills、~/.config/opencode/skills、~/.openclaw/skills、~/.claude/skills以及OPENCLAW_HOME指定的目录安装 skill在forceFalse且目标已存在SKILL.md时返回preserved而非覆盖。语言选择上它会按AGENT_REACH_LANG/LC_ALL/LC_MESSAGES/LANG环境变量自动挑选SKILL_en.md或SKILL.md。7.2 如何读懂 doctor 输出检查 doctor 输出时关注三点每个渠道显示 ✅ / [!]并附明确消息多后端渠道小红书 / Reddit / B 站 / Twitter会报告当前后端…若某个此前正常的渠道现在显示 [X] 或 error消息中会直接给出精确修复方案例如 venv 重装处方照做后重新体检即可--json提供机器可读输出每个渠道包含active_backend字段。这些输出格式的实现位于 agent_reach/doctor.pycheck_all()doctor.py遍历所有渠道收集状态字典含status、tier、backends、active_backend并做了两级健壮性设计——单个渠道异常被降级为statuserror绝不拖垮整个报告所有消息在输出前经scrub_url_credentials()清洗防止上游探测输出回显已配置的 URL 凭据。format_report()doctor.py则按 tier 分组渲染tier 0装好即用、tier 1/2可选渠道并在backends多于一个时显示当前后端{active_backend}最后还会做一次配置安全审计——若~/.agent-reach/config.yaml权限过宽其他用户可读会给出chmod 600修复提示。--json模式的实现对应 cli.py 的_cmd_doctor()读取只读配置后调用check_all()以ensure_asciiFalse输出缩进 JSON。八、Step 6向用户汇报升级结果最后一步是把结果翻译成用户可读的信息文档要求的汇报要素有四当前版本号来自agent-reach version可用渠道数量以及每个多后端平台当前使用的后端来自 doctor任何需要用户亲自操作的事项如 Chrome 扩展点击、小红书走 MCP/存量工具时的 Cookie-Editor 手动导出本次更新的内容来自check-update展示的 release notes。至此一次完整的 Agent Reach 升级闭环结束。九、进阶watch命令与定时巡检除手动升级外cli.py 还提供了专为定时任务设计的watch命令它合并了渠道体检与版本检测只在有问题时输出——一切正常时仅打印一行全部正常 (N/N 渠道可用已是最新)便于 cron 等调度器按输出判断是否需要告警。其版本比较复用了与check-update相同的_is_newer_version()语义见测试 tests/test_cli.py保证本地领先远端 release 时不会误报新版本可用。对于运维大量 Agent 机器的场景watch的静默成功 / 显式告警模式比doctor更适合无人值守巡检。十、小结更新即治理回顾整个更新流程Agent Reach 把升级变成了一门克制的治理艺术只升级已装工具、不卸载任何存量后端、不代用户登录、不读浏览器 Cookie一切破坏性决策都交还用户。配合源码层的语义化版本比较、GitHub API 重试与错误分类、多后端有序探测与用户覆盖机制这套流程既能保证升级成功率又能在任何一步失败时给出可执行的修复处方——这正是选择器 安装器 体检器 路由器架构在运维侧的自然延伸。关联阅读安装指南 docs/install.md、故障排查 docs/troubleshooting.md、Cookie 导出 docs/cookie-export.md。赞分享人工智能AI AgentMCP 服务AI 技能CLI【免费下载链接】Agent-Reach给你的 AI Agent 一键装上互联网能力。13 个平台网页/GitHub/YouTube/小红书/B站/Twitter/Reddit 等多后端路由当下最稳的接入方式替你选好、装好、体检好。GitHub 主仓库同步镜像。项目地址https://gitcode.com/Panniantong/Agent-Reach点击查看免费下载相关推荐现在转 AI 应用开发是不是机会从 MCP 到 Agent 的学习路线与实战项目拆解CodeGuide 篇现在转 AI 应用开发是不是机会从 MCP 到 Agent 的学习路线与实战项目拆解CodeGuide 篇 本文以 CodeGuide 仓库中《现在转AI文档教程后端YASB Update Check 组件实战指南聚合 Windows Update、Winget 与 Scoop 的更新检测与一键升级YASB Update Check 组件实战指南聚合 Windows Update、Winget 与 Scoop 的更新检测与一键升级 本文围绕 yasbA桌面应用npm-check-updatesncu依赖升级实战指南从 dry run、--doctor 到 .ncurc 配置与编程式 APInpm check updatesncu依赖升级实战指南从 dry run、 doctor 到 .ncurc 配置与编程式 API 本篇以仓库中 skil开发工具CLI上一篇video-compress-cj 开发者指南如何扩展新视频格式与自定义压缩质量档位下一篇你的旧Mac能装哪个macOSOCLP-Mod支持机型对照清单与版本选择指南Big Sur到Sequoia全覆盖创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考