Business Card OCR → Markdown 通讯录

Overview

将一整个目录的名片图片本地批量 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 — 环境搭建、模型下载命令与所有踩坑对策。