翔云护照 OCR 识别
Overview
通过调用翔云开放平台证件识别 API，对图片中的护照进行结构化解析，支持中国护照及多国护照的关键字段提取。识别字段包括：护照号码、姓名、姓名拼音、性别、出生日期、出生地点、签发日期、有效期限、签发机关、国籍等。
产品介绍： https://www.netocr.com/products.html
触发词
以下用户表述均应触发本 Skill：
- "识别护照"、"护照识别"、"护照 OCR"
- "解析护照"、"提取护照信息"
- "passport OCR"、"passport recognition"
- "翔云护照"、"netocr 护照"
- "OCR 识别这张护照"、"护照信息提取"
- "扫描护照"、"读取护照"
执行流程
Step 1：加载配置
调用 scripts/config_manager.py 读取配置文件：
python scripts/config_manager.py load
- 配置文件路径：skill 根目录下的
config.json - 若配置文件存在且包含有效的
key和secret，直接进入 Step 3 - 若配置文件不存在或字段为空，进入 Step 2
Step 2：引导配置（首次或缺失配置时）
向用户说明：
> "请前往翔云平台（https://www.netocr.com）注册账号，在「个人中心」获取您的 ocrKey 和 ocrSecret，然后提供给我以完成配置。"
收到 key 和 secret 后：
python scripts/config_manager.py save --key YOUR_KEY --secret YOUR_SECRET
保存至 skill 根目录下的 config.json，格式如下：
{
"key": "用户的ocrKey",
"secret": "用户的ocrSecret"
}
Step 3：接收图片输入
支持以下输入方式：
| 方式 | 说明 |
|---|---|
| 本地文件路径 | 用户提供绝对或相对路径 |
| Base64 字符串 | 用户直接粘贴 Base64 编码数据 |
| URL（需转 Base64） | 先下载图片再转 Base64 |
Step 4：调用识别 API
执行识别脚本：
# 本地文件方式（推荐，识别后自动保存结果到图片同级目录）
python scripts/recognize.py --file /path/to/passport.jpg
# Base64 方式
python scripts/recognize.py --base64 "BASE64_STRING_HERE"
# 表格形式输出（人类可读）
python scripts/recognize.py --file /path/to/passport.jpg --output-format table
# 禁止自动保存（默认自动保存为 {图片名}.json）
python scripts/recognize.py --file /path/to/passport.jpg --no-save
识别成功后，会自动将结果保存为 {图片名}.json 到图片同级目录，避免后续导出时重复调用 API。
API 参数说明：
| 参数 | 值 | 说明 |
|---|---|---|
typeId |
13 |
护照识别固定值，不可更改 |
format |
json |
返回 JSON 格式 |
key |
用户凭证 | 从 config.json 加载 |
secret |
用户凭证 | 从 config.json 加载 |
Base64 接口： POST https://netocr.com/api/recogliu.do
文件上传接口： POST https://netocr.com/api/recog.do
Step 5：格式化输出结果
识别成功后，以表格形式展示结果：
✅ 护照识别成功
| 字段 | 识别结果 |
|------------|-----------------------|
| 护照号码 | E12345678 |
| 姓名 | 张三 |
| 拼音 | ZHANG SAN |
| 性别 | 男 |
| 出生日期 | 1990-01-01 |
| 出生地点 | 北京 |
| 签发日期 | 2020-06-01 |
| 有效期限 | 2030-06-01 |
| 签发机关 | 国家移民管理局 |
| 国籍 | 中国 |
Step 6：导出文件（按需触发）
仅当用户明确要求导出、保存、生成文件时才执行此步骤。
触发词示例："导出结果"、"保存为 Excel"、"生成 CSV"、"export"
优先使用 --from-dir 从已保存的识别结果 JSON 直接导出，避免浪费 API 调用次数。
# 推荐：从图片目录读取已保存的识别结果 JSON，直接导出（零 API 消耗）
python scripts/export.py --from-dir /path/to/images --format excel --output result.xlsx
python scripts/export.py --from-dir /path/to/images --format csv --output result.csv
# 管道方式（先识别再导出，适用于未缓存结果的情况）
python scripts/recognize.py --file passport.jpg | python scripts/export.py --format csv --output result.csv
# 或者指定单个 JSON 文件
python scripts/export.py --input result.json --format excel --output result.xlsx
导出优先级：--from-dir > --batch-input > --input > stdin
错误处理
| 错误码 | 含义 | 处理方式 |
|---|---|---|
-1 |
识别失败（图片质量不佳或未检测到护照） | 提示用户提供更清晰的护照图片 |
-2 |
参数错误 | 检查请求参数是否正确 |
-3 |
服务次数不足 | 提示用户登录翔云平台充值后重试 |
-4 |
认证失败 | 提示用户检查 key/secret，重新配置 |
-5 |
余额不足 | 提示用户充值翔云账户 |
CONFIG_MISSING |
凭证未配置 | 引导用户完成首次配置 |
认证失败时，提示用户可以重新配置：
python scripts/config_manager.py reset
图片要求
| 类型 | 建议规格 |
|---|---|
| 普通图片 | 大小约 200KB，位深度 24 以上 |
| 扫描图像 | 分辨率 300DPI，文件小于 3MB |
| 格式 | JPG、PNG、BMP |
- 建议护照正面平放拍摄，避免反光、遮挡
- 文字清晰可辨，对比度适中
注意事项
typeId固定为 13，调用时不可修改- 配置文件
config.json存放在本 skill 目录下，包含敏感信息，请勿提交至代码仓库 - 每次执行前优先读取 config.json，避免重复询问用户凭证
- 识别结果自动缓存为
{图片名}.json至图片同级目录，导出时直接读取，不再重复调用 API - 文件导出功能仅在用户明确要求时触发，不自动导出
- 本 skill 完全通用，不依赖任何特定宿主环境，可在任意支持 Python 3.x 的环境中运行
Resources
scripts/
config_manager.py— 配置文件的读取、写入、重置工具recognize.py— 调用翔云 API 执行护照识别export.py— 将识别结果导出为 CSV / Excel / JSON
references/
api_docs.md— 翔云护照识别 API 完整接口文档（含请求参数、响应格式、示例代码）
合作机会
公有云销售热线（服务器版OCR识别软件）：
尹经理 [13810080484] [yinhm@sinosecu.com.cn]
