分章节

章节是给观众跳着看用的：拖进度条的人看一眼章节名，就知道要去哪一段；看过的人想回头找某个地方，也靠它。所以章节的标题要说清这一段讲什么，起点要落在话题真正开始的地方，一个章节对应一个话题。

最容易做坏的样子有两种。一种是按时间平均切：每五分钟一章，起点落在一句话的中间，标题是「第一部分」「继续讨论」，观众看了等于没看。另一种是标题太像总结：一章一句长话，章节列表反而读不动。章节名是路标，不是摘要；摘要另有一句话的位置。

1. 取材料

1. 用 videos_inspect 看视频：时长、已有的章节（chapters）、文档。没有转写（kind 为 speech 的文档）时先转写，告诉用户转写在进行。从链接导入的素材另有 assets[].source：chapters 是作者的章节（平台给的结构化章节，或从简介里的时间戳大纲解析出来的），没有时是 []；description 是截断的简介。
2. 带时间码的文稿：export（kind transcript、format md、timestamps true；有几份文稿时按它列出的候选用 documentId 指定），jobs_inspect 等到 completed，读 outputs 里的文件。它按段落给出剪辑后时间线上的时间，章节的时间就取段落开头的这个时间码，不要自己估算。
3. 视频已经有章节时，先问用户是要替换、调整还是保留；用户只说「加章节」而已有的章节是新的，不要覆盖。

2. 有作者章节或用户给了大纲时

作者自己分过的章节通常比你分的更贴近他的意图，照它来，不自己分，也不手工对时间。来源素材自带章节（assets[].source.chapters 不为空），或用户贴来一份带时间的大纲（0:00 开场、1:02:03 问答 这类）时，用 chapters_adopt：

• 作者章节：给 video（素材不止一个时给 asset，有几份转写时给 document）。用户贴的大纲：给 outline，可以是 [{ at, title }]，也可以是贴来的原文。不确定时先带 dryRun 看回执，再正式写。
• 它把每一条吸到文稿里最近的段落或句子起点（段落优先，其次句子、字幕条、词），清洗标题后整份写进视频的章节（替换已有的；已有章节要先按第 1 步问过用户）。
• 读回执的 sourceChapters：entries 共几条；matched 吸到了起点；ambiguous 附近有几个起点、取了离作者时间最近的那个（同样近取靠后的）；snapped 时间挪动过；unanchored 对不上、保留了原来的时间。rows 逐条给标题、写入的时间 at、原来的时间 sourceAt 与状态；带 offTimeline 的条目对应的地方不在时间线上（比如剪掉了）。交付时说清对上几条，把 ambiguous、unanchored、offTimeline 的条目逐条列给用户：这些是他要自己看一眼的地方。
• 带 untitled: true 的章节（作者章节或回执的 rows 里）：平台只给了分界，Untitled Chapter N 是下载工具填的占位名，不是作者的标题。读这一章到下一章之间的转写给它起标题（用视频的语言），连同其余各章用 outline（[{ at: sourceAt, title }]）再调用。不带 dryRun 直接采用会返回 UNTITLED_SOURCE_CHAPTERS，照错误里的 rows 补上标题即可。
• 返回 NO_SOURCE_CHAPTERS：素材没有作者章节，按下面的做法自己分。返回 ASSET_NOT_PLACED：素材不在时间线上，先放上去。
• 用户要你自己写的章节，或想要和作者大纲不同的粗细时，才走下面的做法自己分，作者的大纲当参考：转写和它吻合的地方沿用它的分界和标题（保留作者用的语言与措辞），只在转写明显不同的地方增、并、删章；大纲的时间只是大致的，章节的起点仍取文稿里段落的时间码。

3. 分几章

按粗细定一个大致的目标章数，不硬凑：

粗细	大约多长一章
粗	约 10 分钟
适中（默认）	约 5 分钟
细	约 2.5 分钟

目标章数 = 时长 ÷ 每章时长，取整；至少 2 章，最多 20 章，超过一小时的录音上限按每小时 20 章放大。有作者大纲当参考、用户又没指定粗细时，目标章数取大纲的条数。话题真正的转换比这个少时，少分几章没关系：目标章数是个大概，不是指标。

4. 怎么分

先用 speech_topic_boundaries（video；有几份转写时给 documentId）找话题转折。它按意思比较前后几段讲话，给出话题明显变了的地方。它默认最多给 24 章的候选；超过一小时的录音按第 3 步的上限传 maxChapters（比目标章数多留几章的余地，最多 200），用户要的章节很短时把 minChapterSec 调小：

• mode 为 topic：章节只落在 first（第一段的起点）与 candidates[].at 上，不在别处新开；before / after 是转折前后的原文，对照文稿确认这里确实换了话题。候选比目标章数多时按第 3 步的粗细合并：先合掉 depth 明显小的（多半是小插曲或举例），属于同一个更大话题的相邻几处合成一章。候选带 visualShift（这部视频建了画面索引）时，depth 相近、拿不准留哪处时，留画面也换了的（visualShift 明显大：换场景、换幻灯片、换演示对象）；它只作佐证，不单凭它新开章节。候选的时间已经落在段落或句子的开头，直接用。
• mode 为 model：没有候选（reason 给原因：没装语义模型、文稿太短，或为 null 时没找到明显的转折），照下面的做法读文稿自己找。
• 用户要的粗细比候选更细（候选比目标章数少很多）时，可以在候选之间按文稿再分，但起点仍取文稿里段落的时间码，并在交付时说明哪几章是你另分的。

动手前先通读文稿（有候选时重点读候选前后），列出话题在哪里转换：说话人换了题目、从问题转到做法、从一个案例转到下一个。章节就落在这些地方。

• 每章从一段话的开头开始；时间取文稿里那一段的时间码。不编造时间，不把章节放在一句话的中间。
• 第一章通常从 0 秒开始。
• 每章一个标题和一句话的摘要（不超过约 20 个词，说清这一章讨论什么）。标题是观众扫一眼就懂的路标，用这一段的内容本身，不用「第一部分」「继续」「其他」这类说了等于没说的词；摘要补一句这一章具体讲到什么。
• 标题和摘要不能为空，彼此不同，风格一致；用转写的语言写，用户要别的语言时才换。
• 录音很长时分几部分读：每部分先列出话题单元（各自的起点段落、标题和摘要），再把它们合成最终的章节。单元比目标章数多时，把属于同一个更大话题的相邻单元合成一章，起点取合并后第一个单元的起点，标题和摘要覆盖合并后的整段；分部分的接缝处尤其要合并，那里一个话题常被人为切开。不是第一部分时，开头可能接着上一部分的话题，不必在这一部分的第一段强加一章。

对比一下（只是示意）：

不好：05:00 第二部分 / 10:00 继续讨论模型 / 15:00 其他

好：04:37 为什么蒸馏后效果掉得厉害 / 11:02 混合方案怎么配 / 16:48 上线后的三个坑

后一种每个起点都落在话题开始的那一段，标题看一眼就知道要不要跳过去。

5. 写进视频

用 edits_apply 的 setChapters 一次写入整份章节列表（at 是上面取到的秒数，按时间严格递增；title、summary 照写）。只改一两章时用 upsertChapter 或 removeChapter。章节固定在时间线的时刻上：剪口播（addCuts、接受剪辑建议、恢复剪口）会让章节跟着内容走，别的剪辑（移动、删除片段、波纹删除）不会，这类剪辑改了时长时提醒用户章节可能要重新对一遍。

6. 要避免的

• 不要按时间平均切，不要把起点放在一句话中间，不要自己估算时间。
• 标题不要写成「第一部分」「继续」「其他」，也不要写成一整句摘要。
• 素材有作者章节时不要自己重分；用户已有章节时不要不问就覆盖。
• 不要硬凑目标章数。

7. 交付

• 列出写进去的章节：时间（时:分:秒，不到一小时写分:秒）、标题、摘要。
• 说明用的是作者的大纲还是自己分的，粗细与章数；自己分时说明边界是否来自话题转折候选（speech_topic_boundaries 的 mode），另分的几章点出来。用了作者大纲时报吸附统计：共几条、对上几条；ambiguous、unanchored、offTimeline 的条目逐条列出。
• 分章失败不影响转写和其他结果：如实说明原因，最多重试一次，不反复重试。