证件批量OCR识别与Excel导出

概述

本技能用于批量识别证件图片/PDF/压缩包中的所有文字内容，提取结构化字段信息，并导出为Excel表格。所有单元格值均为文本格式，按证件类型分类组织。

触发场景

当用户出现以下情况时使用此技能：

上传了一张或多张证件图片（jpg/png/bmp/tiff等）
上传了包含证件的PDF文件
上传了包含图片/PDF的压缩包（zip/rar/7z）
要求识别证件上的文字内容
要求将证件信息整理成表格
要求批量提取证件信息并导出Excel

环境准备

本技能依赖以下Python环境。首次使用前需确认环境已就绪：

# 检查venv是否已创建
ls "C:/Users/Lenovo/.workbuddy/binaries/python/envs/default/Scripts/python.exe"

# 如未创建，执行以下命令：
# 1. 创建venv
C:/Users/Lenovo/.workbuddy/binaries/python/versions/3.13.12/python.exe -m venv "C:/Users/Lenovo/.workbuddy/binaries/python/envs/default"
# 2. 安装依赖
"C:/Users/Lenovo/.workbuddy/binaries/python/envs/default/Scripts/pip.exe" install openpyxl PyMuPDF Pillow

Python执行器路径（后续脚本调用均使用此路径）：

C:/Users/Lenovo/.workbuddy/binaries/python/envs/default/Scripts/python.exe

工作流程

第一步：收集输入文件

接收用户上传的文件，确定输入路径。支持的输入类型：

单张图片：.jpg, .jpeg, .png, .bmp, .tiff, .tif, .webp, .gif
单个PDF：.pdf
压缩包：.zip, .rar, .7z
文件夹路径（包含上述文件的目录）

将用户提供的文件保存到工作目录下的 input/ 子目录。

第二步：解压与提取文件

如果输入包含压缩包，或用户提供了文件夹路径，运行解压脚本提取所有图片和PDF文件：

C:/Users/Lenovo/.workbuddy/binaries/python/envs/default/Scripts/python.exe \
  "C:/Users/Lenovo/.workbuddy/skills/certificate-ocr-excel/scripts/extract_archives.py" \
  <input_path> \
  --output-dir <output_dir>

脚本输出JSON，包含 files 数组，列出所有提取出的图片和PDF文件路径。

注意：

.zip 使用Python内置 zipfile 模块直接解压
.rar 和 .7z 需要系统安装 unrar 或 7z 命令行工具。如果未安装，提示用户手动解压后再提供文件路径。

第三步：PDF转图片（仅对PDF文件）

对于PDF文件，使用 pdf_to_images.py 转换为图片，以便后续用视觉能力识别：

C:/Users/Lenovo/.workbuddy/binaries/python/envs/default/Scripts/python.exe \
  "C:/Users/Lenovo/.workbuddy/skills/certificate-ocr-excel/scripts/pdf_to_images.py" \
  <pdf_path> \
  --output-dir <image_output_dir> \
  --dpi 200

每页PDF转换为一张PNG图片。DPI 200 在清晰度和文件大小之间取得平衡。对于小字证件可提高到 300。

多页PDF处理：如果一份证件跨多页，将所有页面的识别结果合并为一个证件记录。

第四步：逐个识别证件内容（核心步骤）

使用 Read 工具逐个读取每张证件图片。Read 工具作为多模态视觉能力，可以直接"看到"图片内容并识别文字。

对每张图片执行以下操作：

读取图片：使用 Read 工具读取图片文件路径
识别证件类型：观察证件标题、布局、印章，判断证件类型
提取所有字段：按照证件类型对应的字段模板，逐个提取字段值
记录全部原文：将图片上所有可见文字按原始排列记录下来

识别要点：

参照 references/certificate_types.md 了解各证件类型的典型字段
识别优先级：先识别标题确定证件类型，再按类型提取对应字段
所有文字必须识别，包括印章文字、手写文字、条码下方文字等
字段值保持原文格式，不做推断或格式转换
日期保持原文格式（如"2020年1月1日"或"2020.01.01"）
数字类字段（身份证号、证书编号等）保持文本格式
如果图片质量差导致部分文字模糊，尽力识别并在该字段后标注"(模糊)"

第五步：构建JSON数据

将所有证件的识别结果整理为以下JSON格式，保存为 certificates.json：

{
  "certificates": [
    {
      "type": "身份证",
      "file_name": "id_card_front.jpg",
      "fields": {
        "证件类型": "身份证",
        "文件名": "id_card_front.jpg",
        "姓名": "张三",
        "性别": "男",
        "民族": "汉",
        "出生": "1990年1月1日",
        "住址": "XX省XX市XX区XX路XX号",
        "公民身份号码": "11010119900101XXXX",
        "签发机关": "XX市公安局XX分局",
        "有效期限": "2020.01.01-2040.01.01"
      },
      "raw_text": "中华人民共和国居民身份证\n姓名 张三\n性别 男 民族 汉\n出生 1990年1月1日\n住址 XX省XX市XX区XX路XX号\n公民身份号码 11010119900101XXXX\n签发机关 XX市公安局XX分局\n有效期限 2020.01.01-2040.01.01"
    }
  ]
}

字段命名规范：

"证件类型"和"文件名"为必填字段
其他字段名使用证件上的原始标题文字
对于无法归入预定义字段的文字内容，以"标题: 内容"格式添加到fields中
"raw_text"包含图片上所有识别到的文字，按原始排列顺序记录

第六步：生成Excel文件

使用 generate_excel.py 将JSON数据转换为Excel文件：

C:/Users/Lenovo/.workbuddy/binaries/python/envs/default/Scripts/python.exe \
  "C:/Users/Lenovo/.workbuddy/skills/certificate-ocr-excel/scripts/generate_excel.py" \
  certificates.json \
  证件识别结果.xlsx

生成的Excel文件包含以下工作表：

汇总表：所有证件的概览，包含序号、证件类型、文件名、姓名、证件号码、证书编号、发证日期、有效期至、颁发机构、其他信息
按类型分类表：每种证件类型一个独立工作表，包含该类型的所有字段列和原始识别文本
全部识别文本表：每行一个证件，包含证件类型、文件名和完整原始识别文本

所有单元格均为文本格式，数字和日期不会被Excel自动转换。

第七步：交付结果

将生成的Excel文件通过 present_files 展示给用户，并简要说明：

共识别了多少份证件
识别了哪些证件类型
各类型证件数量
Excel文件包含的工作表说明

批量处理优化

当证件数量较多（超过10份）时：

分批处理：每次读取5-10张图片，提取结果后继续下一批
中间保存：每批识别完成后，将结果追加到JSON文件中
进度报告：每完成一批，向用户报告进度

常见问题处理

图片质量差

模糊图片：尽力识别，无法识别的字段标注"(模糊)"
倾斜图片：识别时注意文字方向，按原始方向记录
反光/阴影：尝试识别被遮挡区域，标注"(不完整)"

压缩包无法解压

.rar/.7z：如果系统未安装unrar/7z，提示用户手动解压后提供解压后的文件夹路径
密码保护：提示用户提供密码

多证件合并

身份证正反面：如果用户分别上传了正反面图片，合并为一条记录
多页PDF证件：一个PDF可能包含多页同一证件，合并识别

资源文件

scripts/

extract_archives.py - 从压缩包/目录中提取图片和PDF文件
pdf_to_images.py - 将PDF转换为图片（使用PyMuPDF）
generate_excel.py - 从JSON数据生成Excel文件（使用openpyxl）

references/

certificate_types.md - 常见证件类型与字段参考，包含各证件类型的典型字段列表和识别注意事项