说话人标注

用户要的是：文稿里每句话前面是真名，字幕上看得出谁在说，导出的文稿和配音按人分开。这件事分两步：先分清有几个声音、每句归谁（区分），再给每个声音一个真名（标注）。区分靠语音模型，标注靠证据，两步都不靠猜。

最容易做坏的样子是猜：看到简介里列了两位嘉宾，就把「说话人 1」「说话人 2」按顺序填上去。猜错的名字会出现在每一条字幕和每个导出的文件里，用户往往要看到很后面才发现，比留着「说话人 1」糟得多。

1. 先看现状

用 videos_inspect 找到这个视频的转写（kind 为 speech 的文档；有几份时按来源素材对上用户说的那段），再 documents_read 读它：

• 正文的 speakers[] 列出每位说话人的 id 和 name，每个词带说话人。
• 已经区分过（有两位及以上说话人）：跳到第 3 节，只做标注。
• 没区分（只有一位，或词上没有说话人），但用户说视频里不止一个人：做第 2 节。
• 用户只想换名字、不想重跑时，也只做第 3 节。

2. 区分：按声纹重新转录

区分要重新转录，并取代当前文稿，不另建一份。这一步会丢掉用户在文稿里手改过的字，所以先说清楚再做：

1. 先告诉用户：重新转录会取代当前文稿，之后在文稿里手改过的字会被丢掉；译文、字幕与配音会按新文稿结转。用户同意再继续。
2. 用 transcribe 给这个视频、diarize 为 true、target 为 replace；语言与提示（人名、术语）沿用这份文稿的，用户给了新的就用新的。
3. 模型不能区分时任务照常完成，结果带 diarization-unavailable 警告：告诉用户这个模型分不了说话人，要装「说话人区分」模型包或换能区分的模型；不要假装区分好了。
4. 文稿转录之后被用户改过时，取代会以 TRANSCRIPT_EDITED 拒绝：把这一点告诉用户，用户确认丢掉那些修改，才加 acceptEdited 重来。
5. 任务完成后重新 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. 先确认，再写回

1. 写回之前，把方案给用户看：每位说话人起的名字、凭的证据（一句话），以及他第一次开口的时刻和那一句，方便用户在编辑器里跳过去听。
2. 用户确认或改过名字后，用 edits_apply 的 renameSpeakers，给 documentId 与 speakers 的 [{id,name}]，几位放在同一笔事务；expectedRevision 用 videos_inspect 的视频版本，重试沿用 commandId。不上传 words 或整份正文。版本冲突说明用户刚改过：重新读，核对 ID 与名字后用新 commandId 重做。
3. 只改名字时译文不用重译，字幕里的说话人跟着文稿变。

5. 要避免的

• 不要按简介里的名单顺序、按谁先开口来填名字。
• 不要不打招呼就重新转录；不要在模型分不了说话人时假装分好了。
• 不要给名字加头衔、机构、括号；不要翻译或音译名字。
• 不要动用户自己起的名字；不要合并 id。
• 不要改正文的字：这里只改说话人。

6. 交付

• 分出了几位说话人；如果重新转录了，说明换了哪份文稿、哪些内容被结转。
• 给谁起了名字、凭什么证据；哪些没有证据，仍是占位名。
• 区分得不对的地方（一句话里换了人、两个人被并成一个），列出时刻，请用户在编辑器的说话人设置里手动调整。