前言¶
跨境業務、出行類應用或 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
