157 lines
3.0 KiB
Markdown
157 lines
3.0 KiB
Markdown
# 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 管理
|
|
- 等边界稳定后，再考虑开放外部插件目录
|