说话人标注
用户要的是：文稿里每句话前面是真名，字幕上看得出谁在说，导出的文稿和配音按人分开。这件事分两步：先分清有几个声音、每句归谁（区分），再给每个声音一个真名（标注）。区分靠语音模型，标注靠证据，两步都不靠猜。
最容易做坏的样子是猜：看到简介里列了两位嘉宾，就把「说话人 1」「说话人 2」按顺序填上去。猜错的名字会出现在每一条字幕和每个导出的文件里，用户往往要看到很后面才发现，比留着「说话人 1」糟得多。
1. 先看现状
用 videos_inspect 找到这个视频的转写（kind 为 speech 的文档；有几份时按来源素材对上用户说的那段），再 documents_read 读它：
- 正文的
speakers[]列出每位说话人的 id 和 name，每个词带说话人。 - 已经区分过（有两位及以上说话人）：跳到第 3 节，只做标注。
- 没区分（只有一位，或词上没有说话人），但用户说视频里不止一个人：做第 2 节。
- 用户只想换名字、不想重跑时，也只做第 3 节。
2. 区分：按声纹重新转录
区分要重新转录，并取代当前文稿，不另建一份。这一步会丢掉用户在文稿里手改过的字，所以先说清楚再做：
- 先告诉用户：重新转录会取代当前文稿，之后在文稿里手改过的字会被丢掉；译文、字幕与配音会按新文稿结转。用户同意再继续。
- 用 transcribe 给这个视频、
diarize为 true、target为 replace；语言与提示（人名、术语）沿用这份文稿的，用户给了新的就用新的。 - 模型不能区分时任务照常完成，结果带
diarization-unavailable警告：告诉用户这个模型分不了说话人，要装「说话人区分」模型包或换能区分的模型；不要假装区分好了。 - 文稿转录之后被用户改过时，取代会以
TRANSCRIPT_EDITED拒绝：把这一点告诉用户，用户确认丢掉那些修改，才加acceptEdited重来。 - 任务完成后重新 documents_read，看分出了几位、每位说了多少。
3. 标注：给每位起名字
动手前先把每位说话人的证据找齐，再一起定名字：
- 占位名：转写流程自动起的「说话人 n」及它在别的界面语言里的对应（
Speaker 1、Sprecher 1这类「说话人 + 编号」）、识别服务给的编号标签（SPEAKER_00、S1、spk-1），以及名字为空或等于 id 的。别的名字是用户起的，不动。 - 证据从哪来：文稿开头一段；每位说话人第一次开口前后的几句；来源素材的标题、发布者与简介（videos_inspect 的
assets[].source）；画面上的姓名条：用 videos_frames 取开头一两分钟和每位首次开口处的几帧看，姓名条要明确标着这一位在说话，画面上随便出现的名字不算。 - 什么算证据：自我介绍（「我是……」「my name is …」）；对方引介（「今天请到了……」「welcome, …」）；被点名后紧接着这一位的回应；签名式的收尾；来源信息唯一地指明了其中一位。元数据里列出几位嘉宾、但分不出哪个声音是谁时，还要文稿里的证据。发言顺序、说话人编号、话题本身都不算；反过来，标题或简介点出了参与者时更要逐位找证据，把名字对到声音上。
- 名字怎么写：材料里实际用的形式，通常是全名，没有全名时用出现的那种；保留原来的文字与拼写，不翻译、不音译；不加头衔、敬称、机构、括号、引号或说明；不超过 40 个字符。没有名字、但明确说了角色（主持人、采访者、旁白）时可以用简短的角色标签；不能只凭对话的样子编一个角色。
- 不猜：拿不准就保留占位名。
- 一人几个 id：区分可能把同一个人拆成几个 id，或把两个人并成一个。各自有证据时给几个 id 同一个名字，不合并 id；声音差别大、拿不准是不是同一个人时，先问用户。
对比一下（只是示意）：
不好：简介写着「嘉宾：张三、李四」，于是「说话人 1」改成张三、「说话人 2」改成李四。
好：00:12 主持人说「今天请到了张三」，紧接着「说话人 2」答「大家好」，所以「说话人 2」是张三；「说话人 1」一直在提问、没人叫过他的名字，简介也没写主持人是谁，保留占位名，或按用户的意思标成「主持人」。
4. 先确认，再写回
- 写回之前，把方案给用户看：每位说话人起的名字、凭的证据（一句话），以及他第一次开口的时刻和那一句，方便用户在编辑器里跳过去听。
- 用户确认或改过名字后，用 documents_put 写回同一份转写，只改
speakers[].name，words 与其他字段照读到的原样；几位一次写完。版本冲突说明用户刚改过：重新读，在新的正文上重做。 - 只改名字时译文不用重译，字幕里的说话人跟着文稿变。
5. 要避免的
- 不要按简介里的名单顺序、按谁先开口来填名字。
- 不要不打招呼就重新转录；不要在模型分不了说话人时假装分好了。
- 不要给名字加头衔、机构、括号；不要翻译或音译名字。
- 不要动用户自己起的名字；不要合并 id。
- 不要改正文的字：这里只改说话人。
6. 交付
- 分出了几位说话人；如果重新转录了，说明换了哪份文稿、哪些内容被结转。
- 给谁起了名字、凭什么证据；哪些没有证据，仍是占位名。
- 区分得不对的地方（一句话里换了人、两个人被并成一个），列出时刻，请用户在编辑器的说话人设置里手动调整。
