biliup-next/docs/module-contracts.md

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

transcribe(task, source_video, settings) -> subtitle_srt

SongDetector

detect(task, subtitle_srt, settings) -> songs_json, songs_txt

PublishProvider

publish(task, clip_videos, settings) -> PublishRecord

CommentStrategy

sync_comment(task, publish_record, songs_txt, settings) -> comment_record

CollectionStrategy

sync_collection(task, context, settings) -> CollectionBinding[]

Orchestration Rules

模块本身不负责全局编排。

全局编排由任务引擎或 worker 负责：

• 判断下一步该跑什么
• 决定是否重试
• 写入状态
• 调度具体模块

Error Contract

所有模块失败时应返回统一错误结构：

• code
• message
• retryable
• details

不得只返回原始字符串日志作为唯一错误结果。

Non-Goals

• 模块之间不共享私有目录扫描逻辑
• 模块契约不直接暴露 shell 命令细节