# 发布输出示例与流程说明

本文档面向使用者说明 `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` 中完整视频标题与任务标题标准化后相等。