前言¶
跨境业务、出行类应用或 KYC 流程里，经常要从护照扫描件或拍照里抽出结构化字段。若只在对话里让模型「看图猜字段」，准确率和可审计性都不可靠；自己接腾讯云 OCR 又要查接口文档、处理 Base64/URL、对齐 MRZ 与视读区字段。下面介绍 SkillHub 上的 @tencent-adm/tencentcloud-ocr-mlidpassport：把腾讯云 MLIDPassportOCR 能力写成标准 Skill，让 Cursor、Claude Code、Codex 等 Agent 在合适时机直接走官方 SDK 脚本。
这是什么¶
腾讯云护照识别（多国多地区） 是腾讯云文字识别团队发布的 enterprise 来源 Skill（当前版本 1.0.3，分类 ai-agent），坐标 @tencent-adm/tencentcloud-ocr-mlidpassport。它在 Skill 目录里提供 SKILL.md 说明与 scripts/main.py 调用入口，背后对应腾讯云护照识别接口 MLIDPassportOCR。
标签 requires_api_key=true：使用前需配置腾讯云 API 密钥，按量计费与账号开通状态以腾讯云控制台为准。
核心功能¶
依据 Skill 说明与上游 SKILL.md，已核实能力如下。
- 多国多地区护照：覆盖中国大陆、港澳台及其他国家/地区可机读护照，文档写明支持 80+ 国家/地区。
- MRZ 机读区：护照 ID、姓/名、出生日期、性别、有效期、发行国、国籍、国家地区代码、类型、MRZ Code 序列等。
- VRZ 信息区：证件类型、护照号码、姓名、国籍、签发/截止日期等；签名、签发地点、签发机关等字段在中国大陆护照场景下才有有效返回。
- 输入方式：
ImageBase64与ImageUrl二选一（同时提供时仅用 URL）；支持 PNG/JPG/JPEG/BMP/PDF，PDF 会取第 1 页转图识别。 - 人像裁剪：设置
RetImage=true可返回护照人像照片的 Base64。 - 质量告警（仅国际站）：复印件、翻拍、PS、反光、模糊、边框不完整等，通过
WarnCardInfos返回；国内站该数组固定为空。
Agent 侧：当用户要识别护照字段、解析 MRZ、裁剪人像或（国际站）做复印件/翻拍类检测时，Skill 描述会引导模型选用本技能。
安装与启用¶
1. 安装 SkillHub CLI（若尚未安装）¶
command -v skillhub && skillhub --version
未安装时可按 SkillHub 安装文档执行（完整安装示例）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
2. 安装本 Skill 到当前 Agent 的 skills 目录¶
安装时必须用 --dir 指向当前 Agent 实际读取的 skills 目录，否则默认落在 ./skills/ 可能不会被加载。
skillhub install tencent-adm/tencentcloud-ocr-mlidpassport --dir <你的 skills 目录>
常见路径（以 SkillHub 文档为准）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
SkillHub 页面也支持将安装提示词发给 AI，内容为：根据 https://skillhub.cn/install/skillhub.md 安装 @tencent-adm/tencentcloud-ocr-mlidpassport。
3. 运行环境与密钥¶
Skill 要求 Python 3.6+，并安装 SDK：
pip install tencentcloud-sdk-python
在环境中配置：
export TENCENTCLOUD_SECRET_ID="你的 SecretId"
export TENCENTCLOUD_SECRET_KEY="你的 SecretKey"
需在腾讯云开通文字识别相关服务；欠费、未开通或资源包耗尽会对应文档中的 ResourceUnavailable.* 等错误码。
典型用法¶
在已安装 Skill 的目录中，通过 scripts/main.py 调用接口。请求参数与 API 对齐：ImageBase64 / ImageUrl、RetImage、可选 UserAgent（文档建议固定为 Skills）。国内站与国际站通过 --region 等地域配置区分；需要告警信息时需走国际站地域（示例中使用 ap-bangkok）。
通过图片 URL 识别：
python scripts/main.py --image-url "https://example.com/passport.jpg"
识别并返回人像 Base64：
python scripts/main.py --image-url "https://example.com/passport.jpg" --ret-image
本地文件走 Base64（脚本接受文件路径）：
python scripts/main.py --image-base64 "/path/to/passport.jpg"
指定地域以使用国际站告警能力：
python scripts/main.py --image-url "https://example.com/passport.jpg" --region ap-bangkok
成功时返回 JSON，包含顶层 MRZ 相关字段、PassportRecognizeInfos 视读区结构、RequestId 等；国际站可能附带 WarnCardInfos（告警码 -9101～-9109，见 Skill 文档表）。
在 Agent 对话中，用户只需说明护照图片（URL 或本地路径）与是否需要人像或告警；模型按 SKILL.md 选择参数并执行脚本，比手写一次性 curl 更易复现。
适用场景与注意¶
适合：
- 需要在 Agent 工作流里稳定调用腾讯云护照 OCR，而不是让模型自由发挥「读图」。
- 多国护照、MRZ 校验、与后续表单/KYC 字段映射。
- 国际站场景下对复印件、翻拍、PS 等做接口级告警（需正确地域与能力开通）。
注意：
- 密钥与合规：护照属于敏感个人信息；密钥不要写入仓库，图片传输与存储需符合业务合规要求。
- 图片质量：文档建议分辨率约 500×800 以上、证件区域约占画面 2/3；URL 下载超时约 3 秒，Base64 编码后不超过 10M。
- 频率：默认接口限频 5 次/秒，批量任务需自行节流。
- 国内与国际差异：
WarnCardInfos、部分字段行为随地域变化；泰国护照另有 MRZ 与 OCR 区一致性校验逻辑。 - SkillHub 指标（抓取时点）：评分 100000，下载 1730，安装 126；以 SkillHub 页面实时数据为准。
结尾¶
@tencent-adm/tencentcloud-ocr-mlidpassport 把 MLIDPassportOCR 的字段说明、脚本入口和环境要求收敛进一份 Skill，适合已经使用腾讯云 OCR、又希望 Agent 按场景自动选工具的开发者。官方入口：
- https://api.skillhub.cn/tencent-adm/tencentcloud-ocr-mlidpassport
- https://www.skillhub.cn/skills/tencent-adm/tencentcloud-ocr-mlidpassport
接口细节与计费以腾讯云文档为准：https://cloud.tencent.com/document/api/866/37657
