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

> Learn how the Agent Reach doctor command detects and tests platform availability using automated health checks probe commands and a human-readable status report for efficient system monitoring.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-21

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) line 9, the `check_all` function calls this helper to retrieve a list of every concrete channel implementation:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/youtube.py) or [`twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/twitter.py)) load, they register themselves in a global registry defined in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python

# 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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
$ 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.