biliup-next/docs/plugin-system.md

Plugin System

Goal

插件系统的目标不是“让任何东西都能热插拔”，而是为未来的能力替换和扩展提供稳定边界。

优先支持：

• 转录提供者替换
• 歌曲识别提供者替换
• 上传器替换
• 评论策略替换
• 合集策略替换
• 输入源扩展

Design Principles

借鉴 OpenClaw 的思路，采用 manifest-first + registry 设计。

原则：

• 插件先注册元信息，再执行运行时代码
• 控制面优先读取 manifest 和 schema
• 核心系统只依赖抽象接口和 registry
• 插件配置必须可校验

Plugin Composition

每个插件由两部分组成：

1. Manifest

描述插件的元信息和配置能力。

例如：

{
  "id": "codex-song-detector",
  "name": "Codex Song Detector",
  "version": "0.1.0",
  "type": "song_detector",
  "entrypoint": "plugins.codex_song_detector.runtime:register",
  "configSchema": "plugins/codex_song_detector/config.schema.json",
  "capabilities": ["song_detect"],
  "enabledByDefault": true
}

2. Runtime

真正实现业务逻辑的代码。

Registry

系统启动时统一构建 registry。

registry 负责：

• 注册插件能力
• 按类型查找实现
• 根据配置激活当前 provider

Registry Types

• ingest_provider
• transcribe_provider
• song_detector
• split_provider
• publish_provider
• comment_strategy
• collection_strategy

Plugin Loading Flow

Discover manifests
  -> Validate manifests
  -> Register capabilities in registry
  -> Load plugin config schema
  -> Validate plugin config
  -> Activate runtime implementation

Why Manifest-First

这样设计有 4 个直接好处：

• 管理台可以在不执行插件代码时展示插件信息
• UI 可以根据 schema 渲染配置表单
• 系统可以提前发现缺失字段或不兼容版本
• 插件运行失败不会影响元数据层的可见性

Suggested Plugin Boundaries

Transcribe Provider

示例：

• groq
• openai
• local_whisper

Song Detector

示例：

• codex
• rule_engine
• custom_llm

Publish Provider

示例：

• biliup_cli
• bilibili_api

Collection Strategy

示例：

• default_song_collection
• title_match_full_video
• manual_binding

Control Plane Integration

插件系统必须服务于控制面。

因此管理台至少需要知道：

• 当前有哪些插件
• 每个插件类型是什么
• 当前启用的是哪一个
• 配置是否有效
• 最近一次健康检查结果

Restrictions

为了避免再次走向“任意脚本散落”，插件系统需要约束：

• 插件不得直接修改核心数据库结构
• 插件不得绕过统一配置系统
• 插件不得私自写独立日志目录作为唯一状态来源
• 插件不得直接互相调用具体实现

Initial Strategy

第一阶段不追求真正的第三方插件生态。

先实现“内置插件化”：

• 核心仓库内提供多个 provider
• 统一用 manifest + registry 管理
• 等边界稳定后，再考虑开放外部插件目录