agent-reach

一句话总结

给 AI Agent 一键装上互联网能力——17 个平台的搜索、阅读和交互，零配置即可使用 8 个渠道。

核心能力

一键安装：agent-reach install 自动检测环境、安装系统依赖、配置搜索引擎和平台工具
17 平台覆盖：网页、GitHub、Twitter/X、YouTube、Reddit、B站、小红书、抖音、LinkedIn、微博、微信公众号、V2EX、雪球、小宇宙播客、RSS、Exa AI 搜索
零配置即用：8 个渠道（网页、YouTube、RSS、B站本地、GitHub 公开、V2EX、微博、微信公众号）开箱即用
环境诊断：agent-reach doctor 一条命令检测所有渠道的可用状态
渠道可插拔：每个平台是独立的 channel 文件，不满意直接换掉，不依赖 Agent Reach 内部逻辑
安全设计：Cookie/Token 本地存储（权限 600）、安全模式（--safe）、Dry Run 预览、完全开源
多 Agent 兼容：Claude Code、OpenClaw、Cursor、Windsurf 等任何能执行 shell 命令的 Agent

触发场景

当用户要求搜索、阅读或交互任何支持的平台内容时自动触发——分享 URL、要求搜索网页/社交媒体/视频/GitHub、订阅 RSS、查看推文、阅读小红书笔记、提取 YouTube 字幕等。

文件清单

One-Line Summary

Give your AI Agent eyes to see the entire internet — one-click install/diagnose/configure for 17 platforms, 8 channels ready with zero config.

Core Capabilities

One-click install: agent-reach install auto-detects environment, installs system deps, configures search engines and platform tools
17 platforms: Web, GitHub, Twitter/X, YouTube, Reddit, Bilibili, Xiaohongshu, Douyin, LinkedIn, Weibo, WeChat Official Accounts, V2EX, Xueqiu, Xiaoyuzhou Podcast, RSS, Exa AI Search
Zero config: 8 channels (Web, YouTube, RSS, Bilibili-local, GitHub-public, V2EX, Weibo, WeChat) work out of the box
Health check: agent-reach doctor inspects all channels in one command
Pluggable channels: each platform is an independent file — swap any backend without touching internal logic
Security-first: local-only credential storage (permission 600), safe mode (--safe), dry-run preview, fully open source
Multi-agent compatible: Claude Code, OpenClaw, Cursor, Windsurf — any agent that runs shell commands

Trigger Scenarios

Triggers when the user asks to search, read, or interact on any supported platform — sharing a URL, requesting web/social/video/GitHub search, subscribing to RSS, reading tweets, browsing Xiaohongshu notes, extracting YouTube subtitles, etc.

File Inventory

agent-reach
- .gitignore
- CHANGELOG.md
- CLAUDE.md
- CONTRIBUTING.md
- LICENSE
- README.md
- SECURITY.md
- agent_reach
  - __init__.py
  - channels
    - __init__.py
    - base.py
    - bilibili.py
    - douyin.py
    - exa_search.py
    - github.py
    - linkedin.py
    - reddit.py
    - rss.py
    - twitter.py
    - v2ex.py
    - web.py
    - wechat.py
    - weibo.py
    - xiaohongshu.py
    - xiaoyuzhou.py
    - xueqiu.py
    - youtube.py
  - cli.py
  - config.py
  - cookie_extract.py
  - core.py
  - doctor.py
  - guides
  - integrations
    - __init__.py
    - mcp_server.py
  - scripts
    - transcribe_xiaoyuzhou.sh
  - skill
    - SKILL.md
    - SKILL_en.md
    - references
      - career.md
      - dev.md
      - search.md
      - social.md
      - video.md
      - web.md
  - utils
    - paths.py
    - text.py
- config
  - mcporter.json
- constraints.txt
- docs
- llms.txt
- pyproject.toml
- scripts
  - sync-upstream.sh
- test.sh
- tests
- uv.lock

目录结构分析

Agent Reach 采用双层架构：外层是 Python CLI 工具（安装器 + 诊断器 + 配置管理），内层是 Claude Code / OpenClaw 的 SKILL.md 指令文件。Python 层负责初始化和环境准备，SKILL.md 层负责运行时路由——Agent 安装完成后直接调用上游工具（twitter-cli、yt-dlp、gh CLI 等），不经过 Agent Reach 包装层。

核心模块分工明确：

cli.py（1743 行）是整个项目的发动机——包含 install/doctor/configure/uninstall/skill/format/check-update/watch 全套命令
channels/（18 个文件）是渠道检测层——每个平台一个独立文件，继承 BaseChannel，只负责检测上游工具是否可用
doctor.py 是诊断引擎——遍历所有 channel 的 check() 方法，聚合生成状态报告
config.py 是配置中枢——YAML 存储 + 环境变量回退 + 敏感值掩码
skill/ 是 Agent 指令层——SKILL.md 路由表 + 6 个分类 references/*.md，按需加载

SKILL.md 结构解析

SKILL.md 采用路由表模式——这是该 skill 最核心的设计创新。它不是把所有指令塞进一个文件，而是：

YAML frontmatter 定义触发词映射：17 个平台的搜索/社交/职业/开发/网页/视频等意图一一对应中文和英文触发词
路由表 将用户意图映射到分类文档：search → references/search.md，social → references/social.md，等等
零配置快速命令 列出一行即用的上游工具命令（Exa 搜索、Jina Reader、GitHub CLI、twitter-cli 等）
工作区规则 约束 Agent 的行为边界（不用 workspace 目录，用 /tmp/ 和 ~/.agent-reach/）

这种”路由表 + 按需引用”的设计使得 SKILL.md 本身保持精简（约 100 行），而每个渠道的详细文档按需加载，避免了一次性塞入过多上下文导致 token 浪费。

Directory Structure Analysis

Agent Reach uses a two-layer architecture: the outer layer is a Python CLI tool (installer + doctor + config manager), and the inner layer is a SKILL.md instruction file for Claude Code / OpenClaw. The Python layer handles initialization and environment setup; the SKILL.md layer handles runtime routing — after installation, agents call upstream tools directly (twitter-cli, yt-dlp, gh CLI, etc.) without going through Agent Reach’s wrapper layer.

Core module responsibilities are clearly divided:

cli.py (1743 lines) is the engine — contains the full suite of install/doctor/configure/uninstall/skill/format/check-update/watch commands
channels/ (18 files) is the channel detection layer — one file per platform, inheriting BaseChannel, only responsible for checking if upstream tools are available
doctor.py is the diagnostics engine — iterates all channel check() methods and aggregates a status report
config.py is the config hub — YAML storage + environment variable fallback + sensitive value masking
skill/ is the agent instruction layer — SKILL.md routing table + 6 categorized reference docs loaded on demand

SKILL.md Structure Analysis

SKILL.md adopts a routing table pattern — this is the skill’s most innovative design decision. Instead of cramming all instructions into one file, it:

YAML frontmatter defines trigger word mappings: 17 platforms’ search/social/career/dev/web/video intents map to Chinese and English triggers
Routing table maps user intent to categorized docs: search → references/search.md, social → references/social.md, etc.
Zero-config quick commands list one-liner upstream tool commands (Exa search, Jina Reader, GitHub CLI, twitter-cli, etc.)
Workspace rules constrain agent behavior (no workspace directory usage, use /tmp/ and ~/.agent-reach/)

This “routing table + on-demand references” design keeps SKILL.md itself lean (~100 lines), while per-channel detailed docs are loaded on demand — avoiding the token waste of cramming everything into context at once.

SKILL.md — YAML Frontmatter 触发词映射 ↗ 源文件

1 --- 2 name: agent-reach 3 description: > 4 Give your AI agent eyes to see the entire internet. 5 17 platforms via CLI, MCP, curl, and Python scripts. 6 Zero config for 8 channels. 7 triggers: 8 - search: 搜/查/找/search/搜索/查一下/帮我搜 9 - social: 10 - 小红书: xiaohongshu/xhs/小红书/红书 11 - 抖音: douyin/抖音 12 - Twitter: twitter/推特/x.com/推文 13 - 微博: weibo/微博 14 - B站: bilibili/b站/哔哩哔哩 15 - V2EX: v2ex 16 - Reddit: reddit 17 - career: 招聘/职位/求职/linkedin/领英/找工作 18 - dev: github/代码/仓库/gh/issue/pr/分支/commit 19 - web: 网页/链接/文章/公众号/微信文章/rss/读一下/打开这个 20 - video: youtube/视频/播客/字幕/小宇宙/转录/yt 21 - finance: 雪球/股票/stock/xueqiu/行情/基金 22 ---

代码解读

L1 name 字段：skill 的唯一标识符，对应 skill 安装目录名 L2 description: 概述 17 平台覆盖 + 8 渠道零配置，让 Agent 快速理解能力边界 L7 triggers 是路由引擎的核心：中英文双语触发词覆盖，一个意图多种表达方式都能命中 L9 social 分类嵌套子平台映射：小红书/抖音/Twitter/微博/B站/V2EX/Reddit 各自独立触发 L17 career 分类：LinkedIn 求职场景，独立于 social 体现了清晰的领域分离 L18 dev 分类用口语化触发词（gh/issue/pr/分支/commit），降低用户的记忆成本 L21 finance 分类对应雪球平台，为股票/基金场景提供专用入口——按领域分类而非按平台

模块关系

Agent Reach 的核心架构可以概括为”安装器 + 诊断器 + 路由表”三层协作：CLI 入口负责环境初始化，Channel 层负责检测上游工具状态，SKILL.md 路由表负责引导 Agent 在运行时选择正确的上游工具。Agent 安装完成后完全绕过 Agent Reach，直接调用底层工具——这种”脚手架”模式确保了零性能和零耦合开销。

Module Relationships

Agent Reach’s core architecture can be summarized as a three-layer collaboration: “installer + doctor + routing table.” The CLI entry point handles environment initialization, the Channel layer checks upstream tool availability, and the SKILL.md routing table guides the Agent at runtime to select the correct upstream tool. After installation, the Agent bypasses Agent Reach entirely and calls underlying tools directly — this “scaffolding” pattern ensures zero performance and coupling overhead.

agent-reach 模块关系图

graph TD
  CLI["cli.py
CLI 入口
1743 行"] -->|调用| Doctor["doctor.py
诊断引擎"]
  CLI -->|读写| Config["config.py
配置管理"]
  CLI -->|安装| Skill["skill/
SKILL.md 安装"]
  CLI -->|提取| Cookie["cookie_extract.py
Cookie 提取"]
  Doctor -->|遍历检测| Registry["channels/__init__.py
渠道注册表"]
  Registry -->|实例化| Base["channels/base.py
Channel 基类"]
  Base -->|继承| CH["17 个 Channel 文件
twitter/youtube/reddit/..."]
  CH -->|检测状态| UP["上游工具
twitter-cli/yt-dlp/gh CLI/..."]
  Skill -->|路由| REF["skill/references/
6 个分类文档"]
  Core["core.py
AgentReach 类"] -->|封装| Doctor
  MCP["integrations/mcp_server.py"] -->|MCP 协议| UP
  Config -->|读写| FS["~/.agent-reach/
config.yaml"]

脚本全量清单

脚本	语言	行数	复杂度	功能
`cli.py`	Python	~1743	⭐⭐⭐⭐⭐	CLI 入口：install/doctor/configure/uninstall/skill/format/check-update/watch 全套命令，包含所有渠道安装逻辑
`core.py`	Python	~42	⭐⭐	AgentReach 公共 API 封装类，薄层包装 doctor 功能
`doctor.py`	Python	~108	⭐⭐⭐	诊断引擎：遍历所有 channel 生成状态报告，Rich 格式化输出
`config.py`	Python	~109	⭐⭐⭐	配置管理：YAML 存储 + 环境变量回退 + 敏感值掩码 + 文件权限控制
`cookie_extract.py`	Python	~267	⭐⭐⭐⭐	从浏览器自动提取 Cookie（Chrome/Firefox/Edge/Brave/Opera）
`channels/base.py`	Python	~36	⭐⭐	Channel 抽象基类：定义 can_handle/check 契约
`channels/__init__.py`	Python	~65	⭐⭐	渠道注册表：导入并维护 ALL_CHANNELS 列表
`channels/*.py` (16 个)	Python	~2000	⭐⭐⭐	各平台 channel 实现：检测上游工具可用性，tier 0/1/2 分级
`integrations/mcp_server.py`	Python	~67	⭐⭐⭐	MCP 服务器集成：mcporter 管理 + Exa 搜索配置
`utils/paths.py`	Python	~45	⭐⭐	工具路径工具函数：yt-dlp 配置路径等
`utils/text.py`	Python	~14	⭐	文本读取工具函数
`skill/SKILL.md`	Markdown	~106	⭐⭐⭐	Agent 路由指令：路由表 + 快速命令 + 工作区规则
`skill/references/*.md` (6 个)	Markdown	~500	⭐⭐⭐	分类详细文档：search/social/career/dev/web/video
`transcribe_xiaoyuzhou.sh`	Bash	~30	⭐⭐	小宇宙播客转录脚本：Whisper + Groq API

Script	Language	Lines	Complexity	Purpose
`cli.py`	Python	~1743	⭐⭐⭐⭐⭐	CLI entry: full suite of install/doctor/configure/uninstall/skill/format/check-update/watch, includes all channel installers
`core.py`	Python	~42	⭐⭐	AgentReach public API wrapper, thin layer over doctor functionality
`doctor.py`	Python	~108	⭐⭐⭐	Diagnostics engine: iterates channels, generates Rich-formatted status report
`config.py`	Python	~109	⭐⭐⭐	Config management: YAML storage + env var fallback + sensitive value masking + file permissions
`cookie_extract.py`	Python	~267	⭐⭐⭐⭐	Auto-extract cookies from browsers (Chrome/Firefox/Edge/Brave/Opera)
`channels/base.py`	Python	~36	⭐⭐	Abstract Channel base class: defines can_handle/check contract
`channels/__init__.py`	Python	~65	⭐⭐	Channel registry: imports and maintains ALL_CHANNELS list
`channels/*.py` (16 files)	Python	~2000	⭐⭐⭐	Per-platform channel implementations: check upstream tool availability, tier 0/1/2 grading
`integrations/mcp_server.py`	Python	~67	⭐⭐⭐	MCP server integration: mcporter management + Exa search configuration
`utils/paths.py`	Python	~45	⭐⭐	Path utility functions: yt-dlp config path, etc.
`utils/text.py`	Python	~14	⭐	Text reading utility functions
`skill/SKILL.md`	Markdown	~106	⭐⭐⭐	Agent routing instructions: routing table + quick commands + workspace rules
`skill/references/*.md` (6 files)	Markdown	~500	⭐⭐⭐	Categorized detailed docs: search/social/career/dev/web/video
`transcribe_xiaoyuzhou.sh`	Bash	~30	⭐⭐	Xiaoyuzhou podcast transcription: Whisper + Groq API

cli.py — CLI 命令引擎

<cli.py> 是整个项目的核心——1743 行的 CLI 入口，包含 install/doctor/configure/uninstall/skill/format/check-update/watch 8 个子命令。install 命令是最复杂的部分：自动检测环境（本地/服务器）、安装系统依赖（gh CLI、Node.js、yt-dlp 配置）、配置 mcporter Exa 搜索、按需安装可选渠道（twitter/weibo/wechat/xiaohongshu/reddit/bilibili）、从浏览器自动提取 Cookie、最后注册 SKILL.md 到 Agent 目录。

<cli.py> is the project’s core — a 1743-line CLI entry point with 8 subcommands: install, doctor, configure, uninstall, skill, format, check-update, and watch. The install command is the most complex: auto-detects environment (local/server), installs system deps (gh CLI, Node.js, yt-dlp config), configures mcporter Exa search, installs optional channels on demand (twitter/weibo/wechat/xiaohongshu/reddit/bilibili), auto-extracts cookies from browser, and finally registers SKILL.md to agent directories.

cli.py — Channel 安装器注册模式 ↗ 源文件

1 # ── Parse --channels ── 2 CHANNEL_INSTALLERS = { 3 "twitter": _install_twitter_deps, 4 "weibo": _install_weibo_deps, 5 "wechat": _install_wechat_deps, 6 "xiaoyuzhou": _install_xiaoyuzhou_deps, 7 "xiaohongshu": _install_xhs_deps, 8 "reddit": _install_reddit_deps, 9 "bilibili": _install_bili_deps, 10 } 11 12 requested_channels = set() 13 if args.channels: 14 raw = [c.strip().lower() for c in args.channels.split(",") if c.strip()] 15 if "all" in raw: 16 requested_channels = set(CHANNEL_INSTALLERS.keys()) | {"xueqiu", "douyin", "linkedin"} 17 else: 18 requested_channels = set(raw)

代码解读

L1 CHANNEL_INSTALLERS 字典：函数指针映射——渠道名 → 安装函数。新增渠道只需添加一个 k-v 对，无需改控制流 L9 xueqiu/douyin/linkedin 不在此字典中，因为它们只需要 cookie 配置或手动设置，没有自动安装步骤 L13 "all" 特殊值：一键安装所有渠道。巧妙地将 COOKIE_CHANNELS 也加入 requested_channels L14 使用 set() 去重：用户可能输入 "twitter,all" 导致重复，set 自动处理

cli.py — Skill 安装的分层优先级策略 ↗ 源文件

1 # Determine skill install path (priority: .agents > openclaw > claude) 2 skill_dirs = [ 3 os.path.expanduser("~/.agents/skills"), # Generic agents (priority) 4 os.path.expanduser("~/.openclaw/skills"), # OpenClaw 5 os.path.expanduser("~/.claude/skills"), # Claude Code (if exists) 6 ] 7 8 # Insert OPENCLAW_HOME path at the beginning if environment variable is set 9 openclaw_home = os.environ.get("OPENCLAW_HOME") 10 if openclaw_home: 11 skill_dirs.insert(0, os.path.join(openclaw_home, ".openclaw", "skills")) 12 13 installed = False 14 for skill_dir in skill_dirs: 15 if os.path.isdir(skill_dir): 16 target = os.path.join(skill_dir, "agent-reach") 17 if _copy_skill_dir(target): 18 installed = True 19 20 if not installed: 21 # No known skill directory found — create for .agents by default 22 target = os.path.expanduser("~/.agents/skills/agent-reach") 23 os.makedirs(os.path.dirname(target), exist_ok=True) 24 _copy_skill_dir(target)

代码解读

L1 优先级策略：.agents（通用标准）> .openclaw > .claude。优先使用社区标准目录 L7 OPENCLAW_HOME 环境变量支持：自定义安装路径时自动插入到最高优先级位置 L12 遍历安装：找到第一个存在的目录就安装。但可能存在多个 Agent 并存的情况，用 installed 标记而非提前 return L18 兜底策略：如果所有已知目录都不存在，自动创建 ~/.agents/skills/ 并安装。确保不会因为目录缺失而静默失败

doctor.py — 诊断引擎

<doctor.py> 实现了一个简洁的诊断引擎。它不自己检测任何东西——每个 channel 自己知道怎么检测自己（通过 check() 方法）。doctor 只负责遍历 ALL_CHANNELS 收集结果，然后按 tier 分层格式化输出。这种”聚合而非实现”的设计使得新增渠道时 doctor 代码完全不用动。

<doctor.py> implements a clean diagnostics engine. It doesn’t detect anything itself — each channel knows how to check itself (via the check() method). The doctor just iterates ALL_CHANNELS, collects results, and formats output by tier. This “aggregate, not implement” design means adding a new channel never requires touching the doctor code.

doctor.py — Tier 分层报告格式化 ↗ 源文件

1 # Tier 0 — zero config 2 lines.append("[bold]✅ 装好即用：[/bold]") 3 for key, r in results.items(): 4 if r["tier"] == 0: 5 # ... format and append 6 7 # Tier 1 — needs free key / login 8 tier1 = {k: r for k, r in results.items() if r["tier"] == 1} 9 tier1_active = {k: r for k, r in tier1.items() if r["status"] == "ok"} 10 if tier1_active: 11 lines.append("[bold]可选渠道（已安装）：[/bold]") 12 13 # Summarize inactive optional channels in one line 14 all_inactive = list(tier1_inactive.values()) + list(tier2_inactive.values()) 15 if all_inactive: 16 names = [r["name"] for r in all_inactive] 17 lines.append( 18 f"还有 {len(names)} 个可选渠道可以解锁（{'、'.join(names)}），" 19 "告诉你的 Agent「帮我装 XXX」即可" 20 )

代码解读

L1 Tier 0 = 零配置即用：这些是用户最需要看到的部分，放在最前面 L6 Tier 1 = 需免费 Key/登录：过滤出已激活的和未激活的，分开显示 L13 未激活渠道的汇总策略：不逐条列出（会显得冗长），而是在一行中展示所有可用名称，引导用户「帮我装 XXX」 L17 引导式交互：报告不仅是状态展示，还是行动指南——用户可以直接告诉 Agent 安装需要的渠道

channels/base.py — 渠道契约

<base.py> 定义了所有渠道必须遵守的契约。设计极简——只有 36 行，但包含了 5 个关键属性（name/description/backends/tier）和 2 个抽象方法（can_handle/check）。tier 分级（0=零配置/1=需免费 Key/2=需复杂设置）是整个诊断系统的核心元数据，让 doctor 能生成分层的状态报告。

<base.py> defines the contract that all channels must follow. The design is minimal — only 36 lines, but contains 5 key attributes (name/description/backends/tier) and 2 abstract methods (can_handle/check). The tier grading (0=zero-config/1=needs free key/2=needs complex setup) is the core metadata of the entire diagnostic system, enabling the doctor to generate tiered status reports.

base.py — Channel 抽象基类 ↗ 源文件

1 class Channel(ABC): 2 """Base class for all channels.""" 3 4 name: str = "" # e.g. "youtube" 5 description: str = "" # e.g. "YouTube 视频和字幕" 6 backends: List[str] = [] # e.g. ["yt-dlp"] — what upstream tool is used 7 tier: int = 0 # 0=zero-config, 1=needs free key, 2=needs setup 8 9 @abstractmethod 10 def can_handle(self, url: str) -> bool: 11 """Check if this channel can handle this URL.""" 12 ... 13 14 def check(self, config=None) -> Tuple[str, str]: 15 """Returns (status, message) where status is 'ok'/'warn'/'off'/'error'.""" 16 return "ok", f"{'、'.join(self.backends) if self.backends else '内置'}"

代码解读

L1 ABC 继承确保每个子类必须实现 can_handle，编译期（mypy）即可发现遗漏 L4 class 变量而非实例变量：所有 channel 共享相同的类型元数据，不需要每次实例化重新赋值 L6 backends 列表：明确声明使用哪个上游工具，为 doctor 报告提供透明度——用户知道背后是什么在运行 L7 tier 三级分级：0/1/2 对应不同安装复杂度。tier 0 激活率直接影响用户对工具的第一印象 L13 check() 提供默认实现：不需要检测的 channel（纯内置工具）直接用基类默认行为，减少样板代码

设计亮点

脚手架而非框架：Agent Reach 不在运行时路径上——Agent 安装完成后直接调用上游工具（twitter-cli、yt-dlp）的 CLI。这意味着零性能开销、零耦合风险，即使 Agent Reach 出 bug 也不影响已安装的工具正常使用。
路由表 + 按需加载：SKILL.md 保持精简（~100 行），只含路由表和常用命令。详细文档拆分为 6 个 references/*.md，Agent 根据用户意图按需阅读。这避免了大量一次性上下文塞入——17 个平台的完整文档加起来可能数千行，但实际每次会话只需要 1-2 个平台。
渠道可插拔架构：每个平台的检测逻辑是独立的 channel 文件，只需实现 can_handle() 和 check() 两个方法。新增平台只需加一个文件 + 在 __init__.py 注册。不满意某个后端？换掉对应文件即可——整个系统的其他部分不需要任何改动。
tier 分级诊断：将所有渠道分为 tier 0/1/2，让 doctor 报告自动按激活难度分层展示。用户第一时间看到”装好即用”的渠道（正面体验），再看可以解锁的可选渠道（引导进一步安装）。
中英文双语触发词映射：YAML frontmatter 中的 triggers 字段同时支持中文和英文，覆盖口语化表达（如 gh/issue/pr、搜/查/找），大幅降低用户发现功能的门槛。

Scaffolding, not framework: Agent Reach stays off the runtime path — after installation, agents call upstream tools (twitter-cli, yt-dlp) directly via CLI. This means zero performance overhead, zero coupling risk — even if Agent Reach has a bug, installed tools continue working.
Routing table + on-demand loading: SKILL.md stays lean (~100 lines) with only the routing table and common commands. Detailed docs split into 6 references/*.md, loaded on demand based on user intent. This avoids cramming context — full docs for 17 platforms could be thousands of lines, but each session typically needs only 1-2 platforms.
Pluggable channel architecture: Each platform’s detection logic is an independent channel file implementing only can_handle() and check(). Adding a platform = one new file + one registration in __init__.py. Unhappy with a backend? Swap the file — nothing else in the system needs to change.
Tiered diagnostics: Channels are graded tier 0/1/2, enabling the doctor report to display by activation difficulty. Users see “ready out of the box” channels first (positive experience), then unlockable optional channels (onboarding guidance).
Bilingual Chinese/English trigger mappings: The YAML frontmatter’s triggers field supports both Chinese and English, covering colloquial expressions (gh/issue/pr, 搜/查/找), significantly lowering the barrier for feature discovery.

可复用模式 / Reusable Patterns

模式	描述	适用场景
路由表模式	SKILL.md 精简为路由表 + 按需引用的分类文档	平台/功能数量多（10+）的 skill，需要避免 token 浪费
脚手架模式	Skill 只负责安装和配置，不在运行时路径上	依赖外部 CLI 工具的 skill，想要零性能和零耦合开销
tier 分级诊断	将功能按配置难度分级，doctor 报告分层展示	有「零配置」和「需配置」两种功能的工具
函数指针注册表	CHANNEL_INSTALLERS 字典：字符串名 → 安装函数映射	需要动态选择安装逻辑的场景，新增功能只需加 k-v 对
Cookie 多浏览器提取	支持 Chrome/Firefox/Edge/Brave/Opera 自动提取 Cookie	需要用户认证的 CLI 工具，简化配置体验

Pattern	Description	Use Case
Routing Table	SKILL.md keeps only routing table + on-demand categorized references	Skills with 10+ platforms/features, avoiding token waste
Scaffolding	Skill only installs and configures, stays off the runtime path	Skills depending on external CLI tools, wanting zero perf/coupling overhead
Tiered Diagnostics	Grade features by config difficulty, doctor reports by tier	Tools with both zero-config and config-required features
Function Pointer Registry	CHANNEL_INSTALLERS dict: string name → installer function	Scenarios needing dynamic install logic, new features add a k-v pair
Multi-Browser Cookie Extraction	Supports Chrome/Firefox/Edge/Brave/Opera auto cookie extraction	CLI tools needing user auth, simplifying configuration

移植思路 / Porting Guide

如果你想在自己的项目里实现类似的”多平台 Agent 工具箱”，核心思路是：

定义最小契约：一个 base class 只需要 can_handle() 和 check() 两个方法——不要过度设计

每个平台一个文件：保持独立，互不依赖——新增/删除/替换都不影响其他

SKILL.md 做路由不做百科全书：Agent 需要的是”从哪里开始”而不是”所有细节”

doctor 命令是体验关键：用户第一印象来自 doctor 输出，各状态分层清晰且引导下一步行动

To build a similar “multi-platform agent toolkit” in your own project, the core philosophy is:

Define a minimal contract: A base class only needs can_handle() and check() — don’t over-engineer

One file per platform: Keep them independent — add/remove/replace without side effects

SKILL.md is a router, not an encyclopedia: The agent needs “where to start,” not “every detail”

The doctor command is key to UX: First impressions come from doctor output — make status tiers clear and actionable

常见坑 / Common Pitfalls

⚠️ Cookie 跨平台提取不可靠：不同浏览器的 Cookie 加密机制不同（macOS Keychain vs Linux gnome-keyring），自动提取可能在某些环境失败。建议 fallback 到手动输入 Cookie 字符串的方式。

⚠️ 版本号三处同步：CLAUDE.md 明确要求 pyproject.toml、__init__.py、tests/test_cli.py 三处版本号必须一致——这是 CI/CD 容易遗漏的坑。

⚠️ 服务器 IP 被封风险：B站等中国平台对海外/服务器 IP 有限制，需要代理（$1/月 residential proxy）。处理这类问题时需要在检测逻辑中区分”工具已安装但 IP 被封”和”工具未安装”两种状态。

⚠️ yt-dlp JS runtime 配置：YouTube 需要 Node.js 作为 JS runtime 才能正常工作，且 yt-dlp 不会自动配置。cli.py 中专门处理了 yt-dlp 的 --js-runtimes node 配置——这是一个容易被忽略的依赖。

⚠️ Cross-browser cookie extraction is unreliable: Different browsers use different encryption (macOS Keychain vs Linux gnome-keyring). Auto-extraction may fail in some environments. Always provide a manual cookie string fallback.

⚠️ Version sync across three locations: CLAUDE.md requires pyproject.toml, __init__.py, and tests/test_cli.py to have matching versions — an easy CI/CD miss.

⚠️ Server IP blocking risk: Chinese platforms like Bilibili block overseas/server IPs, requiring a proxy (~$1/month residential). Detection logic must distinguish “tool installed but IP blocked” from “tool not installed.”

⚠️ yt-dlp JS runtime config: YouTube requires Node.js as a JS runtime and yt-dlp won’t auto-configure it. cli.py handles --js-runtimes node configuration explicitly — an easily overlooked dependency.