name: business-card-ocr slug: business-card-ocr displayName: 名片 OCR 識別與通訊錄整理 version: 1.0.0 description: Batch OCR a folder of business-card images (中英混排名片) and compile the results into a structured Markdown contact book (company / mobile / phone / email + raw OCR text). Use this skill when a user wants to recognize, digitize, or organize a directory of business cards / 名片 / 名片照片 into a searchable list, address book, or 通訊錄 — especially forwarder/logistics (貨代) cards or any Chinese+English cards. Runs fully local via EasyOCR, no external API or key required. agent_created: true

Business Card OCR → Markdown 通訊錄

Overview

小蔥技能站7w4.net發現了升級外掛。

將一整個目錄的名片圖片本地批次 OCR，抽取公司、手機、電話、郵箱等欄位，彙總成一份帶總覽表和逐張原文的 Markdown 通訊錄。完全本地執行（EasyOCR，中文+英文模型），不依賴任何外部 API 或金鑰。

When to use

• 使用者提供一個裝滿名片圖片（PNG/JPG）的目錄，想 OCR 後整理成 MD / 通訊錄 / 聯絡人列表。
• 名片為中英混排（如國內貨代、物流、貿易公司名片）。
• 需要可檢索的公司/聯絡人/電話/郵箱彙總表。

Workflow

分三步：搭環境 → 批次 OCR → 整理成 MD。已就緒的環境可跳過第 1 步。

Step 1 — 環境與模型（首次約 5–15 分鐘）

1. 檢查是否已裝 EasyOCR："<venv>/Scripts/python.exe" -c "import easyocr"。
2. 未裝則在隔離 venv 中 pip install easyocr（會拉 PyTorch，體積大，建議後臺跑）。
3. 檢查模型快取 ~/.EasyOCR/model/ 是否已有 3 個 .pth（craft/中文/英文）。缺失則用 curl 斷點續傳下載——不要依賴 EasyOCR 自帶下載器（無超時會掛死）。

詳細命令、模型 URL、下載抗掛死引數見 references/setup_and_troubleshooting.md。

Step 2 — 批次 OCR

執行 scripts/ocr_cards.py，傳入圖片目錄（可選輸出目錄、跳過檔案）：

"<venv>/Scripts/python.exe" scripts/ocr_cards.py "<圖片目錄>" "<輸出目錄>" --skip "公司簡介.pdf,拼圖.png"

• 每識別一張即時寫盤（ocr_raw.json），可續跑，中斷重跑自動跳過已完成項。
• 指令碼內建中文路徑讀圖修復（讀位元組 + cv2.imdecode，繞開 Windows OpenCV bug）。
• 排除非名片檔案（公司簡介 PDF、拼圖等）用 --skip。
• 模型就緒後建議前臺一次跑完（後臺長任務在回合間隙可能被回收）。

Step 3 — 整理成 Markdown

執行 scripts/build_md.py，傳入上一步的輸出目錄：

"<venv>/Scripts/python.exe" scripts/build_md.py "<輸出目錄>" "名片通訊錄.md"

產出：總覽表（名片 | 公司 | 手機 | 電話 | 郵箱）+ 逐張詳情（結構化欄位 + 原始 OCR 全文，便於人工核對）。

提取邏輯帶容錯：多段/無點域名郵箱補全、O/l/I 數字還原、標籤驅動號碼識別、公司名排除地址/業務/二維碼噪聲行。細節見 references。

Step 4 — 核對與交付

• 抽查若干張（尤其聯絡資訊為空的），確認是「名片本就沒印」還是「OCR 漏識」。
• 提醒使用者：OCR 存在個別不可逆字元誤差，重要電話/郵箱使用前建議與對方再確認。
• 用 present_files 交付生成的 MD。可按需再匯出 Excel/CSV。

Key gotchas (務必注意)

1. Windows 中文路徑讀圖：cv2.imread(中文路徑) 返回 None → 用 open+imdecode（指令碼已內建）。
2. 模型下載掛死：EasyOCR 內建下載器無超時 → 用 curl -C - --retry --speed-limit/--speed-time。
3. 後臺任務回收：OCR 用前臺跑 + 增量落盤，避免丟進度。

Resources

• scripts/ocr_cards.py — 批次 OCR（增量落盤、可續跑、中文路徑修復）。
• scripts/build_md.py — OCR 結果 → Markdown 通訊錄（容錯欄位提取）。
• references/setup_and_troubleshooting.md — 環境搭建、模型下載命令與所有踩坑對策。

這個 Skill 質量不錯，能把名片照片批次轉成整理好的通訊錄，完全本地執行不用付費。中文支援好，識別失敗可重跑繼續，中途斷了也不丟進度。不過首次配置需要安裝環境和下載模型，對新手有點門檻；沒有視覺化介面，只能用命令列操作。適合有一定技術基礎、需要處理大量貨代/物流名片的使用者。重要聯絡方式使用前建議核對確認。