230 lines
3.2 KiB
Markdown
230 lines
3.2 KiB
Markdown
# 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 命令细节
|