How the Doctor Command in Agent Reach Detects and Tests Platform Availability

The doctor command in Agent Reach performs automated health checks by discovering all registered channel subclasses, executing lightweight executable probes via probe_command, and aggregating the results into a human-readable status report that categorizes platforms by configuration complexity.

The doctor command acts as the diagnostic backbone of Agent Reach, ensuring that every supported platform—from YouTube to Twitter—has its required upstream tools installed, accessible on the system PATH, and properly authenticated. According to the Agent-Reach source code, this workflow combines dynamic channel registry discovery with subprocess-based verification to prevent runtime failures before they occur.

How the Doctor Command Discovers Available Channels

Dynamic Channel Registry Discovery

The health check begins by importing get_all_channels from the channels package. At agent_reach/doctor.py line 9, the check_all function calls this helper to retrieve a list of every concrete channel implementation:

from agent_reach.channels import get_all_channels

def check_all(config: Config) -> Dict[str, dict]:
    results = {}
    for ch in get_all_channels():
        # Probe each channel...

Channel registration happens automatically at import time. When individual channel modules (such as youtube.py or twitter.py) load, they register themselves in a global registry defined in agent_reach/channels/__init__.py. This design ensures that get_all_channels() always returns the complete, up-to-date set of supported platforms without manual maintenance lists.

The Platform Availability Testing Mechanism

The Check Method Contract

Every channel inherits from the abstract base class Channel defined in agent_reach/channels/base.py (lines 61-70). The base implementation provides a default check method, but concrete channels override this method to execute real probes:

# agent_reach/channels/base.py

def check(self, config=None) -> Tuple[str, str]:
    """
    Check if this channel's upstream tool is available.
    Returns (status, message) where status is 'ok'/'warn'/'off'/'error'.
    """
    self.active_backend = self.backends[0] if self.backends else "内置"
    return "ok", f"{'、'.join(self.backends) if self.backends else '内置'}"

Executable Probing with probe_command

Concrete implementations leverage agent_reach.probe.probe_command to verify that binaries are not merely present but actually executable. A typical channel override iterates through its ordered backends and attempts to run a lightweight version check:

from agent_reach.probe import probe_command

def check(self, config=None):
    for backend in self.ordered_backends(config):
        ok, msg = probe_command(backend, ["--version"])
        if ok:
            self.active_backend = backend
            return "ok", f"{backend} ({msg})"
    return "off", "not installed"

The probe_command helper executes the command in a subprocess, captures the exit code, and returns a boolean success flag paired with the output string. This confirms four critical criteria:

• PATH accessibility: The executable exists and is discoverable
• Runtime viability: The binary launches without crashing
• Version verification: The tool responds with expected output (e.g., youtube-dl --version)
• Credential validation: Required API keys or authentication tokens are present in the configuration object

Error Resilience in Batch Checking

At agent_reach/doctor.py lines 20-34, the check_all function wraps each channel probe in a try-except block to ensure that a single misbehaving channel cannot abort the entire health report:

def check_all(config: Config) -> Dict[str, dict]:
    results = {}
    for ch in get_all_channels():
        try:
            status, message = ch.check(config)          # ← probe each channel

            active = getattr(ch, "active_backend", None)
        except Exception as e:                           # ← robust error handling

            status, message, active = "error", f"体检异常：{e}", None
        results[ch.name] = {
            "status": status,
            "name": ch.description,
            "message": message,
            "tier": ch.tier,
            "backends": ch.backends,
            "active_backend": active,
        }
    return results

If a probe crashes—perhaps because a binary exists but segfaults on launch—the exception is caught, the status is recorded as "error", and the loop continues to the next platform.

Rendering the Platform Status Report

Tiered Output Formatting

After collecting per-channel dictionaries, doctor.format_report (defined at lines 47-99 of agent_reach/doctor.py) constructs the final output using Rich markup. The report organizes channels into three tiers based on setup complexity:

• Tier 0: Zero-configuration channels that work immediately
• Tier 1: Channels requiring free API keys or simple login
• Tier 2: Complex setup requirements

The formatter decorates each entry with visual indicators:

• ✅ (available): Executable found and responding correctly
• ❗ (warning): Installed but requires authentication or configuration
• ❌ (missing): Binary not found on PATH

Example Doctor Command Output

When executed via python -m agent_reach.cli doctor, the command produces a structured status summary:

$ python -m agent_reach.cli doctor
[bold cyan]Agent Reach 状态[/bold cyan]
========================================
图例：✅ 可用  [yellow][!][/yellow] 已装但需配置/登录  [red][X][/red] 未安装

✅ 装好即用：
  ✅ YouTube — 已就绪
  [!]"Twitter" — 需要登录

可选渠道（已安装）：
  ✅ Reddit — 已就绪（当前后端：praw）

状态：[green]3/5[/green] 个渠道可用
还有 2 个可选渠道可以解锁（Bilibili、GitHub），告诉你的 Agent「帮我装 XXX」即可

The report explicitly displays the active backend when a channel supports multiple implementations (e.g., yt-dlp versus youtube-dl), giving users immediate visibility into which specific tool Agent Reach will invoke.

Summary

• The doctor command automatically discovers all platform channels through a dynamic registry pattern in agent_reach/channels/__init__.py.
• Availability testing relies on probe_command to execute real subprocess calls (such as --version checks) rather than simply verifying file existence on PATH.
• Error isolation ensures that individual channel failures are captured as "error" status entries without crashing the entire diagnostic run.
• The status report groups channels by configuration tier and uses Rich console markup to indicate availability, warnings, and missing dependencies.
• Active backend tracking allows users to see which specific tool (e.g., praw for Reddit) has been selected when multiple backends are supported.

Frequently Asked Questions

What platforms does the doctor command check?

The command checks every platform channel registered in the Agent Reach ecosystem, including YouTube, Twitter, GitHub, Reddit, and Bilibili. Because channels self-register in agent_reach/channels/__init__.py at import time, the doctor automatically includes any new channels added to the codebase without requiring manual updates to the check logic.

How does the doctor command verify a tool is actually working versus just installed?

Rather than checking for file existence, the doctor invokes agent_reach.probe.probe_command to execute a lightweight test command (typically --version) in a subprocess. This confirms the binary is both on the PATH and capable of running successfully, catching issues like permission errors, missing shared libraries, or corrupted installations that a simple file check would miss.

What happens if a specific channel check throws an exception?

The check_all function in agent_reach/doctor.py catches all exceptions during individual channel checks (lines 20-34). It records the status as "error" and stores the exception message, then continues checking remaining channels. This ensures that a single broken tool or misconfigured environment cannot prevent the doctor from reporting on all other platforms.

Can I run the doctor check programmatically instead of via CLI?

Yes. You can import and call check_all directly from agent_reach.doctor, passing a Config object to receive the raw dictionary of results. This allows programmatic health monitoring or integration with external dashboards without parsing the Rich-formatted console output.

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