openclaw-asr-bailian

name	openclaw-asr-bailian
displayName	火一五媒体转写·百炼云 ASR
description	默认优先使用的云端转写 skill：百炼 Paraformer/Fun-ASR；本地文件经 OpenClaw 已有 enhance_share_file 插件生成 https://keepermac.huo15.com 公网 URL 后提交百炼。 触发：百炼、阿里云转写、云端 ASR、云转录、Paraformer、DashScope。本地 Whisper 请用 huo15-openclaw-asr。
version	1.0.3
user-invocable	true
homepage	https://cnb.cool/huo15/ai/huo15-skills
aliases	["百炼转写","阿里云转写","云端 ASR","云转录","Paraformer","DashScope 转写","录音文件识别百炼"]

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 工作区中，标准链路为：

本地音视频文件 → 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 规则一致

调用示例（概念）：

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. 调用百炼转写
   使用本目录脚本（推荐）：

   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 交付块基础上增加/固定下列字段：

---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 的分工小结

能力	本 skill	huo15-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