翔云银行卡 OCR 识别

Overview

通过调用翔云开放平台银行卡识别 API（typeId=17），对图片中的银行卡进行结构化解析，支持横版、竖版、异型银行卡及平面/凸面字体。识别字段包括：卡号、卡类型、卡名称、银行名称、银行编号。

API 文档参考： https://www.netocr.com/bankCard.html

触发词

以下用户表述均应触发本 Skill：

• "识别银行卡"、"银行卡识别"
• "识别卡号"、"解析银行卡"
• "bankcard OCR"、"bank card 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/bankcard.jpg

# Base64 方式
python scripts/recognize.py --base64 "BASE64_STRING_HERE"

# 表格形式输出（人类可读）
python scripts/recognize.py --file /path/to/bankcard.jpg --output-format table

# 禁止自动保存（默认自动保存为 {图片名}.json）
python scripts/recognize.py --file /path/to/bankcard.jpg --no-save

识别成功后，会自动将结果保存为 {图片名}.json 到图片同级目录，避免后续导出时重复调用 API。

API 参数说明：

| 参数 | 值 | 说明 |

|------|----|------|

| typeId | 17 | 银行卡识别固定值，不可更改 |

| 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：格式化输出结果

识别成功后，以表格形式展示结果：

✅ 银行卡识别成功

| 字段       | 识别结果         |
|------------|-----------------|
| 卡号       | 6222 **** **** 1234 |
| 卡类型     | 储蓄卡           |
| 卡名称     | XX 银行储蓄卡    |
| 银行名称   | 中国工商银行     |
| 银行编号   | ICBC             |

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 bankcard.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

错误处理

| 错误码 | 含义 | 处理方式 |

|--------|------|----------|

| 10001 | 认证失败 | 提示用户检查 key/secret，重新配置 |

| 10002 | 余额不足 | 提示用户充值翔云账户 |

| 10003 | 图片格式错误 | 提示支持 JPG/PNG/BMP，建议压缩至 200KB 以内 |

| 10004 | 图片过大 | 提示压缩图片至 3MB 以内 |

| 其他 | API 异常 | 显示原始错误信息，建议稍后重试 |

认证失败时，提示用户可以重新配置：

python scripts/config_manager.py reset

图片要求

| 类型 | 建议规格 |

|------|---------|

| 普通图片 | 大小约 200KB，位深度 24 以上 |

| 扫描图像 | 分辨率 300DPI，文件小于 3MB |

| 格式 | JPG、PNG、BMP |

注意事项

• typeId 固定为 17，调用时不可修改
• 配置文件 config.json 存放在本 skill 目录下，包含敏感信息，请勿提交至代码仓库
• 每次执行前优先读取 config.json，避免重复询问用户凭证
• 文件导出功能仅在用户明确要求时触发，不自动导出
• 本 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]