القائمة
使用本地 FunASR 服务将音频或视频文件转录为带时间戳的 Markdown 文件，支持 mp4、mov、mp3、wav、m4a 等常见格式。本技能应在用户需要语音转文字、会议记录、视频字幕、播客转录时使用。
استنادا إلى تصنيف SOC المهني
| name | funasr-transcribe |
| homepage | https://github.com/cat-xierluo/legal-skills |
| author | 杨卫薪律师（微信ywxlaw） |
| version | 1.9.4 |
| license | Complete terms in LICENSE.txt |
| description | 使用本地 FunASR 服务将音频或视频文件转录为带时间戳的 Markdown 文件，支持 mp4、mov、mp3、wav、m4a 等常见格式。本技能应在用户需要语音转文字、会议记录、视频字幕、播客转录时使用。 |
本 skill 提供本地语音识别服务，将音频或视频文件转换为结构化的 Markdown 文档。
paraformer-onnx 与实验性的 SenseVoice-Small ONNX--fast / "fast": true 关闭 diarization，默认仍走 paraformerparaformer-onnx 单人/多人路径都会先 VAD 分段，再清理文本输出、恢复标点并输出句子级时间戳；单人路径使用全局标点恢复，多人路径使用逐段标点以保留 speaker 对齐| 依赖 | 安装方式 |
|---|---|
| Python 3.8+ | macOS: brew install python@3.14 |
| curl | macOS 通常自带；如缺失可执行 brew install curl |
| 包名 | 用途 | 安装命令 |
|---|---|---|
funasr | FunASR 原生推理与 CAM++ diarization | pip install -r assets/requirements.txt |
funasr-onnx | Paraformer / SenseVoice ONNX 加速 | pip install -r assets/requirements.txt |
scenedetect[opencv]、imagehash | 视频关键帧提取 | pip install -r assets/requirements.txt |
首次需要运行 ONNX 模式时，直接执行：
python3 scripts/setup.py
即可同时安装 funasr-onnx 及其依赖；SenseVoiceSmall 仅在显式指定 model=sensevoice 时按需下载。
paraformer-onnx 默认使用质量优先的参数组合；单人路径会复用多人路径的 ONNX VAD 分段 ASR，但不执行 CAM++ 说话人聚类：
| 参数 | 默认值 | 说明 |
|---|---|---|
FUNASR_ONNX_TEXT_SOURCE | preds | 使用清理后的 ONNX preds 文本；如遇到异常可设为 raw_tokens 回退 |
FUNASR_SERVER_ONNX_THREADS | 4 | ONNX Runtime 推理线程数，主要影响速度，不直接改善识别质量 |
FUNASR_ONNX_COMPAT_CACHE | ~/.cache/funasr-onnx-compat | ONNX 兼容导出缓存目录；兼容导出会复制模型目录，可删除该缓存后重新生成 |
单人 paraformer-onnx 会将各 VAD 片段的识别文本先拼接，再做一次全局标点恢复；这样比逐片段恢复标点更接近原生 paraformer，也能减少重复调用标点模型的耗时。
ONNX 句子级时间戳是根据字符位置和 token 时间戳做的近似映射，适合定位段落和发言轮次，不应视为逐字强对齐结果。
已验证不建议作为默认的调参方向：
当用户请求转录音频/视频时，应遵循以下流程，一次性完成转录和 AI 总结：
前置步骤（必须第一个执行）：设置 PATH。 某些执行环境（如 agent-executor headless 模式）的 PATH 被限制为只有插件目录，curl、python3 等系统命令找不到。必须先执行：
export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
之后所有 bash 命令都必须在同一命令块中跟在
export PATH=...后面，或在每个命令块开头都加上这行。
在执行转录前，检查 assets/skill-env.json 是否存在。如果不存在，先运行环境检测：
export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && cd <skill目录> && python3 scripts/init_env.py
如果检测失败（退出码非0），按提示运行安装脚本：
export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && cd <skill目录> && python3 scripts/setup.py
安装完成后会自动重新检测并生成 skill-env.json。
export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && curl -s http://127.0.0.1:8765/health
如果服务未运行，后台启动：
export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && cd <skill目录> && python3 scripts/server.py --idle-timeout 600 &
等待服务就绪（轮询 /health 直到返回 200）。
export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && curl -s -X POST http://127.0.0.1:8765/transcribe \
-H "Content-Type: application/json" \
-d '{"file_path": "/path/to/audio.aac"}'
注意：
diarize默认为true，无需显式传入。如需禁用，传"diarize": false。 视频文件（mp4、mov 等）会自动启用关键帧截图提取（extract_slides），无需手动传入。如需禁用，显式传"extract_slides": false。 单人讲课/语音可传"fast": true关闭说话人分离，默认仍使用paraformer；"model": "sensevoice"仅作为实验性显式选项。
响应中包含以下关键字段：
output_path: 转录输出的 Markdown 文件路径text: 转录全文summary_prompt: AI 总结提示词（已自动附带，无需额外调用 /summary）text_preview: 转录文本前 500 字预览根据 summary_prompt（或直接根据 text 内容），Agent 生成结构化 JSON 总结：
{
"full_summary": "至少400字，分成2-3段，交代背景、问题、关键事实、数据、风险与行动建议",
"speaker_summary": [
{
"speaker_order": "发言人1",
"speaker_name": "如能识别请写姓名，否则写未知",
"summary": "至少180字，涵盖该发言人的观点、依据、数据、态度与潜在影响"
}
],
"highlights": ["6-10条重点，每条60-100字"],
"keywords": ["5-8个关键词"]
}
重要：不要只描述注入操作，必须实际执行以下命令。
将步骤 3 生成的 JSON 写入临时文件，然后调用脚本注入（比 curl 注入更可靠，无需 JSON 转义）：
export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && cat > /tmp/summary_<文件名>.json << 'JSONEOF'
{步骤3生成的JSON内容}
JSONEOF
python3 <skill目录>/scripts/summary.py inject "<output_path>" /tmp/summary_<文件名>.json
脚本会自动：
<!-- AI-SUMMARY:START --> / <!-- AI-SUMMARY:END --> 标记注入后必须执行验证，确认摘要确实写入文件。如果验证失败，必须重试步骤 4。
export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && python3 <skill目录>/scripts/summary.py verify "<output_path>"
✅ 摘要已存在 → 成功，向用户报告完成❌ 摘要不存在 → 失败，回到步骤 4 重试用户：转录这个音频
↓
Agent：
1. 检查/启动服务
2. POST /transcribe {"file_path": "xxx.aac"} ← 一次调用拿到转录+提示词
3. 根据转录内容直接生成总结 JSON
4. 写 JSON 到临时文件 → python3 summary.py inject 注入
5. python3 summary.py verify 验证 → 失败则重试步骤 4
↓
用户：收到带 AI 总结的 Markdown 文件
重要：首次使用前必须先检测环境是否满足要求。
运行环境检测：
python3 scripts/check_env.py
检测脚本会检查以下环境要求：
| 必需项 | 要求 | 检测命令 |
|---|---|---|
| Python | >= 3.8，python3 命令可用 | python3 --version |
| curl | HTTP 客户端（用于 API 调用） | curl --version |
| 基本命令 | ls, ps, grep | shell 内置 |
如果环境检测失败：
Python3 命令不可用：
# macOS 使用 homebrew 安装 Python
brew install python@3.14
curl 不可用：
# macOS 确保 curl 已安装
brew install curl
验证环境修复后，重新运行检测：
python3 scripts/check_env.py
运行安装脚本完成环境配置：
python3 scripts/setup.py
安装脚本会自动：
~/.cache/modelscope/hub/models/验证安装状态：
python3 scripts/setup.py --verify
python3 scripts/server.py
如需默认开启 ONNX 加速与 INT8 量化，使用：
python3 scripts/server-onnx.py --preload
服务默认运行在 http://127.0.0.1:8765
智能特性：
--idle-timeout 参数自定义空闲超时时间（秒）服务生命周期：
重要提示：
Ctrl+C 或等待 10 分钟空闲超时示例：自定义 30 分钟空闲超时
python3 scripts/server.py --idle-timeout 1800
使用客户端脚本转录文件：
# 转录单个文件
python3 scripts/transcribe.py /path/to/audio.mp3
# 指定输出路径
python3 scripts/transcribe.py /path/to/video.mp4 -o transcript.md
# 启用说话人分离
python3 scripts/transcribe.py /path/to/meeting.m4a --diarize
# Paraformer ONNX（更快；默认仍支持 diarization）
python3 scripts/transcribe.py /path/to/meeting.m4a --model paraformer-onnx
# Paraformer ONNX 单人路径（VAD 分段 ASR，不做说话人聚类）
python3 scripts/transcribe.py /path/to/course.m4a --model paraformer-onnx --no-diarize
# 单人讲课快速模式（关闭说话人分离，保留默认 Paraformer）
python3 scripts/transcribe.py /path/to/course.m4a --fast
# 批量转录目录
python3 scripts/transcribe.py /path/to/media_folder/
# 提取视频关键帧截图（PPT幻灯片）
python3 scripts/transcribe.py /path/to/video.mp4 --slides
# 自定义场景检测阈值（值越低越灵敏，默认20.0）
python3 scripts/transcribe.py /path/to/video.mp4 --slides --slide-threshold 15.0
转录完成后，可以生成 AI 智能总结，充分利用 Claude Code 的原生 AI 能力。
自动模式（推荐）：
使用 --auto-summary 参数，转录完成后自动生成并注入总结：
# 转录并自动生成总结（Claude Code 原生环境，无需配置 API Key）
python3 scripts/transcribe.py /path/to/audio.m4a --auto-summary
# 完整流程：说话人分离 + 自动总结
python3 scripts/transcribe.py /path/to/meeting.m4a --diarize --auto-summary
工作原理：
AI_SUMMARY_REQUEST）手动模式：
# 转录单个文件（输出提示词供手动调用）
python3 scripts/transcribe.py /path/to/audio.mp3
# 禁用自动总结（只输出提示词）
python3 scripts/transcribe.py /path/to/audio.m4a --no-summary
总结内容结构：
提示词特点：
详细文档请查看：<references/api-reference.md>
检查服务状态：
curl http://127.0.0.1:8765/health
使用 curl 直接调用 API：
curl -X POST http://127.0.0.1:8765/transcribe \
-H "Content-Type: application/json" \
-d '{"file_path": "/path/to/audio.mp3"}'
# 单人快速模式（关闭说话人分离，保留默认 Paraformer）
curl -X POST http://127.0.0.1:8765/transcribe \
-H "Content-Type: application/json" \
-d '{"file_path": "/path/to/course.m4a", "fast": true}'
# 指定 Paraformer ONNX（默认启用 diarization）
curl -X POST http://127.0.0.1:8765/transcribe \
-H "Content-Type: application/json" \
-d '{"file_path": "/path/to/meeting.m4a", "model": "paraformer-onnx"}'
# Paraformer ONNX 单人路径（VAD 分段 ASR，不做说话人聚类）
curl -X POST http://127.0.0.1:8765/transcribe \
-H "Content-Type: application/json" \
-d '{"file_path": "/path/to/course.m4a", "model": "paraformer-onnx", "diarize": false}'
# 提取视频关键帧截图
curl -X POST http://127.0.0.1:8765/transcribe \
-H "Content-Type: application/json" \
-d '{"file_path": "/path/to/video.mp4", "extract_slides": true}'
API 文档（Swagger UI）：
FastAPI 自动生成交互式 API 文档，访问：http://127.0.0.1:8765/docs
可在此页面中：
响应示例（健康检查）：
{
"status": "ok",
"service": "FunASR Transcribe",
"uptime": 300,
"idle_time": 120
}
返回字段说明：
uptime：服务运行时间（秒）idle_time：当前空闲时间（秒）详细的 API 参考文档请查看：<references/api-reference.md>
包含：
| 脚本 | 用途 |
|---|---|
scripts/init_env.py | 环境检测 + 生成 skill-env.json |
scripts/check_env.py | 环境检测（简化版） |
scripts/setup.py | 一键安装依赖和下载模型 |
scripts/server.py | 启动 HTTP API 服务 |
scripts/server-onnx.py | 启动默认 ONNX 加速服务 |
scripts/transcribe.py | 命令行客户端 |
scripts/auto_transcribe.py | 自动化转录脚本（推荐） |
本 skill 支持在任意 Agent 平台中自动完成转录 + 总结全流程。
# 自动转录 + 获取总结提示词（说话人分离默认启用）
python3 scripts/auto_transcribe.py /path/to/audio.aac
# 禁用说话人分离
python3 scripts/auto_transcribe.py /path/to/audio.aac --no-diarize
# 单人快速模式（关闭说话人分离，保留默认 Paraformer）
python3 scripts/auto_transcribe.py /path/to/course.m4a --fast
# 只获取总结提示词，不生成总结
python3 scripts/auto_transcribe.py /path/to/audio.aac --prompt-only
curl -X POST http://127.0.0.1:8765/transcribe \
-H "Content-Type: application/json" \
-d '{"file_path": "/path/to/audio.aac"}'
响应中包含 summary_prompt 字段，可直接用于生成总结，无需额外调用 /summary。
生成总结后，调用：
curl -X POST http://127.0.0.1:8765/inject_summary \
-H "Content-Type: application/json" \
-d '{
"md_path": "/path/to/audio.md",
"summary_content": "## AI 摘要\n\n### 全文总结\n...\n\n### 重点内容\n- ...\n\n### 关键词\n..."
}'
| 端点 | 方法 | 功能 |
|---|---|---|
/health | GET | 健康检查 |
/transcribe | POST | 转录音频/视频 |
/batch_transcribe | POST | 批量转录目录 |
/summary | POST | 生成 AI 总结提示词 |
/inject_summary | POST | 将总结注入 Markdown 文件 |
/verify_summary | POST | 验证摘要是否已注入 |
| 文件 | 说明 |
|---|---|
assets/models.json | ASR 模型配置清单 |
assets/requirements.txt | Python 依赖清单 |
转录结果保存为 Markdown 文件，包含：
发言人N HH:MM:SS 换行 内容示例格式（视频含截图）：
# 转录：视频.mp4
## 转录内容
发言人1 00:02:49
各位好，今天我们来讲...
发言人1 00:03:30
这是第二段的内容...
模型存储在 ModelScope 默认缓存目录 ~/.cache/modelscope/hub/models/：
正确顺序：FunASR（优先）→ Whisper CLI（fallback）
python3 scripts/setup.py --verify 检查 funasr-onnx 是否可用process_log 查看 proc_<session_id># 提取音频（16kHz 单声道）
ffmpeg -i "/path/to/video.mp4" -vn -acodec pcm_s16le -ar 16000 -ac 1 -y "/tmp/audio.wav"
# Whisper 转录（tiny 模型最快，medium 质量更好）
/opt/homebrew/bin/whisper "/tmp/audio.wav" \
--model tiny \
--language Chinese \
--output_dir /tmp/transcript \
--output_format all
性能参考：19 分钟音频，tiny 模型约 3-5 分钟（Mac CPU）。
症状：POST /transcribe 返回 {"detail":"No module named 'cv2'"}，但 pip show opencv-python-headless 显示已安装。
根因：服务进程使用的 Python 环境与 pip 安装目标不同。常见于 macOS Homebrew Python 3.14 环境，pip 安装到了系统 site-packages，但服务进程加载的是 Homebrew 路径。
排查步骤：
python3 -c "import cv2; print('ok')"python3 -m pip install opencv-python-headless --break-system-packageslsof -p <server_pid> | grep python正确启动流程：
# 确认 cv2 可用后再启动服务
python3 -c "import cv2; print('cv2 ok')"
# 如服务已在运行，先杀掉再重启
lsof -ti:8765 | xargs kill -9 2>/dev/null; sleep 1
# 重启服务
python3 scripts/server.py --idle-timeout 600 &
症状：Address already in use（Errno 48）
# 杀掉占用端口的进程
lsof -ti:8765 | xargs kill -9 2>/dev/null
sleep 1
首次转录需要下载模型（约 1-2GB），耐心等待。后续请求模型已缓存，速度会快很多。
视频截图功能：
视频文件（mp4、mov、avi、mkv、wmv、webm）转录时会自动启用关键帧提取。
依赖 scenedetect[opencv] 和 imagehash 已包含在 requirements.txt 中，setup.py 安装时会一并安装。
如未安装这些依赖，服务端会输出提示但不影响普通转录功能。
服务启动失败时，运行验证命令检查安装状态：
python3 scripts/setup.py --verify
重新下载模型：
python3 scripts/setup.py --skip-deps
基于现有文章、专栏、课程讲稿、逐字稿、访谈、课件、会议纪要、案例材料、PDF 文本、Word 文档和笔记等内容资产，判断它们最适合转化为书、小册子、课程、系列文章、实务手册或知识库，并输出精简策划意见；用户提到“把现有内容整理成书”“判断素材适合做书还是课程”“把文章/直播稿/课程稿/笔记重组成知识产品”等场景时，应使用本技能。
Git 工作流安全助手。本技能应在需要执行分支管理、Monorepo 安全合并、PR 创建/审查/合并、冲突处理、cherry-pick、安全回退，以及 stale/已合并分支审计与清理（branch cleanup，含 squash/rebase merge 校验）时使用。不要用于：批量生成提交信息、项目任务分配、长期任务状态管理或本地多 Agent 会话编排。
本技能应在用户需要 OCR、扫描识别、图片文字识别、文档识别，或将 PDF、图片、Office 文档、URL 转换为 Markdown 时使用。检测到法律材料时可进行保守的法律术语与文书结构优化。不要用于法律事实判断、补写缺失内容、语义改写、印章深度识别或图表实体分析。
Skill 质量验收与格式审查工具，也可称 Skilllint。本技能应在用户需要审查 Claude Code Skill 的目录结构、Frontmatter、引用一致性、发布版本、业务流深度、可评估性和安全风险时使用。不要用于：创建新技能、代码审查、应用功能测试、通用编程任务。
转录稿纠错与轻度优化。本技能应在用户需要按用户词典纠正 ASR 转录稿同音字与英文专有名称漂移时使用。不要用于：重写为课程章节、报告、总结，或完全空白的素材创作。
元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。