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/-） |

| 工具 | 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. 调用百炼转写

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

```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 等支持的模型）

1. 结果检查（不做 Whisper 模型升级）
• 任务状态须为 SUCCEEDED；原文非空。
• 若明显乱码、大段空结果 → 提示用户换模型（如 fun-asr）或检查 URL/格式，不要编造纪要。
2. 生成纪要 + OpenClaw 交付块

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

1. 可选落盘

与 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