字幕双语本地化

用于把单语字幕转换为适合视频观看的中英双语字幕，并尽量保证结构稳定、结果完整、适合直接用于视频。

适用场景

当用户出现以下意图时，主动使用本技能：
- 翻译字幕文件
- 生成中英双语字幕
- 处理 .srt、.vtt 等常见字幕文件
- 做字幕本地化
- 将粘贴的字幕文本整理成双语字幕
- 要求保留字幕编号、时间轴、分块顺序
- 强调不能漏字幕、不能截断输出
- 字幕内容较长，需要安全分批再整合
- 强调字幕要适合视频观看、不要太长、不要太满

核心目标

接收常见字幕文件，或接收用户直接粘贴的字幕文本；基于上下文理解，将原始字幕转换为适合视频观看的中英双语字幕。

默认规则：
- 输出中英双语字幕
- 英文在上，中文在下
- 中文翻译优先自然、准确、适合字幕观看
- 严格保留原结构，包括：
- SRT 编号
- 时间轴
- WEBVTT 头
- 原有分块顺序
- 默认输出两份结果：
- 字幕文件
- 纯文本预览版

可用脚本

本技能附带脚本，用于提高稳定性。需要时先阅读 references/format-rules.md。

scripts/parse_subtitles.py

当你需要先把字幕转成结构化数据，再逐块处理、批处理或重建时，使用这个脚本。它适合：
- 将 .srt / .vtt 解析成 JSON
- 保留 format、header、blocks
- block 中保留 block_position、SRT index / VTT cue_id、timecode、lines、raw、valid、error
- 为后续翻译、校验和重建提供稳定中间层

如果任务较长、结构要求严格，优先考虑先解析再处理。

scripts/rebuild_subtitles.py

当你已经有结构化 JSON，或已经对字幕块完成逐项修改后，使用这个脚本重建字幕文件。它适合：
- 从 JSON 恢复为 .srt 或 .vtt
- 按 JSON 中原始格式输出，或使用 --format 覆盖输出格式
- 在批处理后重新生成完整字幕文件
- 减少手工拼接造成的结构错误

scripts/validate_subtitles.py

当你已经拿到原字幕和生成后的双语字幕时，使用这个脚本做完整性校验。它适合检查：
- 是否漏块
- 是否断号
- 时间轴是否损坏
- WEBVTT 头是否丢失
- 每块是否至少包含英文和中文两行正文
- 支持输出 JSON report，失败返回非 0

该脚本已做过最小兼容修复，可正确处理双语字幕块内部出现空行的场景，避免把一个字幕块误拆成多个 block。

如果校验失败，不要直接把结果当作最终交付。

scripts/split_merge_batches.py

当字幕过长、一次处理有截断风险时，使用这个脚本：
- 先切分长字幕为多个批次
- 生成 manifest.json
- 分别处理每个批次
- 再合并为完整文件
- 合并后再校验

如果用户特别强调“不要输出不全”，优先采用这个脚本辅助流程。

scripts/length_check.py

当用户强调字幕要适合视频观看、不要太长、不要过满时，使用这个脚本检查风险。它适合提示：
- 单条英文是否偏长
- 单条中文是否偏长
- 中文字幕阅读速度是否过高
- 是否存在双语两行缺失
- 支持输出 JSON report，失败返回非 0

默认阈值：
- 中文 22 字/块
- 英文 48 字/块
- 中文 8.0 字/秒

长度检查主要用于提醒需要复核和优化的字幕块，不代替上下文翻译判断。

输入要求

支持以下输入形式：
- 用户上传字幕文件
- 用户直接粘贴字幕文本

支持的常见字幕格式包括但不限于：
- .srt
- .vtt
- 其他结构与 SRT/VTT 接近的常见字幕文本

如果输入格式不标准，但仍能识别出字幕块、时间轴与正文，应尽量修复并继续处理；如果无法可靠识别，再明确告诉用户具体问题。

输出要求

1. 字幕文件输出

• 默认尽量保持原始字幕格式
• 输入是 .srt，优先输出 .srt
• 输入是 .vtt，优先输出 .vtt
• 保留原有编号、时间轴、块顺序和头部信息
• 每个字幕块正文改为：
• 第一行：英文原文
• 第二行：中文译文

2. 纯文本预览版

同时提供纯文本预览，便于用户快速检查。

纯文本预览应按原字幕块顺序展示，并保留时间轴信息，格式可更易读，但不能丢块。

处理原则

上下文理解优先

翻译前先理解上下文，不要逐词硬译。对于代词、省略、口语、术语、语气和上下句衔接，要结合前后文判断。

面向视频观看优化

译文应适合视频字幕，不追求逐字直译。优先满足：
- 自然
- 准确
- 简洁
- 易读
- 节奏合适

控制字幕长度

注意单条字幕的可读性，避免中文过长导致观看负担明显增加。

如果原文很长，仍然不得破坏整体字幕结构。可采用以下方式优化：
- 压缩不必要的冗余表达
- 使用更自然、更短的中文说法
- 保持关键信息完整

必要时可在交付前使用 scripts/length_check.py 做风险检查，优先处理被标记为过长或阅读速度过高的字幕块。

不要为了缩短而删除实质信息，也不要因为追求完整复述而让字幕明显不适合视频观看。

结构保持优先

除非用户明确要求重切字幕，否则不要：
- 合并字幕块
- 拆分字幕块
- 修改时间轴
- 改动编号顺序
- 删除任何字幕块

本技能默认是结构保持型转换，而不是重新制轴。

长内容处理策略

当字幕内容很多、整份文件较长时：
- 允许在内部按批次处理，以降低遗漏风险
- 处理长字幕时，优先考虑使用 scripts/parse_subtitles.py 建立结构化中间层
- 如有必要，再使用 scripts/split_merge_batches.py 切分批次
- 最终必须重新整合为一个完整结果后再交付
- 如经过结构化处理，优先使用 scripts/rebuild_subtitles.py 重建最终文件
- 交付前优先使用 scripts/validate_subtitles.py 做校验
- 如用户特别在意观看体验，再使用 scripts/length_check.py 检查长度风险
- 不要把未整合的半成品直接当最终答案交给用户
- 不要因为输出过长而只给前半部分

交付前必须自检：
- 是否包含全部字幕块
- 起始块和结束块是否齐全
- 编号是否连续（对 SRT）
- 时间轴是否完整保留
- 是否保留 WEBVTT 头（对 VTT）
- 是否存在明显过长、过满、不利于观看的字幕块

如果由于系统限制无法在当前轮次安全输出完整结果，应明确说明风险，并优先采用“内部完成后一次性交付”的方式，而不是静默截断。

推荐工作流程

普通字幕任务

1. 识别输入类型：文件或粘贴文本
2. 判断字幕格式：SRT、VTT 或其他近似格式
3. 提取完整字幕结构
4. 通读并理解上下文与语气
5. 逐块生成双语字幕：英文在上，中文在下
6. 检查中文长度是否适合视频观看
7. 复核全文件完整性与结构一致性
8. 输出字幕文件与纯文本预览版

长字幕或高风险任务

1. 识别格式并保留原始文件
2. 使用 scripts/parse_subtitles.py 解析字幕结构
3. 视情况使用 scripts/split_merge_batches.py split 切分批次
4. 逐块或逐批完成双语转换
5. 使用 scripts/split_merge_batches.py merge 或 scripts/rebuild_subtitles.py 重建结果
6. 使用 scripts/validate_subtitles.py 校验完整性
7. 视情况使用 scripts/length_check.py 检查可读性风险
8. 通过校验后再输出字幕文件与纯文本预览版

修改脚本后的推荐回归动作

如果修改了以下任一脚本：
- scripts/parse_subtitles.py
- scripts/rebuild_subtitles.py
- scripts/validate_subtitles.py
- scripts/split_merge_batches.py
- scripts/length_check.py

优先执行完整回归：

cd /mnt/user-data/outputs/字幕双语本地化
python tests/run_regression_tests.py --verbose

预期行为：
- 运行前清空并重建 tests/tmp/
- 所有中间文件与 JSON report 输出到 tests/tmp/
- 汇总结果写入 tests/tmp/summary.json
- 任一测试失败返回退出码 1
- 全部通过返回退出码 0

推荐将“先补 fixture，再补回归，再做最小修复”作为默认维护方式，而不是直接扩大脚本主体改动。

回归测试覆盖

当前 tests/run_regression_tests.py 已覆盖 9 项真实可运行测试：
- test_parse_rebuild_srt
- test_parse_rebuild_vtt
- test_split_merge_srt
- test_validate_pass_srt
- test_validate_fail_missing_cn
- test_validate_fail_broken_index
- test_validate_fail_missing_webvtt_header
- test_length_check_pass
- test_length_check_fail

对应 fixture 包括：
- tests/fixtures/source_basic.srt
- tests/fixtures/bilingual_basic.srt
- tests/fixtures/bilingual_missing_cn.srt
- tests/fixtures/source_basic.vtt
- tests/fixtures/bilingual_basic.vtt
- tests/fixtures/source_long.srt
- tests/fixtures/bilingual_length_ok.srt
- tests/fixtures/bilingual_length_fail.srt
- tests/fixtures/bilingual_missing_header.vtt
- tests/fixtures/bilingual_broken_index.srt

这些样本当前已能验证：
- 基础 SRT 双语输出
- WEBVTT 头保留
- 长字幕完整交付
- SRT parse → rebuild 结构不变
- VTT parse → rebuild 保留 WEBVTT
- validate_subtitles.py 双语两行要求
- length_check.py 长度/阅读速度风险
- split_merge_batches.py 切分与回拼完整性
- 高可靠推荐流程说明可落到真实测试链路

评测覆盖建议

evals/evals.json 应至少覆盖以下几类场景：
- 基础 SRT 双语输出
- WEBVTT 头保留
- 长字幕完整交付
- SRT parse → rebuild 结构不变
- VTT parse → rebuild 后 WEBVTT 头保留
- validate 检查双语两行缺失
- length_check 标记过长与阅读速度风险
- split → merge 后块数一致、可继续校验
- 完整推荐流程可被模型正确说明

这样可以把评测从“只测翻译结果”扩展到“测脚本辅助工作流是否被正确使用”。

质量检查清单

在交付前，检查以下项目：
- 是否漏掉任何字幕块
- 是否保留全部时间轴
- 是否保留原有头部信息
- 是否保持原有块顺序
- 是否为每个字幕块都生成了双语内容
- 是否统一为“英文在上，中文在下”
- 中文是否自然、准确、适合视频观看
- 是否存在过长、拗口或明显机器直译的表达
- 是否存在阅读速度过高的字幕块
- 最终结果是否完整而非截断

与用户沟通的默认方式

如果用户没有额外说明，默认按本技能规则直接处理。

若遇到以下情况，再主动补充说明：
- 字幕格式损坏严重
- 文件编码异常导致正文不可读
- 用户要求与默认规则冲突，例如要求改时间轴、改为中文在上、只输出纯文本等

输出模板

字幕文件

按原格式输出完整字幕内容。

纯文本预览版

可使用如下结构：

[字幕块 1]
00:00:01,000 --> 00:00:03,000
English line
中文译文

[字幕块 2]
00:00:03,500 --> 00:00:06,000
English line
中文译文

示例

示例 1

输入：

1
00:00:01,000 --> 00:00:03,000
This is a good example.

输出：

1
00:00:01,000 --> 00:00:03,000
This is a good example.
这是一个很好的例子。

示例 2

输入：

WEBVTT

00:00:01.000 --> 00:00:03.000
I don't think that's true.

输出：

WEBVTT

00:00:01.000 --> 00:00:03.000
I don't think that's true.
我不认为那是真的。

失败规避

不要：
- 只翻译前面一部分字幕
- 因内容太长而静默截断
- 丢失编号或时间轴
- 把整份字幕改写成摘要
- 把双语字幕变成仅中文或仅英文
- 在未获授权时擅自重切时间轴或重组字幕结构

用户真正需要的是：完整、可用、适合视频、结构稳定的中英双语字幕结果。