How Bili-Backend Routing Works in Agent Reach: bili-cli → OpenCLI → Search API

Agent Reach routes Bilibili requests through a three-tier fallback system—prioritizing the local bili-cli tool, falling back to the OpenCLI browser extension, and finally resorting to the public Bili search API when neither local tool is available.

The Bili-backend routing in Agent Reach abstracts platform complexity behind the BilibiliChannel class in agent_reach/channels/bilibili.py. By automatically probing three distinct backends in order of capability, the system ensures AI agents can access Bilibili content without manual configuration, selecting the first healthy option that returns an "ok" or "warn" status.

The Three-Tier Backend Architecture

The BilibiliChannel declares three backends in its backends list, ranked by functionality:

bili-cli (Preferred)

The bili-cli backend leverages the standalone bilibili-cli command-line tool. When available, this backend provides the full feature set—including video downloads and metadata extraction—without requiring browser authentication.

OpenCLI (Browser Bridge)

The OpenCLI backend acts as a Chrome-extension bridge capable of fetching subtitles and video data via the logged-in browser session. This option activates when bili-cli is missing but the user has the OpenCLI daemon running and extension installed.

B站搜索 API (Fallback)

The B站搜索 API backend provides a lightweight HTTP search endpoint that only supports keyword search. It serves as the final fallback when no local tools are present on the system.

Routing Logic Implementation

The routing mechanism centers on BilibiliChannel.check() (lines 46-76 in agent_reach/channels/bilibili.py), which implements a probe-and-select pattern.

Backend Ordering with User Overrides

Channel.ordered_backends() (defined in agent_reach/channels/base.py, lines 45-60) generates the candidate list. By default, the order follows BilibiliChannel.backends: ["bili-cli", "OpenCLI", "B站搜索 API"].

Users can override this ordering by setting an environment variable or config key named <channel>_backend (e.g., BILIBILI_BACKEND). When configured, the specified backend moves to the front of the probe sequence.

The Probe Sequence

The check() method iterates over the ordered backends, dispatching to dedicated verification methods for each:

1. _check_bili_cli (lines 84-91): Invokes probe_command("bili", ["--version"], ...) from agent_reach/probe.py to verify the binary exists and executes successfully.

2. _check_opencli: Calls opencli_status() (defined in agent_reach/backends/opencli.py, lines 80-100), which returns a status object indicating whether the daemon is running and the extension is connected.

3. _check_search_api: Executes _search_api_ok() (lines 24-31), performing an HTTP GET to the public Bili search endpoint and validating that the JSON response contains code == 0.

Status Resolution and Selection

The probe sequence follows strict selection rules:

• First viable wins: The first backend returning "ok" or "warn" becomes self.active_backend.
• Error tracking: Backends reporting "error" (e.g., a broken bili command) collect messages as broken notes (lines 62-71) and append them to the final status message.
• Complete failure: If all candidates fail, the channel reports "off" and provides installation hints (lines 73-80).

Practical Usage Examples

Checking Channel Status from CLI

Verify which backend is active and diagnose connectivity issues:

$ python -m agent_reach.cli check bilibili

# Probes bili-cli first; if missing falls back to OpenCLI; finally tries the API

Overriding the Backend Selection

Force a specific backend regardless of availability:

# Prioritize OpenCLI over local tools

$ export BILIBILI_BACKEND=OpenCLI
$ python -m agent_reach.cli check bilibili

# Ordered backends become ["OpenCLI", "bili-cli", "B站搜索 API"]

Accessing Content Programmatically

Once the channel has selected an active backend, content reads automatically route through it:

from agent_reach.core import read

# Assuming active_backend = "OpenCLI" after health check

content = read("https://www.bilibili.com/video/BV1xxxxxx")

# Under the hood: invokes opencli bilibili video <url> -f yaml

Summary

• Three-tier hierarchy: Agent Reach prefers bili-cli, falls back to OpenCLI, and finally uses the public search API.
• Dynamic probing: The check() method in bilibili.py (lines 46-76) probes each backend via specialized methods: _check_bili_cli, _check_opencli, and _check_search_api.
• User control: Set BILIBILI_BACKEND to force a specific backend, overriding the default priority order defined in ordered_backends() (base.py lines 45-60).
• Graceful degradation: The system collects error messages from broken backends and only reports "off" when absolutely no option is available.

Frequently Asked Questions

How does Agent Reach choose which Bili backend to use?

Agent Reach probes backends in the order defined by ordered_backends() in agent_reach/channels/base.py, which defaults to ["bili-cli", "OpenCLI", "B站搜索 API"]. The first backend returning "ok" or "warn" from its respective check function becomes the active backend.

Can I force Agent Reach to use a specific backend?

Yes. Set the environment variable BILIBILI_BACKEND (or the corresponding config key) to the preferred backend name. This moves that backend to the front of the probe list, making Agent Reach try it first.

What happens if all Bili backends fail the health check?

If bili-cli is broken, OpenCLI is unreachable, and the search API returns an error code, the BilibiliChannel reports status "off" and includes diagnostic messages from any backends that returned "error" status (collected at lines 62-71 in bilibili.py).

Why does Agent Reach prefer bili-cli over OpenCLI?

The bili-cli tool provides the most complete feature set without requiring a browser session. OpenCLI requires a running Chrome extension and authenticated browser, while the search API is limited to keyword searches only. The ranking ensures the richest data source is used when available.

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