init biliup-next

2026-04-01 00:44:58 +08:00
commit d0cf1fd0df
127 changed files with 15582 additions and 0 deletions
--- a/docs/module-contracts.md
+++ b/docs/module-contracts.md
@ -0,0 +1,229 @@
+# Module Contracts
+
+## Goal
+
+定义各模块的职责边界、输入输出和契约，避免旧系统中“脚本互相读目录、互相猜状态”的耦合方式。
+
+## Contract Principles
+
+- 每个模块只处理一类能力
+- 模块只接收明确输入，不扫描全世界
+- 模块输出必须结构化
+- 模块不直接操控其他模块的内部实现
+- 模块不直接依赖具体 provider
+
+## Shared Concepts
+
+所有模块统一围绕这些对象协作：
+
+- `Task`
+- `TaskStep`
+- `Artifact`
+- `Settings`
+- `ProviderRef`
+
+## Ingest Module
+
+### Responsibility
+
+- 接收文件输入
+- 校验最小处理条件
+- 创建任务
+
+### Input
+
+- 本地文件路径
+- 当前配置
+
+### Output
+
+- `Task`
+- `source_video` artifact
+
+### Must Not Do
+
+- 不直接转录
+- 不写上传状态
+
+## Transcribe Module
+
+### Responsibility
+
+- 调用转录 provider
+- 生成字幕产物
+
+### Input
+
+- `Task`
+- `source_video` artifact
+- `transcribe` settings
+
+### Output
+
+- `subtitle_srt` artifact
+
+### Must Not Do
+
+- 不识别歌曲
+- 不决定切歌策略
+
+## Song Detect Module
+
+### Responsibility
+
+- 根据字幕识别歌曲
+- 生成歌曲结构化结果
+
+### Input
+
+- `Task`
+- `subtitle_srt` artifact
+- `song_detect` settings
+
+### Output
+
+- `songs_json` artifact
+- `songs_txt` artifact
+
+### Must Not Do
+
+- 不切歌
+- 不上传
+
+## Split Module
+
+### Responsibility
+
+- 根据歌曲列表切割纯享版片段
+
+### Input
+
+- `Task`
+- `songs_json` artifact
+- `source_video` artifact
+- `split` settings
+
+### Output
+
+- 多个 `clip_video` artifact
+
+## Publish Module
+
+### Responsibility
+
+- 上传纯享版视频
+- 记录发布结果
+
+### Input
+
+- `Task`
+- `clip_video[]`
+- `publish` settings
+
+### Output
+
+- `PublishRecord`
+- `publish_bvid` artifact
+
+### Must Not Do
+
+- 不负责评论文案生成
+- 不负责合集匹配策略
+
+## Comment Module
+
+### Responsibility
+
+- 发布并置顶评论
+
+### Input
+
+- `Task`
+- `PublishRecord`
+- `songs_txt` artifact
+- `comment` settings
+
+### Output
+
+- `comment_record` artifact
+
+## Collection Module
+
+### Responsibility
+
+- 根据策略同步合集 A / B
+
+### Input
+
+- `Task`
+- `PublishRecord` 或外部 `full_video_bvid`
+- `collection` settings
+- `collection strategy`
+
+### Output
+
+- `CollectionBinding`
+
+### Internal Sub-Strategies
+
+- `full_video_collection_strategy`
+- `song_collection_strategy`
+
+## Provider Contracts
+
+### TranscribeProvider
+
+```text
+transcribe(task, source_video, settings) -> subtitle_srt
+```
+
+### SongDetector
+
+```text
+detect(task, subtitle_srt, settings) -> songs_json, songs_txt
+```
+
+### PublishProvider
+
+```text
+publish(task, clip_videos, settings) -> PublishRecord
+```
+
+### CommentStrategy
+
+```text
+sync_comment(task, publish_record, songs_txt, settings) -> comment_record
+```
+
+### CollectionStrategy
+
+```text
+sync_collection(task, context, settings) -> CollectionBinding[]
+```
+
+## Orchestration Rules
+
+模块本身不负责全局编排。
+
+全局编排由任务引擎或 worker 负责：
+
+- 判断下一步该跑什么
+- 决定是否重试
+- 写入状态
+- 调度具体模块
+
+## Error Contract
+
+所有模块失败时应返回统一错误结构：
+
+- `code`
+- `message`
+- `retryable`
+- `details`
+
+不得只返回原始字符串日志作为唯一错误结果。
+
+## Non-Goals
+
+- 模块之间不共享私有目录扫描逻辑
+- 模块契约不直接暴露 shell 命令细节