OpenClaw 媒体转写 · 百炼云 ASR（默认云端路线）#

定位：凡用户需要 云端转写、或明确说 百炼 / 阿里云 / 不用本地 Whisper 时， 优先加载并执行本 skill，不要在本仓库的 huo15-openclaw-asr 里自行对接百炼 API。

本地隐私转写（Whisper / WhisperX / .tty）→ 使用 huo15-openclaw-asr。

本 skill 与 huo15-openclaw-asr 共用 纪要模板、OpenClaw 交付块结构、保存 Markdown/Word（office-doc）流程；差异仅在 ASR 引擎固定为百炼。

官方文档： 百炼 · 录音文件识别（Paraformer / Fun-ASR） · Python SDK

---

默认策略#

场景使用 skill云端 / 百炼 / 阿里云 ASR**本 skill（默认）**本地、不上云、Whisper、 .tty``huo15-openclaw-asr用户未说明先问：本地还是云端；若倾向云端 → 本 skill

上云前必须确认：用户同意音频通过公网 URL 提交至阿里云百炼处理。

---

百炼 URL 约束与 OpenClaw 公网分享（必读）#

百炼录音文件识别 只接受 HTTP/HTTPS 的音频 URL， 不支持 本地路径直传、Base64 或二进制流（见 百炼文档）。

在 OpenClaw 工作区中，标准链路为：

text

本地音视频文件 → enhance_share_file（已有插件）→ 公网 URL → 百炼 API

项说明公网域名https://keepermac.huo15.com（bot 对外 base URL；分享链接形如 https://keepermac.huo15.com/plugins/enhance-share/<token>-<filename>）工具**enhance_share_file（ OpenClaw 已安装，来自 enhance 插件； 不要 在本 skill 内实现或要求用户新写该插件）agent 动作对本地待转写文件 调用已有工具 enhance_share_file，从返回的 structuredContent.url 取真实公网 URL，再传给 transcribe_bailian.py --file-url 或等效百炼 SDK严禁**手写、拼接、猜测 share URL（缺 token 会 404）；与 huo15-markdown-export / enhance 规则一致

调用示例（概念）：

json

enhance_share_file({
  "filePath": "<本地音视频绝对路径>",
  "label": "<展示名，如 会议录音>",
  "expireHours": 24
})
→ structuredContent.url = "https://keepermac.huo15.com/plugins/enhance-share/<token>-meeting.mp4"

若用户 已提供 可公网访问的 URL，可跳过 enhance_share_file；若工具不可用或失败，如实告知用户并降级（勿伪造 URL）。

---

百炼支持的音视频格式（不必先转 MP3）#

百炼录音文件识别支持多种 音视频 格式（不限 MP3），见 官方说明：

aac、 amr、 avi、 flac、 flv、 m4a、 mkv、 mov、 mp3、 mp4、 mpeg、 ogg、 opus、 wav、 webm、 wma、 wmv

• mp4 / mkv / mov 等视频 可直接提交（服务端处理音轨）， 默认无需 本地先抽音频再转 MP3。
• 单文件： ≤ 2GB、≤ 12 小时；启用说话人分离时建议 ≤ 2 小时。
• 格式变种众多， 不保证每一种都能识别成功；若失败再考虑 可选本地转码。

---

总流程（决策树）#

1. 确认引擎：本 skill 固定 asr_engine: bailian_paraformer（默认模型 paraformer-v2）。

2. 识别输入

   • .tty → 转交 huo15-openclaw-asr 的 .tty 分支（百炼不做终端录屏解析）。
   • 音视频 → 继续本流程。

3. 是否本地转码（默认：否）

   • 默认：源文件扩展名属于 格式列表 → 不跑 ffmpeg，直接进入步骤 4。
   • 仅在下述情况 再本地转码（见 可选本地转码）：格式不在列表、百炼返回失败/无识别结果、需说话人分离但为多声道、或用户要求压缩体积。
   • 不要 为「百炼只认 MP3」而习惯性转码。

4. 获得公网 URL（必做）

   • OpenClaw 标准路径：对步骤 2/3 得到的本地文件调用 enhance_share_file，使用返回的 structuredContent.url（域名 https://keepermac.huo15.com）。详见 百炼 URL 约束与 OpenClaw 公网分享。
   • 若用户已提供合法公网 URL，可跳过分享步骤。
   • 勿 在 skill、脚本或对话中写入 DASHSCOPE_API_KEY； 勿 自行实现 enhance 插件。

5. 调用百炼转写

   使用本目录脚本（推荐）： bash

   pip install dashscope
   # 环境变量 DASHSCOPE_API_KEY 已设置
   python scripts/transcribe_bailian.py --file-url "https://keepermac.huo15.com/plugins/enhance-share/..." -o verbatim.txt
   
   

   可选参数：

   • --model paraformer-v2（默认；方言/嘈杂场景可改 fun-asr，见百炼文档选型）
   • --diarization：说话人分离（ 仅单声道；多声道需先 ffmpeg -ac 1 混成单声道， 不必 强行转成 MP3）
   • --language-hints zh en（ 仅 paraformer-v2 等支持的模型）

6. 结果检查（不做 Whisper 模型升级）

   • 任务状态须为 SUCCEEDED；原文非空。
   • 若明显乱码、大段空结果 → 提示用户换模型（如 fun-asr）或检查 URL/格式， 不要 编造纪要。

7. 生成纪要 + OpenClaw 交付块

   严格基于原文；模板与 YAML 字段与 huo15-openclaw-asr 一致，但交付块须标明云端来源（见下节）。

8. 可选落盘

   与 huo15-openclaw-asr 相同：询问后保存 Markdown（原文+纪要+交付块）或 Word（仅纪要，调用 huo15-openclaw-office-doc）。

---

可选本地转码（ffmpeg）#

仅在需要时使用； 百炼路线默认跳过本节。

情况建议扩展名不在百炼支持列表转为 mp3 或 wav 等支持格式后，再 enhance_share_file 分享百炼任务失败或识别结果为空先查 share URL 是否有效、百炼能否拉取；仍失败可试转码或换 fun-asr``--diarization 且源文件为多声道ffmpeg -i INPUT -ac 1 OUTPUT.wav（或其它支持格式）， 不必 MP3减小上传体积可 ffmpeg 压成 mp3/ aac 后再 enhance_share_file

转 MP3 可复用 huo15-openclaw-asr 脚本（ 仅当选择转 MP3 时）：

• Windows： ../huo15-openclaw-asr/scripts/transcode_mp3.ps1
• Unix： ../huo15-openclaw-asr/scripts/transcode_mp3.sh

---

凭证与环境#

变量说明DASHSCOPE_API_KEY百炼 API Key（ 配置到环境变量，禁止硬编码）

任务为 异步：提交后排队，通常数分钟内完成；结果 JSON 的下载链接 24 小时有效（以官方说明为准）。

---

OpenClaw（龙虾）交付块#

在 huo15-openclaw-asr 交付块基础上 增加/固定 下列字段：

markdown

---OPENCLAW_ASR_DELIVERY---
version: 1
asr_engine: bailian_paraformer
bailian_model: "<paraformer-v2 | fun-asr | ...>"
source_kind: audio_video
source_path: "<原始文件路径或标识>"
file_url: "<enhance_share_file 返回的 structuredContent.url，或用户提供的公网 URL>"
share_via: "enhance_share_file | user_provided_url"
local_transcode: "<none | 说明：如 ffmpeg 混单声道 wav；默认 none 表示直传原文件>"
language_guess: "<zh | en | mixed | unknown>"
type_candidates:
  - code: "<meeting|interview|...>"
    confidence: <0.0-1.0>
    reason: "<一句理由>"
verbatim_text: |
  <原文全文>
summary_markdown: |
  <纪要全文>
notes_for_openclaw: |
  云端百炼转写；模型=<模型名>；用户已确认上云；<其它不确定性>
---END_OPENCLAW_ASR_DELIVERY---

纪要模板、类型候选表：见 huo15-openclaw-asr · 纪要模板。

---

保存 Word（纪要）#

与 huo15-openclaw-asr 相同：调用 huo15-openclaw-office-doc 的 create-word-doc.py， --doc-format 会议纪要。详见 选项 B：保存为 Word。

---

与 huo15-openclaw-asr 的分工小结#

能力本 skillhuo15-openclaw-asr百炼 Paraformer / Fun-ASR✔ 默认不实现，仅指向本 skill公网 URL（enhance_share_file）✔ 标准✘Whisper / WhisperX✘✔ 默认.tty 终端日志✘✔纪要 / 交付块 / 落盘✔（复用约定）✔

---

自检清单#

• 已确认用户同意 云端 转写。
• 已配置 DASHSCOPE_API_KEY（未泄露到仓库或对话）。
• 已通过 enhance_share_file 取得公网 URL（ https://keepermac.huo15.com/...），或用户已提供合法 URL； 未手写/拼接 share 链接。
• 音频 URL 已提交百炼； 默认未做不必要的本地转码。
• 若曾本地转码：已在 local_transcode / notes_for_openclaw 中说明原因（格式、分轨、压缩等）。
• 已用 transcribe_bailian.py 或等效 SDK 调用，任务 SUCCEEDED，原文非空。
• 若启用说话人分离：音频为 单声道。
• 纪要严格来源于原文；已输出带 asr_engine: bailian_paraformer 的交付块。
• 若保存 Word：已走 huo15-openclaw-office-doc。

---

附加资源#

• 标准操作（SOP）： docs/SOP.md
• 脚本说明： scripts/README.md