asr-transcribe — 录音转文字（ASR）

版本历史

• v1.1.4（2026-07-21）显示名优化：将 SkillHub 显示名从"录音转写"改为"录音转文字"，与用户常用表述和触发词一致。
• v1.1.3（2026-07-20）品牌图标：新增自定义 SkillHub 图标（深蓝底 · 声波→金色箭头→文本线，表达"语音转文字"），替换平台默认占位图标。
• v1.1.2（2026-07-20）E 维补丁：新增 scripts/smoke_test.py 分级验证脚本（环境层/脚本层/链路层），零依赖合成音频，让用户"装完第一次跑通"可验证。装完依赖后跑 $PY scripts/smoke_test.py，三级全过即可正式使用。
• v1.1.1（2026-07-20）R 维补丁：修复云端路径临时目录不清理、_write_cloud 不用 with、split_audio 无异常兜底、dashscope SDK 版本兼容性 4 处静默失败/资源泄漏隐患。基线备份：scripts/transcribe.py.baseline-v1.1。

一句话定位

把录音变成"可直接用于纪要/访谈整理"的高质量文字稿。本地优先（数据不出域）+ 云端兜底， 默认输出带时间戳的 .srt/.vtt，按需带说话人标注。

保密红线（国企/央企录音，先过这一关）

1. 默认走本地引擎（whisperX 离线），音频不上传任何第三方。 这是客户构成 （≈70% 国企/央企）的硬约束。
2. 只有在本地不可用、且用户显式同意后，才走云端 API。走云前必须一次性问清： 「本地引擎不可用，是否允许把这段录音上传到云端 ASR？国企/涉密录音请回避。」 用户不同意 → 停在"环境未就绪"，给安装引导，不擅自上云。
3. 文件名/落盘路径用代号，不在对话里回显甲方真实名称、涉密内容原文片段（除非用户要求看全文）。

Python 执行环境

本 skill 的脚本使用 WorkBuddy managed venv 执行（首次使用前需装依赖，见 references/install.md）：

• Python 解释器（下文简称 $PY）： C:UsersLenovo.workbuddybinariespythonenvsdefaultScriptspython.exe
• 安装依赖：$PY -m pip install <包名>
• 脚本路径相对于本 skill 根目录：~/.workbuddy/skills/asr-transcribe/

触发后立即做的事

1. 定位音频文件：用户在对话中提供的文件路径（用户上传或给出绝对路径）。确认扩展名 （m4a/mp3/wav/aac/flac/ogg/mp4/mov 均支持，whisperX 内部用 ffmpeg 解码）。
2. 跑环境自检：$PY scripts/check_env.py
   • 探测 ffmpeg、whisperx、faster-whisper、（如需说话人分离）pyannote / HF_TOKEN、 （如需云兜底）OPENAI_API_KEY / DASHSCOPE_API_KEY。
   • 自检结果决定走哪条分支，不要假设环境已装好。
3. 按自检结果选分支（见下）。

决策分支

标准命令

本地（默认，带说话人分离、出 srt+vtt+txt）：

$PY scripts/transcribe.py "<音频路径>" 
  --engine auto --lang zh --diarize 
  --min-speakers 2 --max-speakers 6 
  --formats srt,txt --output-dir ./outputs

不需要说话人分离（更快更稳）：

$PY scripts/transcribe.py "<音频路径>" --engine local --lang zh --formats srt,txt

云兜底（已获用户同意上云）：

# 默认 OpenAI；国企/国内业务优先用阿里云境内节点（国产合规）：
$PY scripts/transcribe.py "<音频路径>" --engine cloud --cloud-provider dashscope --lang zh --formats srt,txt

云端两家二选一：--cloud-provider openai（需 OPENAI_API_KEY）或 dashscope（需 DASHSCOPE_API_KEY， 阿里云 Paraformer，境内节点、本地文件直传）。两者均不做说话人分离。

关键参数：--model（默认 large-v3，弱机用 medium/small）、--compute-type （CPU 用 int8）、--speakers N（已知确切人数时直接指定）、--hf-token、--hint-words （行业术语/人名热词，提升专名准确率）。

转写质量纪律（交付前必看）

• ASR 输出是机器转写，必有错。 文字稿顶部自动加一行水印： [本文为 ASR 机器转写，专名/数字/口径以原音频为准，未经人工校对]，下游纪要/引用 必须二次核对，不得直接当【实证】源。
• 中文录音务必 --lang zh，避免 whisper 自动语种判错导致整段乱码或翻译成英文。
• 长录音（>1.5h）默认分块处理，脚本已内置；如显存/内存不足，降 --model 与 --batch-size。
• 专名、领导职务、甲方代号用 --hint-words 喂进去；转写后仍要人工扫一遍领导姓名/职务 （遵循内容政策与人名校对纪律）。

下游衔接（转完之后）

• 要出正式会议纪要 → 让位 meeting-minutes（销售会/经营分析会/项目管理会） 等下游纪要 skill（如已安装）。
• 一对一深度访谈 → 让位 interview-insight 做结构化洞察（如已安装）。
• 本 skill 产出的 .txt/.srt 即这些 skill 的标准输入，转完主动询问是否接力。
• 若未安装下游 skill，直接将文字稿交付用户，提示可用于纪要整理。

产出与回执

转写完成后：列出生成的文件（.srt/.vtt/.txt 及可选 .md 分段稿），用 present_files 工具 展示给用户，一句话报识别时长 + 用的引擎 + 是否带说话人 + 是否本地（数据是否出域）。