本地语音识别（Windows · Qwen3-ASR · OpenVINO）

模型: snake7gun/Qwen3-ASR-0.6B-fp16-ov（ModelScope FP16）

SKILL_VERSION: 'v1.0.3'

首次使用？ 使用此技能前，请在终端中运行以下两个脚本各一次：

python setup.py          # [系统 Python 可用] 创建虚拟环境，安装依赖（约 5 分钟）
python download_model.py # [系统 Python 可用] 下载模型（约 2 GB，支持断点续传）

两个脚本均位于技能目录中，与此 SKILL.md 同级。

智能体路由

始终使用 acoustic_pipeline.py 作为入口，调用时使用 VENV_PY（从 check_env.py 输出中获取）。它处理所有情况：

# VENV_PY = 来自 check_env.py 输出的值，例如 C:\intel_openvino\venv\Scripts\python.exe

# 单个文件
& "<VENV_PY>" "<skill_dir>\acoustic_pipeline.py" --file "<FILE_PATH>" --language auto

# 单个文件 + 保存转录文本
& "<VENV_PY>" "<skill_dir>\acoustic_pipeline.py" --file "<FILE_PATH>" --language auto --archive json

# 监视文件夹
& "<VENV_PY>" "<skill_dir>\acoustic_pipeline.py" --watch "<DIR_PATH>" --language auto --archive both

# 批量处理文件夹
& "<VENV_PY>" "<skill_dir>\acoustic_pipeline.py" --batch "<DIR_PATH>" --language auto --archive json

**切勿使用系统 python 运行 acoustic_pipeline.py。** 它导入的模型包（openvino、qwen_asr）仅安装在虚拟环境中。

仅当 acoustic_pipeline.py 内部调用时，才直接使用 transcribe.py —— 不要将其作为独立入口点调用。

技能契约（输入 / 输出）

接受的输入

任何智能体都应将此技能视为本地音频/视频转录技能。

1. 单个文件路径

* 音频：.wav、.mp3、.flac、.m4a、.ogg、.aac、.wma、.opus

* 视频：.mp4、.mkv、.webm、.flv、.mov、.avi、.mts、.m2ts、.ts、.m3u8

1. 文件夹路径

* 监视模式：持续处理文件夹中的新文件

* 批量模式：递归处理文件夹中已有文件

1. 运行时选项

* language：auto 或明确的语言名称

* archive：none | txt | json | both

* archive_dir：可选的转录文件输出文件夹

* auto_bootstrap：环境缺失时自动初始化 ASR

成功时的输出

结果应以 JSON 对象（或等效字典）返回，包含：

* text：转录内容

* language：检测到或指定的语言

* source_file：原始输入路径

* source_format：源文件扩展名

* confidence：可选的置信度值（如有）

* archive_files：可选的对象，包含 txt/json 输出路径

示例结构：

{
    "text": "...",
    "language": "Chinese",
    "source_file": "C:\\demo\\meeting.mp4",
    "source_format": ".mp4",
    "confidence": null,
    "archive_files": {
        "json": "C:\\demo\\transcripts\\meeting_20260326_120000.json"
    }
}

失败时的输出

智能体应返回一个简短的结构化错误摘要，包括：

* error：人类可读的失败原因

* stage：bootstrap | extract_audio | transcribe | archive

* source_file：输入路径（如果已知）

* recoverable：如果重试合理则为 true

⚠️ 智能体指令

1. 仅限 Windows / PowerShell。 切勿使用 Linux 命令（ls、rm、cat）。切勿使用 && 或 call。
2. **每个步骤自行读取 state.json** —— 不要手动在步骤之间传递路径。
3. **对推理调用使用 state.json 中的 VENV_PY** —— 切勿使用系统 python 进行推理。check_env.py 和 setup.py 是唯一有意使用系统 python 运行的脚本（它们创建或验证虚拟环境，因此不能依赖虚拟环境）。check_env.py 验证的是*虚拟环境*中的包，而非系统 Python 的包 —— 来自 check_env.py 的 PACKAGES_MISSING 表示虚拟环境不完整，而非系统安装的问题。
4. transcribe.py 在 setup.py 运行时自动部署到 ASR_DIR。如果缺失，请重新运行 setup.py。
5. **如果 transcribe.py 在运行时失败**，请勿手动编辑。重新运行 setup.py 以从仓库重新部署原始版本。
6. 在未运行步骤 1 的检查脚本之前，切勿诊断“模型问题”。 模型布局可能使用 thinker/ 子目录 —— 脚本会自动处理。
7. 不要在智能体工作区目录中生成辅助脚本。 请使用仓库管理的 check_env.py。
8. 目标：转录音频文件并将结果发送到对话中。

自动恢复策略 —— 先尝试，再询问用户：

⚠️ 网络处理（感知代理）

当运行 setup.py 或 download_model.py 时：

1. 尝试读取系统代理设置：

* 环境变量：HTTP_PROXY / HTTPS_PROXY

* Windows WinHTTP 代理（netsh winhttp show proxy）

1. 如果检测到代理：

* 自动应用它

* 继续安装/下载

1. 如果未检测到代理：

* 正常继续（直接连接）

1. 如果下载/安装失败：

* 告知用户是否检测到代理

* 如果未检测到代理，建议配置一个

* 然后重试

重要：

* 许多网络（企业 / 中国大陆 / 校园网）需要代理

* 下载支持断点续传 —— 修复网络后重试是安全的

* 如果 STATE=MISSING、VENV_PY=BROKEN 或 PACKAGES_MISSING：自动运行 setup.py（最多 3 次尝试）。仅当所有 3 次尝试均失败时，才要求用户手动运行它。setup.py 是幂等的 —— 它会跳过任何已完成的步骤（虚拟环境、包、仓库克隆、asr_engine.py、transcribe.py）。在已工作的环境中重新运行是安全且快速的。

* 如果 MODEL_STATUS=MISSING：自动运行 download_model.py（最多 3 次尝试）。仅当所有 3 次尝试均失败，或单次尝试运行超过 8 分钟仍未完成（可能是慢速连接 —— download_model.py 支持断点续传，部分进度不会丢失）时，才要求用户手动运行它。download_model.py 在模型已完成时立即退出 —— 对已下载的模型重新运行脚本是安全的。

* 每次尝试前始终宣布您正在做什么：“⚙️ 自动设置环境（尝试 N/3）…”

预检：验证运行时要求（首次使用必须）

🔍 预检：正在检查 Python 和 git...

检查 Python 版本

python --version

解释：

如果输出包含“不传递参数运行以从 Microsoft Store 安装”，则表示 Windows Store 应用执行别名遮挡了真正的 Python。不要要求用户更改设置，也不要编写辅助脚本。使用 where.exe（原生 Windows 工具，可在 PowerShell 和 cmd 中运行）找到真正的 Python：

⚠️ 不要编写任何 .ps1 辅助脚本。直接在终端中运行以下命令。

where.exe python 2>$null | Where-Object { $_ -notlike "*WindowsApps*" } | Select-Object -First 1

* 输出了一个路径 → **将该字符串记录为 SYSTEM_PYTHON**（这是系统级 Python，仅用于运行 setup.py、check_env.py 和 download_model.py）。对于标记为 [SYSTEM PYTHON] 的每个命令，将完整路径替换 python。例如：python "<skill_dir>\check_env.py" 变为 "C:\Users\intel\AppData\Local\Programs\Python\Python312\python.exe" "<skill_dir>\check_env.py"。请勿将此路径用于推理 — 推理必须始终使用 VENV_PY（check_env.py 打印的 venv Python 路径）。**请勿跨工具调用依赖 $variable** — 每次调用都是一个新 shell 进程；始终直接嵌入字面路径。

* 无任何输出 → Python 未安装 — 安装它（见下文）。

如果 Python 缺失或版本过旧，在 PowerShell 中运行以下一键静默安装程序（推荐，无需管理员权限）：

$f = "$env:TEMP\python-installer.exe"
Invoke-WebRequest "https://www.python.org/ftp/python/3.12.10/python-3.12.10-amd64.exe" -OutFile $f
Start-Process $f -ArgumentList "/quiet InstallAllUsers=0 PrependPath=1 Include_pip=1" -Wait
Remove-Item $f

PrependPath=1 自动将 Python 添加到 PATH；Include_pip=1 安装 pip；InstallAllUsers=0 避免需要管理员权限。

安装后，重启终端，然后运行 python --version 确认显示 Python 3.12.x。

如果更喜欢手动安装：下载 https://www.python.org/ftp/python/3.12.10/python-3.12.10-amd64.exe，并确保在安装过程中勾选 “Add python.exe to PATH”。

检查 git

git --version

解释：

如果 git 缺失，在 PowerShell 中运行以下一键静默安装程序：

$f = "$env:TEMP\git-installer.exe"
Invoke-WebRequest "https://github.com/git-for-windows/git/releases/download/v2.49.0.windows.1/Git-2.49.0-64-bit.exe" -OutFile $f
Start-Process $f -ArgumentList "/VERYSILENT /NORESTART /NOCANCEL /SP- /CLOSEAPPLICATIONS /RESTARTAPPLICATIONS /COMPONENTS=icons,ext\reg\shellhere,assoc,assoc_sh" -Wait
Remove-Item $f

安装后，重启终端，然后运行 git --version 确认。

如果更喜欢手动安装：打开 https://git-scm.com/download/win，下载安装程序，按默认选项进行。

git 是 requirements_imagegen.txt 中 git+https:// 依赖所必需的；没有 git，pip install 将失败并提示 git: command not found。

预检通过标准：python --version >= 3.10 且 git --version 返回有效的版本字符串。

状态消息：✅ Python and git are ready. Starting main workflow.

流水线 — 严格按以下顺序执行，不可跳过：

Step 0: parse request       → AUDIO_PATH, LANGUAGE, TOPIC
Step 1: verify environment  → run check_env.py → record VENV_PY and ASR_DIR
         ↳ if STATE=MISSING or VENV_BROKEN or PACKAGES_MISSING: auto-run setup.py (3 attempts)
         ↳ if SCRIPTS_STALE=...: auto-run setup.py to redeploy runtime scripts
         ↳ if MODEL_STATUS=MISSING: auto-run download_model.py (3 attempts)
Step 2: transcribe + send   → run acoustic_pipeline.py using VENV_PY from Step 1
         ↳ fallback: run transcribe.py directly using VENV_PY and ASR_DIR from Step 1

Step 0: 解析请求（仅限 LLM — 无需工具）

从用户消息中提取：

如果未提供音频文件，请先询问用户再继续。

Step 1: 验证环境和模型

Step 1/3: checking environment and model...

[系统 Python] check_env.py 创建/验证虚拟环境 — 此处不能使用 venv 中的 Python

python "<skill_dir>\check_env.py"

> `check_env.py` 和 `setup.py` 专门使用系统 Python 运行——它们创建并验证虚拟环境，因此不能依赖虚拟环境。

**成功时**：从输出中记录 `VENV_PY` 和 `ASR_DIR`，然后继续执行步骤 2。

> 当部署的 `transcribe.py` 过期时，`check_env.py` 还会打印 `SCRIPTS_STALE=<旧版本>-><新版本>`。
> 如果出现这一行，则必须将其视为强制性的**自动更新**——在步骤 2 之前运行 `setup.py`（见下文）。

**失败时 — 自动恢复（在询问用户之前先尝试）：**

### 如果 SCRIPTS_STALE=... → 自动运行 setup.py 重新部署运行时脚本

`SCRIPTS_STALE` 表示虚拟环境和模型都正常，但部署在 `ASR_DIR` 中的 `transcribe.py`（和/或 `asr_engine.py`）是旧版本。`setup.py` 是幂等的——它会跳过虚拟环境、包和模型步骤，仅重新部署过期的文件。

⚙️ 运行时脚本已过期。正在重新部署（尝试 1/3）...

[系统 Python] — 将 transcribe.py 和 asr_engine.py 重新部署到 ASR_DIR

python "<skill_dir>\setup.py"

运行后，重新运行 `check_env.py` 确认 `SCRIPTS_STALE` 不再出现，然后继续步骤 2。

### 如果 STATE=MISSING 或 VENV_PY=BROKEN 或 PACKAGES_MISSING → 自动运行 setup.py

`PACKAGES_MISSING` 表示虚拟环境存在，但所需的包（例如 `openvino`、`qwen_asr`）未安装。重新运行 `setup.py` 仅安装缺失的包；不会重新创建虚拟环境或重新克隆仓库。

宣布并运行（最多尝试 3 次）：

⚙️ 环境未初始化。正在自动设置（尝试 1/3）...

[系统 Python] setup.py 创建虚拟环境 — 此处不能使用 venv 中的 Python

python "<skill_dir>\setup.py"

每次尝试后，重新运行 `check_env.py` 验证。如果所有 3 次尝试都失败，显示下面的手动回退方案。

### 如果 MODEL_STATUS=MISSING → 自动运行 download_model.py

宣布并运行（最多尝试 3 次，单次尝试超过 8 分钟则停止）：

📥 模型未找到。正在启动自动下载（尝试 1/3）...

预计时间：100 Mbps 约 3 分钟，50 Mbps 约 5 分钟

下载支持断点续传；中断后可安全重新运行。

[系统 Python] download_model.py 在虚拟环境之前运行 — 此处不能使用 venv 中的 Python

python "<skill_dir>\download_model.py"

每次尝试后，重新运行 `check_env.py` 验证。如果所有 3 次尝试都失败，显示下面的手动回退方案。

### 手动回退（仅在所有 3 次自动尝试都失败时）

向用户显示以下消息：

⚠️ 自动设置失败。需要手动操作。

打开 Windows 终端（PowerShell 或命令提示符），并按顺序运行以下命令：

1) 安装环境（如果尚未安装）：

python "<skill_dir>\setup.py" # [系统 Python 可以]

预计耗时：约 5 分钟，全自动化。

2) 下载模型（约 2 GB）：

python "<skill_dir>\download_model.py" # [系统 Python 可以]

下载支持断点续传；中断后可安全重新运行。

预计时间：100 Mbps 约 3 分钟，50 Mbps 约 5 分钟。

完成后，返回此处并重新发送您的请求。

---

## 步骤 2：转录并发送结果

> 步骤 2/2：正在转录...

**首选路径** — 使用步骤 1 获得的**虚拟环境 Python** 运行 `acoustic_pipeline.py`：

[VENV PYTHON] VENV_PY = check_env.py 打印的值，例如 C:\intel_openvino\venv\Scripts\python.exe

此处绝不能使用系统 Python — openvino/qwen_asr 仅在虚拟环境中

& "<VENV_PY>" "<skill_dir>\acoustic_pipeline.py" --file "AUDIO_PATH" --language auto --archive json

如果用户指定了语言：

[VENV PYTHON]

& "<VENV_PY>" "<skill_dir>\acoustic_pipeline.py" --file "AUDIO_PATH" --language "LANGUAGE" --archive json

直接将 JSON 结果返回给对话，并包含 `archive_files` 路径。

**回退方案** — 仅在 `acoustic_pipeline.py` 以非零退出码结束时使用：

[VENV PYTHON] 回退 — VENV_PY 和 ASR_DIR 均来自 check_env.py（步骤 1）

& "<VENV_PY>" "<ASR_DIR>\transcribe.py" --audio "AUDIO_PATH" --language "LANGUAGE"

> 此处绝不能使用系统 Python。

**成功**：`$LASTEXITCODE -eq 0`。标准输出为单行 JSON，结构如下：

{"text": "...", "language": "Chinese", "time_elapsed": 12.3, "audio_path": "C:\\audio\\file.wav"}

使用 `$result = $stdout | ConvertFrom-Json` 解析。从 `$result.text` 记录 `TRANSCRIPT`，从 `$result.language` 记录 `LANG`。

**失败**：如果 `$LASTEXITCODE -ne 0`，不要尝试解析标准输出。向用户显示标准错误输出。

通过 `message` 工具发送：

action: "send" message: "✅ LANG\n\nTRANSCRIPT"

---

## 故障排除

| 错误 | 修复 |
|---|---|
| `Python was not found; run without arguments...` | Windows Store 别名屏蔽了 `python`。运行：`where.exe python 2>$null | Where-Object { $_ -notlike "*WindowsApps*" } | Select-Object -First 1`。记下打印的文本路径，并在后续的每条命令中用它替换 `python`（不要使用 `$variable`，每次工具调用都是新 shell）。 |
| `STATE=MISSING` | 运行 `python "<skill_dir>\setup.py"` |
| `VENV_PY=BROKEN` | 重新运行 `python "<skill_dir>\setup.py"` — 它将重建虚拟环境 |
| `PACKAGES_MISSING: ...` | 重新运行 `python "<skill_dir>\setup.py"` — 仅重新安装缺失的 venv 包；跳过已完成的步骤 |
| `MODEL_STATUS=MISSING` | 运行 `python "<skill_dir>\download_model.py"` — 如果模型已完成，立即退出 |
| `[ERROR] Audio not found` | 检查文件路径是否正确且文件存在 |
| `[ERROR] Model incomplete` | 重新运行 `python "<skill_dir>\download_model.py"` — 支持断点续传 |
| `[ERROR] state.json not found` | 重新运行步骤 1（`check_env.py`） |
| `SCRIPTS_STALE=v1.0.1->v1.0.2` | 部署的运行脚本已过时。运行 `python "<skill_dir>\setup.py"` — 仅重新部署更改的文件，跳过 venv/包/模型（快速）。 |
| `RuntimeError` on GPU | 先运行 `check_env.py` 确认模型已就绪。如果模型正常，尝试添加 `--language auto` 消除语言不匹配。若仍失败，重新运行 `setup.py` 升级 OpenVINO 并重新部署运行时文件。 |

---

## LLM API 使用

对于偏好 Python 导入接口而非 shell 命令的智能体，请在子进程中使用 **VENV_PY** 运行：

必须使用 VENV_PY 运行，而非系统 python

& "<VENV_PY>" -c "

import sys; sys.path.insert(0, r'<skill_dir>')

from acoustic_pipeline import AcousticPipeline

pipeline = AcousticPipeline()

result = pipeline.transcribe(r'C:\\meeting.mp4', language='auto', archive_mode='json')

print(result['text'])

"

或者，如果智能体框架已在 venv Python 进程中运行：

from acoustic_pipeline import AcousticPipeline

pipeline = AcousticPipeline()

result = pipeline.transcribe("C:\\meeting.mp4", language="auto", archive_mode="json")

print(result["text"])

print(result.get("archive_files"))

---

## 工作区卫生

* 使用仓库管理的 `check_env.py` — 它是版本化、可审计且可重复的。
* 如果执行环境强制使用临时文件，请将其视为可丢弃的，并在命令完成后删除。