Agent Reach 开发者指南：从 CLAUDE.md 看"安装器 + 体检工具 + 配置层"的架构约定与工程规范

本文以仓库根目录的 CLAUDE.md 为主线，完整解读 Agent Reach 的项目定位、开发命令、代码结构、渠道契约与工程规则。读完后你将掌握：如何在本地完成开发安装与全量/集成测试，如何用源码印证"glue layer（胶水层）"的设计边界，以及版本一致性、提交规范、Cookie 鉴权安全等项目级约定。

一、项目定位：安装器 + 体检工具 + 配置工具，而不是包装层

CLAUDE.md 在开篇用一句话定调了项目性质：

Agent Reach — Python CLI + library that gives AI agents read/search access to 13 internet platforms. Positioning: installer + doctor + config tool. NOT a wrapper — after install, agents call upstream tools directly.

即：Agent Reach 负责选型、安装、体检、配置，安装完成之后，实际的读取与搜索由 Agent 直接调用上游工具（twitter-cli、yt-dlp、mcporter、gh 等）完成，项目本身不提供包装调用层。这一设计在源码中得到了印证：

• agent_reach/core.py 中的 AgentReach 类自述"provides health-check functionality. For reading/searching, use the upstream tools directly"，对外只暴露 doctor() 与 doctor_report() 两个体检入口；
• agent_reach/integrations/mcp_server.py 的 MCP 服务同样只注册了一个 get_status 工具，返回各渠道的安装与激活状态，而不代理任何读取请求。

项目当前版本为 1.5.0（见 CLAUDE.md 与 pyproject.toml），采用 MIT 协议，运行要求 Python 3.10+。

二、开发命令速查与集成测试流程

CLAUDE.md 的 "Commands" 一节列出了 6 条核心命令，这里逐条给出并在源码层面补充细节：

命令	用途
pip install -e .	开发模式安装（可编辑安装）
pytest tests/ -v	运行全部测试
pytest tests/test_cli.py -v	只跑 CLI 测试
bash test.sh	完整集成测试：创建 venv、安装、跑 doctor + 仓库测试
python -m agent_reach.cli doctor	运行诊断体检
python -m agent_reach.cli install --env=auto	自动配置

其中 bash test.sh 是最值得注意的一条。查看 test.sh 可以看到它实现了一个完全隔离的干净环境验证流程：

1. 用 mktemp -d 创建临时目录并重写 HOME、XDG_CONFIG_HOME，保证不污染真实用户目录；
2. 依次探测 python3 / python / py -3 / 仓库自带 .venv，找到第一个满足 3.10+ 的解释器；
3. 创建独立 venv 并 pip install -c constraints.txt -e .[dev] 安装当前代码（附带 constraints.txt 依赖锁）；
4. 执行 agent-reach version 验证 CLI 可运行；
5. 运行只读的 agent-reach install --env=auto --safe、agent-reach install --env=auto --system --dry-run 与 agent-reach doctor --json，并断言 doctor 返回了非空的渠道字典；
6. 最后执行 pytest tests -q 跑完整个仓库测试套件。

从 test.sh 可以看出，集成测试刻意把"只读安全检查（--safe）"与"显式授权的系统安装（--system --dry-run）"分开验证，这与项目"默认只检查、显式授权才改系统"的安全原则一致。

CLI 入口本身是标准 argparse 实现：agent_reach/cli.py 中 main() 定义了 setup、install、configure 等子命令，install 支持 --env {local,server,auto}、--proxy、互斥的 --system/--safe 以及 --dry-run、--channels 参数；pyproject.toml 将其注册为 agent-reach 可执行命令（agent_reach.cli:main）。

三、代码结构逐文件解读

CLAUDE.md 的 "Structure" 一节给出了项目骨架，结合源码可以进一步确认每个文件的职责：

路径	职责（CLAUDE.md 描述）	源码印证
agent_reach/cli.py	CLI 入口（argparse）	main() 定义子命令与参数
agent_reach/core.py	核心 read/search 路由逻辑	AgentReach 类，仅暴露体检能力
agent_reach/config.py	配置管理（YAML、环境变量）	配置存于 ~/.agent-reach/config.yaml，写入走原子替换 + 600 权限
agent_reach/doctor.py	诊断引擎	check_all() 遍历渠道收集状态，format_report() 渲染报告
agent_reach/channels/	每平台一个文件（twitter.py、reddit.py、youtube.py 等）	目录下按平台拆分为 web、bilibili、github、xiaohongshu 等文件
agent_reach/channels/base.py	基类，所有渠道继承它	Channel 抽象基类，定义后端路由语义
agent_reach/integrations/mcp_server.py	MCP server 集成	仅暴露 get_status 工具
agent_reach/skill/	OpenClaw skill 文件	含 SKILL.md 与按场景划分的参考文档
agent_reach/guides/	使用指南	setup-exa.md、setup-twitter.md 等
tests/	pytest 测试	30+ 测试文件覆盖 CLI、渠道契约、凭据安全等
config/mcporter.json	MCP 工具配置	随仓库提供的 mcporter 配置文件

一个值得注意的细节是配置安全：agent_reach/config.py 中 _atomic_write_yaml() 采用"同目录临时文件 + os.replace 原子替换"的策略，并在写入前后两次拒绝符号链接、显式将文件权限设为仅所有者可读写——这与 README 中"凭据本地存储、文件权限 600"的安全承诺相互对应。

四、渠道契约：can_handle / read / search / check 与后端路由

CLAUDE.md 的 "Conventions" 规定：

Each channel is a single file in channels/, inherits from BaseChannel. Channel contract: must implement can_handle(url), read(url), search(query), check() methods.

打开 agent_reach/channels/base.py 可以看到契约的基类实现：

• Channel(ABC) 抽象基类定义了类属性 name、description、backends（有序候选后端列表，backends[0] 为首选）、tier（0=零配置、1=需免费 Key、2=需额外设置）与 active_backend（当前实际生效的后端）；
• can_handle(url) 是抽象方法，要求每个子类判断给定 URL 是否属于该平台——在 agent_reach/channels/ 下，bilibili、github、reddit、v2ex、web 等渠道都实现了该方法；
• check(config) 的默认实现直接返回第一个后端，但基类文档明确要求：有外部后端的子类必须真实探测并设置 self.active_backend。

关于 read() 与 search()：从源码结构看，并非每个渠道都实现了这两个方法——例如 v2ex.py 实现了内置 search()，web.py 实现了 read()；而大多数需要登录态的渠道（Twitter、小红书等）读取由上游工具完成，渠道文件主要负责 check() 探测与后端排序。可以理解为契约中 read/search 是"渠道具备内置能力时应当提供"的部分，can_handle 与 check 则是所有渠道的硬约束。

后端路由语义："换接入方式 = 调整列表顺序"

base.py 的模块文档是理解本项目的关键：

backends is an ORDERED candidate list: backends[0] is the preferred backend, the rest are fallbacks. "Switching backends" for a platform means reordering this list (or a user override) — not rewriting code. shutil.which() alone is NOT proof of health — a stale venv shim passes which() but cannot execute.

ordered_backends(config) 方法还实现了用户强制指定后端的机制：配置键 <channel>_backend（或环境变量 <CHANNEL>_BACKEND）会把指定后端移到列表头部，未知值会被忽略，"an stale override can never hide working backends"。

真实探测：probe_command 区分 missing / broken / timeout

CLAUDE.md 强调渠道检查"真实探测"，其实现落在 agent_reach/probe.py 的 probe_command()：

• 命令不在 PATH → missing；
• which() 找到了但 exec 抛 FileNotFoundError/OSError（典型场景：系统 Python 升级后 venv shim 的 shebang 解释器丢失，pipx/uv tool 安装常这样坏）→ broken，并给出重装处方（uv tool install --force <pkg> 或 pipx reinstall <pkg>）；
• 执行超时 → timeout；退出码 126/127 也归类为 broken；
• 重试只对瞬态失败（timeout/error）生效，missing/broken 不会重试。

这个设计保证了 agent-reach doctor 报告的是真实健康状态而非"文件存在与否"。诊断的收集逻辑在 agent_reach/doctor.py 的 check_all()：逐个渠道调用 check(config)，单个渠道异常会降级为 status="error" 而不拖垮整份报告，输出边界上还会对消息做凭据清洗（scrub_url_credentials），报告中若存在多个候选后端会标注"当前后端：xxx"。

五、工程规范与硬性规则（Conventions & Rules）

CLAUDE.md 最后两节是项目必须遵守的约定，均可在仓库中找到落点：

1. 技术栈约定

• Python 3.10+ 且使用类型提示——pyproject.toml 中 requires-python = ">=3.10"，base.py 等模块均带完整类型标注；
• loguru 负责日志、rich 负责 CLI 输出——两者都在 pyproject.toml 的依赖列表中；cli.py 的 _configure_logging() 默认移除 loguru 的 stderr handler，仅在 --verbose 时打开；
• 提交格式 type(scope): message，一次提交只做一件事；
• 所有上游工具调用只走公开 API/CLI，绝不 hack 内部实现——这与"glue layer"定位互为表里。

2. 版本三处必须一致

Version in THREE places must match: pyproject.toml, __init__.py, tests/test_cli.py

当前仓库中三处一致为 1.5.0：pyproject.toml、agent_reach/__init__.py（__version__ = "1.5.0"，CLI 的 --version 直接取此值），以及 tests/test_cli.py 中对版本比较逻辑 _is_newer_version 的断言（含 v1.5.0 tag 的 GitHub Release 模拟）。修改版本号时必须三处同步，否则测试会失配。

3. 协作流程规则

• 永不修改上游开源项目的源码，Agent Reach 只做路由与调用；
• 所有变更走新分支 + PR 合入 main，禁止直接 push main；
• 提交前必须 pytest tests/ -v 全量通过——tests/ 目录下有 30 余个测试文件，覆盖渠道契约（test_channel_contracts.py）、CLI（test_cli.py）、doctor（test_doctor.py）、凭据安全（test_cookie_security.py、test_scrub_credentials.py）等。

4. Cookie 鉴权的唯一路径

Cookie-based auth (Twitter, XHS): use Cookie-Editor export method only, no QR scan. XHS login: Cookie-Editor browser export only (QR will hang).

即 Twitter 与小红书的 Cookie 只接受用户通过 Cookie-Editor 插件手工导出的内容，禁止使用扫码登录（扫码会挂起）。这一约束在 README 的安全章节中有对应说明，仓库也提供了配套的 agent_reach/cookie_extract.py 与 tests/test_cookie_security.py 等凭据处理与安全测试；cli.py 中 _SENSITIVE_CONFIG_KEYS 显式维护了 twitter-cookies、xhs-cookies 等敏感配置键，configure 子命令还提供 --stdin 参数避免把敏感值暴露在进程参数里（见 agent_reach/cli.py）。

六、本地验证路径

按照 CLAUDE.md 的规范，一次完整的本地开发验证应包含：

pip install -e .            # 开发模式安装
pytest tests/ -v            # 全量单测（提交前必须通过）
bash test.sh                # 隔离环境集成测试：venv + doctor + 全量测试
python -m agent_reach.cli doctor                # 诊断体检
python -m agent_reach.cli install --env=auto    # 只读自动检查（默认安全模式）

其中 bash test.sh 会自动完成"干净环境安装 → 只读 doctor → 仓库测试"的全链路，是提交前最接近 CI 的验证手段；agent-reach doctor --json 输出结构化结果，便于脚本化断言（集成测试脚本即以此方式校验渠道数量）。

小结

CLAUDE.md 虽篇幅不长，却完整约束了 Agent Reach 的三大核心：定位（installer + doctor + config tool，glue layer 而非 wrapper）、结构（每平台一个 channel 文件、继承 Channel 基类、有序后端列表 + 真实探测）、规范（Python 3.10+ 类型提示、loguru/rich、版本三处一致、Cookie-Editor 唯一鉴权路径、分支 PR 流程与提交前全量测试）。源码中 base.py 的路由语义、probe.py 的真实探测、doctor.py 的容错收集以及 test.sh 的隔离集成测试，正是这些约定的具体落地——理解这份文档并对照上述文件，即可快速上手 Agent Reach 的开发与测试工作。