dsh-plugin-wwrs-whisper

English

本地语音转写 DSH 插件（开源）：TranscriberBackend 后端缝加 MLX 实现（Mac 先行）；覆盖转写/对齐/字幕/分段。运行时只有官方 dsh-tools 契约依赖。

v1 仅含 MLX 后端（Mac 先行），TranscriberBackend 接口给 CUDA 等后端留门。非 Mac 主机大声失败并给出路，绝不静默降级。

工具

W2 工具已落地（src/cordis.ts 注册，工作区写守卫看护）。episode 仅为通用媒体分段语义（按时长约束切分 units）。

工具	参数	输出
speech_transcribe	audioPath、language?（缺省 zh）、artifactDir?（缺省 <ws>/.wwrs/artifacts/speech/<stem>）、overwrite?（缺省 false 即 {skipped:true}）	{skipped, units:[{text, startMs, endMs}], artifactDir, rawAsrPath}；后端只读音频——视频请先提音频（ffmpeg 插件）
speech_align	mediaPath、expected（非空 [{id, text}]）、language?、quality?、artifactDir?、overwrite?（缺省 false 即 {skipped:true}）	{skipped, accepted, timedCoverageRatio, normalizedEditDistance, corrected, issues, artifactDir, resultPath}（落盘 alignment.json）；缺省阈值 {maxNormalizedEditDistance: 0.2, minTimedCoverageRatio: 0.85}
speech_correct_transcript	expectedText、asrUnits	纯函数 → {units} 逐字时间戳
subtitles_segment	text、lineMax?（缺省 15）	纯函数 → {cues:[{text, start, end}]} 字符区间
subtitles_merge_timed_tokens	groups	纯函数 → {tokens}，按组 offsetMs 平移后合并
episodes_plan	units、maxDurationMs、minDurationMs?（缺省 10000）	纯函数 → {episodes}；永不切开单元，返回相邻合法端点备选

合同

转写能力收敛到 TranscriberBackend 接口，v1 只打包 MlxBackend 实现以便 Mac 先行，非 Mac 主机遇到该后端即大声失败。守护生命周期：首次使用懒加载，按 SPEECH_WORKER_IDLE_MS 空闲卸载，宿主 dispose 时 close（不留野进程）。取消只 abort 当次请求，共享守护继续服务其他请求。缺 venv/模型即大声失败并给出路，工具调用内绝不同步冷安装。

python/ 内是模型侧脚本，随包路径注入（MlxBackend 拉起包内 python/whisper_mlx_daemon.py；不要手工跑——仅测试/调试经 WWRS_WHISPER_DAEMON_SCRIPT 覆盖）。

配置

键	含义	缺省
workspace	项目根（绝对路径）	WWRS_WORKSPACE 环境变量，再中性锚探测

解析顺序：config.workspace > 环境变量 WWRS_WORKSPACE > 向上找 .wwrs/workspace.json > 大声失败。音频/产物路径必须落在工作区内，否则抛错；配了 config.workspace 时静态守卫也会拒收越界路径。

环境变量（只写注入面，不写死绝对路径缺省）：

变量	含义	缺省
WWRS_WORKSPACE	工作区根回落	（再中性锚探测）
WWRS_WHISPER_PYTHON	转写 Python 解释器	安装节建出的 venv（不写死路径）
WWRS_WHISPER_MODEL	模型（本地目录或已缓存 HF 仓，不自动下载）	mlx-community/whisper-large-v3-turbo
WWRS_WHISPER_MODEL_DIR	模型缓存根（永不写仓内）	HF 缓存约定（不写死路径）
WWRS_WHISPER_DAEMON_SCRIPT	守护脚本覆盖（测试/调试用）	包内 python/whisper_mlx_daemon.py
SPEECH_WORKER_IDLE_MS	守护空闲 TTL（0=用完即卸）	300000（5 分钟）
WWRS_TEST_MLX	=1 启用真机转写测试	（skip）

缺失即大声失败并给出路；绝不静默降级。

安装

{
  "dependencies": {
    "dsh-plugin-wwrs-whisper": "link:/path/to/plugin-wwrs-whisper"
  },
  "dsh": { "profile": { "bundles": ["dsh-plugin-wwrs-whisper"] } }
}

语音环境一次性准备（在终端手工执行；工具调用内永不自动安装）：

python3 -m venv ~/.cache/wwrs-whisper/.venv
~/.cache/wwrs-whisper/.venv/bin/pip install mlx-whisper
huggingface-cli download mlx-community/whisper-large-v3-turbo

验证

跑 pnpm check（prettier 检查 + tsc --noEmit + node --test tests/*.test.ts；真机转写只在 WWRS_TEST_MLX=1 跑，否则 skip）。

无浏览器半

纯服务端工具——pnpm check 即全部门，无 check:browser 链。

已知边界

• Mac 先行：v1 只含 MLX 后端，非 Mac 主机大声失败。
• 后端只读音频——视频请先提音频（ffmpeg 插件）。
• 工具调用内永不自动安装；缺 venv/模型即大声失败并给出路。
• 真机转写测试只在 WWRS_TEST_MLX=1 跑，否则 skip。

许可

MIT.