How Agent Reach Handles Bilibili Access: Channel Architecture and Backend Selection

Agent Reach abstracts Bilibili access through a configurable channel architecture that automatically probes and selects between the bili-cli tool, OpenCLI integration, or a zero-dependency public API based on availability and health status.

Agent Reach treats Bilibili as a modular channel, routing requests through a pluggable backend system implemented in agent_reach/channels/bilibili.py. This design, extending the generic contract defined in agent_reach/channels/base.py, allows the framework to adapt to diverse runtime environments—whether a user has local CLI tools installed or requires a dependency-free fallback—while presenting a unified interface for video metadata retrieval, subtitle extraction, and search operations.

Backend Selection and Priority Order

The Bilibili channel declares its candidate backends through the class attribute backends, specifying the probe order:

backends = ["bili-cli", "OpenCLI", "B站搜索 API"]

As implemented in [agent_reach/channels/bilibili.py lines 36‑40](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py#L36-L40), this list determines the default priority. The Channel.ordered_backends() method—defined in [agent_reach/channels/base.py lines 45‑59](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py#L45-L59)—respects the user override environment variable BILIBILI_BACKEND, allowing you to force a specific implementation regardless of the default order.

Health Probing Mechanism

When agent_reach doctor runs, BilibiliChannel.check() iterates over the ordered backends and executes lightweight health probes to determine the first viable option. The method collates results, records fallback notes, and returns a (status, message) tuple. If no backend responds, it returns an "off" status with remediation advice (see [bilibili.py lines 46‑80](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py#L46-L80)).

bili-cli Probe

The channel first attempts to locate the bili-cli tool by executing bili --version via probe_command() ([bilibili.py lines 82‑94](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py#L82-L94)). The probe distinguishes three states:

• Missing – The command is not found; the backend is skipped.
• Broken – The command exists but reports a non-zero status; a warning is issued with a reinstall hint.
• Healthy – The version check passes, setting self.active_backend = "bili-cli" and returning an "ok" status.

OpenCLI Integration

Next, the channel probes the OpenCLI backend by calling opencli_status() ([bilibili.py lines 96‑110](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py#L96-L110)). This backend is preferred for subtitle retrieval when available, as indicated by the status object returned from the OpenCLI integration layer.

B站搜索 API Fallback

Finally, the channel tests the zero-dependency public API by performing an HTTP GET against https://api.bilibili.com/x/web-interface/search/all/v2?keyword=test&page=1. The helper _search_api_ok() ([bilibili.py lines 24‑33](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py#L24-L33)) returns True only when the response contains code == 0. This backend provides search capability without requiring external CLI installation.

Runtime Usage and Configuration

Once check() succeeds, the active backend identifier is stored in self.active_backend. Subsequent read() or search() calls dispatch to the appropriate implementation, allowing agents to fetch video details or subtitles without knowing the underlying provider.

Run the diagnostic command to verify your current setup:

python -m agent_reach.cli doctor

The output includes the active Bilibili backend and its capabilities, such as:

Bilibili: bili-cli 可用（搜索/热门/排行/视频详情/音频，无需登录；字幕需 OpenCLI。上游 2026-03 起停更）

To force a specific backend (for example, to always use the public API), set the environment variable before running:

export BILIBILI_BACKEND="B站搜索 API"
python -m agent_reach.cli doctor

In Python, the core router automatically selects the active Bilibili backend when you specify the platform:

from agent_reach.core import AgentReach

ar = AgentReach()
results = ar.search("python tutorial", platform="bilibili")
print(results)  # Output varies by backend: structured CLI output or raw JSON from the API

Summary

• Channel Architecture – Bilibili access is encapsulated in agent_reach/channels/bilibili.py, extending the base contract from agent_reach/channels/base.py.
• Three-Tier Backend System – The channel probes bili-cli, OpenCLI, and B站搜索 API in order, selecting the first healthy option.
• Automatic Failover – If bili-cli is missing or broken, the system transparently falls back to OpenCLI or the public search API.
• User Override – Set BILIBILI_BACKEND to bypass automatic selection and force a specific implementation.
• Zero-Dependency Option – The B站搜索 API backend requires no local installation, enabling search functionality in restricted environments.

Frequently Asked Questions

How does Agent Reach choose which Bilibili backend to use?

Agent Reach calls ordered_backends() to retrieve the priority list, respecting the BILIBILI_BACKEND environment variable if set. It then iterates through bili-cli, OpenCLI, and B站搜索 API, executing health checks via check() until it finds a responsive backend. The first healthy backend becomes the active channel for subsequent operations.

What happens if no Bilibili backend is available?

If all probes fail—meaning bili-cli is not installed, OpenCLI is unreachable, and the public API returns a non-zero code—the check() method returns an "off" status with a tuple containing a remediation message. The agent_reach doctor command surface this status, advising users to install the missing CLI tools or check network connectivity.

Can I force Agent Reach to use a specific Bilibili backend?

Yes. Export the BILIBILI_BACKEND environment variable with the exact string from the backends list (e.g., export BILIBILI_BACKEND="bili-cli"). The ordered_backends() method in agent_reach/channels/base.py checks this variable first, placing your specified backend at the top of the probe sequence.

Does the B站搜索 API require authentication?

No. The _search_api_ok() probe and subsequent search calls use Bilibili's public search endpoint (api.bilibili.com/x/web-interface/search/all/v2), which does not require API keys or user login credentials. However, this backend may have rate limits or reduced functionality compared to authenticated CLI tools for operations beyond basic search.

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