Understanding the Multi-Backend System for Bilibili in Agent-Reach

Agent-Reach implements a resilient multi-backend system for Bilibili that routes requests through bili-cli for standard operations, OpenCLI for specialized tasks like subtitles, and maintains a deprecated yt-dlp fallback path that was disabled after Bilibili began returning HTTP 412 responses.

Agent-Reach treats every supported platform as a channel that abstracts concrete implementation details behind a unified interface. The Bilibili channel, implemented in agent_reach/channels/bilibili.py, exemplifies this approach through a sophisticated multi-backend architecture that decouples the logical API from underlying tools. This design allows the system to gracefully adapt to service changes while providing users with clear installation guidance for missing dependencies.

The Three-Backend Architecture

The Bilibili channel delegates operations to three distinct backends, each serving specific capabilities and fallback scenarios.

yt-dlp (Legacy and Deprecated)

Historically, yt-dlp served as the primary backend for fetching video metadata and stream information. As of June 2026, Bilibili began returning HTTP 412 responses to yt-dlp requests, rendering the tool unusable for this platform. The source code now contains an explicit deprecation notice (yt-dlp was REMOVED…), and while the code path remains structurally present as a last-ditch fallback, it is effectively disabled in the current version.

bili-cli (Primary Backend)

The bili-cli (package name bilibili-cli) serves as the primary backend for all read and search operations. This public CLI tool provides fast, login-free access to video titles, URLs, hot-lists, and basic metadata. The channel detects its presence using probe_command("bili", ["--version"], …) during initialization. When available, the channel delegates all standard operations—such as retrieving video details and performing searches—to this executable.

OpenCLI (Specialized Backend)

For capabilities not covered by bili-cli—most notably subtitle extraction—the channel forwards requests to OpenCLI. The command opencli bilibili subtitle <BV-id> invokes this backend, which may internally call the same bili-cli binary for initial search before falling back to a dedicated subtitle API when necessary.

Routing Logic and Capability Detection

When the Bilibili channel is instantiated, it performs capability detection by probing for the bili executable. If the binary is not found in the system path, the channel outputs a specific installation hint: pipx install bilibili-cli（搜索/热门/视频详情，无需登录）.

The routing logic follows this pattern:

• Read operations (agent-reach read <url>): When processing a video URL, the channel executes bili video <BV-id> via the bili-cli backend.
• Search operations (agent-reach search-bilibili <query>): The channel runs bili search "<query>" through the bili-cli backend.
• Subtitle operations: The channel directly invokes opencli bilibili subtitle <BV-id>, delegating to the OpenCLI backend.

If any backend fails due to network errors or missing binaries, the channel attempts to fall back to the legacy yt-dlp path, though this is effectively non-functional in the current implementation.

Installation and Dependency Management

Agent-Reach automates dependency management through the _install_bili_deps helper function located in agent_reach/cli.py. This function attempts to install bilibili-cli using either pipx or uv when the user triggers installation commands or when the system detects a missing dependency during channel initialization.

The installation process ensures users receive a "plug-and-play" experience without manual configuration, while the modular backend design allows the system to leverage the best-available implementation for each specific capability.

Practical Usage Examples

The following commands demonstrate how the multi-backend system handles different Bilibili operations:

# Basic video read (delegates to bili-cli)

$ agent-reach read 'https://www.bilibili.com/video/BV1d4411N7zD'

# Search Bilibili for "AI" (uses bili-cli)

$ agent-reach search-bilibili 'AI' -n 3

# Download subtitles for a Bilibili video (delegates to OpenCLI)

$ opencli bilibili subtitle BV1d4411N7zD -f yaml

If bili-cli is not installed, the first command automatically displays the installation hint, guiding the user to run pipx install bilibili-cli before retrying.

Summary

• Agent-Reach implements a channel-based architecture where the Bilibili platform (agent_reach/channels/bilibili.py) abstracts three concrete backends.
• bili-cli serves as the primary backend for read and search operations, providing fast, login-free access to video metadata.
• OpenCLI handles specialized tasks like subtitle extraction that require additional API endpoints.
• yt-dlp is deprecated and effectively disabled due to HTTP 412 errors from Bilibili, though the fallback structure remains in the codebase.
• The system uses probe_command for capability detection and provides automated installation via _install_bili_deps in agent_reach/cli.py.

Frequently Asked Questions

Why was yt-dlp removed from the Bilibili backend?

Bilibili began returning HTTP 412 responses to yt-dlp requests as of June 2026, breaking metadata extraction functionality. The Agent-Reach maintainers added a deprecation notice in agent_reach/channels/bilibili.py indicating that yt-dlp was REMOVED, and while the fallback code path structurally remains, it is effectively disabled in the current version to prevent errors.

How does Agent-Reach detect if bili-cli is installed?

During channel initialization, the system calls probe_command("bili", ["--version"], …) to check for the executable in the system path. If the probe fails, the channel outputs a specific installation hint directing users to install bilibili-cli via pipx or uv, ensuring the multi-backend system can route operations to the primary backend.

What happens if I try to download subtitles without bili-cli installed?

Subtitle download operations are routed through the OpenCLI backend (opencli bilibili subtitle …), which may attempt to use bili-cli internally for initial video lookup. If the CLI is missing, the operation will fail with an error indicating the missing dependency, and the user will be prompted to install bilibili-cli using the standard installation helper.

Can I still use yt-dlp as a fallback for Bilibili videos?

No. While the source code retains a structural fallback path to yt-dlp that triggers when primary backends fail, this path is effectively disabled in the current version. The deprecation notice explicitly indicates that yt-dlp was removed from the Bilibili channel, and the system is designed to rely exclusively on bili-cli and OpenCLI for all operations.

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