yuanflow-cli 0.1.18 → 0.1.20

package/skills/yuanflow-skill//351/237/263/350/247/206/351/242/221/345/234/250/347/272/277/350/275/254/346/226/207/345/255/227/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: 音视频在线转文字
+description: 当用户需要把本地音频或视频通过 YuanFlow 在线 ASR 接口转成文字、云端转写、快速转写，或明确要求使用 doubao-asr 在线识别时使用。
+---
+
+# 音视频在线转文字
+
+本 Skill 使用 YuanFlow 网关的在线 ASR 能力，把音频或视频转成文字。它不下载本地模型；如果用户明确要求离线、本地模型或本地 ASR，改用 `本地音视频转文字`。
+
+## 适用场景
+
+- 用户要求“在线转文字”“云端转写”“快速转写”“音频识别”“视频提取文字”。
+- 用户提供本地音频、视频文件路径，并希望得到完整文字稿。
+- 用户明确要求 `doubao-asr`。
+
+## 固定流程
+
+1. 判断输入类型。
+   - 音频：直接进入上传流程。
+   - 视频：先用 ffmpeg 分离音频，再进入上传流程。
+2. 上传前把待上传音频整理为英文文件名。
+   - 官方参数只要求 `metadata.audio_url` 是可公网访问的音频 URL，没有说明必须英文文件名。
+   - 但为避免 OSS URL 编码、上游下载和中文文件名兼容问题，上传前必须使用 ASCII 英文文件名，例如 `transcription-input.mp3`。
+3. 使用 `OSS文件中转工具` 上传音频。
+4. 从 OSS 返回中优先取 `data.signed_url` 作为 ASR 的 `metadata.audio_url`。
+   - 不要优先使用裸域名 `data.url`；实测裸域名可能导致上游报 `Invalid audio URI` 或音频下载失败。
+   - 如果只有 `data.url`，必须补齐 `https://` 后再尝试；失败时说明 OSS URL 不可被 ASR 上游下载。
+5. 调用在线 ASR 接口。
+6. 默认只把干净文本返回给用户，不展示原始 JSON。
+7. 只有用户明确要求时间戳、分句、原始结构或调试信息时，才返回 JSON 摘要或原始字段。
+
+## 视频转音频
+
+视频输入必须先抽音频：
+
+```powershell
+ffmpeg -y -i "C:\path\to\input.mp4" -vn -acodec libmp3lame -ar 44100 -ac 2 "transcription-input.mp3"
+```
+
+如果 ffmpeg 不可用，必须明确告诉用户缺少 ffmpeg，不能伪造转写结果。
+
+## OSS 上传
+
+YuanFlow 主程序内优先调用 `yuanflow_cli_call`，使用 OSS 子命令上传英文命名后的音频：
+
+```json
+{
+  "args": [
+    "oss",
+    "temp-upload",
+    "--file",
+    "C:\\path\\to\\transcription-input.mp3",
+    "--filename",
+    "transcription-input.mp3",
+    "--content-type",
+    "audio/mpeg",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 180
+}
+```
+
+外部 Agent 可直接执行：
+
+```bash
+yuanflow-cli oss temp-upload \
+  --file ./transcription-input.mp3 \
+  --filename transcription-input.mp3 \
+  --content-type audio/mpeg \
+  --format agent-json
+```
+
+解析返回时优先使用：
+
+```text
+response.data.signed_url
+```
+
+## ASR 接口
+
+调用端点：
+
+```http
+POST https://open.yuanchuangai.com/v1/audio/transcriptions
+Authorization: Bearer <由 YuanFlow 自动注入>
+Content-Type: application/json
+```
+
+请求体：
+
+```json
+{
+  "model": "doubao-asr",
+  "response_format": "json",
+  "metadata": {
+    "audio_url": "<OSS signed_url>"
+  }
+}
+```
+
+在 YuanFlow 主程序内优先使用 `yuanflow_gateway_request`：
+
+```json
+{
+  "method": "POST",
+  "path": "/v1/audio/transcriptions",
+  "body": {
+    "model": "doubao-asr",
+    "response_format": "json",
+    "metadata": {
+      "audio_url": "<OSS signed_url>"
+    }
+  },
+  "timeout": 180
+}
+```
+
+## 返回处理
+
+当前实测成功响应为：
+
+```json
+{
+  "text": "完整转写文本..."
+}
+```
+
+默认最终回复只输出 `text` 字段清洗后的文本内容。
+
+如果用户要求时间戳：
+
+- 先检查接口返回里是否包含 `utterances`、`words`、`segments`、`start_time`、`end_time` 等结构。
+- 如果本次接口没有返回时间戳字段，如实说明“当前网关响应只返回全文 text，未返回时间戳”。
+- 不要编造时间戳。
+
+## 失败处理
+
+- `Invalid audio URI` / `audio download failed`：优先检查是否误用了 `data.url` 裸域名；改用 `data.signed_url` 重试。
+- OSS 上传成功但 ASR 失败：说明 OSS key 已生成，但上游无法下载或识别该 URL。
+- 视频抽音频失败：报告 ffmpeg 错误，不继续调用 ASR。
+- 不要暴露 token、Authorization header、签名 URL 的完整敏感查询参数，除非用户明确需要调试链接。