前言¶
在 DSH 里处理字幕，常见做法是读整段 SRT 文本、用正则改时间戳，或让模型自己推导「整体偏移 2.5 秒、后面越拖越多」这类算术。SRT、VTT、ASS 三种格式的时间戳语法不同，ASS 的 Dialogue: 字段顺序还依赖 Format: 行；一旦写错字符或按位置硬读，播放器不认，模型也难以对「哪两句太近、哪条 20 秒」做推理。
下面介绍社区插件 yuehancn/dsh-tool-subtitle（维护者 yuehancn，分类：模型推理）：为 DeepSeek Harness 提供 7 个结构化工具，覆盖转写、互转、校时与出片前体检，把字幕从「一堆正则」收成「能问能改」的本地运算；解析与校时逻辑在 README 中说明已用 291 条断言对着真实 @deepseek-ai/dsh-tools 与子进程验证，且不 mock 字节级解析。
这是什么¶
dsh-tool-subtitle 是面向 DeepSeek Harness 的自建工具插件：读写字幕为带数字时间戳的 cue 列表（JSON），在 SRT / VTT / ASS 之间互转，做整体位移与缩放，并在绑定可选 ASR 命令时把音视频转成 SRT。不配识别引擎时，读、写、转换、校时、体检仍可在本机完成。
- 目录页：https://www.skillhub.cn/plugins/yuehancn/dsh-tool-subtitle
- 源码与文档：https://github.com/yuehancn/dsh-tool-subtitle
- 许可证：MIT（package.json 版本 1.0.0）
- 兼容性：README 写明针对 dsh
0.2.0-rc.2（preview）构建与测试；apply(ctx)插件规范稳定，较新版本需自行核对。
社区插件目录（SkillHub）与 DeepSeek / 幻方无官方从属关系；安装前建议自行查看源码与许可证。插件以当前 dsh 进程权限运行，只读写你指定的输入与配置的 outputDir，识别引擎为你本机配置的可执行文件。
七个工具在做什么¶
| 工具 | 作用 |
|---|---|
subtitle_status |
探测本机是否有可用识别引擎，列出可读写字幕方言 |
subtitle_read |
将字幕读成带数字时间戳的结构化 cue 列表 |
subtitle_write |
将 cue 列表写回文件（时间戳可用秒数或字符串） |
subtitle_convert |
SRT ↔ VTT ↔ ASS 互转，可顺带校时、合并、拆分 |
subtitle_retime |
整体位移 + 缩放，处理固定偏移与时间漂移 |
subtitle_check |
出片前体检：过长、过短、阅读过快、重叠、空文本、繁体等 |
subtitle_transcribe |
用配置的 ASR 命令把音视频转成字幕 |
subtitle_read 返回 JSON 而非大段文本，是为了让模型基于数字时间轴推理（间距、单条时长、空洞等）。subtitle_retime 单独成工具，是为把「偏移 + 漂移」统一为 时间 × factor + offset，避免每次重新推导。
subtitle_check 默认判据包括：单条超过 7 秒（too-long）、短于 0.8 秒（too-short）、阅读速度超过 9 字/秒（too-fast）、时间重叠、非正时长、空文本、可能的繁体专用字等；阈值可在配置中调整。
安装与启用¶
先做一行安装（README 原文命令；desktop 与 web profile 均支持），装完重启 dsh。
dsh plugin --profile desktop add github:yuehancn/dsh-tool-subtitle
Web 版将 --profile desktop 换成 web 即可。插件通过 cordis.patch.yml 注册，id 为 tool-subtitle。
配置识别引擎（可选）¶
转写依赖你在 profile 下补丁里配置的 ASR 命令；留空则 subtitle_transcribe 不可用，其余工具照常。
配置写在 ~/.dsh/profiles/<profile>/cordis.patch.yml，示例结构如下（路径按本机修改）：
- id: tool-subtitle
config:
outputDir: C:/Users/you/Videos/subtitle-output
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
asrLanguage: zh
asrArgs 占位符：{input} 输入音视频绝对路径，{output} 期望 SRT 路径，{dir} 插件输出目录，{lang} / {model} 语言与模型。README 说明引擎不识别 {output}、只写 --output_dir 时，插件会把产物改名到你要求的输出名；跑完未生成 SRT 时，错误信息会带上实际执行的完整命令行。
常用配置项摘要：
| 配置项 | 默认 | 说明 |
|---|---|---|
outputDir |
subtitle-output |
产物目录 |
timeoutMs |
1800000 | 单次调用超时（30 分钟） |
asrCommand |
空 | 空则禁用转写 |
asrModel / asrLanguage |
large-v3 / zh |
传给占位符 |
maxCueSeconds / minCueSeconds |
7 / 0.8 | 体检阈值 |
maxCharsPerSecond |
9 | 阅读速度上限 |
maxCues |
500 | 单次内联返回 cue 上限 |
status/read/…/check |
true |
可按需关闭单个工具 |
子进程使用 spawn(command, argsArray)，不拼接 shell 字符串；识别引擎需自行安装，插件不下载模型。
典型用法思路¶
README 未给出固定对话示例，但工具链可按下列顺序在 Harness 里组合（路径与格式按任务替换）：
subtitle_status：确认本机 ASR 与支持的读写格式。subtitle_transcribe（已配asrCommand）：音视频 → SRT。subtitle_check：出片前查过长、重叠、繁体等。subtitle_retime：整体加 2.5 秒或按 factor 修漂移。subtitle_convert：导出 VTT / ASS，或合并、拆分轴。subtitle_read/subtitle_write：在 cue 列表上改字幕后写回。
项目自带 e2e 测试描述过「transcribe → check → 拆分 → 校时 → VTT → ASS → 读回」全链路；本地跑测试可用 README 中的命令（依赖已安装的 dsh profile 内 @deepseek-ai 包，e2e 使用替身引擎 _test/fixtures/mock-asr.mjs，无需真实模型）。
适用场景与注意¶
适合：需要在 DSH 智能体工作流里稳定处理 SRT/VTT/ASS、校时间轴、批量体检字幕，并可选对接任意「输入媒体、输出 SRT」的 ASR 可执行文件（whisper.cpp、faster-whisper 等，插件不绑定单一引擎）。
注意：
- 与 dsh
0.2.0-rc.2对齐测试；升级 dsh 后应验证工具 schema 与行为。 - 转写耗时可能很长，默认
timeoutMs为 30 分钟。 - 安装插件等于信任其读写本地文件与 spawn 你配置的 ASR；使用前请阅读 MIT 许可下的源码。
- GitHub 星标为 0（目录线索），不代表功能完整性；质量以 README 中的测试说明为准。
结尾¶
dsh-tool-subtitle 把字幕相关的格式解析、时间轴算术和体检规则收进 7 个 DSH 工具，不配 ASR 也能完成读写、互转与校时；配好 asrCommand 后可在同一套工具里完成转写与后续处理。
- 社区目录：https://www.skillhub.cn/plugins/yuehancn/dsh-tool-subtitle
- GitHub：https://github.com/yuehancn/dsh-tool-subtitle
