name: doc-lingxi version: 1.0.0 displayName: 文件靈析 slug: doc-lingxi description: | 專業級中文文件 OCR 技能，基於百度飛槳雲 API。 支援文件解析（表格還原、公式 LaTeX、版面分析）、文字識別、批次處理和 Excel 表格匯出。 專為中文發票、身份證、合同、論文等國內辦公場景最佳化，無需本地 GPU。 This skill should be used when users need to extract text, tables, formulas from Chinese documents (invoices, contracts, academic papers, ID cards, business licenses), perform OCR on images or PDFs with Chinese content, or convert scanned documents to structured Markdown/JSON/Excel. category: 通用辦公 tags: [ocr, document-parsing, text-recognition, chinese, table-extraction, invoice, paddleocr, office-automation, excel-export] license: Apache-2.0

PaddleOCR 中文文件解析技能

專業級中文文件 OCR 技能。基於百度飛槳引擎，支援文件解析和文字識別兩大核心能力，中文場景準確率業界領先。

快速判斷：用哪個模式？

特徵判斷規則： - 有表格/公式/多欄排版 → 文件解析 (doc-parse) - 純文字截圖/簡單圖片 → 文字識別 (text-recog) - 多檔案 → 批次處理 (batch)

安裝與配置

1. 安裝依賴

python scripts/install_deps.py

可選依賴（表格匯出、PDF分頁）：

python scripts/install_deps.py --with-optional

2. 獲取 PaddleOCR API 憑證

在 paddleocr.com 註冊賬號，進入 API 頁面獲取： - API Key 和 Secret Key（用於生成 access_token） - 或直接獲取 access_token

3. 配置憑證

方法一：環境變數（推薦）

export PADDLEOCR_TOKEN="your_access_token_here"

方法二：配置檔案 (~/.paddleocr/config.json)

{
  "access_token": "your_token",
  "default_language": "ch"
}

詳見 references/api_reference.md 的 Token Management 章節。

能力一：文件解析 (Document Parsing)

完整文件理解，保留所有結構。

CLI 使用

# 基本用法 - 輸出到終端
python scripts/paddleocr_api.py doc-parse invoice.jpg

# 儲存為 Markdown 檔案
python scripts/paddleocr_api.py doc-parse report.pdf -o report.md --json-output report.json

# 中英混合文件
python scripts/paddleocr_api.py doc-parse paper.pdf --language ch_en

# 完整引數
python scripts/paddleocr_api.py doc-parse contract.pdf \
  --token "your_token" \
  --language ch \
  --format both \
  --output contract.md \
  --json-output contract.json \
  --timeout 180

Python API

from scripts.paddleocr_api import parse_document

result = parse_document(
    "invoice.jpg",
    access_token="your_token",  # 或設定 PADDLEOCR_TOKEN 環境變數
    language="ch",
    output_format="markdown"
)

if result["success"]:
    print(result["text"])          # Markdown 格式文本
    print(result["tables"])        # 提取的表格資料
    print(result["formulas"])      # LaTeX 格式公式
    print(result["layout"])        # 版面分析結果

返回結果說明

適用場景

• 發票/財務報告 → 表格完整保留
• 學術論文 → 公式以 LaTeX 輸出
• 合同/法律文件 → 條款結構保留
• 多欄排版 → 自動版面分析
• 含圖表的文件 → 圖表區域單獨標註

能力二：文字識別 (Text Recognition)

快速準確的文本提取，返回結構化 JSON。

CLI 使用

# 基本用法
python scripts/paddleocr_api.py text-recog photo.jpg

# 儲存結果
python scripts/paddleocr_api.py text-recog scan.png -o text.txt --json-output result.json

# 英文識別
python scripts/paddleocr_api.py text-recog english_doc.jpg --language en

Python API

from scripts.paddleocr_api import recognize_text

result = recognize_text(
    "screenshot.png",
    access_token="your_token",
    language="ch",
    detect_direction=True
)

if result["success"]:
    print(result["text"])           # 純文本（換行分隔）
    for word in result["words"]:    # 逐詞結果
        print(f"  [{word['bbox']}] {word['text']}")

返回結果說明

適用場景

• 截圖文字提取
• 照片/掃描件快速 OCR
• 簡單文件純文本提取
• 需要結構化 JSON 的二次開發

能力三：批次處理

# CLI 批次處理
python scripts/paddleocr_api.py batch page1.jpg page2.jpg page3.jpg --mode parse -d ./results

# 併發處理（Unix/macOS 下可用萬用字元，Windows 下請用具體檔名）
python scripts/paddleocr_api.py batch *.jpg --mode parse --workers 5

# Python API
from scripts.paddleocr_api import batch_process

results = batch_process(
    ["page1.jpg", "page2.jpg", "page3.jpg"],
    mode="parse",                    # "parse" 或 "recognize"
    output_dir="./ocr_results",      # 結果儲存目錄
    language="ch",
    max_workers=3,                   # 併發執行緒數
)

# 每個檔案生成 {filename}.parse.json 或 {filename}.recognize.json

能力四：表格匯出

將文件解析結果中的表格匯出為 Excel 或 CSV。

# 匯出為 Excel（預設），每張表一個 Sheet
python scripts/table_exporter.py result.json --format xlsx -o tables.xlsx

# 匯出為 CSV
python scripts/table_exporter.py result.json --format csv -o ./tables/

# 只匯出第1和第3張表
python scripts/table_exporter.py result.json --table-index 1 3
小蔥技能站7w4.net發現了升級外掛。

中文場景專項最佳化

針對國內常見文件型別的特殊處理，詳見 references/chinese_scenarios.md：

錯誤處理

常見錯誤

自動處理

指令碼內建以下自動處理： - RGBA → RGB 自動轉換 - 大圖自動縮放（保持寬高比） - Base64 編碼自動完成 - 臨時錯誤自動重試（預設 3 次，指數退避） - 錯誤時返回結構化錯誤資訊（success: false + error 欄位），不拋異常

參考資源

• API 詳細文件：references/api_reference.md — 完整 API 規範、引數說明、錯誤碼
• 中文場景指南：references/chinese_scenarios.md — 發票/身份證/營業執照等專項模板
• PaddleOCR 官網：https://www.paddleocr.com
• 百度 AI 開放平臺：https://ai.baidu.com/tech/ocr

與同類技能對比

這個技能質量不錯，文件寫得詳細清楚，功能覆蓋全面（文件解析、表格識別、批次處理等），對中文場景有專門最佳化。上手難度較低，錯誤提示也比較友好。主要不足是缺少一些後設資料資訊，部分功能在某些系統上可能受限。總體來說是一個成熟可用的 OCR 技能，適合需要處理中文文件的使用者。