\r \r

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

\r

定位：凡用户需要云端转写、或明确说 百炼 / 阿里云 / 不用本地 Whisper 时，优先加载并执行本 skill，不要在本仓库的 huo15-openclaw-asr 里自行对接百炼 API。 \r 本地隐私转写（Whisper / WhisperX / .tty）→ 使用 huo15-openclaw-asr。\r \r 本 skill 与 huo15-openclaw-asr 共用纪要模板、OpenClaw 交付块结构、保存 Markdown/Word（office-doc）流程；差异仅在 ASR 引擎固定为百炼。\r \r 官方文档：百炼 · 录音文件识别（Paraformer / Fun-ASR） · Python SDK\r \r ---\r \r

默认策略\r

\r | 场景 | 使用 skill |\r |------|------------|\r | 云端 / 百炼 / 阿里云 ASR | 本 skill（默认） |\r | 本地、不上云、Whisper、.tty | huo15-openclaw-asr |\r | 用户未说明 | 先问：本地还是云端；若倾向云端 → 本 skill |\r \r 上云前必须确认：用户同意音频通过公网 URL 提交至阿里云百炼处理。\r \r ---\r \r

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

\r 百炼录音文件识别只接受 HTTP/HTTPS 的音频 URL，不支持本地路径直传、Base64 或二进制流（见百炼文档）。\r \r 在 OpenClaw 工作区中，标准链路为：\r \r

本地音视频文件 → enhance_share_file（已有插件）→ 公网 URL → 百炼 API\r
```\r
\r
| 项 | 说明 |\r
|----|------|\r
| **公网域名** | `https://keepermac.huo15.com`（bot 对外 base URL；分享链接形如 `https://keepermac.huo15.com/plugins/enhance-share/\x3Ctoken>-\x3Cfilename>`） |\r
| **工具** | **`enhance_share_file`**（**OpenClaw 已安装**，来自 enhance 插件；**不要**在本 skill 内实现或要求用户新写该插件） |\r
| **agent 动作** | 对本地待转写文件**调用已有工具** `enhance_share_file`，从返回的 **`structuredContent.url`** 取真实公网 URL，再传给 `transcribe_bailian.py --file-url` 或等效百炼 SDK |\r
| **严禁** | 手写、拼接、猜测 share URL（缺 token 会 404）；与 `huo15-markdown-export` / enhance 规则一致 |\r
\r
**调用示例（概念）**：\r
\r
```json\r
enhance_share_file({\r
  "filePath": "\x3C本地音视频绝对路径>",\r
  "label": "\x3C展示名，如 会议录音>",\r
  "expireHours": 24\r
})\r
→ structuredContent.url = "https://keepermac.huo15.com/plugins/enhance-share/\x3Ctoken>-meeting.mp4"\r
```\r
\r
若用户**已提供**可公网访问的 URL，可跳过 `enhance_share_file`；若工具不可用或失败，如实告知用户并降级（勿伪造 URL）。\r
\r
---\r
\r
## 百炼支持的音视频格式（不必先转 MP3）\r
\r
百炼录音文件识别支持多种**音视频**格式（不限 MP3），见[官方说明](https://help.aliyun.com/zh/model-studio/recording-file-recognition)：\r
\r
`aac`、`amr`、`avi`、`flac`、`flv`、`m4a`、`mkv`、`mov`、`mp3`、`mp4`、`mpeg`、`ogg`、`opus`、`wav`、`webm`、`wma`、`wmv`\r
\r
- **mp4 / mkv / mov 等视频**可直接提交（服务端处理音轨），**默认无需**本地先抽音频再转 MP3。\r
- 单文件：**≤ 2GB、≤ 12 小时**；启用说话人分离时建议 **≤ 2 小时**。\r
- 格式变种众多，**不保证每一种都能识别成功**；若失败再考虑 [可选本地转码](#可选本地转码ffmpeg)。\r
\r
---\r
\r
## 总流程（决策树）\r
\r
1. **确认引擎**：本 skill 固定 `asr_engine: bailian_paraformer`（默认模型 **`paraformer-v2`**）。\r
2. **识别输入**\r
   - `.tty` → 转交 **`huo15-openclaw-asr`** 的 [`.tty` 分支](../huo15-openclaw-asr/SKILL.md#tty终端录屏--会话日志)（百炼不做终端录屏解析）。\r
   - 音视频 → 继续本流程。\r
3. **是否本地转码（默认：否）**  \r
   - **默认**：源文件扩展名属于[格式列表](#百炼支持的音视频格式不必先转-mp3) → **不跑 ffmpeg**，直接进入步骤 4。  \r
   - **仅在下述情况**再本地转码（见 [可选本地转码](#可选本地转码ffmpeg)）：格式不在列表、百炼返回失败/无识别结果、需说话人分离但为多声道、或用户要求压缩体积。  \r
   - **不要**为「百炼只认 MP3」而习惯性转码。\r
4. **获得公网 URL（必做）**  \r
   - **OpenClaw 标准路径**：对步骤 2/3 得到的本地文件调用 **`enhance_share_file`**，使用返回的 **`structuredContent.url`**（域名 **`https://keepermac.huo15.com`**）。详见 [百炼 URL 约束与 OpenClaw 公网分享](#百炼-url-约束与-openclaw-公网分享必读)。  \r
   - 若用户已提供合法公网 URL，可跳过分享步骤。  \r
   - **勿**在 skill、脚本或对话中写入 `DASHSCOPE_API_KEY`；**勿**自行实现 enhance 插件。\r
5. **调用百炼转写**  \r
   使用本目录脚本（推荐）：\r
\r
   ```bash\r
   pip install dashscope\r
   # 环境变量 DASHSCOPE_API_KEY 已设置\r
   python scripts/transcribe_bailian.py --file-url "https://keepermac.huo15.com/plugins/enhance-share/..." -o verbatim.txt\r
   ```\r
\r
   可选参数：\r
   - `--model paraformer-v2`（默认；方言/嘈杂场景可改 **`fun-asr`**，见百炼文档选型）\r
   - `--diarization`：说话人分离（**仅单声道**；多声道需先 `ffmpeg -ac 1` 混成单声道，**不必**强行转成 MP3）\r
   - `--language-hints zh en`（**仅 `paraformer-v2`** 等支持的模型）\r
\r
6. **结果检查（不做 Whisper 模型升级）**  \r
   - 任务状态须为 **SUCCEEDED**；原文非空。  \r
   - 若明显乱码、大段空结果 → 提示用户换模型（如 `fun-asr`）或检查 URL/格式，**不要**编造纪要。\r
7. **生成纪要 + OpenClaw 交付块**  \r
   严格基于原文；模板与 YAML 字段与 `huo15-openclaw-asr` 一致，但交付块须标明云端来源（见下节）。\r
8. **可选落盘**  \r
   与 `huo15-openclaw-asr` 相同：询问后保存 Markdown（原文+纪要+交付块）或 Word（仅纪要，调用 **`huo15-openclaw-office-doc`**）。\r
\r
---\r
\r
## 可选本地转码（ffmpeg）\r
\r
仅在需要时使用；**百炼路线默认跳过本节。**\r
\r
| 情况 | 建议 |\r
|------|------|\r
| 扩展名不在百炼支持列表 | 转为 `mp3` 或 `wav` 等支持格式后，再 `enhance_share_file` 分享 |\r
| 百炼任务失败或识别结果为空 | 先查 share URL 是否有效、百炼能否拉取；仍失败可试转码或换 `fun-asr` |\r
| `--diarization` 且源文件为多声道 | `ffmpeg -i INPUT -ac 1 OUTPUT.wav`（或其它支持格式），**不必** MP3 |\r
| 减小上传体积 | 可 `ffmpeg` 压成 `mp3`/`aac` 后再 `enhance_share_file` |\r
\r
转 MP3 可复用 `huo15-openclaw-asr` 脚本（**仅当选择转 MP3 时**）：\r
\r
- Windows：`../huo15-openclaw-asr/scripts/transcode_mp3.ps1`\r
- Unix：`../huo15-openclaw-asr/scripts/transcode_mp3.sh`\r
\r
---\r
\r
## 凭证与环境\r
\r
| 变量 | 说明 |\r
|------|------|\r
| `DASHSCOPE_API_KEY` | 百炼 API Key（[配置到环境变量](https://help.aliyun.com/zh/model-studio/paraformer-recorded-speech-recognition-python-sdk)，禁止硬编码） |\r
\r
任务为**异步**：提交后排队，通常数分钟内完成；结果 JSON 的下载链接 **24 小时有效**（以官方说明为准）。\r
\r
---\r
\r
## OpenClaw（龙虾）交付块\r
\r
在 `huo15-openclaw-asr` 交付块基础上**增加/固定**下列字段：\r
\r
```markdown\r
---OPENCLAW_ASR_DELIVERY---\r
version: 1\r
asr_engine: bailian_paraformer\r
bailian_model: "\x3Cparaformer-v2 | fun-asr | ...>"\r
source_kind: audio_video\r
source_path: "\x3C原始文件路径或标识>"\r
file_url: "\x3Cenhance_share_file 返回的 structuredContent.url，或用户提供的公网 URL>"\r
share_via: "enhance_share_file | user_provided_url"\r
local_transcode: "\x3Cnone | 说明：如 ffmpeg 混单声道 wav；默认 none 表示直传原文件>"\r
language_guess: "\x3Czh | en | mixed | unknown>"\r
type_candidates:\r
  - code: "\x3Cmeeting|interview|...>"\r
    confidence: \x3C0.0-1.0>\r
    reason: "\x3C一句理由>"\r
verbatim_text: |\r
  \x3C原文全文>\r
summary_markdown: |\r
  \x3C纪要全文>\r
notes_for_openclaw: |\r
  云端百炼转写；模型=\x3C模型名>；用户已确认上云；\x3C其它不确定性>\r
---END_OPENCLAW_ASR_DELIVERY---\r
```\r
\r
纪要模板、类型候选表：见 [huo15-openclaw-asr · 纪要模板](../huo15-openclaw-asr/SKILL.md#纪要模板)。\r
\r
---\r
\r
## 保存 Word（纪要）\r
\r
与 `huo15-openclaw-asr` 相同：调用 **`huo15-openclaw-office-doc`** 的 `create-word-doc.py`，`--doc-format 会议纪要`。详见 [选项 B：保存为 Word](../huo15-openclaw-asr/SKILL.md#选项-b保存为-word仅纪要)。\r
\r
---\r
\r
## 与 `huo15-openclaw-asr` 的分工小结\r
\r
| 能力 | 本 skill | huo15-openclaw-asr |\r
|------|----------|-------------------|\r
| 百炼 Paraformer / Fun-ASR | ✔ 默认 | 不实现，仅指向本 skill |\r
| 公网 URL（enhance_share_file） | ✔ 标准 | ✘ |\r
| Whisper / WhisperX | ✘ | ✔ 默认 |\r
| `.tty` 终端日志 | ✘ | ✔ |\r
| 纪要 / 交付块 / 落盘 | ✔（复用约定） | ✔ |\r
\r
---\r
\r
## 自检清单\r
\r
- [ ] 已确认用户同意**云端**转写。\r
- [ ] 已配置 `DASHSCOPE_API_KEY`（未泄露到仓库或对话）。\r
- [ ] 已通过 **`enhance_share_file`** 取得公网 URL（`https://keepermac.huo15.com/...`），或用户已提供合法 URL；**未手写/拼接** share 链接。\r
- [ ] 音频 URL 已提交百炼；**默认未做不必要的本地转码**。\r
- [ ] 若曾本地转码：已在 `local_transcode` / `notes_for_openclaw` 中说明原因（格式、分轨、压缩等）。\r
- [ ] 已用 `transcribe_bailian.py` 或等效 SDK 调用，任务 **SUCCEEDED**，原文非空。\r
- [ ] 若启用说话人分离：音频为**单声道**。\r
- [ ] 纪要严格来源于原文；已输出带 `asr_engine: bailian_paraformer` 的交付块。\r
- [ ] 若保存 Word：已走 `huo15-openclaw-office-doc`。\r
\r
---\r
\r
## 附加资源\r
\r
- 脚本说明：[scripts/README.md](scripts/README.md)\r