Agent Reach 贡献者指南开发环境搭建、代码质量工具链与新增渠道的完整实践【免费下载链接】Agent-ReachGive your AI agent eyes to see the entire internet. Read search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-ReachAgent 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 工作模型共六步在 GitHub 上 fork 仓库将 fork 克隆到本地为贡献创建新分支完成代码修改运行测试与 lint 检查提交 Pull Request提交 PR 时项目明确偏好小而聚焦的变更small, focused changes反对一次性大重构。同时有几条硬性约定在 CLAUDE.md 中也被再次强调新分支 PR 进 main禁止直接 push 到 main每次提交遵循type(scope): message格式一个 commit 只做一件事提交前必须跑通全部测试pytest tests/ -vAgent 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 installpip install -e .[dev]安装的是可编辑模式加dev可选依赖。查看 pyproject.toml 可知devextras 的具体内容是一整套质量工具链dev [ pytest8.0, ruff0.8, mypy1.12, types-requests2.32, types-PyYAML6.0, ]其中types-requests与types-PyYAML是 stub 包供 mypy 对第三方库做类型检查。项目要求Python 3.10requires-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 等全部钉死到具体版本如ruff0.15.1、mypy1.19.1。集成测试脚本 test.sh 在安装阶段正是使用-c $REPO_ROOT/constraints.txt来保证测试环境与已测试依赖集一致——贡献者本地调试时同样建议加上这个参数可显著减少我这边能跑的环境差异问题。2.3 一键集成测试test.sh仓库自带 test.sh 作为完整的干净环境集成测试它模拟了一个全新的用户机器分五步执行创建一个隔离的 venvpython -m venv并隔离HOME、XDG_CONFIG_HOME避免污染开发者本机配置用 constraints 锁定安装本仓库的[dev]依赖执行agent-reach version验证 CLI 已正确安装运行只读的安装检查agent-reach install --envauto --safe、agent-reach install --envauto --system --dry-run以及agent-reach doctor --json并断言 doctor 返回的渠道字典非空执行pytest tests/ -q跑完整仓库测试集。该脚本会自动探测 python3 / python /py -3/.venv中第一个满足 3.10 的解释器跨平台兼容含 Windows 的Scripts/activate路径。贡献者在 PR 前跑一遍bash test.sh能覆盖安装 → 体检 → 单测全链路。三、代码风格与质量检查项目使用三个工具维持代码质量配置全部声明在 pyproject.toml 中工具职责关键配置ruffLint import 排序line-length 100、target-version py310、select [E, F, I]、忽略E501mypy类型检查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 采用统一渠道接口新增一个平台的标准流程是在agent_reach/channels/下创建新文件实现渠道契约参考现有渠道的实现在tests/test_channels.py中补充测试更新 agent_reach/doctor.py 使其纳入新渠道更新文档。下面结合源码把渠道契约具体化。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()四类能力日志统一用loguruCLI 输出统一用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。新增渠道后需要在文件中 import 新渠道类在ALL_CHANNELS中追加其实例get_channel(name)/get_all_channels()会自动生效无需改动其他调用点。体检引擎 agent_reach/doctor.py 的check_all()遍历注册表逐渠道调用check(config)并做了两条重要的防御性设计新渠道的实现必须兼容单个渠道异常不能拖垮整份报告check_all()用 try/except 把任何渠道异常降级为statuserror# 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_checkcheck()之后active_backend只能是None或strtest_ordered_backends_contractordered_backends(config)必须是backends的一个重排相同多重集test_channel_can_handle_contractcan_handle()必须返回布尔值并针对 13 类 URL 样本逐一验证归属判断。具体渠道的行为测试则写在 tests/test_channels.py。以TestRedditChannel为例它用 monkeypatch 隔离各后端候选验证OpenCLI 完整可用时按序获胜active_backend OpenCLI、仅有存储 Cookie 但未实时验证时返回 warn 且不激活后端等状态机细节TestV2EXChannel则演示了纯 API 渠道如何 mockurlopen来覆盖 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_FILEmonkeypatch 到临时目录——所以测试中读写配置完全不会影响开发者本机isolated_xueqiu_cookie_jar清空 Xueqiu 渠道的模块级 cookie jar防止会话状态在测试间泄漏。新增涉及配置、Cookie 或文件路径的测试时应当依赖而不是绕过这套隔离机制例如tests/test_channels.py中大量使用isolated_homefixture 在临时 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 在提交前应满足ruff check agent_reach tests ruff format agent_reach tests无输出mypy agent_reach通过pytest全绿其中包含tests/test_channel_contracts.py对全部渠道的契约断言更稳妥地跑一遍bash test.sh在干净 venv 中验证安装 → doctor → 测试全链路若改动版本号确认pyproject.toml、agent_reach/__init__.py、tests/test_cli.py三处一致变更小而聚焦、新能力附测试、commit 信息符合type(scope): message格式、PR 描述关联相关 issue。掌握以上流程后无论是修复一个小 bug、增强某个渠道的探测逻辑还是接入一个全新平台都能在 Agent Reach 现有的渠道契约与测试体系内安全落地。【免费下载链接】Agent-ReachGive your AI agent eyes to see the entire internet. Read search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Reach创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Reach 贡献者指南：开发环境搭建、代码质量工具链与新增渠道的完整实践
Agent Reach 贡献者指南开发环境搭建、代码质量工具链与新增渠道的完整实践【免费下载链接】Agent-ReachGive your AI agent eyes to see the entire internet. Read search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-ReachAgent 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 工作模型共六步在 GitHub 上 fork 仓库将 fork 克隆到本地为贡献创建新分支完成代码修改运行测试与 lint 检查提交 Pull Request提交 PR 时项目明确偏好小而聚焦的变更small, focused changes反对一次性大重构。同时有几条硬性约定在 CLAUDE.md 中也被再次强调新分支 PR 进 main禁止直接 push 到 main每次提交遵循type(scope): message格式一个 commit 只做一件事提交前必须跑通全部测试pytest tests/ -vAgent 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 installpip install -e .[dev]安装的是可编辑模式加dev可选依赖。查看 pyproject.toml 可知devextras 的具体内容是一整套质量工具链dev [ pytest8.0, ruff0.8, mypy1.12, types-requests2.32, types-PyYAML6.0, ]其中types-requests与types-PyYAML是 stub 包供 mypy 对第三方库做类型检查。项目要求Python 3.10requires-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 等全部钉死到具体版本如ruff0.15.1、mypy1.19.1。集成测试脚本 test.sh 在安装阶段正是使用-c $REPO_ROOT/constraints.txt来保证测试环境与已测试依赖集一致——贡献者本地调试时同样建议加上这个参数可显著减少我这边能跑的环境差异问题。2.3 一键集成测试test.sh仓库自带 test.sh 作为完整的干净环境集成测试它模拟了一个全新的用户机器分五步执行创建一个隔离的 venvpython -m venv并隔离HOME、XDG_CONFIG_HOME避免污染开发者本机配置用 constraints 锁定安装本仓库的[dev]依赖执行agent-reach version验证 CLI 已正确安装运行只读的安装检查agent-reach install --envauto --safe、agent-reach install --envauto --system --dry-run以及agent-reach doctor --json并断言 doctor 返回的渠道字典非空执行pytest tests/ -q跑完整仓库测试集。该脚本会自动探测 python3 / python /py -3/.venv中第一个满足 3.10 的解释器跨平台兼容含 Windows 的Scripts/activate路径。贡献者在 PR 前跑一遍bash test.sh能覆盖安装 → 体检 → 单测全链路。三、代码风格与质量检查项目使用三个工具维持代码质量配置全部声明在 pyproject.toml 中工具职责关键配置ruffLint import 排序line-length 100、target-version py310、select [E, F, I]、忽略E501mypy类型检查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 采用统一渠道接口新增一个平台的标准流程是在agent_reach/channels/下创建新文件实现渠道契约参考现有渠道的实现在tests/test_channels.py中补充测试更新 agent_reach/doctor.py 使其纳入新渠道更新文档。下面结合源码把渠道契约具体化。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()四类能力日志统一用loguruCLI 输出统一用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。新增渠道后需要在文件中 import 新渠道类在ALL_CHANNELS中追加其实例get_channel(name)/get_all_channels()会自动生效无需改动其他调用点。体检引擎 agent_reach/doctor.py 的check_all()遍历注册表逐渠道调用check(config)并做了两条重要的防御性设计新渠道的实现必须兼容单个渠道异常不能拖垮整份报告check_all()用 try/except 把任何渠道异常降级为statuserror# 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_checkcheck()之后active_backend只能是None或strtest_ordered_backends_contractordered_backends(config)必须是backends的一个重排相同多重集test_channel_can_handle_contractcan_handle()必须返回布尔值并针对 13 类 URL 样本逐一验证归属判断。具体渠道的行为测试则写在 tests/test_channels.py。以TestRedditChannel为例它用 monkeypatch 隔离各后端候选验证OpenCLI 完整可用时按序获胜active_backend OpenCLI、仅有存储 Cookie 但未实时验证时返回 warn 且不激活后端等状态机细节TestV2EXChannel则演示了纯 API 渠道如何 mockurlopen来覆盖 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_FILEmonkeypatch 到临时目录——所以测试中读写配置完全不会影响开发者本机isolated_xueqiu_cookie_jar清空 Xueqiu 渠道的模块级 cookie jar防止会话状态在测试间泄漏。新增涉及配置、Cookie 或文件路径的测试时应当依赖而不是绕过这套隔离机制例如tests/test_channels.py中大量使用isolated_homefixture 在临时 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 在提交前应满足ruff check agent_reach tests ruff format agent_reach tests无输出mypy agent_reach通过pytest全绿其中包含tests/test_channel_contracts.py对全部渠道的契约断言更稳妥地跑一遍bash test.sh在干净 venv 中验证安装 → doctor → 测试全链路若改动版本号确认pyproject.toml、agent_reach/__init__.py、tests/test_cli.py三处一致变更小而聚焦、新能力附测试、commit 信息符合type(scope): message格式、PR 描述关联相关 issue。掌握以上流程后无论是修复一个小 bug、增强某个渠道的探测逻辑还是接入一个全新平台都能在 Agent Reach 现有的渠道契约与测试体系内安全落地。【免费下载链接】Agent-ReachGive your AI agent eyes to see the entire internet. Read search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Reach创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考