asr

适用场景

• 用户想将音频文件转录为文本
• 用户提供音频文件路径并请求转录
• 用户说“转录”“识别”“transcribe”“语音转文字”

不适用场景

• 用户想从文本合成语音（使用 /tts）
• 用户想制作播客或解说内容（使用 /podcast 或 /explainer）

用途

使用 coli asr 将音频文件转录为文本。该工具通过本地语音识别模型完全离线运行，无需 API 密钥。支持中文、英语、日语、韩语和粤语（sensevoice 模型），或仅支持英语（whisper 模型）。

运行 coli asr --help 查看当前 CLI 选项和支持的标志。

硬性约束

• 不得使用 Shell 脚本。只能使用直接命令。
• 开始任何交互前，务必阅读 shared/config-pattern.md 中的配置。
• 遵循 shared/cli-patterns.md 中的交互模式。
• 每次最多只能问一个问题。

每个多选步骤都必须使用 AskUserQuestion 工具——不得以纯文本形式列出选项。一次只问一个问题。等待用户回答后再继续。 收集完所有参数后，先总结并请用户确认，再进行任何转录。

交互流程

步骤 0：先决条件检查

设置配置前，静默检查环境：

COLI_OK=$(which coli 2>/dev/null && echo yes || echo no)
FFMPEG_OK=$(which ffmpeg 2>/dev/null && echo yes || echo no)
MODELS_DIR="$HOME/.coli/models"
MODELS_OK=$([ -d "$MODELS_DIR" ] && ls "$MODELS_DIR" | grep -q sherpa && echo yes || echo no)

问题	操作
未找到 coli	阻止继续。告知用户先运行 npm install -g @marswave/coli
未找到 ffmpeg	发出警告（WAV 文件仍可使用）。建议运行 brew install ffmpeg / sudo apt install ffmpeg
尚未下载模型	告知用户：首次转录时会自动将模型下载到 ~/.coli/models/（约 60MB）

如果缺少 coli，请在此处停止，不要继续。

步骤 0：配置设置

按照 shared/config-pattern.md 的步骤 0（零问题启动）操作。

如果文件不存在——静默使用默认值创建文件，然后继续：

mkdir -p ".listenhub/asr"
echo '{"model":"sensevoice","polish":true}' > ".listenhub/asr/config.json"
CONFIG_PATH=".listenhub/asr/config.json"
CONFIG=$(cat "$CONFIG_PATH")

不要询问任何设置问题。 直接使用合理的默认值（sensevoice 模型，启用润色）进入交互流程。

如果文件存在——静默读取配置，然后继续：

CONFIG_PATH=".listenhub/asr/config.json"
[ ! -f "$CONFIG_PATH" ] && CONFIG_PATH="$HOME/.listenhub/asr/config.json"
CONFIG=$(cat "$CONFIG_PATH")

设置流程（仅由用户发起的重新配置）

仅当用户明确要求重新配置时才运行。显示当前设置：

当前配置 (asr)：
  模型：sensevoice / whisper-tiny.en
  润色：开启 / 关闭

按顺序询问：

1. model：“默认使用哪个语音识别模型？”

   • “sensevoice（推荐）”——支持中文、英语、日语、韩语和粤语，可检测语言、情绪和音频事件
   • “whisper-tiny.en”——仅支持英语

2. polish：“转录后由 AI 润色文本？（修正标点、去除语气词、提升可读性）”

   • “是（推荐）” → polish: true
   • “否，保留原始转录” → polish: false

收集完所有答案后，一次性保存。

步骤 1：获取音频文件

如果用户尚未提供文件路径，请询问：

“请提供要转录的音频文件路径。”

继续前请确认文件存在。

步骤 2：确认

准备转录：

  文件：{filename}
  模型：{model}
  润色：{是 / 否}

继续？

步骤 3：转录

运行 coli asr 并使用 JSON 输出（以获取元数据）：

coli asr -j --model {model} "{file}"

首次运行时，coli 会自动下载所需模型。这可能需要一些时间——如果模型尚未下载，请告知用户。

解析 JSON 结果，提取 text、lang、emotion、event 和 duration。

步骤 4：润色（若已启用）

如果 polish 为 true，则使用转录结果中的原始 text，修改标点、去除语气词并提升可读性。保留原意和说话者意图。不要总结或改写。

步骤 5：呈现结果

直接在对话中显示转录文本：

转录完成

{transcript text}

─────────────────
语言：{lang} · 情绪：{emotion} · 时长：{duration}s

如果经过润色，请显示润色后的版本，并说明文本经 AI 润色。告知用户可按需查看原始文本。

步骤 6：导出为 Markdown（可选）

呈现结果后，询问：

Question: "保存为 Markdown 文件到当前目录？"
Options:
  - "是" — save to current directory
  - "否" — done

如果用户同意，请将 {audio-filename}-transcript.md 写入当前工作目录（即用户运行 Claude Code 的目录）。文件应包含转录文本（如果启用了润色，则使用润色后的版本），并带有以下 front-matter 标头：

---
source: {original audio filename}
date: {YYYY-MM-DD}
model: {model used}
duration: {duration}s
lang: {detected language}
---

{transcript text}

组合使用

• 由以下内容调用：未来需要转录录制音频的技能
• 调用：无

示例

“帮我转录这个文件 meeting.m4a”

1. 检查前置条件
2. 读取配置
3. 确认：meeting.m4a、sensevoice、开启润色
4. 运行 coli asr -j --model sensevoice "meeting.m4a"
5. 润色原始文本
6. 内联显示

“转录 interview.wav，不要润色”

1. 检查前置条件
2. 读取配置
3. 在本次会话中将润色选项覆盖为 false
4. 运行 coli asr -j --model sensevoice "interview.wav"
5. 内联显示原始转录文本