---
title: "W07 工具说明：Agent-Reach"
---

# Agent-Reach

## 项目介绍

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

| 项 | 内容 |
| --- | --- |
| 开发与维护 | GitHub 个人开发者 Panniantong（显示名 Pnant） |
| 开源与许可证 | 开源，MIT |
| 首次发布 | 仓库建于 2026-02-24；首个 GitHub Release 为 v1.1.0，2026-02-25 |
| 最新版本 | v1.5.0，2026-06-11；之后 main 分支仍有提交，版本号未变 |
| GitHub 星数与最近提交 | 约 9.9 万星；默认分支最近一次提交 2026-10-07（2026-10 核查） |
| 接入方式 | CLI＋Skill：CLI 是命令行程序，Skill 是一份告诉智能体怎么用这些命令的说明书（`SKILL.md`） |

**核心能力：**

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

**在同类工具里的位置：**它是一层“装配与路由”，不是读取工具本身。和 [web-access](https://ai.lingnan.top/materials/2026-autumn/w07/tool-07-web-access) 一样是 CLI＋Skill，但 web-access 接管日常浏览器的登录态，Agent-Reach 按平台调用现成的命令行工具。

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

## 官方链接

| 项目 | 链接或内容 |
| --- | --- |
| GitHub 仓库 | https://github.com/Panniantong/Agent-Reach |
| 安装说明（写给智能体读） | https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md |
| 更新说明（写给智能体读） | https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md |
| 常见问题 | https://github.com/Panniantong/Agent-Reach/blob/main/docs/troubleshooting.md |
| 发布记录 | https://github.com/Panniantong/Agent-Reach/releases |
| 更新日志 | 仓库根目录 `CHANGELOG.md` |
| 价格页 | 无。工具本身免费；README 称唯一可能的花费是部署在服务器上时的代理（约 1 美元／月），本地电脑不需要 |
| 版本 | v1.5.0，2026-06-11 发布（“能力层：多后端路由＋真体检＋OpenCLI”）；之前是 v1.4.2（2026-06-10）、v1.4.0（2026-03-31）、v1.3.0（2026-03-04，含 Windows 修复）（2026-10 核查） |

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

## 能做什么、不能做什么

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

| 档 | 渠道 | 需要什么 |
| --- | --- | --- |
| 装好即用 | 任意网页（Jina Reader）、RSS（feedparser）、V2EX、B 站搜索（搜索 API 兜底） | 只要 `pip` 装好本体 |
| 补装工具后可用，不需登录 | YouTube 搜索与字幕（yt-dlp，随本体装进来，另需 JS 运行时）、B 站完整版（bili-cli）、全网语义搜索（Exa，经 mcporter 接入，要 Node.js） | `--system` 授权安装上游工具 |
| 要登录或 Key | GitHub（gh CLI＋`gh auth login`）、Twitter/X（Cookie）、Reddit（登录态，没有零配置路径）、小红书、Facebook、Instagram（OpenCLI 复用 Chrome 登录态）、雪球（Cookie）、LinkedIn（专用浏览器登录）、Boss 直聘（专用 Chrome 手动登录）、小宇宙播客转写（Groq Key） | 用户本人登录、导出 Cookie 或申请 Key |

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

| 渠道 | 国内网络下 | 怎么用 |
| --- | --- | --- |
| B 站搜索与视频信息 | 可用，不需登录。doctor 自带的 curl 兜底会先取 B 站首页 Cookie，再带浏览器信息调搜索接口，能搜到视频；从清华源装 bili-cli 后，`bili search`、`bili hot` 正常 | 主用渠道 |
| RSS | 可用；能不能读取取决于订阅源本身是否在国内可达 | 选国内可达的订阅源 |
| 任意网页（Jina Reader） | 连不上，读不回内容；doctor 仍显示 ✅ | 不用。读网页改用 [DeepSeek 搜索与读取](https://ai.lingnan.top/materials/2026-autumn/w07/tool-01-deepseek-web)或本地浏览器类工具 |
| 小红书 | 首页、搜索页都跳转登录，三种后端都要 Cookie 或扫码 | 不建议用自己的账号配 |
| 雪球、Boss 直聘、小宇宙 | 需要登录或配置 | 不配 |
| V2EX、YouTube、Reddit、X | 国内连不上（doctor 里 V2EX 报超时） | 不用，也不配代理 |
| GitHub 渠道 | 需要装 gh 并登录 | 不配 |
| 全网语义搜索（Exa） | 境外服务，要 Node.js 与 mcporter | 不配；网页搜索用 DeepSeek Search |

不能做的事：

- 不做内容加工。官方 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 直聘）不建议用自己的账号配置，原因见“费用、额度、隐私与安全”。

## 安装与配置

### 前置条件

| 依赖 | 用途 | 说明 |
| --- | --- | --- |
| Python 3.10 及以上 | 运行本体 | `pyproject.toml` 写明 `requires-python >= 3.10`。WorkBuddy 自带一份 Python，也可以用 |
| curl | 网页渠道 | Windows 10/11 自带 `curl.exe` |
| Node.js | mcporter（Exa 搜索、小红书服务器版）、OpenCLI | 只走零配置渠道时可以不装 |
| gh CLI | GitHub 渠道 | 要单独安装并登录 GitHub 账号 |
| Chrome | OpenCLI 类渠道 | 只在配需要登录的平台时用到 |

官方给的装法（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`。

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

| 命令 | 作用 |
| --- | --- |
| `agent-reach install --env=auto` | 默认，只读检查，列出缺什么，不改系统 |
| `agent-reach install --env=auto --dry-run` | 预览 `--system` 会做什么 |
| `agent-reach install --env=auto --system` | 用户明确同意后，安装 gh、mcporter 等上游工具，写配置，并把 SKILL.md 注册进各智能体的 skills 目录 |
| `agent-reach install --env=auto --system --channels=bilibili` | 只加装指定的可选渠道 |

### 官方的一句话装法

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

```txt
帮我安全检查并安装 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，复制下面这段：

```txt
请帮我安装 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 里新建任务，复制下面这段：

```txt
请帮我安装 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）时应停下来问你，而不是绕过去；如果它没停，你在权限弹窗里拒绝即可。

### 智能体会请求哪些权限

| 请求 | 处理 |
| --- | --- |
| 执行 `py -3 -m venv`、`python.exe -m pip install ...main.zip`、`agent-reach doctor` | 可以允许 |
| 联网下载 GitHub zip 和 Python 依赖（requests、yt-dlp 等） | 可以允许；WorkBuddy 沙箱会弹窗请求访问 github.com、pypi.tuna.tsinghua.edu.cn 等域名 |
| `bili search ...`、`curl` 请求 `api.bilibili.com` | 可以允许，这是正常读取 |
| `curl https://r.jina.ai/...`、`yt-dlp ... "ytsearch5:..."` | 可以允许，但国内网络下会超时，不必等它 |
| 写入 `~/.claude/skills/agent-reach/` 或 `~/.workbuddy/skills/agent-reach/` | 可以允许，这一步就是注册 Skill |
| 任何带 `--system`、`sudo`、管理员 PowerShell、`winget install`、`brew install`、`npm install -g` 的命令 | 看清装的是什么再决定；按上面的提示词它应先停下来问你 |
| `agent-reach configure --from-browser ...`、请你粘贴 Cookie | 拒绝，除非你决定用专用小号配置该平台 |
| 修改执行策略（`Set-ExecutionPolicy`）、关闭杀毒或防火墙 | 拒绝 |

### 要你亲手做的部分

- **决定开哪些渠道**。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`）：

```powershell
py -3 --version
```

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

```powershell
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`）：

```powershell
& "$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` 等目录）：

```powershell
& "$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 的个人技能目录：

```powershell
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 安装方式）：

```powershell
winget install --id GitHub.cli
gh auth login
```

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

```bash
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 时）：

```bash
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
```

装好后：

```bash
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 搜索与读取](https://ai.lingnan.top/materials/2026-autumn/w07/tool-01-deepseek-web)（`deepseek-web` Skill）：先 Search 拿到发布稿链接，再 Fetch 读具体发布稿。

可直接复制的提示词：

```txt
请完成下面的任务。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`，在提示词里重申一次即可。

预期看到的工具调用：

| 步骤 | 智能体调用 | 说明 |
| --- | --- | --- |
| 体检 | `agent-reach.exe doctor` | 国内网络下应看到 RSS、任意网页、B 站三项可用，其中任意网页是误报 |
| 搜发布稿 | deepseek-web Skill → `ds_web.py search "..."` | 结果里应有统计局发布稿“2026年9月份居民消费价格同比上涨0.9%” |
| 读原文 | `ds_web.py fetch "https://www.stats.gov.cn/sj/zxfb/202610/t20261014_1965477.html"` | 首次可能失败，重试一次即可 |
| 读技能 | Skill（agent-reach）→ 读 `references/video.md` | 按路由表找 B 站 |
| B 站搜索 | `bili.exe search "9月CPI 解读" --type video -n 5`，或 `curl` 先取 B 站首页 Cookie、再带浏览器 UA 和 Referer 请求 `api.bilibili.com/x/web-interface/search/...` | 两种都能返回结果；不带浏览器信息直接请求会被 B 站拒绝 |
| 写文件 | Write `output/cpi_2026-09.md` | — |

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

验收：

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

## 常见问题与排错

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 输入 `python3` 弹出微软商店 | Windows 的商店别名，不是真的 Python | 用 `py -3`，或 Python 安装目录里的 `python.exe`（install.md 原文提示） |
| `Activate.ps1` 报“在此系统上禁止运行脚本” | PowerShell 执行策略 | 不改策略，直接用 `Scripts\python.exe`、`Scripts\agent-reach.exe` 的完整路径 |
| 输入 `agent-reach` 提示找不到命令 | venv 未激活，Scripts 目录不在 PATH | 用完整路径；或在 `CLAUDE.md` 里告诉智能体路径 |
| `pip install` 报 `externally-managed-environment` | Homebrew Python 的 PEP 668 保护 | 改用 venv 或 pipx（install.md 原文） |
| 装上的版本是 0.1.0、命令对不上 | 从 PyPI 装到了同名的另一个项目 | 卸载后用 GitHub zip 地址重装 |
| 下载 main.zip 很慢或中断 | GitHub 在国内能连上，但时好时坏 | 重试；Gitee 上没有找到官方镜像，不要改用来历不明的转存 |
| 装依赖很慢或超时 | pip 默认连 pypi.org | 加 `-i https://pypi.tuna.tsinghua.edu.cn/simple`，或 `pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple`；清华不通时换阿里云 `https://mirrors.aliyun.com/pypi/simple/` |
| doctor 里 YouTube 是 `[X] yt-dlp 未安装` | doctor 只查 PATH，yt-dlp 装在 venv 里；Windows 上还可能缺 JS 运行时 | 国内网络下 YouTube 本来就连不上，不用处理 |
| Windows 上 doctor 认不出已装的 bash 脚本类工具 | 官方 issue #631、#590：Windows 上 `shutil.which()` 认不出无扩展名脚本 | 截至 2026-10 未修复，按 issue 跟进；不影响零配置渠道 |
| PowerShell 里 `curl -s` 报参数错误 | Windows PowerShell 5.1 中 `curl` 是 `Invoke-WebRequest` 的别名 | 写 `curl.exe` |
| `/tmp/...` 路径在 Windows 上不存在 | SKILL.md 的命令按 Mac/Linux 写 | 让智能体改用 `%TEMP%` 或你指定的项目目录 |
| 中文输出乱码 | 控制台编码 | 1.5.0 已在 Windows 上把输出设为 UTF-8；仍乱码时在 PowerShell 先执行 `chcp 65001` |
| doctor 显示“任意网页”✅，但读网页超时 | r.jina.ai 在国内网络下连不上，doctor 的 ✅ 是误报（issue #685） | 不用这个渠道；读网页改用 [DeepSeek 搜索与读取](https://ai.lingnan.top/materials/2026-autumn/w07/tool-01-deepseek-web)，或本地浏览器类工具（[Playwright MCP](https://ai.lingnan.top/materials/2026-autumn/w07/tool-03-playwright-mcp)、[agent-browser](https://ai.lingnan.top/materials/2026-autumn/w07/tool-05-agent-browser)）。Claude Code 自带的 WebFetch 在国内网络下也不可用，不用它 |
| GitHub 渠道 `command not found: gh` | 没装 gh | 这里不配，跳过 GitHub 渠道 |
| GitHub 渠道显示 warn：未检测到认证 | gh 装了但没登录 | `gh auth login` |
| B 站返回 412 | B 站风控：请求不带浏览器信息；yt-dlp 也已被拦，退出 B 站路线 | 用 bili-cli；或用 curl 先取 B 站首页 Cookie，再带浏览器 UA 和 `Referer: https://www.bilibili.com/` 调搜索接口（doctor 的兜底就是这样做的）；不要让智能体换 yt-dlp 重试 |
| YouTube、Twitter、Reddit、V2EX 连接超时 | 国内网络连不上这些站 | 不用这些渠道，也不配代理；只用 B 站、RSS 等国内可达的渠道 |
| 小红书返回登录页或 302／301 跳转 | 小红书首页、搜索页不登录读不了 | 不配；要配须本人决定并用专用小号，见下节 |
| 雪球报 HTTP 400 | 需要登录 Cookie，不代表股票代码不存在 | 见官方 troubleshooting；不建议配置 |
| 小宇宙转写在 Windows 上拒绝链接 | issue #819：`python3` 是商店别名时脚本误判 | 截至 2026-10 未修复 |
| WorkBuddy 里智能体说没有 agent-reach 技能 | `skill --install` 不写 WorkBuddy 目录 | 手动复制到 `.workbuddy/skills/agent-reach/`，新建任务 |
| 创建 venv 时 `ensurepip` 返回 1 | 安全软件拦截了 `__pycache__` 删除 | 检查 `python -m pip --version`，能用就继续 |

## 费用、额度、隐私与安全

- **费用**：工具和零配置渠道不收费。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 搜索与读取](https://ai.lingnan.top/materials/2026-autumn/w07/tool-01-deepseek-web)这类网页工具比，Agent-Reach 不需要 API Key、能进 B 站这类平台内部，但要在电脑上装一串上游命令行工具，稳定性随平台风控波动，国内网络下能用的渠道只有 B 站、RSS 等少数几个；只要“搜网页、读网页”，用 DeepSeek Search／Fetch 更省事（Claude Code 自带的 WebFetch 在国内网络下不可用）。和 [web-access](https://ai.lingnan.top/materials/2026-autumn/w07/tool-07-web-access) 比，Agent-Reach 不碰日常浏览器，按平台调现成命令行工具。

## 信息来源

| 内容 | 来源 |
| --- | --- |
| 安装方式、边界、渠道菜单、Cookie 与封号提示、Windows 商店别名提示 | https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md （官方文档） |
| 渠道表、默认安全模式、凭据存放、卸载、PyPI 同名包提示 | https://github.com/Panniantong/Agent-Reach （官方仓库 README） |
| 版本号、发布日期与说明 | https://github.com/Panniantong/Agent-Reach/releases |
| Skill 注册目录、`skill --install`、Windows UTF-8 处理、gh 遥测变量、SKILL.md 路由表 | 官方仓库源码 `agent_reach/cli.py`、`agent_reach/channels/github.py`、`agent_reach/skill/SKILL.md` |
| 雪球 400、排错 | https://github.com/Panniantong/Agent-Reach/blob/main/docs/troubleshooting.md （官方文档） |
| Windows 相关未修复问题（#590、#631、#685、#819） | https://github.com/Panniantong/Agent-Reach/issues （官方仓库 issue） |
| PyPI 同名包 0.1.0 | https://pypi.org/pypi/agent-reach/json |
| gh 的 winget 安装方式 | https://cli.github.com （gh 官方文档） |