Agent Reach 贡献者指南：开发环境搭建、代码质量工具链与新增渠道的完整实践

Agent Reach 是一个"给 AI Agent 装上网"的 Python CLI 项目：安装并体检各类上游读取工具，让 Agent 可以直接读取与搜索 Twitter、Reddit、YouTube、GitHub、Bilibili、XiaoHongShu 等十余个平台。对于希望向该项目提交代码的贡献者，CONTRIBUTING.md 定义了从 fork 分支、开发环境搭建、代码风格检查到新增渠道的完整流程；本文以该文档为骨架，结合 pyproject.toml、agent_reach/channels/base.py、tests/test_channel_contracts.py 等仓库源码，把每个步骤背后的工程细节讲透，读完即可独立完成一个合规的 Pull Request。

一、贡献工作流概览

贡献流程遵循标准的 fork 工作模型，共六步：

1. 在 GitHub 上 fork 仓库
2. 将 fork 克隆到本地
3. 为贡献创建新分支
4. 完成代码修改
5. 运行测试与 lint 检查
6. 提交 Pull Request

提交 PR 时，项目明确偏好小而聚焦的变更（small, focused changes），反对一次性大重构。同时有几条硬性约定，在 CLAUDE.md 中也被再次强调：

• 新分支 + PR 进 main，禁止直接 push 到 main；
• 每次提交遵循 type(scope): message 格式，一个 commit 只做一件事；
• 提交前必须跑通全部测试（pytest tests/ -v）；
• Agent Reach 是"胶水层"，只负责路由和调用上游工具，绝不允许修改任何上游开源项目的源码；
• 版本号需要同步维护在三处：pyproject.toml、agent_reach/__init__.py 和 tests/test_cli.py，三处必须一致（当前版本为 1.5.0）。

二、开发环境搭建

2.1 基础安装命令

CONTRIBUTING.md 给出的开发环境初始化命令如下（将地址替换为你自己的 fork）：

# Clone your fork
git clone https://github.com/YOUR_USERNAME/Agent-Reach.git
cd Agent-Reach

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks (optional but recommended)
pre-commit install

pip install -e ".[dev]" 安装的是可编辑模式加 dev 可选依赖。查看 pyproject.toml 可知，dev extras 的具体内容是一整套质量工具链：

dev = [
    "pytest>=8.0",
    "ruff>=0.8",
    "mypy>=1.12",
    "types-requests>=2.32",
    "types-PyYAML>=6.0",
]

其中 types-requests 与 types-PyYAML 是 stub 包，供 mypy 对第三方库做类型检查。项目要求 Python >= 3.10（requires-python = ">=3.10"），并且声明兼容 3.10 / 3.11 / 3.12。

2.2 锁定依赖版本：constraints.txt

仓库根目录的 constraints.txt 提供了一份经过测试的锁定依赖集，其头部注释说明了用法：

# Agent Reach tested dependency set
# Usage:
#   pip install -c constraints.txt -e .[dev]

文件内把 requests、feedparser、loguru、rich、yt-dlp、pytest、ruff、mypy 等全部钉死到具体版本（如 ruff==0.15.1、mypy==1.19.1）。集成测试脚本 test.sh 在安装阶段正是使用 -c "$REPO_ROOT/constraints.txt" 来保证测试环境与"已测试依赖集"一致——贡献者本地调试时同样建议加上这个参数，可显著减少"我这边能跑"的环境差异问题。

2.3 一键集成测试：test.sh

仓库自带 test.sh 作为完整的干净环境集成测试，它模拟了一个全新的用户机器，分五步执行：

1. 创建一个隔离的 venv（python -m venv），并隔离 HOME、XDG_CONFIG_HOME，避免污染开发者本机配置；
2. 用 constraints 锁定安装本仓库的 [dev] 依赖；
3. 执行 agent-reach version 验证 CLI 已正确安装；
4. 运行只读的安装检查 agent-reach install --env=auto --safe、agent-reach install --env=auto --system --dry-run，以及 agent-reach doctor --json，并断言 doctor 返回的渠道字典非空；
5. 执行 pytest tests/ -q 跑完整仓库测试集。

该脚本会自动探测 python3 / python / py -3 / .venv 中第一个满足 3.10+ 的解释器，跨平台兼容（含 Windows 的 Scripts/activate 路径）。贡献者在 PR 前跑一遍 bash test.sh，能覆盖"安装 → 体检 → 单测"全链路。

三、代码风格与质量检查

项目使用三个工具维持代码质量，配置全部声明在 pyproject.toml 中：

工具	职责	关键配置
ruff	Lint + import 排序	line-length = 100、target-version = "py310"、select = ["E", "F", "I"]、忽略 E501
mypy	类型检查	python_version = "3.10"、check_untyped_defs = true、排除 tests/
pytest	测试	测试位于 tests/ 目录，配合 conftest 自动隔离环境

提交 PR 前需要运行文档给出的完整检查组合：

# Linting
ruff check agent_reach tests
ruff format agent_reach tests

# Type checking
mypy agent_reach

# Tests
pytest

从 pyproject.toml 的 mypy 段还能看到几个值得注意的严格项：warn_unused_configs、warn_redundant_casts、warn_unused_ignores、check_untyped_defs = true——也就是说即使未标注返回类型的函数体也会被检查，而 ignore_missing_imports = true 则容忍无 stub 的第三方库。注意 mypy 的 exclude = ["^tests/"]：类型检查只针对 agent_reach 包本身，测试代码只需通过 ruff 与 pytest。

四、新增渠道：核心扩展机制

这是 CONTRIBUTING.md 中最有技术含量的部分。Agent Reach 采用统一渠道接口，新增一个平台的标准流程是：

1. 在 agent_reach/channels/ 下创建新文件；
2. 实现渠道契约（参考现有渠道的实现）；
3. 在 tests/test_channels.py 中补充测试；
4. 更新 agent_reach/doctor.py 使其纳入新渠道；
5. 更新文档。

下面结合源码把"渠道契约"具体化。

4.1 Channel 基类：一个渠道必须长什么样

所有渠道继承自 agent_reach/channels/base.py 中的 Channel 抽象基类，其核心属性与方法是：

class Channel(ABC):
    name: str = ""          # 如 "youtube"
    description: str = ""   # 如 "YouTube 视频和字幕"
    backends: List[str] = []  # 有序候选后端，backends[0] 为优先
    tier: int = 0           # 0=零配置, 1=需免费 key, 2=需复杂配置

    @abstractmethod
    def can_handle(self, url: str) -> bool:
        """判断该 URL 是否属于本平台"""
        ...

check(config) 则返回 (status, message) 二元组，status 取值 ok / warn / off / error。基类文档注释明确了三条关键语义，新增渠道时必须遵守：

• backends 是有序候选列表：backends[0] 是首选后端，其余是回退；"切换后端"意味着重排列表而不是改写代码；
• check() 必须设置 self.active_backend 为当前真正在服务的后端（无可用后端时置 None）。注释特别强调：shutil.which() 存在并不等于健康——过期的 venv shim 能过 which() 却执行不了，渠道应当真正执行一条轻量命令来探测（参见 agent_reach/probe.py）；
• 用户可通过配置键 <channel>_backend（或环境变量 <CHANNEL>_BACKEND）强制指定后端，ordered_backends() 会把它移到列表头部；未知取值会被直接忽略，保证过期的覆盖值永远无法遮蔽可用后端。

此外，CLAUDE.md 补充了完整的渠道契约口径：每个渠道是 channels/ 下的单文件实现，必须提供 can_handle(url)、read(url)、search(query)、check() 四类能力；日志统一用 loguru，CLI 输出统一用 rich。

4.2 注册表与 doctor 体检

渠道实例统一注册在 agent_reach/channels/init.py 的 ALL_CHANNELS 列表中（当前共 15 个：GitHub、Twitter、YouTube、Reddit、Facebook、Instagram、Bilibili、XiaoHongShu、LinkedIn、Xiaoyuzhou、V2EX、Xueqiu、RSS、Exa、Web）。新增渠道后需要：

1. 在文件中 import 新渠道类；
2. 在 ALL_CHANNELS 中追加其实例；
3. get_channel(name) / get_all_channels() 会自动生效，无需改动其他调用点。

体检引擎 agent_reach/doctor.py 的 check_all() 遍历注册表逐渠道调用 check(config)，并做了两条重要的防御性设计，新渠道的实现必须兼容：

• 单个渠道异常不能拖垮整份报告：check_all() 用 try/except 把任何渠道异常降级为 status="error"（# noqa: BLE001 — doctor must survive any channel）；
• 输出边界统一清洗：所有渠道消息在渲染前都会经过 scrub_url_credentials() 去除 URL 中可能残留的凭据。

因此新渠道的 check() 应保持"快速、只读、不抛异常"的特性。

4.3 契约测试：你的新渠道会被自动审查

tests/test_channel_contracts.py 是一组面向所有已注册渠道的契约测试，新渠道加入注册表后会立即被以下断言覆盖：

• test_channel_registry_contract：渠道名唯一、name/description 非空、backends 是列表、tier ∈ {0, 1, 2}；
• test_channel_check_contract_with_minimal_runtime：把 shutil.which 全部 mock 成 None（模拟什么都没装的机器），要求每个渠道的 check() 仍返回合法 status 与非空消息——这直接验证了 4.1 中"off 指引必须给出安装建议"的口径；
• test_channel_active_backend_attribute_contract / test_channel_active_backend_set_by_check：check() 之后 active_backend 只能是 None 或 str；
• test_ordered_backends_contract：ordered_backends(config) 必须是 backends 的一个重排（相同多重集）；
• test_channel_can_handle_contract：can_handle() 必须返回布尔值，并针对 13 类 URL 样本逐一验证归属判断。

具体渠道的行为测试则写在 tests/test_channels.py。以 TestRedditChannel 为例，它用 monkeypatch 隔离各后端候选，验证"OpenCLI 完整可用时按序获胜"（active_backend == "OpenCLI"）、"仅有存储 Cookie 但未实时验证时返回 warn 且不激活后端"等状态机细节；TestV2EXChannel 则演示了纯 API 渠道如何 mock urlopen 来覆盖 ok / warn 两条路径。新渠道测试应当遵循同样的模式：不发起真实网络请求，用 monkeypatch 注入假响应，并断言 status 与 active_backend 的组合。

五、测试隔离：conftest 的工程细节

跑 pytest 时，tests/conftest.py 中的两个 autouse fixture 会自动生效，理解它们有助于写出不会被环境状态污染的测试：

• isolated_home（每个测试前自动执行）：把 HOME、USERPROFILE、XDG_CONFIG_HOME、APPDATA、LOCALAPPDATA 全部重定向到 tmp_path 下的临时目录，并把 Config.CONFIG_DIR / Config.CONFIG_FILE monkeypatch 到临时目录——所以测试中读写配置完全不会影响开发者本机；
• isolated_xueqiu_cookie_jar：清空 Xueqiu 渠道的模块级 cookie jar，防止会话状态在测试间泄漏。

新增涉及配置、Cookie 或文件路径的测试时，应当依赖（而不是绕过）这套隔离机制，例如 tests/test_channels.py 中大量使用 isolated_home fixture 在临时 home 下写入 credential.json / cookies.json 来模拟"已登录"状态。

六、Bug 报告与提问规范

CONTRIBUTING.md 要求 issue 报告包含五项信息，这也是维护者定位问题的最小输入集：

• Python 版本（结合 pyproject.toml 的 requires-python = ">=3.10" 判断是否在支持范围内）；
• 操作系统；
• 复现步骤；
• 期望行为 vs 实际行为；
• 完整错误信息。

由于渠道探测会输出上游命令的探测结果，报错信息中可能夹带本机路径或配置片段——提交 issue 前建议先脱敏，这与 doctor 侧 scrub_url_credentials() 的清洗逻辑是同一安全口径（参见 SECURITY.md 与 agent_reach/doctor.py 中的输出边界处理）。对使用类问题，文档建议直接开 issue 或参与讨论。

七、提交前检查清单

综合以上各节，一个合规 PR 在提交前应满足：

1. ruff check agent_reach tests && ruff format agent_reach tests 无输出；
2. mypy agent_reach 通过；
3. pytest 全绿，其中包含 tests/test_channel_contracts.py 对全部渠道的契约断言；
4. 更稳妥地，跑一遍 bash test.sh，在干净 venv 中验证"安装 → doctor → 测试"全链路；
5. 若改动版本号，确认 pyproject.toml、agent_reach/__init__.py、tests/test_cli.py 三处一致；
6. 变更小而聚焦、新能力附测试、commit 信息符合 type(scope): message 格式、PR 描述关联相关 issue。

掌握以上流程后，无论是修复一个小 bug、增强某个渠道的探测逻辑，还是接入一个全新平台，都能在 Agent Reach 现有的渠道契约与测试体系内安全落地。