feat: package docker deployment and publish flow

docs/publish-output-examples.md

@@ -0,0 +1,321 @@
+# 发布输出示例与流程说明
+
+本文档面向使用者说明 `biliup-next` 的主流程、输入输出、当前已实现功能，以及一次多段同场直播发布后的示例文案。
+
+## 项目功能
+
+`biliup-next` 将一场直播录播拆成两个最终发布目标：
+
+- 直播完整版：由外部流程或人工上传到 B 站，本项目负责记录/绑定它的 BV 号，并给它补充置顶时间轴评论、加入完整版合集。
+- 歌曲纯享版：由本项目从直播录播中识别歌曲、切出歌曲片段、合并发布为一个分 P 视频，并给它补充置顶歌单评论、加入纯享版合集。
+
+当前主链路：
+
+```text
+stage 输入视频
+  -> ingest 导入并归并 session
+  -> transcribe 语音转字幕
+  -> song_detect 识别歌曲
+  -> split 切出歌曲片段
+  -> publish 发布歌曲纯享版
+  -> comment 发布/置顶评论
+  -> collection 加入合集
+```
+
+## 输入
+
+最常见输入是把录播视频放入 `data/workspace/stage/`。
+
+支持的形式：
+
+- 单个视频文件：一场直播只有一个录播文件。
+- 多个视频文件：同一场直播被分成多段录播文件。
+- 浏览器上传：通过控制台上传到 stage。
+- 本机复制：通过控制台把服务器上的文件复制到 stage。
+
+输入文件名会用于推测主播和直播开始时间，例如：
+
+```text
+王海颖唱歌录播 04月19日 22时10分.mp4
+王海颖唱歌录播 04月19日 23时05分.mp4
+王海颖唱歌录播 04月20日 00时01分.mp4
+```
+
+## Session 归并
+
+同一主播、时间接近的多个录播片段会归入同一个 session。
+
+同一 session 的行为：
+
+- 只发布一个歌曲纯享版 BV。
+- 多段录播的歌曲会按时间顺序聚合。
+- 评论按 `P1`、`P2`、`P3` 分段展示。
+- 歌曲序号全局递增，不在每个 P 内重新从 1 开始。
+
+示例：
+
+```text
+P1:
+1. 程艾影 — 赵雷
+2. 钟无艳 — 谢安琪
+
+P2:
+3. 慢慢喜欢你 — 莫文蔚
+
+P3:
+4. 空白格 — 蔡健雅
+```
+
+## BV 获取
+
+### 歌曲纯享版 BV
+
+歌曲纯享版由本项目调用 `biliup upload` 发布。
+
+发布成功后，项目会从 `biliup` 输出中提取 BV 号，并写入当前 session 目录：
+
+```text
+bvid.txt
+```
+
+这个 BV 会用于：
+
+- 纯享版评论发布。
+- 完整版评论顶部反向链接。
+- 纯享版合集同步。
+
+### 直播完整版 BV
+
+完整版 BV 可以来自三种方式：
+
+- 控制台手动绑定。
+- API/webhook 传入。
+- `biliup list` 标题匹配。
+
+`biliup list` 会同时接受 `开放浏览` 和 `审核中` 状态。完整版视频只要上传后生成了 BV，即使仍在审核中，也可以被写入纯享版简介、动态和评论互链。
+
+成功解析后会写入：
+
+```text
+full_video_bvid.txt
+```
+
+默认标题匹配是保守的精确匹配：会先去掉空格、标点、括号、冒号等，只保留中文、英文、数字，再比较标题是否相等。
+
+如果 `allow_fuzzy_full_video_match=false`，不会做包含式模糊匹配。为了避免误匹配，推荐在完整版上传完成后手动绑定 BV。
+
+## 示例场景
+
+假设本次直播由三段录播组成：
+
+```text
+王海颖唱歌录播 04月19日 22时10分
+王海颖唱歌录播 04月19日 23时05分
+王海颖唱歌录播 04月20日 00时01分
+```
+
+假设 BV 绑定结果如下：
+
+```text
+本次直播完整版：BVFULLCURR
+本次歌曲纯享版：BVPURECURR
+上次直播完整版：BVFULLPREV
+```
+
+假设识别出的歌曲如下：
+
+```text
+P1:
+00:06:32 程艾影 — 赵雷
+00:14:45 钟无艳 — 谢安琪
+
+P2:
+00:20:57 慢慢喜欢你 — 莫文蔚
+
+P3:
+00:27:16 空白格 — 蔡健雅
+```
+
+## 歌曲纯享版标题
+
+当前模板：
+
+```text
+【{streamer} (歌曲纯享版)】 {date} 共{song_count}首歌
+```
+
+示例：
+
+```text
+【王海颖 (歌曲纯享版)】 04月19日 22时10分 共4首歌
+```
+
+## 歌曲纯享版简介
+
+当前模板会保持简介较短，完整歌单放到置顶评论中，避免 B 站简介截断。
+
+示例：
+
+```text
+王海颖 04月19日 22时10分 歌曲纯享版。
+
+完整歌单与时间轴见置顶评论。
+直播完整版：https://www.bilibili.com/video/BVFULLCURR
+上次直播：https://www.bilibili.com/video/BVFULLPREV
+
+本视频为歌曲纯享切片，适合只听歌曲。
+```
+
+如果某个链接暂时没有 BV，项目会自动移除对应的空链接行。
+
+## 歌曲纯享版动态
+
+示例：
+
+```text
+王海颖 04月19日 22时10分 歌曲纯享版已发布。完整歌单见置顶评论。
+直播完整版：https://www.bilibili.com/video/BVFULLCURR
+上次直播：https://www.bilibili.com/video/BVFULLPREV
+```
+
+## 歌曲纯享版置顶评论
+
+纯享版评论主要给听歌用户看，不带歌曲时间轴，只展示歌名、歌手和互链。
+
+默认由 `runtime/upload_config.json` 的 `comment_template.split_header`、`comment_template.split_part_header`、`comment_template.split_song_line` 生成。
+
+示例：
+
+```text
+当前视频：歌曲纯享版：只保留本场直播中的歌曲片段，歌单见下方。
+直播完整版：https://www.bilibili.com/video/BVFULLCURR （完整录播，含聊天/互动/完整流程）
+上次纯享：https://www.bilibili.com/video/BVPUREPREV （上一场歌曲纯享版）
+
+P1:
+1. 程艾影 — 赵雷
+2. 钟无艳 — 谢安琪
+
+P2:
+3. 慢慢喜欢你 — 莫文蔚
+
+P3:
+4. 空白格 — 蔡健雅
+```
+
+## 直播完整版置顶评论
+
+完整版评论主要给看完整录播的用户跳转歌曲纯享版，并提供完整时间轴。
+
+默认由 `runtime/upload_config.json` 的 `comment_template.full_header`、`comment_template.full_part_header`、`comment_template.full_timeline_line` 生成。
+
+示例：
+
+```text
+当前视频：直播完整版：保留本场完整录播内容，歌曲时间轴见下方。
+歌曲纯享版：https://www.bilibili.com/video/BVPURECURR （只听歌曲看这里）
+上次完整版：https://www.bilibili.com/video/BVFULLPREV （上一场完整录播）
+
+P1:
+1. 00:06:32 程艾影 — 赵雷
+2. 00:14:45 钟无艳 — 谢安琪
+
+P2:
+3. 00:20:57 慢慢喜欢你 — 莫文蔚
+
+P3:
+4. 00:27:16 空白格 — 蔡健雅
+```
+
+## 评论格式配置
+
+评论格式可以像标题、简介、动态一样通过 `runtime/upload_config.json` 修改：
+
+```json
+"comment_template": {
+  "split_header": "当前视频：歌曲纯享版：只保留本场直播中的歌曲片段，歌单见下方。\n直播完整版：{current_full_video_link} （完整录播，含聊天/互动/完整流程）\n上次纯享：{previous_pure_video_link} （上一场歌曲纯享版）",
+  "full_header": "当前视频：直播完整版：保留本场完整录播内容，歌曲时间轴见下方。\n歌曲纯享版：{current_pure_video_link} （只听歌曲看这里）\n上次完整版：{previous_full_video_link} （上一场完整录播）",
+  "split_part_header": "P{part_index}:",
+  "full_part_header": "P{part_index}:",
+  "split_song_line": "{song_index}. {title}{artist_suffix}",
+  "split_text_song_line": "{song_index}. {song_text}",
+  "full_timeline_line": "{song_index}. {line_text}"
+}
+```
+
+字段含义：
+
+- `split_header`：纯享版评论顶部说明。
+- `full_header`：完整版评论顶部说明。
+- `split_part_header` / `full_part_header`：多片段 session 的分段标题，例如 `P1:`。
+- `split_song_line`：从 `songs.json` 生成纯享歌单时的单行格式。
+- `split_text_song_line`：`songs.json` 不可用时，从 `songs.txt` 兜底生成纯享歌单的单行格式。
+- `full_timeline_line`：完整版时间轴评论的单行格式。
+
+常用变量：
+
+- `{current_full_video_link}`：本场直播完整版链接。
+- `{current_pure_video_link}`：本场歌曲纯享版链接。
+- `{previous_full_video_link}`：上一场直播完整版链接。
+- `{previous_pure_video_link}`：上一场歌曲纯享版链接。
+- `{part_index}`：P 分段序号。
+- `{song_index}`：歌曲全局序号。
+- `{title}` / `{artist}` / `{artist_suffix}`：歌曲标题、歌手、带分隔符的歌手后缀。
+- `{song_text}`：不带时间戳的歌曲文本。
+- `{line_text}`：原始时间轴行，通常包含时间戳。
+
+如果评论头部某一行包含空链接变量，例如 `{previous_full_video_link}` 为空，这一整行会自动省略。
+
+## 合集同步
+
+项目维护两个合集目标：
+
+- 合集 A：直播完整版。
+- 合集 B：歌曲纯享版。
+
+当前配置中的示例 ID：
+
+```text
+直播完整版合集：7196643
+歌曲纯享版合集：7196624
+```
+
+合集同步完成后，如果启用了清理策略，项目可以删除本地原视频或切片视频以节省空间。当前默认不删除。
+
+## 幂等与重试
+
+项目会在 session 目录写入标记文件，避免重复上传和重复评论。
+
+常见标记：
+
+```text
+bvid.txt
+full_video_bvid.txt
+upload_done.flag
+comment_split_done.flag
+comment_full_done.flag
+collection_a_done.flag
+collection_b_done.flag
+```
+
+发布阶段的关键行为：
+
+- 首批最多上传 5 个分 P。
+- 超过 5 个分 P 时，后续通过 append 追加。
+- 已经写入 `bvid.txt` 后，重试会优先 append 到已有视频，而不是重新发布。
+- `publish_progress.json` 记录 append 进度，避免重试时重复追加已完成批次。
+
+评论阶段的关键行为：
+
+- 同一 session 只由最早片段负责聚合评论。
+- 非 anchor 片段进入评论步骤时会跳过实际发评。
+- 这样可以避免同一场直播的多个片段重复发布相同评论。
+
+## 使用建议
+
+发布前建议确认：
+
+- stage 中的视频文件名能解析出主播和时间。
+- `runtime/upload_config.json` 中标题、简介、动态符合预期。
+- 完整版上传完成后，尽量手动绑定 `full_video_bvid`。
+- worker 重启前确认已有 `bvid.txt` 和 `publish_progress.json` 是否符合当前发布进度。
+- 如需自动匹配完整版 BV，确认 `biliup list` 中完整视频标题与任务标题标准化后相等。