# Plugin System

## Goal

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

优先支持：

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

## Design Principles

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

原则：

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

## Plugin Composition

每个插件由两部分组成：

### 1. Manifest

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

例如：

```json
{
  "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

```text
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 管理
- 等边界稳定后，再考虑开放外部插件目录