How the Agent Reach Doctor Command Verifies Channel Availability Across All Platforms

The doctor command verifies channel availability by iterating over all registered platform classes in agent_reach.channels, invoking each channel's check() method to probe for required external binaries, and aggregating the results into a human-readable health report.

The doctor command in Agent Reach serves as the unified health-checking engine for multi-platform agent deployments. This diagnostic tool systematically verifies that every supported channel—from Twitter and YouTube to Weibo and Bilibili—is correctly installed and ready for operation. Understanding how the doctor command verifies channel availability across all platforms reveals the modular architecture that makes Agent Reach extensible for new integrations.

Channel Registry and Discovery

The verification process begins with discovering all available platform integrations. In agent_reach/channels/__init__.py, the framework maintains a global list called ALL_CHANNELS that registers every channel class upon import.

The function get_all_channels() exposes this registry to the doctor module. When the health check initiates, it calls this function to retrieve a complete list of channel objects without hardcoding platform-specific references. This design allows the doctor command to automatically include new channels as they are added to the codebase, ensuring the availability verification remains comprehensive as the project evolves.

Orchestrating the Health Check

The central coordination logic resides in agent_reach/doctor.py. The check_all() function serves as the primary orchestrator for channel availability verification.

This function accepts a Config object and performs the following sequence:

1. Retrieves all channel instances via get_all_channels()
2. Iterates through each channel object
3. Invokes ch.check(config) to execute platform-specific diagnostics
4. Captures the returned (status, message) tuple alongside static metadata (name, description, tier, back-ends)
5. Stores results in a dictionary keyed by the channel's name attribute

The check_all() function delegates the actual verification work to individual channel classes while maintaining a uniform data structure for result aggregation. This separation of concerns keeps the doctor module focused on workflow orchestration rather than platform-specific implementation details.

Platform-Specific Verification Logic

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 verification requires overriding this method in specific channel files.

External Tool Probing

Channels that depend on external CLI tools implement custom check() methods that probe for binary availability and authentication status. For example, in agent_reach/channels/twitter.py, the TwitterChannel.check() method performs a multi-stage verification:

• Binary Detection: Uses shutil.which to locate the twitter-cli executable
• Functionality Test: Executes twitter status and parses the output
• Status Determination: Returns ("ok", ...) if authenticated, ("warn", "Twitter CLI 未安装…") if missing, or a distinct warning if the binary exists but lacks credentials

Other platforms follow identical patterns:

• YouTube: Verifies yt-dlp installation
• Weibo: Checks for mcporter binary
• Bilibili: Locates bili-cli

Each probe interprets exit codes and command output to classify availability into four states: ok (fully operational), warn (installed but misconfigured), off (not installed), or error (exception during check).

Rendering the Availability Report

After check_all() completes its iteration, agent_reach/doctor.py passes the results dictionary to format_report(). This function transforms raw status data into a Rich-styled terminal output that groups channels by tier and applies color-coded symbols for immediate visual parsing.

The formatted report includes a summary line indicating total availability (e.g., "状态：✅ 3/5 个渠道可用") and actionable suggestions for unlocking additional channels. This presentation layer remains separate from the verification logic, allowing the same check_all() results to drive different output formats if needed.

Running the Doctor Command

CLI Usage

The doctor sub-command is registered in agent_reach/cli.py. When invoked via the command line, the _cmd_doctor() function instantiates a default Config() and executes the verification workflow:

# Run the comprehensive health check

python -m agent_reach.cli doctor

Typical output displays tiered availability:

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

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

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

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

Programmatic Usage

You can also trigger availability verification directly from Python scripts without invoking the CLI:

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

This programmatic interface enables integration with monitoring systems or custom dashboard applications that need to verify Agent Reach channel availability as part of larger deployment pipelines.

Summary

• Registry Loading: The doctor command discovers platforms dynamically via get_all_channels() in agent_reach/channels/__init__.py, avoiding hardcoded channel lists.
• Delegated Verification: Each channel class implements check() in agent_reach/channels/base.py to self-diagnose by probing for required tools like twitter-cli, yt-dlp, or bili-cli.
• Result Aggregation: The check_all() function in agent_reach/doctor.py collects (status, message) tuples from every channel into a unified results dictionary.
• Formatted Output: format_report() converts technical status codes into visual reports with availability counts and installation suggestions.
• CLI Integration: The doctor command in agent_reach/cli.py wires user input to the verification engine through _cmd_doctor().

Frequently Asked Questions

What happens if a channel's external CLI tool is missing?

When shutil.which fails to locate the required binary (such as twitter-cli for Twitter or mcporter for Weibo), the channel's check() method returns a ("warn", ...) tuple with a descriptive message indicating the tool is not installed. The final report categorizes these channels as unavailable but suggests installation commands to unlock functionality.

Can I run the doctor check programmatically without the CLI?

Yes. Import check_all and format_report from agent_reach.doctor along with Config from agent_reach.config. Pass a Config instance to check_all() to receive a dictionary of channel statuses, then use format_report() to generate the display string or process the raw results dict directly for custom monitoring integrations.

How do I add a new platform to the doctor verification system?

Create a new file in agent_reach/channels/ that inherits from Channel (defined in base.py). Override the check() method to probe for your platform's specific requirements (API keys, CLI binaries, or network endpoints). Register the class in agent_reach/channels/__init__.py by adding it to ALL_CHANNELS. The doctor command will automatically include it in the next availability scan.

What do the different status codes mean in the doctor output?

The check() methods return four possible status strings: ok indicates the channel is fully operational with all dependencies satisfied; warn signals that dependencies exist but require configuration (e.g., unauthenticated CLI); off means the external tool is not installed; and error captures exceptions thrown during the verification process itself.

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