Metadata

name: ocr-passport-xiangyun
description: 翔云平台护照 OCR 识别 Skill。调用翔云 API (typeId=13) 对图片中的护照进行结构化识别，输出护照号码、姓名、性别、出生日期、签发日期、有效期、签发机关、国籍等字段。支持 Base64 图片流和本地文件两种方式。触发场景：用户提到护照识别、识别护照、passport OCR、解析护照或要求提取护照信息时使用。首次使用时需要引导用户配置 API 凭证（key / secret），配置持久化至 skill 目录下的 config.json。

翔云护照 OCR 识别

Overview

通过调用翔云开放平台证件识别 API（typeId=13），对图片中的护照进行结构化解析，支持中国护照及多国护照的关键字段提取。识别字段包括：护照号码、姓名、姓名拼音、性别、出生日期、出生地点、签发日期、有效期限、签发机关、国籍等。

产品介绍： 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]

ocr-passport-xiangyun

安装技能