工具说明：Agent-Reach

项目介绍

**它是什么。**Agent-Reach 是一个开源命令行工具，替智能体选好、装好、体检好一批读网页和社交平台的上游工具（Jina Reader、yt-dlp、gh、bili-cli、OpenCLI、mcporter 等），再附一份 SKILL.md 告诉智能体每个平台该调哪条命令。它解决的问题是：智能体默认能搜网页，但看不了 YouTube 字幕、搜不了 B 站、读不了推特和小红书。Agent-Reach 自己不做读取，读取由智能体按 SKILL.md 直接调用上游工具完成；它负责选型、安装、doctor 诊断和路由（按平台分派到对应工具）。官方 README 的说法是“能力层，不是又一个工具”。

核心能力：

• 一条命令装好各平台的上游读取工具；
• doctor 体检 16 个渠道，列出哪些可用、缺什么；
• SKILL.md 按平台告诉智能体该调哪条命令；
• 集中管理需要 Cookie、登录或 Key 的渠道配置。

**在同类工具里的位置：**它是一层“装配与路由”，不是读取工具本身。和 web-access 一样是 CLI＋Skill，但 web-access 接管日常浏览器的登录态，Agent-Reach 按平台调用现成的命令行工具。

**国内网络：**部分可用。B 站不登录可用，RSS 可用；“任意网页”渠道依赖的 Jina Reader 在国内连不上，doctor 显示可用也不代表能用；小红书要登录；YouTube、Reddit、X、V2EX 连不上。

官方链接

注意：PyPI 上有一个同名包 agent-reach（0.1.0，作者和仓库都不同）。官方 README 写明“不要从 PyPI 安装同名包，它不是本项目”，安装一律用 GitHub 的 zip 地址。

能做什么、不能做什么

16 个渠道，按门槛分三档（据 1.5.0 的 doctor 输出与 README）：

上表是官方的分档，没有考虑国内网络。国内网络下各渠道的情况：

不能做的事：

• 不做内容加工。官方 SKILL.md 写明它只负责“从互联网获取内容”，写报告、分析、翻译交给智能体本身。
• 不承诺稳定。上游接口随平台风控变化：1.5.0 发布说明写到 yt-dlp 已被 B 站风控拦截、B 站改走 bili-cli；仓库里还有 2026-10 新开的 Instagram、Twitter 适配失效 issue。
• doctor 的结论是某一时刻的快照，会有误报：Jina Reader 连不上时，“任意网页”仍显示 ✅（官方 issue #685 记录了同一问题）；yt-dlp 装在虚拟环境里、不在 PATH 上时，YouTube 会被标为“未安装”，实际能用。
• 国内网络下读不了境外平台（YouTube、Reddit、X、V2EX），网页渠道也不通。本文不写代理配置。
• 雪球行情 SKILL 写明“可能延迟，不构成投资建议”。

适合的任务：

• 在 B 站搜一个经济话题的公开讲解视频，列出标题、UP 主、链接，再看视频信息做要点整理。
• 用 RSS 跟踪几个国内可达的财经媒体或研究机构的更新。
• 观察“工具调用”的过程：智能体读 SKILL.md、选渠道、跑命令、读回结果，这一套过程正好对应本周主题；doctor 把不通的 Jina 标成 ✅，也是“工具自检结果要核对”的例子。

读政策或统计发布页的正文（国家统计局、人民银行、证监会）不走 Agent-Reach，改用 DeepSeek Fetch。

需要登录的渠道（小红书、推特、雪球、Boss 直聘）不建议用自己的账号配置，原因见“费用、额度、隐私与安全”。

安装与配置

前置条件

官方给的装法（install.md Step 1）：

1. pipx：官方标注“推荐：pipx（最省心）”。
2. venv（Python 虚拟环境，一个独立文件夹，里面装的包不影响系统里的其他 Python）：Python 来自 Homebrew、遇到 PEP 668 externally-managed-environment 报错时改用，目录约定为 ~/.agent-reach-venv。
3. uv：install.md 没有列出用 uv 装本体的方式。不要自行改用 uv tool install。

建议用 venv：Windows 电脑多数没有 pipx；出问题时把整个 venv 目录删掉就回到原状。

国内网络下的下载源：

• 本体：只有 GitHub 一个来源（https://github.com/Panniantong/agent-reach/archive/main.zip），国内能下，但速度时好时坏，失败就重试。Gitee 上没有找到 Agent-Reach 的官方镜像，不要用来历不明的转存。
• 依赖（requests、feedparser、yt-dlp 等）：用清华 PyPI 镜像，装得快。备选阿里云 https://mirrors.aliyun.com/pypi/simple/。
• 想让这台电脑上的 pip 默认都走清华源，可以执行一次 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple；只想这一次走镜像，在 pip install 后面加 -i https://pypi.tuna.tsinghua.edu.cn/simple。

安装命令有几个模式，要分清：

官方的一句话装法

官方 install.md 分“For Humans”和“For AI Agents”两节，后一节写明了目标、边界（不用 sudo、不改 ~/.agent-reach/ 以外的系统文件、不装清单外的包、不关防火墙、不在工作区里克隆仓库）、目录规则和逐步命令，本身就是写给智能体执行的。官方给人的用法是把一句话复制给智能体：

帮我安全检查并安装 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md

这句话太短，智能体可能顺手执行 --system、去装 gh 或 Node。建议用下面的提示词，边界写全。两端的差别在第 6 步：Claude Code 用 skill --install 注册，WorkBuddy 要手动复制到它的技能目录。下面是 Windows 版；Mac 把路径换成 ~/.agent-reach-venv。

交给智能体装：Claude Code 端

在项目文件夹里打开 Claude Code，复制下面这段：

请帮我安装 Agent Reach（官方仓库 https://github.com/Panniantong/Agent-Reach ），先读官方安装说明 https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md ，按它的 For AI Agents 一节操作，并遵守下面的要求：

1. 用虚拟环境安装：创建 %USERPROFILE%\.agent-reach-venv，安装地址用 https://github.com/Panniantong/agent-reach/archive/main.zip ，pip 加 -i https://pypi.tuna.tsinghua.edu.cn/simple 走清华镜像。不要从 PyPI 装同名包。Windows 上如果 python3 会打开微软商店，改用 py -3。GitHub 下载失败就重试，不要换成别的转存地址。
2. 不要激活虚拟环境（避免 PowerShell 脚本策略问题），直接用 %USERPROFILE%\.agent-reach-venv\Scripts\python.exe 和 Scripts\agent-reach.exe 的完整路径执行命令。
3. 只做两步检查：agent-reach install --env=auto（只读检查），再跑 agent-reach doctor。不要加 --system，不要用管理员权限，不要安装 gh、Node、mcporter、OpenCLI 或任何浏览器扩展；缺什么就列出来，问我要不要装。
4. 另外用同一个 venv 的 pip（同样走清华镜像）装 bilibili-cli，这是 B 站渠道的完整后端。
5. 不配置任何需要登录、Cookie 或 Key 的渠道（Twitter、小红书、Reddit、Facebook、Instagram、雪球、Boss 直聘、LinkedIn、小宇宙），不要读取我浏览器里的 Cookie，不要配置代理。
6. 装完后把 SKILL.md 注册给 Claude Code：运行 agent-reach skill --install，确认 ~/.claude/skills/agent-reach/ 里有 SKILL.md。
7. 自查：报告 agent-reach version 的输出、doctor 里每个渠道的状态；再用 Scripts\bili.exe 搜一次“CPI 解读”，取 3 条视频的标题和 BV 号。doctor 里“任意网页”显示可用也不代表能用（它依赖的 Jina Reader 在国内连不上），不要拿它读网页。
8. 遇到要输入 Key、要登录、要管理员授权、要从官方清单以外的地址下载东西时，停下来问我。

交给智能体装：WorkBuddy 端

在 WorkBuddy 里新建任务，复制下面这段：

请帮我安装 Agent Reach（官方仓库 https://github.com/Panniantong/Agent-Reach ），先读官方安装说明 https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md ，按它的 For AI Agents 一节操作，并遵守下面的要求：

1. 用虚拟环境安装：创建 %USERPROFILE%\.agent-reach-venv，安装地址用 https://github.com/Panniantong/agent-reach/archive/main.zip ，pip 加 -i https://pypi.tuna.tsinghua.edu.cn/simple 走清华镜像。不要从 PyPI 装同名包。Windows 上如果 python3 会打开微软商店，改用 py -3。GitHub 下载失败就重试，不要换成别的转存地址。
2. 不要激活虚拟环境（避免 PowerShell 脚本策略问题），直接用 %USERPROFILE%\.agent-reach-venv\Scripts\python.exe 和 Scripts\agent-reach.exe 的完整路径执行命令。
3. 只做两步检查：agent-reach install --env=auto（只读检查），再跑 agent-reach doctor。不要加 --system，不要用管理员权限，不要安装 gh、Node、mcporter、OpenCLI 或任何浏览器扩展；缺什么就列出来，问我要不要装。
4. 另外用同一个 venv 的 pip（同样走清华镜像）装 bilibili-cli，这是 B 站渠道的完整后端。
5. 不配置任何需要登录、Cookie 或 Key 的渠道（Twitter、小红书、Reddit、Facebook、Instagram、雪球、Boss 直聘、LinkedIn、小宇宙），不要读取我浏览器里的 Cookie，不要配置代理。
6. 装完后把 SKILL.md 注册给 WorkBuddy：agent-reach skill --install 不写 WorkBuddy 的目录，请把 venv 里 Lib\site-packages\agent_reach\skill 整个文件夹（含 references）复制到 %USERPROFILE%\.workbuddy\skills\agent-reach\。
7. 自查：报告 agent-reach version 的输出、doctor 里每个渠道的状态；再用 Scripts\bili.exe 搜一次“CPI 解读”，取 3 条视频的标题和 BV 号。doctor 里“任意网页”显示可用也不代表能用（它依赖的 Jina Reader 在国内连不上），不要拿它读网页。
8. 遇到要输入 Key、要登录、要管理员授权、要从官方清单以外的地址下载东西时，停下来问我。

按这两段提示词，智能体遇到超出边界的步骤（例如补装 gh 需要 brew 或 winget）时应停下来问你，而不是绕过去；如果它没停，你在权限弹窗里拒绝即可。

智能体会请求哪些权限

要你亲手做的部分

• 决定开哪些渠道。install.md Step 2 要求智能体列出可选渠道请用户选，这一步要你回答。
• GitHub 渠道（这里不配）：装好 gh 后运行 gh auth login，在浏览器里用自己的 GitHub 账号授权。doctor 只有检测到 gh 已登录才标为可用。
• 需要登录的平台（不建议配）：在浏览器里本人登录；Chrome 扩展（OpenCLI、Cookie-Editor）要你在扩展商店本人点“添加至 Chrome”，官方写明智能体无法代点。国内连不上 Chrome 应用店，这些扩展装不上。
• Groq Key（小宇宙转写）（这里不配）：要到境外的 https://console.groq.com 申请。官方命令 agent-reach configure groq-key 用隐藏输入，Key 不会回显；不要把 Key 直接打在对话框里。
• 重开客户端：Skill 注册后新开一个会话（Claude Code 重新运行 claude，WorkBuddy 新建任务），智能体才会看到它。

参考：手动安装命令

Windows 11 x64（PowerShell），来源为 install.md 的 Windows 示例，改成不激活 venv 的写法。

先确认 Python 可用（不要用会打开微软商店的 python3）：

py -3 --version

创建虚拟环境并安装（本体来自 GitHub，依赖走清华镜像）：

py -3 -m venv $env:USERPROFILE\.agent-reach-venv
& "$env:USERPROFILE\.agent-reach-venv\Scripts\python.exe" -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple https://github.com/Panniantong/agent-reach/archive/main.zip

装 B 站完整后端 bili-cli（PyPI 包名 bilibili-cli）：

& "$env:USERPROFILE\.agent-reach-venv\Scripts\python.exe" -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple bilibili-cli

只读检查与诊断，再注册 SKILL.md（写入已存在的 ~/.claude/skills、~/.agents/skills 等目录）：

& "$env:USERPROFILE\.agent-reach-venv\Scripts\agent-reach.exe" install --env=auto
& "$env:USERPROFILE\.agent-reach-venv\Scripts\agent-reach.exe" doctor
& "$env:USERPROFILE\.agent-reach-venv\Scripts\agent-reach.exe" skill --install

用 WorkBuddy 时，再把 Skill 复制到 WorkBuddy 的个人技能目录：

Copy-Item -Recurse "$env:USERPROFILE\.agent-reach-venv\Lib\site-packages\agent_reach\skill" "$env:USERPROFILE\.workbuddy\skills\agent-reach"

install.md 原文用的是 Activate.ps1 激活 venv。若 PowerShell 报“禁止运行脚本”，不要改执行策略，按上面写完整路径即可。

doctor 的提示写的是 pipx install bilibili-cli；按本文的 venv 装法，用同一个 venv 的 pip 即可，装好后命令在 Scripts\bili.exe。

可选（这里不需要）：GitHub 渠道补装 gh（gh 官方提供 winget 安装方式）：

winget install --id GitHub.cli
gh auth login

macOS（install.md 原文，加了清华镜像）。方式一 pipx（官方推荐）：

pipx install --index-url https://pypi.tuna.tsinghua.edu.cn/simple https://github.com/Panniantong/agent-reach/archive/main.zip

方式二 venv（Homebrew Python 或遇到 PEP 668 时）：

python3 -m venv ~/.agent-reach-venv
source ~/.agent-reach-venv/bin/activate
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple https://github.com/Panniantong/agent-reach/archive/main.zip
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple bilibili-cli

装好后：

agent-reach install --env=auto     # 只读检查
agent-reach doctor
agent-reach skill --install        # 注册 SKILL.md

更新：把 update.md 的地址交给智能体（“帮我更新 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md”），或手动 pip install --upgrade -i https://pypi.tuna.tsinghua.edu.cn/simple https://github.com/Panniantong/agent-reach/archive/main.zip。卸载：agent-reach uninstall（会删除 ~/.agent-reach/ 里的全部 Token 和 Cookie、各客户端的 skill 文件、mcporter 配置），再删除 venv 目录。

Claude Code 端说明

• Skill 位置：agent-reach skill --install 会把 SKILL.md 和 references/*.md 复制到已经存在的这几个目录：~/.agents/skills/、~/.config/opencode/skills/、~/.openclaw/skills/、~/.claude/skills/。用过 Claude Code 的电脑一般已有 ~/.claude/skills/，Skill 会装到 ~/.claude/skills/agent-reach/，所有项目可用。
• 只想在某个项目里用：把 venv 里 site-packages/agent_reach/skill/ 整个文件夹复制到项目的 .claude/skills/agent-reach/。
• 不需要 claude mcp add。Agent-Reach 不是 MCP 服务器；它要求智能体能执行命令，Claude Code 的 Bash 工具即可。Exa、小红书服务器版这类渠道走的是 mcporter（一个命令行 MCP 客户端），也不进 Claude Code 的 MCP 列表。
• PATH：venv 方式安装后 agent-reach、bili、yt-dlp 不在 PATH 上（PATH 是系统查找命令的目录清单）。SKILL.md 里的命令写的是裸命令名（yt-dlp ...），智能体可能报“找不到命令”。处理办法是在项目 CLAUDE.md 里写一句“agent-reach、bili 和 yt-dlp 在 %USERPROFILE%\.agent-reach-venv\Scripts\ 下，用完整路径调用”。
• 经 CC Switch 接 DeepSeek 时，Skill 的触发靠模型读描述。SKILL.md 的描述写得很宽（“调研、搜索、查、找”都要用它），可能抢走其他搜索工具的任务；不想让它触发时，在提示词里写明“这次不用 agent-reach”。
• 如果 ~/.claude/skills/agent-reach/ 里已有旧版 Skill（描述写 13+ 平台、Twitter 用 bird），先按 update.md 更新，或删掉旧 Skill 再重新注册，避免智能体按过时命令执行。

WorkBuddy 端说明

• agent-reach skill --install 的目录清单里没有 WorkBuddy 的目录，要手动复制：个人级放 ~/.workbuddy/skills/agent-reach/（Windows 为 %USERPROFILE%\.workbuddy\skills\agent-reach\），只给某个项目用就放 <工作区>/.workbuddy/skills/agent-reach/。复制的是整个文件夹（SKILL.md 加 references/）。放好后新建任务，在输入框输入 / 能在技能列表里看到它。
• 不需要在“连接器”或 .workbuddy/mcp.json 里加任何东西。
• Python 可以用 WorkBuddy 自带的那份，不必另装。提示词里写 py -3，电脑上没有系统 Python 时再让它找 WorkBuddy 自带的。
• 创建 venv 时如果安全软件拦截了 pip/__pycache__ 的删除，ensurepip 会返回 1，但 pip 往往仍可用。看到这类报错先让它检查 python -m pip --version，能用就继续，不用重来。

Key、Cookie 放在哪里

• Agent-Reach 的 Token、Cookie、代理地址保存在 ~/.agent-reach/config.yaml，README 称文件权限为 600（只有本人账户能读写）、不上传。
• 写入一律用 agent-reach configure <项目>（隐藏输入）或 --stdin，不要把 Cookie 或 Key 粘进对话框、写进项目文件或截图。
• 官方 SKILL.md 规定临时文件放 /tmp/、持久数据放 ~/.agent-reach/，不在工作区创建文件。分享项目文件夹前不必担心它在项目里留下凭据，但要确认对话记录里没有你粘过的 Cookie。

怎样确认装好了

1. agent-reach version 输出 1.5.0（或更新的版本）。
2. agent-reach doctor 显示“N/16 个渠道可用”。只装本体、什么都不补时，国内网络下是 3/16：RSS、任意网页、B 站（仅搜索）；V2EX 报超时。其中“任意网页”的 ✅ 是误报，见下一条。
3. 不要用网页渠道验收。curl https://r.jina.ai/... 在国内网络下等很久也没有响应，doctor 的 ✅ 没有反映 Jina 的实际连通情况。
4. B 站读一次能出结果：<venv>\Scripts\bili.exe search "CPI 解读" --type video -n 3 返回 3 条视频的标题、UP 主和 BV 号。
5. 新开会话，问智能体“你有哪些技能”，或在 WorkBuddy 输入 /，能看到 agent-reach。
6. YouTube 显示 [X]、V2EX 显示超时，是国内网络连不上这两个站，不用处理。

使用教程：查 9 月 CPI 的官方原文与 B 站公开解读视频

目标：读国家统计局关于 9 月 CPI 的发布原文，摘出同比、环比数字并附原文链接；再在 B 站搜几条相关的公开解读视频，列成表。只用国内网络可达、不需登录的渠道。

Agent-Reach 在国内网络下负责 B 站这一半。读统计局原文这一半，Agent-Reach 的网页渠道（Jina Reader）连不上，改用 DeepSeek 搜索与读取（deepseek-web Skill）：先 Search 拿到发布稿链接，再 Fetch 读具体发布稿。

可直接复制的提示词：

请完成下面的任务。agent-reach 和 bili 装在 %USERPROFILE%\.agent-reach-venv\Scripts\ 下，用完整路径调用；开始前先运行一次 agent-reach doctor，把各渠道状态记下来。

1. 用 deepseek-web 技能先搜索“国家统计局 2026年9月 居民消费价格”，从结果里找到国家统计局官网（www.stats.gov.cn）的发布稿链接，再用 fetch 读这篇发布稿，摘出全国 CPI 同比、环比涨幅，以及食品、非食品各自的同比涨幅，每个数字后面附原句和原文链接。fetch 第一次返回 failed to fetch URL 时，同一网址重试一次。不要读“最新发布”列表页，它是动态页面，读不出文章。不要用 agent-reach 的网页渠道（Jina Reader），它在国内网络下连不上。
2. 用 agent-reach 的 B 站渠道（bili search，没有 bili 时用 doctor 里的 B 站搜索兜底）搜“9月CPI 解读”，取前 5 条视频的标题、UP 主、BV 号链接。相关性明显不对的条目标出来，不要删。
3. 把结果写进当前项目的 output/cpi_2026-09.md：第一节是数字表（指标、数值、原句、链接），第二节是视频表，第三节写你每一步用了哪个工具、执行了什么命令、哪一步失败了及报错原文。
4. 不登录任何平台，不读取浏览器 Cookie，不安装新工具，不配置代理；哪个渠道不通就记录报错，不要绕过。

第 3 步的输出路径是你明确指定的，与 SKILL.md“不在工作区创建文件”的默认规则冲突时，以你的指定为准；如果智能体坚持写到 /tmp，在提示词里重申一次即可。

预期看到的工具调用：

产出文件：output/cpi_2026-09.md，三节。

验收：

• 打开第一节的每个链接，原句和数字要与页面一致。统计局这篇发布稿 2026-10-14 发布，标题为“2026年9月份居民消费价格同比上涨0.9%”；其余数字以原文为准。
• 视频表的链接能打开，标题与链接对应。搜“9月CPI 解读”的前几条里可能混入讲三季度 GDP 或 CPI 概念课的视频，相关性参差，看智能体有没有标出来。
• 第三节的命令能在终端复现，doctor 记录里能看到“任意网页”显示可用而智能体没有用它。

常见问题与排错

费用、额度、隐私与安全

• 费用：工具和零配置渠道不收费。Jina Reader 不带 Key 时有调用频率限制（国内网络下连不上，这里不用）；README 写 Exa 经 mcporter 接入“免费无需 Key”，这里不配。小宇宙转写用 Groq 免费额度，install.md 写约每小时 2 小时音频。积分消耗：WorkBuddy 跑一轮 Agent-Reach 安装加试用约 15 积分。
• 封号风险：官方 README 警告，用 Cookie 登录的平台“存在被平台检测并封号的风险”，要求使用专用小号，不要用主账号。原因有两条：平台可能识别出非浏览器调用而限制或封禁账号；Cookie 等同完整登录权限，泄露后影响面就是整个账号。小红书、推特、微博类账号常与手机号和实名绑定，不要拿日常账号试。
• 登录态：OpenCLI 类渠道复用 Chrome 里已登录的会话，等于让智能体以你的身份浏览这些网站。Boss 直聘渠道会启动带远程调试端口（9222）的专用 Chrome，官方提醒本机任何进程都能通过这个端口控制该浏览器，必须绑定 127.0.0.1、用独立 profile、不用时关掉。
• Cookie 读取：agent-reach configure --from-browser chrome --platform xueqiu 会从浏览器读取指定平台的 Cookie（官方称只读该平台、雪球只存 xq_a_token）。这类命令要你本人发起，不要让智能体自己决定执行。
• 凭据存放：全部在 ~/.agent-reach/config.yaml；agent-reach uninstall 会一并删除。
• 遥测：Agent-Reach 源码里没有自身遥测。调用 gh 时它设置了 GH_TELEMETRY=false、DO_NOT_TRACK=true（源码 channels/github.py），可见 gh 本身有遥测。check-update 会访问 GitHub API 查新版本，SKILL.md 要求智能体在大任务后顺手跑一次。
• 合规：抓取平台内容受各平台用户协议约束。只做少量、公开内容的读取，不批量采集，不发帖（SKILL.md 也写明不负责发帖、评论、点赞）。

与同类工具对比

和 DeepSeek 搜索与读取这类网页工具比，Agent-Reach 不需要 API Key、能进 B 站这类平台内部，但要在电脑上装一串上游命令行工具，稳定性随平台风控波动，国内网络下能用的渠道只有 B 站、RSS 等少数几个；只要“搜网页、读网页”，用 DeepSeek Search／Fetch 更省事（Claude Code 自带的 WebFetch 在国内网络下不可用）。和 web-access 比，Agent-Reach 不碰日常浏览器，按平台调现成命令行工具。

信息来源