yuanflow-cli 0.1.11 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuanflow-cli",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "YuanFlow API CLI and skill installer for supported AI coding agents.",
   "type": "module",
   "license": "MIT",

package/skills/yuanflow-skill/README.md

@@ -10,6 +10,7 @@ YuanFlow Skill 是 `yuanflow-cli` 的 Agent Skill 仓库，用于把社媒平台
 - `OSS文件中转工具/`：OSS 临时上传、签名链接、对象复制 Skill，走 `yuanflow-cli oss`。
 - `生图技能/`：图片生成与编辑 Skill，优先走 YuanFlow 内置 `yuanflow_image_request`。
 - `HTML报告生成/`：单页 HTML 报告生成 Skill，内置 9 种米色留白报告模板。
+- `本地音视频转文字/`：本地 SenseVoice 音视频转文字 Skill，首次明确使用时按需下载模型。
 
 ## 适用场景
 
@@ -20,6 +21,7 @@ YuanFlow Skill 是 `yuanflow-cli` 的 Agent Skill 仓库，用于把社媒平台
 - 上传文件到临时 OSS、生成签名链接或复制 OSS 对象。
 - 生成图片、编辑图片，并缓存返回 URL 或 base64 图片。生成图片必填 `prompt`，可选 `size / quality / style / n / response_format`；编辑图片必须通过 multipart 上传本地图片。
 - 把自媒体分析、数据复盘、文案方案、账号监控、知识梳理和执行计划生成可直接打开的单页 HTML 报告。
+- 在用户明确要求本地转写时，把本地音频或视频转成文字；视频会先抽取音频，模型和缓存都保存在 Skill 自己目录下。
 
 ## 双环境使用方式
 
@@ -85,6 +87,9 @@ yuanflow-skill list-skills
 │  ├─ SKILL.md
 │  ├─ templates/
 │  └─ references/
+├─ 本地音视频转文字
+│  ├─ SKILL.md
+│  └─ scripts/
 └─ OSS文件中转工具
    └─ SKILL.md
 ```

package/skills/yuanflow-skill/SKILL.md

@@ -22,6 +22,7 @@ description: Use when the user asks about social-media API workflows, platform d
 - `OSS文件中转工具/`
 - `生图技能/`
 - `HTML报告生成/`
+- `本地音视频转文字/`
 
 ## 环境判断
 
@@ -165,6 +166,16 @@ description: Use when the user asks about social-media API workflows, platform d
 
 - `HTML报告生成`
 
+### 11. 走 `本地音视频转文字`
+
+只有当用户明确要求使用本地音视频转文字、本地转写、本地 ASR、离线转写或本地模型把音频/视频转成文字时，才进入这个子 Skill。
+
+不要因为用户普通提到音频、视频、口播、文案或总结就自动使用。
+
+子 Skill 名称：
+
+- `本地音视频转文字`
+
 ## 多需求时怎么处理
 
 如果用户一次提了多段流程，不要强行塞进一个子 Skill，按阶段拆开：

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

@@ -0,0 +1,148 @@
+---
+name: 本地音视频转文字
+description: 仅当用户明确要求使用本地音视频转文字、本地转写、本地 ASR、离线/本地模型把音频或视频转成文字时使用；不要因为用户普通提到音频、视频、文案或总结就自动使用。
+---
+
+# 本地音视频转文字
+
+本 Skill 用本地 SenseVoice 模型把音频或视频转成文字。它只在用户明确提出“使用本地音视频转文字”“本地转写”“用本地模型转文字”“离线转写”等需求时使用。
+
+## 触发边界
+
+只有满足下面条件之一时才使用：
+
+- 用户明确要求使用“本地音视频转文字”这个技能。
+- 用户明确要求本地转写、本地 ASR、离线转写、本地模型转文字。
+- 用户提供音频或视频文件，并明确说要用本地能力把它转成文字。
+
+不要在下面情况自动使用：
+
+- 用户只是让你总结一段已有文字。
+- 用户只是提到音频、视频、文案、脚本，但没有要求本地转写。
+- 用户要求在线识别、云端转写或其它指定服务。
+
+## 固定目录
+
+本 Skill 的脚本目录为当前 Skill 目录下的 `scripts/`。
+
+默认目录：
+
+- 模型保存目录：`scripts/models`
+- 任务缓存目录：`scripts/cache`
+- 抽取音频目录：`scripts/cache/audio`
+- 转写文本目录：`scripts/cache/transcripts`
+
+在 YuanFlow 程序内置环境中，`skill_read` 返回的 `config.managed_skill_dir` 是当前 Skill 的真实目录。执行脚本时优先以这个目录为基准：
+
+```powershell
+cd "<config.managed_skill_dir>\scripts"
+```
+
+不要把模型下载到用户桌面、项目根目录或系统临时目录。不要把模型文件打包进 Skill 或 npm 包。
+
+## 首次使用模型下载规则
+
+开始转写前先检查模型目录是否已经存在：
+
+- `scripts/models/SenseVoiceSmall`
+- `scripts/models/fsmn-vad`
+
+如果这两个目录都存在且不为空，直接执行后续任务。
+
+如果首次使用没有模型，运行脚本时允许自动下载：
+
+- SenseVoice：`iic/SenseVoiceSmall`
+- VAD：`iic/speech_fsmn_vad_zh-cn-16k-common-pytorch`
+
+下载由 `modelscope.snapshot_download()` 完成，保存到 `scripts/models`。下载完成后继续转写。
+
+## 执行流程
+
+1. 确认用户明确要求本地转写。
+2. 读取本 Skill 完整说明。
+3. 定位 `config.managed_skill_dir` 或当前 Skill 目录。
+4. 检查 Python 虚拟环境和依赖；不要全局安装依赖。
+5. 如果用户提供的是视频，先转为音频，再把音频转成文字。
+6. 如果用户提供的是音频，直接转成文字。
+7. 把输出的 `.txt` 文件路径和核心转写结果报告给用户。
+
+## 环境准备
+
+在 `scripts/` 目录下创建虚拟环境并安装依赖：
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -r requirements-transcribe.txt
+```
+
+视频转音频需要本机可用 `ffmpeg`。如果用户给的是视频且系统找不到 `ffmpeg`，先明确报告缺少 ffmpeg，不要伪造转写结果。
+
+## 推荐调用方式
+
+统一入口脚本：
+
+```powershell
+cd "<Skill目录>\scripts"
+.\.venv\Scripts\python.exe .\transcribe_media.py "C:\path\to\input.mp3"
+```
+
+视频示例：
+
+```powershell
+cd "<Skill目录>\scripts"
+.\.venv\Scripts\python.exe .\transcribe_media.py "C:\path\to\input.mp4"
+```
+
+常用参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `input_path` | 音频文件、视频文件或目录。 |
+| `--cache-root` | 缓存目录，默认 `scripts/cache`。 |
+| `--models-root` | 模型目录，默认 `scripts/models`。 |
+| `--recursive` | 输入为目录时递归扫描。 |
+| `--device` | `auto`、`cpu`、`cuda:0` 等，默认 `auto`。 |
+| `--language` | `zh`、`en`、`yue`、`ja`、`ko`、`auto`，默认 `auto`。 |
+| `--batch-size-s` | 动态 batch 秒数，默认 `60`。设备性能差时调小。 |
+| `--overwrite` | 允许覆盖已存在的音频缓存和文本结果。 |
+
+## 低性能设备处理
+
+如果用户设备性能较差，或执行期间出现 CPU、内存不足、进程被系统杀掉、模型加载失败等情况，不要一次性硬跑完整任务。
+
+处理方式：
+
+- 优先把 `--batch-size-s` 调小，例如 `20` 或 `10`。
+- 明确告诉用户当前设备资源不足，正在改用更小批次。
+- 如果仍然失败，建议先用 ffmpeg 把长音频切分成多个片段后逐段转写。
+- 每段完成后保留对应 `.txt` 文件，并在最终结果中说明哪些片段已完成、哪些片段失败、失败原因是什么。
+
+不要只回复“失败”或“网络错误”。要报告：
+
+- 模型目录是否已存在。
+- 是否发生了首次模型下载。
+- 输入文件类型是音频还是视频。
+- 视频是否已抽取音频。
+- 输出文本文件路径。
+- 如果分段执行，列出每段结果文件。
+
+## 清理规则
+
+只有用户明确要求删除缓存或模型文件时，才可以删除：
+
+- 缓存目录：`scripts/cache`
+- 模型目录：`scripts/models`
+
+删除前必须确认目标路径位于当前 Skill 的 `scripts/` 目录下，不能删除其它项目目录、用户桌面目录或系统目录。
+
+## 输出要求
+
+成功后回复必须包含：
+
+- 转写是否成功。
+- 是否首次下载模型，或复用了已有模型。
+- 如果输入是视频，说明已先抽取音频。
+- `.txt` 结果文件的绝对路径。
+- 转写文本的核心内容，长文本可以先给摘要并提示文件里有完整文本。
+
+不要编造没有生成的文件路径。不要暴露任何 token 或认证信息。

package/skills/yuanflow-skill//346/234/254/345/234/260/351/237/263/350/247/206/351/242/221/350/275/254/346/226/207/345/255/227/scripts/common/__init__.py

@@ -0,0 +1 @@
+

package/skills/yuanflow-skill//346/234/254/345/234/260/351/237/263/350/247/206/351/242/221/350/275/254/346/226/207/345/255/227/scripts/common/media.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from .utils import ensure_parent
+
+
+def extract_audio(
+    video_path: Path,
+    output_path: Path,
+    *,
+    ffmpeg_bin: str = "ffmpeg",
+    sample_rate: int = 16000,
+    channels: int = 1,
+    overwrite: bool = False,
+) -> Path:
+    if not shutil.which(ffmpeg_bin):
+        raise FileNotFoundError(f"未找到 ffmpeg：{ffmpeg_bin}")
+    if output_path.exists() and not overwrite:
+        return output_path
+
+    ensure_parent(output_path)
+    command = [
+        ffmpeg_bin,
+        "-y" if overwrite else "-n",
+        "-i",
+        str(video_path),
+        "-vn",
+        "-ac",
+        str(channels),
+        "-ar",
+        str(sample_rate),
+        str(output_path),
+    ]
+    result = subprocess.run(
+        command,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "ffmpeg 抽音频失败")
+    return output_path

package/skills/yuanflow-skill//346/234/254/345/234/260/351/237/263/350/247/206/351/242/221/350/275/254/346/226/207/345/255/227/scripts/common/sensevoice.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .utils import ensure_dir
+
+
+SENSEVOICE_REPO = "iic/SenseVoiceSmall"
+VAD_REPO = "iic/speech_fsmn_vad_zh-cn-16k-common-pytorch"
+TOKEN_RE = re.compile(r"<\|[^>]+\|>")
+
+
+def import_snapshot_download():
+    try:
+        from modelscope import snapshot_download  # type: ignore
+    except ImportError:
+        from modelscope.hub.snapshot_download import snapshot_download  # type: ignore
+    return snapshot_download
+
+
+def model_dir_ready(model_dir: Path) -> bool:
+    return model_dir.exists() and any(model_dir.iterdir())
+
+
+def ensure_model_dir(model_dir: Path, model_id: str) -> tuple[Path, bool]:
+    if model_dir_ready(model_dir):
+        return model_dir, False
+    snapshot_download = import_snapshot_download()
+    ensure_dir(model_dir)
+    try:
+        snapshot_download(
+            model_id=model_id,
+            local_dir=str(model_dir),
+            local_dir_use_symlinks=False,
+        )
+    except TypeError:
+        snapshot_download(
+            model_id=model_id,
+            local_dir=str(model_dir),
+        )
+    return model_dir, True
+
+
+def ensure_models(models_root: Path) -> tuple[Path, Path, bool]:
+    sensevoice_dir, downloaded_sensevoice = ensure_model_dir(
+        models_root / "SenseVoiceSmall",
+        SENSEVOICE_REPO,
+    )
+    vad_dir, downloaded_vad = ensure_model_dir(models_root / "fsmn-vad", VAD_REPO)
+    return sensevoice_dir, vad_dir, downloaded_sensevoice or downloaded_vad
+
+
+def resolve_device(device: str = "auto") -> str:
+    if device != "auto":
+        return device
+    try:
+        import torch  # type: ignore
+
+        return "cuda:0" if torch.cuda.is_available() else "cpu"
+    except Exception:
+        return "cpu"
+
+
+def clean_transcript(text: str) -> str:
+    cleaned = TOKEN_RE.sub(" ", text)
+    cleaned = re.sub(r"\s+", " ", cleaned)
+    return cleaned.strip()
+
+
+def build_model(models_root: Path, device: str = "auto"):
+    from funasr import AutoModel  # type: ignore
+
+    sensevoice_dir, vad_dir, downloaded = ensure_models(models_root)
+    model = AutoModel(
+        model=str(sensevoice_dir),
+        trust_remote_code=True,
+        vad_model=str(vad_dir),
+        vad_kwargs={"max_single_segment_time": 30000},
+        device=resolve_device(device),
+    )
+    return model, downloaded

package/skills/yuanflow-skill//346/234/254/345/234/260/351/237/263/350/247/206/351/242/221/350/275/254/346/226/207/345/255/227/scripts/common/utils.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Iterable
+
+
+VIDEO_SUFFIXES = {".mp4", ".mov", ".mkv", ".avi", ".webm", ".m4v"}
+AUDIO_SUFFIXES = {".wav", ".mp3", ".m4a", ".aac", ".flac", ".ogg", ".opus"}
+MEDIA_SUFFIXES = VIDEO_SUFFIXES | AUDIO_SUFFIXES
+INVALID_FILENAME_RE = re.compile('[<>:"/\\\\|?*\\x00-\\x1F]')
+
+
+def sanitize_filename(name: str, max_length: int = 120) -> str:
+    cleaned = INVALID_FILENAME_RE.sub("_", name).strip()
+    cleaned = re.sub(r"\s+", " ", cleaned)
+    cleaned = cleaned.rstrip(". ")
+    if not cleaned:
+        cleaned = "untitled"
+    return cleaned[:max_length].rstrip(". ")
+
+
+def ensure_parent(path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def ensure_dir(path: Path) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def write_json(path: Path, data: object) -> Path:
+    ensure_parent(path)
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    return path
+
+
+def write_text(path: Path, text: str) -> Path:
+    ensure_parent(path)
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def iter_media_files(path: Path, recursive: bool = False) -> Iterable[Path]:
+    if path.is_file():
+        if path.suffix.lower() in MEDIA_SUFFIXES:
+            yield path
+        return
+    iterator = path.rglob("*") if recursive else path.glob("*")
+    for candidate in iterator:
+        if candidate.is_file() and candidate.suffix.lower() in MEDIA_SUFFIXES:
+            yield candidate
+
+
+def is_video_file(path: Path) -> bool:
+    return path.suffix.lower() in VIDEO_SUFFIXES
+
+
+def is_audio_file(path: Path) -> bool:
+    return path.suffix.lower() in AUDIO_SUFFIXES

package/skills/yuanflow-skill//346/234/254/345/234/260/351/237/263/350/247/206/351/242/221/350/275/254/346/226/207/345/255/227/scripts/requirements-transcribe.txt

@@ -0,0 +1,2 @@
+funasr>=1.1.6
+modelscope>=1.18.1

package/skills/yuanflow-skill//346/234/254/345/234/260/351/237/263/350/247/206/351/242/221/350/275/254/346/226/207/345/255/227/scripts/transcribe_media.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from common.media import extract_audio
+from common.sensevoice import build_model
+from common.sensevoice import clean_transcript
+from common.utils import ensure_dir
+from common.utils import is_audio_file
+from common.utils import is_video_file
+from common.utils import iter_media_files
+from common.utils import sanitize_filename
+from common.utils import write_text
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+DEFAULT_CACHE_ROOT = SCRIPT_DIR / "cache"
+DEFAULT_MODELS_ROOT = SCRIPT_DIR / "models"
+
+
+def prepare_audio(
+    source: Path,
+    *,
+    audio_cache_dir: Path,
+    ffmpeg_bin: str,
+    overwrite: bool,
+) -> tuple[Path, str]:
+    if is_audio_file(source):
+        return source, "audio"
+    if not is_video_file(source):
+        raise ValueError(f"不支持的媒体文件类型：{source}")
+    output_path = audio_cache_dir / f"{sanitize_filename(source.stem)}.wav"
+    extract_audio(
+        source,
+        output_path,
+        ffmpeg_bin=ffmpeg_bin,
+        overwrite=overwrite,
+    )
+    return output_path, "video"
+
+
+def transcribe_file(
+    model,
+    audio_file: Path,
+    *,
+    output_dir: Path,
+    language: str,
+    batch_size_s: int,
+    overwrite: bool,
+) -> Path:
+    output_path = output_dir / f"{sanitize_filename(audio_file.stem)}.txt"
+    if output_path.exists() and not overwrite:
+        return output_path
+    result = model.generate(
+        input=str(audio_file),
+        cache={},
+        language=language,
+        use_itn=True,
+        batch_size_s=batch_size_s,
+        merge_vad=True,
+        merge_length_s=15,
+        ban_emo_unk=True,
+    )
+    raw_text = ""
+    if result and isinstance(result, list):
+        raw_text = str(result[0].get("text", ""))
+    return write_text(output_path, clean_transcript(raw_text))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="本地音视频转文字：视频先抽音频，音频直接转写。")
+    parser.add_argument("input_path", type=Path, help="音频文件、视频文件或目录")
+    parser.add_argument("--cache-root", type=Path, default=DEFAULT_CACHE_ROOT, help="缓存目录")
+    parser.add_argument("--models-root", type=Path, default=DEFAULT_MODELS_ROOT, help="模型目录")
+    parser.add_argument("--recursive", action="store_true", help="目录模式下递归扫描")
+    parser.add_argument("--overwrite", action="store_true", help="覆盖已有缓存和文本结果")
+    parser.add_argument("--ffmpeg-bin", default="ffmpeg", help="ffmpeg 可执行文件名或路径")
+    parser.add_argument("--device", default="auto", help="auto、cpu、cuda:0 等")
+    parser.add_argument("--language", default="auto", help="zh、en、yue、ja、ko、auto")
+    parser.add_argument("--batch-size-s", type=int, default=60, help="动态 batch 秒数")
+    args = parser.parse_args()
+
+    cache_root = args.cache_root.resolve()
+    models_root = args.models_root.resolve()
+    audio_cache_dir = ensure_dir(cache_root / "audio")
+    transcript_dir = ensure_dir(cache_root / "transcripts")
+
+    media_files = list(iter_media_files(args.input_path.resolve(), recursive=args.recursive))
+    if not media_files:
+        raise SystemExit("没有找到可处理的音频或视频文件。")
+
+    try:
+        model, downloaded_models = build_model(models_root, device=args.device)
+    except ImportError as exc:
+        raise SystemExit(
+            "缺少 FunASR 或 ModelScope 依赖。请先在 scripts/.venv 中安装 requirements-transcribe.txt。"
+        ) from exc
+
+    print(f"模型目录: {models_root}")
+    print(f"缓存目录: {cache_root}")
+    print(f"模型首次下载: {'是' if downloaded_models else '否'}")
+
+    for media_file in media_files:
+        audio_file, source_type = prepare_audio(
+            media_file,
+            audio_cache_dir=audio_cache_dir,
+            ffmpeg_bin=args.ffmpeg_bin,
+            overwrite=args.overwrite,
+        )
+        text_path = transcribe_file(
+            model,
+            audio_file,
+            output_dir=transcript_dir,
+            language=args.language,
+            batch_size_s=max(1, args.batch_size_s),
+            overwrite=args.overwrite,
+        )
+        print(f"输入文件: {media_file}")
+        print(f"输入类型: {'视频，已先抽取音频' if source_type == 'video' else '音频'}")
+        print(f"音频文件: {audio_file}")
+        print(f"转写结果: {text_path}")
+
+
+if __name__ == "__main__":
+    main()