How Agent-Reach Doctor Checks Channel Availability and Detects Platform Health

The agent-reach doctor command verifies platform integrations by executing each channel's check() method and aggregating health statuses into a styled report.

The Agent-Reach repository provides a unified interface for AI agents to interact with multiple social platforms. The doctor sub-command serves as the health-checking engine, validating that every supported channel—from Twitter to YouTube—has its required external dependencies installed and authenticated.

Understanding the Doctor Command Architecture

The availability check follows a registry-based pattern where channel classes self-register and expose standardized health diagnostics.

Channel Registry and Discovery

All platform integrations are catalogued in agent_reach/channels/__init__.py. This module maintains a global list called ALL_CHANNELS that contains every supported channel class. The function get_all_channels() exposes this registry to the rest of the application.

When the doctor command runs, it first retrieves this complete list of channels to determine which platforms need verification.

The Check Orchestration Loop

The main orchestration logic resides in agent_reach/doctor.py. The function check_all() iterates over the list returned by get_all_channels(). For each channel instance, it invokes ch.check(config) and stores the returned (status, message) tuple alongside static metadata—including the channel's name, description, tier, and backends—in a dictionary keyed by channel name.

This design delegates the actual validation logic to each channel class while the doctor module handles aggregation and reporting.

How Individual Channels Self-Diagnose

Every concrete channel inherits from agent_reach.channels.base.Channel. The base class provides a default check implementation that simply returns ("ok", ...) for built-in channels requiring no external tools. Real availability checks override this method in specific channel files.

Base Channel Implementation

The abstract Channel class in agent_reach/channels/base.py defines the interface that all platforms must implement. Its default check method acts as a pass-through for channels that are always available, while subclasses implement tool-specific detection logic.

Concrete Channel Examples

Twitter: In agent_reach/channels/twitter.py, the TwitterChannel.check() method first probes for the twitter-cli binary using shutil.which. If found, it executes twitter status and parses the output. A successful authentication yields ("ok", ...) with a message confirming CLI availability. Missing binaries return ("warn", "Twitter CLI 未安装…"), while present but unauthenticated tools produce distinct warning messages.

Other Platforms: Each channel follows the same pattern:

• YouTube: Checks for yt-dlp
• Weibo: Checks for mcporter
• Bilibili: Checks for bili-cli

These implementations interpret exit codes and output to classify status as ok, warn, off, or error.

Report Generation and CLI Integration

After completing the validation loop, the doctor command transforms raw status data into human-readable output.

Formatting Results

The function format_report() in agent_reach/doctor.py converts the results dictionary into a Rich-styled report. The output groups channels by tier (e.g., "装好即用" vs. "可选渠道") and displays colored status symbols. A summary line indicates overall availability, such as "状态：✅ 3/5 个渠道可用".

CLI Entry Point

The command registration occurs in agent_reach/cli.py. The sub-parser named "doctor" wires to _cmd_doctor(), which instantiates Config() and invokes check_all(Config()) before printing the formatted report. This makes the CLI layer a thin orchestrator that delegates all validation to the channel classes.

Practical Usage Examples

Run the health check from your terminal:

python -m agent_reach.cli doctor

Typical output includes categorized availability:

Agent Reach 状态
========================================

✅ 装好即用：
  ✅ YouTube — 内置
  ✅ GitHub — 内置

可选渠道（已安装）：
  ✅ Twitter — twitter-cli 完整可用（搜索、读推文、时间线、长文/Article、用户查询、Thread）
  ✅ Bilibili — bili-cli 已安装

状态：[green]4/5[/green] 个渠道可用
还有 1 个可选渠道可以解锁（Weibo），告诉你的 Agent「帮我装 Weibo」即可

Programmatic access from Python scripts:

from agent_reach.doctor import check_all, format_report
from agent_reach.config import Config

cfg = Config()
results = check_all(cfg)            # dict of channel statuses

print(format_report(results))       # pretty text report

Summary

• The agent-reach doctor command validates platform integrations by iterating through the ALL_CHANNELS registry in agent_reach/channels/__init__.py.
• Each channel's check() method in agent_reach/doctor.py probes for specific external tools like twitter-cli, yt-dlp, or bili-cli.
• Status classifications include ok, warn, off, and error, determined by binary presence and authentication state.
• The base Channel class in agent_reach/channels/base.py provides default implementations, while concrete channels like TwitterChannel override with tool-specific logic.
• Results render via format_report() in agent_reach/doctor.py, producing tiered, color-coded summaries through the CLI entry point in agent_reach/cli.py.

Frequently Asked Questions

What external tools does agent-reach doctor check for?

The doctor command detects platform-specific CLI tools including twitter-cli for Twitter, yt-dlp for YouTube, mcporter for Weibo, and bili-cli for Bilibili. Each channel's check() method uses shutil.which to verify binary availability before testing authentication status.

How does the doctor command determine if a channel is available?

Availability follows a two-step process: first, check_all() in agent_reach/doctor.py calls get_all_channels() to retrieve registered channel classes. Then it executes each channel's check(config) method, which returns a status tuple. Channels report ok when tools are present and authenticated, warn when tools are missing or unauthenticated, and error for detection failures.

Can I run the doctor check programmatically without the CLI?

Yes. Import check_all and format_report from agent_reach.doctor, instantiate Config() from agent_reach.config, and pass it to check_all(). This returns a dictionary mapping channel names to status metadata, which you can process directly or format using format_report() for human-readable output.

What do the different status levels mean in the doctor report?

The report uses four statuses: ok indicates full functionality, warn signals missing dependencies or authentication issues, off marks disabled channels, and error captures unexpected failures during the check process. These statuses originate from each channel's check() implementation in files like agent_reach/channels/twitter.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}