init biliup-next

docs/plugin-system.md

@@ -0,0 +1,156 @@
+# 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 管理
+- 等边界稳定后，再考虑开放外部插件目录