自动同步: 2026-03-14 02:10

skills/kb-ocr-processor/SKILL.md

@@ -1,66 +1,146 @@
+---
+name: kb-ocr-processor
+description: 视频OCR识别 - 从视频帧中提取文字
+---
+
 # KB OCR Processor Skill
 
-**kb-ocr-processor** - Extract text from video frames using OCR.
+**kb-ocr-processor** - 从视频帧中提取文字，作为语音识别的补充或替代方案。
 
-## Features
+## 什么时候使用
 
-- **视频截帧**: 直接从视频文件截取帧图片
-- **批量处理**: 支持处理帧目录
-- **双引擎**: EasyOCR / Tesseract
-- **置信度评分**: 每帧识别结果带置信度
-- **文本合并**: 自动合并所有帧的识别结果
+- kb-workflow 步骤 4 的降级方案：当 Whisper 语音识别效果不佳时
+- 音频质量差、有背景音乐干扰、多种语言混合等情况
 
-## Commands
+## 功能
+
+- 视频截帧：直接从视频文件截取帧图片
+- 批量处理：支持处理帧目录
+- 双引擎：EasyOCR / Tesseract
+- 置信度评分：每帧识别结果带置信度
+- 文本合并：自动合并所有帧的识别结果
+
+## 命令
 
 ```bash
-# 方式1: 直接从视频截帧并OCR（推荐）
-python ocr_processor.py --video ./video.flv --output ocr.json
+# 方式1: 直接从视频截帧并 OCR（推荐）
+python3 ocr_processor.py --video ./video.mp4 --output ocr.json
 
 # 方式2: 处理已截取的帧目录
-python ocr_processor.py --input ./frames/ --output ocr.json
+python3 ocr_processor.py --input ./frames/ --output ocr.json
 
 # 指定截帧帧率（默认1帧/秒）
-python ocr_processor.py --video ./video.flv --fps 2 --output ocr.json
+python3 ocr_processor.py --video ./video.mp4 --fps 2 --output ocr.json
 
 # 同时生成合并的文本文件
-python ocr_processor.py --video ./video.flv --output ocr.json --merge
+python3 ocr_processor.py --video ./video.mp4 --output ocr.json --merge
 
 # 使用 Tesseract 引擎
-python ocr_processor.py --input ./frames/ --engine tesseract --output ocr.json
+python3 ocr_processor.py --input ./frames/ --engine tesseract --output ocr.json
 ```
 
-## Workflow 中的使用
+## 输出格式 Schema
 
-```bash
-# 步骤5: OCR处理（视频无字幕时）
-python ocr_processor.py --video ${CONTENT_VIDEO_PATH} --output ${CONTENT_DIR}/ocr.json --merge
-```
+### 必需字段
 
-## Output
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | boolean | 是否识别成功 |
+| `engine` | string | 使用的 OCR 引擎 |
+| `total_frames` | number | 处理的总帧数 |
+
+### 可选字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `results` | array | 每帧的识别结果 |
+| `merged_text` | string | 合并后的文本 |
+| `output_file` | string | 输出文件路径 |
+| `error` | string | 错误信息 |
+
+## 成功示例
 
 ```json
 {
   "success": true,
   "engine": "easyocr",
   "total_frames": 619,
+  "output_file": "content/bilibili_BV1xx411c7mD_ocr.json",
   "results": [
     {
       "source": "0001.jpg",
       "text": "字幕文字",
       "confidence": 0.95
+    },
+    {
+      "source": "0002.jpg",
+      "text": "更多字幕文字",
+      "confidence": 0.92
     }
-  ]
+  ],
+  "merged_text": "字幕文字\n更多字幕文字\n..."
 }
 ```
 
-## Installation
+## 错误示例
+
+### 视频文件不存在
+
+```json
+{
+  "success": false,
+  "error": "视频文件不存在",
+  "video": "./missing.mp4"
+}
+```
+
+### ffmpeg 未安装
+
+```json
+{
+  "success": false,
+  "error": "ffmpeg 未安装",
+  "suggestion": "请运行: sudo apt-get install ffmpeg"
+}
+```
+
+### 内存不足
+
+```json
+{
+  "success": false,
+  "error": "内存不足",
+  "suggestion": "尝试降低帧率或处理较短的片段"
+}
+```
+
+## 安装
 
 ```bash
-cp -r kb-ocr-processor/ ~/skills/
-pip install -r requirements.txt
+cp -r kb-ocr-processor/ ~/.openclaw/skills/
+pip install easyocr pytesseract Pillow
 
-# 依赖说明
-# - easyocr: 主要OCR引擎（自动下载模型）
-# - pytesseract: Tesseract引擎
-# - ffmpeg: 视频截帧（apt install ffmpeg）
+# 系统依赖
+sudo apt-get install ffmpeg tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-eng
 ```
+
+## 在 kb-workflow 中的使用
+
+```bash
+# 步骤 4 的降级方案（当 Whisper 效果不佳时）
+python3 ~/.openclaw/skills/kb-ocr-processor/ocr_processor.py \
+    --video "content/downloads/bilibili_BV1xx411c7mD.mp4" \
+    --output "content/bilibili_BV1xx411c7mD_ocr.json" \
+    --merge
+
+# 输出：
+# - bilibili_BV1xx411c7mD_ocr.json (完整结果)
+# - bilibili_BV1xx411c7mD_ocr.txt (合并文本)
+```
+
+## 注意事项
+
+- **耗时操作**：OCR 处理需要截帧和识别，可能较慢
+- **帧率选择**：1帧/秒适合大多数场景，更高帧率增加精度但耗时更长
+- **引擎选择**：EasyOCR 精度较高，Tesseract 速度较快
+- **适用场景**：音频质量差、背景音乐干扰、多语言混合时使用