name: "smart-ocr" description: "Perform OCR on image-based documents with multi-strategy Tesseract recognition + DeepSeek AI validation and correction. Invoke when user needs to extract text from scanned books, document screenshots, or image-heavy files."

Smart OCR: AI-Assisted Image-to-Text Recognition

A three-layer OCR pipeline that combines Tesseract multi-strategy recognition with DeepSeek AI validation and correction for high-accuracy text extraction from images.

When to Invoke

• User uploads a .doc / .docx / .pdf file containing mostly images (scanned pages)
• User asks to "extract text from images," "OCR these pictures," or "convert image to text"
• User needs accurate Chinese+English bilingual OCR from document images
• User complains about garbled OCR results and needs better quality

Architecture

┌──────────────────────────────────────────────────────────┐
│  Layer 0: Mosaic Detection                               │
│  → Detect images with dense mosaic/blurred regions        │
│  → If valid Chinese char density < 5%, skip OCR entirely  │
│  → Mark image as "(含馬賽克區域，已跳過識別)"              │
├──────────────────────────────────────────────────────────┤
│  Layer 1: Multi-Strategy Tesseract OCR                   │
│  (Original / Gray / CLAHE / 2× Upscale / Sharp)          │
│  → Auto-select best result by Chinese char count          │
│  → Apply common OCR error correction dictionary           │
├──────────────────────────────────────────────────────────┤
│  Layer 2: DeepSeek AI Validation                         │
│  → Judge if OCR text is coherent (score 0-10)            │
│  → Route based on confidence level:                       │
│    ≥ 7/10: Accept as-is, minor typo fix only             │
│    4-6/10: Request DeepSeek to correct garbled chars      │
│    < 4/10: Check if mosaic; if yes, discard; if not, raw │
├──────────────────────────────────────────────────────────┤
│  Layer 3: Results Assembly                                │
│  → Combine per-image results into structured output       │
│  → Skip mosaic-only images (output note instead)          │
│  → Generate .docx with continuous paragraphs              │
└──────────────────────────────────────────────────────────┘

Prerequisites

1. API Key Setup

This skill requires a DeepSeek API key for the AI validation layer. Each user must provide their own key.

How to get a key: Register at platform.deepseek.com and create an API key.

How to provide the key: Set it as an environment variable before running the pipeline:

$env:DEEPSEEK_API_KEY = "sk-your-own-api-key-here"

The scripts read the key at runtime from $env:DEEPSEEK_API_KEY. No key is ever hardcoded in the skill files.

• API Endpoint: https://api.deepseek.com/v1/chat/completions
• Model: deepseek-chat

  來源於7w4.net。

Note: If no API key is set, the pipeline still runs — it simply falls back to Tesseract-only OCR (Layer 1 + error dictionary), skipping the DeepSeek validation step.

2. Dependencies (Pre-installed)

Workflow (Step-by-Step)

Step 1: Prepare Images

# Pseudo-code — see scripts/ocr_pipeline.py for full implementation
1. Convert .doc → .docx (via LibreOffice: soffice --headless --convert-to docx)
2. Unpack .docx to extract /word/media/* images
3. Sort images by index (image1.png, image2.png, ...)

Step 0 (Pre-filter): Mosaic Detection

Before running OCR, detect images that contain mostly mosaic/blurred/redacted regions:

When an image is classified as mosaic-containing: - Skip the full OCR + DeepSeek pipeline for that image - Output （含馬賽克區域，已跳過識別） in the final document - The image's entry is still listed with its filename but no text content

### Step 2: Multi-Strategy OCR

For each image, run Tesseract with **5 preprocessing strategies** and auto-select the best:

| Strategy | Code | Best For |
|----------|------|----------|
| **Original** | Raw image → OCR | Clean photos, good lighting |
| **Gray** | `cv2.COLOR_BGR2GRAY` | Standard scanned pages |
| **CLAHE** | `cv2.createCLAHE(clipLimit=2.0)` | Uneven lighting, faded text |
| **2× Upscale** | `cv2.resize(..., INTER_CUBIC)` | Small text, low DPI |
| **Sharp** | `cv2.addWeighted(sharp)` | Slightly blurry edges |

**Selection criterion**: Run each strategy with `--psm 6 --oem 1` and pick the result with the highest Chinese character count.

### Step 3: Apply OCR Error Dictionary + Space Removal

After Tesseraut, apply a correction map for common Tesseract errors found in testing, then remove inter-CJK spaces:

```python
# Common Chinese char substitutions from Tesseract
ocr_corrections = {
    "睿": "特",    # 睿(ruì) vs 特(tè) — very common
    "藹": "勒",    # 形近字
    # See full list in scripts/ocr_errors.json
}

# Remove spaces between Chinese characters (Tesseract artifact)
# "等 、 博 愛 而 慶 祝" → "等、博愛而慶祝"
# English words and numbers are kept intact

Step 4: DeepSeek Validation & Correction

For each image's OCR text, call the DeepSeek API.

Validation Prompt — checks coherence:

你是一位專業的OCR校對專家。請評估以下OCR識別出的文字的通順程度。
評分標準（0-10分）：
- 8-10分：意思通順，基本無錯別字
- 5-7分：基本可讀但有個別錯別字或亂碼
- 2-4分：部分可讀但存在大量亂碼
- 0-1分：幾乎完全不可讀

注意：這是書籍/文章內容，是一段連續的論述文字。
請直接輸出分數，不需要解釋。

文字內容：
{ocr_text}

Correction Prompt — for score 4-6:

你是一位專業的OCR文字校對專家。請對以下OCR識別出的文字進行修正。
修正原則：
1. 只修改明顯錯誤的字詞（形近字、音近字）
2. 不要改變原意和句式結構
3. 保持原文的標點和段落
4. 如果遇到無法判斷的亂碼，保持原樣不要猜測
5. 專有名詞（人名、地名、書名）請根據上下文合理修正

只輸出修正後的文字，不要新增任何解釋。

待修正的文字：
{ocr_text}

Step 5: Assemble Output

Generate a .docx file with: - Each image → labeled section (▎圖片 N (filename.png)) - OCR text as a single continuous paragraph (no internal line breaks) - Separator between images

Scripts Reference

The skill includes these scripts in scripts/:

Error Handling

Known Error Patterns (from testing)

這是一個專業級的文字識別工具，能從圖片和掃描文件中準確提取文字，支援多種語言。文件提供了詳細的使用指導和實用示例，對辦公場景（如處理名片、收據等）很有幫助。質量較好，但釋出前的許可證和後設資料資訊需要核對統一。適合需要頻繁處理圖片文字提取的使用者使用。