live-script-monitor-win — 直播话术巡检系统 (Windows 版)

实时采集直播音频 → ASR 语音转写 → 关键词检测 → 场景自动切换 → 告警推送 → 大屏可视化。

一键启动 (核心功能)

双击 start_windows.bat 即可一键启动！

脚本会自动完成：

1. 检查 Python 环境（需预先安装 Python 3.10+）
2. 创建 Python 虚拟环境 + 安装依赖（含国内镜像源降级）
3. 检查并自动安装 FFmpeg（winget → imageio-ffmpeg 多级降级）
4. 检查 VB-Cable 虚拟声卡（需手动安装，见下文）
5. 启动巡检系统

启动后打开浏览器访问：http://localhost:9999

首次使用前需自行安装的组件

本 Skill 包不含 FFmpeg、VB-Cable 等大型二进制依赖，首次使用需手动安装以下组件：

1. Python 3.10+（必须）

winget install Python.Python.3.12

或从 https://www.python.org/downloads/ 下载，安装时勾选 "Add Python to PATH"。

2. VB-Cable 虚拟声卡（采集系统音频必须）

1. 访问 https://vb-audio.com/Cable/
2. 下载 VBCABLE_Setup_x64.exe
3. 以管理员身份运行安装程序
4. 安装后重启电脑
5. 系统声音设置 → 输出设备选「CABLE Input (VB-Audio Virtual Cable)」

没有 VB-Cable 也可以启动系统，但无法采集系统音频。

3. FFmpeg（采集音频必须，启动脚本会自动安装）

启动脚本 start_windows.bat 会自动尝试安装 FFmpeg（winget 或 imageio-ffmpeg），无需手动操作。如自动安装失败，请手动安装：

winget install Gyan.FFmpeg

或从 https://www.gyan.dev/ffmpeg/builds/ 下载，将 ffmpeg.exe 放到 toolsffmpeg 目录。

4. 阿里云 ASR 密钥（语音识别必须）

1. 阿里云控制台开通「智能语音交互」服务
2. 创建项目，获取 AppKey
3. 创建 AccessKey（需 AliyunNLSFullAccess 权限）
4. 编辑 scripts/config.yaml，填入你的密钥：

aliyun_asr:
  enabled: true
  app_key: "你的AppKey"
  access_key_id: "你的AccessKeyId"
  access_key_secret: "你的AccessKeySecret"

也可以通过大屏管理后台（右上角齿轮）在线配置。

系统架构

live-script-monitor-win/
├── start_windows.bat         # ← 一键启动脚本 (双击运行)
├── check_env.bat             # 环境检查脚本 (只检查不安装)
├── assets/dashboard/         # 大屏前端 (Vue.js 3 SPA)
│   ├── index.html           # 主页面 (含弹窗管理后台)
│   └── vue.global.prod.js   # Vue 本地文件 (不依赖 CDN)
├── scripts/                  # Python 后端
│   ├── main.py              # 主入口 (LiveMonitorApp)
│   ├── config.yaml          # 配置文件 (含场景/规则/ASR密钥)
│   ├── audio_capture.py     # 音频采集 (跨平台: BlackHole/VB-Cable/WASAPI)
│   ├── asr_base.py          # ASR 抽象基类 + 工厂方法
│   ├── asr_aliyun.py        # 阿里云 ASR 驱动 (WebSocket + httpx Token)
│   ├── asr_iflytek.py       # (预留) 科大讯飞 ASR 驱动
│   ├── asr_tencent.py       # (预留) 腾讯云 ASR 驱动
│   ├── asr_baidu.py         # (预留) 百度 ASR 驱动
│   ├── rule_engine.py       # 规则引擎 (关键词检测/场景切换/告警)
│   ├── dashboard_server.py  # HTTP+WS 大屏服务 (FastAPI+Uvicorn)
│   ├── setup_env.py         # 环境检查脚本 (Python 版)
│   ├── test_local.py        # 本地测试脚本 (无需 ASR/音频)
│   ├── requirements.txt     # Python 依赖
│   └── .venv/               # Python 虚拟环境 (start_windows.bat 自动创建)
├── tools/                    # FFmpeg 存放目录 (自动下载)
│   └── ffmpeg/
│       └── ffmpeg.exe       # (启动脚本自动安装)
├── recordings/               # 录制输出目录
├── logs/                     # 日志目录
└── references/               # 参考文档

数据流

系统音频 ──→ VB-Cable 虚拟声卡 ──→ FFmpeg(dshow)
  ──→ PCM s16le 16kHz mono ──→ AudioCapture._emit_audio()
  ──→ ASR.send_audio() ──→ 阿里云 NLS WebSocket
  ──→ TranscriptionResultChanged(中间结果) ──→ 大屏流式显示 + 规则引擎
  ──→ SentenceEnd(最终结果) ──→ 大屏历史记录 + 规则引擎全量检查
  ──→ 关键词命中 ──→ 场景切换 + 告警判定 ──→ 大屏推送告警

VB-Cable 虚拟声卡配置 (重点)

1. 安装 VB-Cable

1. 访问 https://vb-audio.com/Cable/
2. 下载 VBCABLE_Setup_x64.exe
3. 以管理员身份运行安装程序
4. 安装后重启电脑

2. 配置音频路由

打开 Windows 系统设置 → 声音：

1. 输出设备选「CABLE Input (VB-Audio Virtual Cable)」
   • 这样系统声音会发送到 VB-Cable 虚拟设备
2. 输入设备保持你的麦克风不变

或者使用「立体声混音」替代方案：

• 系统托盘 → 声音 → 录制 → 右键空白处 → 显示禁用设备 → 启用「立体声混音」

3. 验证

# 列出 dshow 设备，确认 CABLE Output
ffmpeg -list_devices true -f dshow -i dummy

# 测试抓 3 秒音频
ffmpeg -f dshow -i "audio=CABLE Output (VB-Audio Virtual Cable)" -f s16le -ac 1 -ar 16000 -t 3 test.raw

4. FFmpeg 命令 (Windows)

系统自动构建的命令：

ffmpeg -f dshow -i "audio=CABLE Output (VB-Audio Virtual Cable)" 
  -f s16le -acodec pcm_s16le -ac 1 -ar 16000 
  -loglevel error pipe:1

• dshow — Windows DirectShow 音频采集
• audio=CABLE Output (VB-Audio Virtual Cable) — VB-Cable 虚拟声卡完整设备名
• s16le — 16 位小端 PCM
• ac 1 — 单声道
• ar 16000 — 16kHz 采样率（阿里云 ASR 要求）

阿里云 ASR 配置

前置条件

1. 阿里云控制台开通「智能语音交互」服务
2. 创建项目，获取 AppKey
3. 创建 AccessKey（需 AliyunNLSFullAccess 权限）
4. 确认区域（默认 cn-shanghai）

config.yaml 配置

asr_provider: aliyun
aliyun_asr:
  enabled: true
  app_key: "你的AppKey"
  access_key_id: "你的AccessKeyId"
  access_key_secret: "你的AccessKeySecret"
  url: "wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1"
  params:
    format: pcm
    sample_rate: 16000
    enable_intermediate_result: true
    enable_punctuation_prediction: true
    enable_inverse_text_normalization: true

也可以通过大屏管理后台（右上角齿轮）在线配置，保存后自动重启。

Token 获取方式

使用 httpx 直接调用阿里云 CreateToken REST API，通过 HMAC-SHA1 签名鉴权。不需要安装 aliyun-python-sdk-core。

音频采集配置

config.yaml 参数

streamer:
  capture_mode: system_audio    # 推荐值
  audio:
    sample_rate: 16000          # 阿里云 ASR 要求 16kHz
    channels: 1                 # 单声道
    format: s16le               # 16位小端 PCM
    chunk_seconds: 1            # 每片 1 秒，越小延迟越低

支持的采集模式

静音检测

_emit_audio() 会采样检测非零字节比例：

• 0-1% 非零 — 可能无音频播放或路由未配好，打印 WARNING
• 正常播放时 — 非零比例通常 40-100%

注意：没有声音播放时 VB-Cable 抓到全零是正常现象，不是 Bug。

规则引擎

场景切换 (auto_keyword 模式)

config.yaml 中 app.scene_mode: auto_keyword 时启用关键词驱动场景切换：

• detect_scene_by_keywords 基于 switch_keywords 精确子串匹配
• 阈值：新场景得分 >= 1 且 > 当前场景得分即可切换

告警规则类型

告警去重：同一 scene_id + rule_type + window 组合在 5 分钟内只触发一次。

大屏与管理后台

• 大屏地址：http://localhost:9999
• 管理后台：大屏右上角齿轮图标 → 弹窗
• 保存配置后自动热重启（os.execv 原地重启）
• 前端 saveSystemConfig() 自动设 enabled: true

前端技术栈

• Vue.js 3 (本地引用 vue.global.prod.js，不依赖 CDN)
• WebSocket 实时推送
• 暖色调 UI

本地测试 (无需 ASR/音频)

cd scripts
.venvScriptspython.exe test_local.py

模拟直播话术数据，验证大屏展示和规则引擎工作正常。

故障排查

部署检查清单

1. 端口 9999 是否 LISTENING (netstat -an | findstr 9999)
2. 日志中是否有「阿里云 ASR 识别已开始」
3. 日志中是否有「已发送 N 个音频块」
4. 日志中是否有「ASR 中间结果」或「ASR 句子结束」
5. 检查 config.yaml 是否有真实密钥（非占位符）
6. 检查 capture_mode 是否为 system_audio
7. 检查 FFmpeg 是否在 PATH 中 (ffmpeg -version)

常见问题速查

更新日志

v2.2.0 (2026-06-23) — Skill 分发版

轻量化打包

• 移除 .venv（121MB）、tools/ffmpeg/ffmpeg.exe（87MB）、VBCABLE_Driver_Pack45.zip（1.3MB）
• Skill 包总大小 < 1MB
• 所有运行时依赖由 start_windows.bat 自动下载安装
• config.yaml 密钥替换为占位符，用户自行填入

Windows 适配修复

• 修复 VB-Cable dshow 设备名不完整导致 FFmpeg 退出的 Bug
• audio_capture.py 自动提取完整设备名 CABLE Output (VB-Audio Virtual Cable)
• 修复 Windows GBK 编码导致 FFmpeg 设备列表崩溃的问题

v2.1.0 (2026-06-22) — Windows 版

• 创建 start_windows.bat 一键启动脚本
• 自动检查 Python/FFmpeg/VB-Cable 环境
• 自动创建虚拟环境并安装 Python 依赖
• 支持使用国内镜像源安装依赖（网络问题自动降级）
• 适配 Windows 路径分隔符和命令语法

v2.0.0 — Mac 版基线

• 支持 macOS/Windows 跨平台音频采集
• 阿里云 ASR 实时语音转写
• 关键词检测 + 场景切换 + 告警推送
• FastAPI + WebSocket 大屏