字幕工具箱 —— 给 dsh 一套真的能改时间轴的字幕工具

转写、互转、校时、体检 —— 把音频变成带时间戳的字幕，把 SRT 换成 ASS， 把整体偏移 2.5 秒的字幕对齐回去，在出片前先查一遍有没有「一句 20 秒」。

给 DeepSeek Harness 用的自建工具插件：7 个结构化工具，把字幕这件事从 「一堆正则」变成「能问能改」。

Compatibility: built and tested against dsh 0.2.0-rc.2 (preview). The apply(ctx) plugin spec is stable; verify against your own dsh version if newer.

---

一行安装

dsh plugin --profile desktop add github:yuehancn/dsh-tool-subtitle

支持的 profile：desktop（桌面版）/ web（Web 版）。装完重启 dsh 即可用。

---

为什么需要它

字幕是格式知识 + 时间轴算术，两样都容易做错：

• 三种方言的时间戳语法各不相同 —— SRT 用逗号、VTT 用点、ASS 用厘秒 且小时只有一位。写错一个字符，播放器直接不认。
• ASS 的 Dialogue: 字段顺序由 Format: 行声明，真实文件会重排字段； 按位置硬读就会把「样式名」读成「开始时间」。
• 「字幕比声音快 2.5 秒，而且越到后面差得越多」是一个纯算术问题 （时间 × 1.015 + 2.5），但每次都要重新推导一遍。

这个插件把这些收进工具里。不 mock 一个字节：解析器能吃真实世界里的脏文件， 时间轴运算有 291 条断言对着真实 @deepseek-ai/dsh-tools 和真实子进程跑过。

---

七个工具

工具	干什么
subtitle_status	探本机有没有可用的识别引擎，列出能读写的方言
subtitle_read	把字幕读成带数字时间戳的结构化 cue 列表
subtitle_write	把 cue 列表写成文件（时间戳可以给秒数，也可以给字符串）
subtitle_convert	SRT ↔ VTT ↔ ASS 互转，可顺带校时/合并/拆分
subtitle_retime	整体位移 + 缩放，专治「偏移」和「漂移」
subtitle_check	出片前体检：过长、过短、读不过来、重叠、空文本、繁体
subtitle_transcribe	用你配置的识别引擎把音视频转成字幕

为什么 subtitle_read 返回 JSON 而不是一大段文本

因为「把字幕转成文本」用 cat 就够了，模型真正需要的是能推理的时间轴 —— 哪两句挨得太近、那句 20 秒的有多长、第 47 条后面有没有空洞。这些都要数字。

为什么 subtitle_retime 单独成一个工具

「偏移 2.5 秒」和「漂移 1.5%」在实操里同时出现，正确答案是 时间 × factor + offset 一个式子。把它做成工具，模型就不用每次自己推导。

subtitle_check 查什么

问题	判据（可配）
too-long	单条超过 maxCueSeconds（默认 7 秒）
too-short	单条短于 minCueSeconds（默认 0.8 秒）
too-fast	阅读速度超过 maxCharsPerSecond（默认 9/秒）
overlap	两条字幕时间重叠（多数播放器会糊成一团）
non-positive-duration	结束不晚于开始
empty-text	没有文字
possible-traditional-chinese	出现繁体专用字（ASR 常见坑）

阅读速度按汉字逐字 + 拉丁词逐词 + 数字逐位算 —— 因为观众读 2026 是读四个符号，不是读一个词。

---

配置

# ~/.dsh/profiles/<profile>/cordis.patch.yml
- id: tool-subtitle
  config:
    outputDir: C:/Users/you/Videos/subtitle-output
    # 识别引擎：任何会写出 SRT 的可执行文件
    asrCommand: C:/Users/you/.local/bin/whisper-faster.exe
    asrArgs:
      - "{input}"
      - "--model"
      - "{model}"
      - "--output_dir"
      - "{dir}"
      - "--output_format"
      - "srt"
      - "--language"
      - "{lang}"
    asrModel: D:/models/whisper        # 也可以填 large-v3
    asrLanguage: zh

asrArgs 里的占位符：

占位符	含义
{input}	输入的音视频绝对路径
{output}	期望的 SRT 绝对路径
{dir}	插件输出目录
{lang}	识别语言
{model}	模型名或路径

配置项	默认	说明
outputDir	subtitle-output	产物目录
timeoutMs	1800000	单次调用预算（30 分钟，转写很慢）
asrCommand	空	留空则禁用转写，其余工具照常可用
asrModel / asrLanguage	large-v3 / zh	传给 {model} / {lang}
asrEnv	[]	给引擎进程的额外环境变量，"KEY=VALUE" 形式
maxCueSeconds / minCueSeconds	7 / 0.8	体检阈值
maxCharsPerSecond	9	阅读速度上限
maxCues	500	单次最多内联返回多少条
status/read/write/convert/retime/transcribe/check	true	按需关掉某个工具

不配 asrCommand 也能用 —— 读、写、转换、校时、体检都是纯本地运算， 不依赖任何外部引擎。

---

兼容性说明

• 引擎无关：本插件不绑定 faster-whisper。任何「接受输入路径、写出 SRT」的 命令都能接 —— whisper.cpp、openai-whisper、内部 ASR 服务客户端都行。
• 引擎不认 {output} 时会自动归位：很多引擎只有 --output_dir（文件名由它自己定）， 此时插件会把产物改名到你要求的 outputName，而不是让你去猜它写哪儿了。
• 引擎静默失败会被抓到：跑完却没写出 SRT 时，报错里会带上实际执行的完整命令行， 让你知道是参数不对还是路径没写对。

---

安全说明

• 只用 spawn(command, argsArray) —— 不拼 shell 字符串， 路径里有空格、引号、中文都不会出事（有专门的中文带空格用例）。
• 只读写你指定的输入文件与 outputDir，不上传、不联网。
• 识别引擎是你自己配置的可执行文件，插件不下载、不安装任何东西。

---

跑测试

mkdir -p node_modules/@deepseek-ai
cp -r "$HOME/.dsh/profiles/desktop/node_modules/@deepseek-ai/." node_modules/@deepseek-ai/
node _test/run-all.mjs

三个套件，291 条断言全绿（对着真实 @deepseek-ai/dsh-tools 跑，不 mock）：

套件	断言	内容
test-logic.mjs	162	三套时间戳语法与往返、SRT/VTT/ASS 解析（含 CRLF/BOM/缺索引行/字段重排/卡拉OK标签）、三套序列化与跨方言往返、阅读速度、排序重编号、位移/缩放、拆分、合并、7 类体检、占位符展开、cue 强制转换
test-integration.mjs	84	模块导出、注册数量、defineTool schema 归一化、七个开关、18 条错误路径、卡片标题、输出渲染
test-e2e.mjs	45	真的起子进程当识别引擎 → 真写 SRT → 真解析；引擎不可达/退出非零/静默无输出的三种诊断；transcribe → check → 拆分 → 校时 → VTT → ASS → 读回 全链路；中文带空格路径

test-e2e.mjs 用一个自带的替身引擎 _test/fixtures/mock-asr.mjs， 所以不需要装任何模型就能跑，也不需要联网。

---

许可

MIT