前言¶
實名認證、開戶、政務填報等流程裏，經常要把身份證照片裏的姓名、身份證號、住址等字段錄入系統。手寫或肉眼抄寫容易錯，自己對接 OCR 又要處理圖片編碼、正反面字段映射和接口鑑權。若你已經在用 Cursor、Claude Code 等支持 Skills 的 Agent，可以把「識別二代身份證」交給 SkillHub 上的企業技能 @tencent-adm/tencentcloud-ocr-idcard，由 Agent 按技能說明調用騰訊雲身份證識別（IDCardOCR）接口。
這是什麼¶
騰訊雲身份證識別 是 SkillHub 座標 @tencent-adm/tencentcloud-ocr-idcard 的技能包，當前版本 1.0.5，來源爲 enterprise，由 騰訊雲文字識別團隊 發佈，分類爲 dev-programming。技能封裝騰訊雲 IDCardOCR 能力：從中國大陸居民二代身份證正反面圖片中提取結構化信息，並支持 Base64、URL 兩種圖片輸入方式，同時具備身份證照片裁剪與多種告警相關能力（以技能內說明爲準）。
SkillHub 頁面標註 requires_api_key=true，使用前需準備騰訊雲文字識別相關 API 密鑰，並按技能文檔完成配置。
核心功能¶
以下能力均來自 SkillHub 與官方技能頁簡介，可與騰訊雲 IDCardOCR 產品能力對應理解：
- 正反面字段提取：姓名、性別、民族、出生日期、住址、身份證號；反面含簽發機關、有效期限等。
- 兩種圖片輸入：支持圖片 Base64 與 URL 傳入識別請求。
- 圖像與質量相關能力：支持身份證圖片照片裁剪；具備多種告警功能（具體告警項以技能內文檔及騰訊雲接口返回爲準）。
安裝與啓用¶
官方技能頁寫明：安裝請參照 SkillHub 安裝與優先源配置，安裝座標 @tencent-adm/tencentcloud-ocr-idcard。
1、安裝 SkillHub CLI（若尚未安裝）¶
先檢查本機是否已有 skillhub：
command -v skillhub && skillhub --version
未安裝時，可按安裝文檔執行完整安裝（CLI + 默認 Skill）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
僅需 CLI 時：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
2、安裝技能到當前 Agent 的 skills 目錄¶
安裝文檔要求：安裝時必須用 --dir 指向當前 Agent 正在使用的 skills 目錄，否則默認會裝到 ./skills/，Agent 可能無法加載。
skillhub install @tencent-adm/tencentcloud-ocr-idcard --dir <你的 skills 目錄>
常用客戶端 skills 路徑（摘自安裝文檔，按你實際環境選擇其一）：
| 客戶端 | skills 目錄 |
|---|---|
| Cursor | ~/.cursor/skills/ |
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.codex/skills/ 或項目下的 .agents/skills/ |
| Windsurf | ~/.codeium/windsurf/skills/ 或 .windsurf/skills/ |
安裝後按所用客戶端要求重啓或刷新 Agent，使技能生效。
3、API 密鑰¶
技能標籤爲 requires_api_key=true。具體環境變量名、配置文件路徑以技能包內 SKILL.md 及騰訊雲控制台說明爲準；勿將 SecretId、SecretKey 寫入倉庫或對話日誌。
典型用法¶
技能設計目標是：當用戶需要識別身份證圖片中二代證正反面信息時，由 Agent 選用本技能並調用 IDCardOCR。
可復現的操作路徑如下（不編造未公開的接口參數名）：
- 在對話中說明要識別正面或反面，並提供圖片：本地文件（由 Agent 按技能要求轉爲 Base64）或可公網訪問的 圖片 URL。
- 確認 Agent 已加載
@tencent-adm/tencentcloud-ocr-idcard，且你已按技能文檔配置騰訊雲 API 密鑰。 - 讓 Agent 返回結構化字段（姓名、性別、民族、出生日期、住址、身份證號、簽發機關、有效期限等），並對照原圖做人工抽檢。
若需覈對字段含義或與告警碼對應關係，應查閱技能包內文檔及騰訊雲 IDCardOCR 官方 API 文檔，本文不展開未出現在 SkillHub 簡介中的請求示例。
適用場景與注意¶
適合誰
- 已在 Agent 工作流中處理證件照、需要快速抽出二代證字段的開發者。
- 希望複用騰訊雲文字識別團隊維護的企業技能，而不是從零寫 OCR 調用腳本的場景。
限制與注意
- 識別對象爲中國大陸居民二代身份證正反面；港澳臺或其他證件類型不在本技能簡介範圍內。
- 依賴騰訊雲賬號與 API 密鑰，產生調用費用與合規義務需自行評估。
- SkillHub 統計（以抓取資料爲準）：評分 100000，下載 2687，安裝 131；數據會隨時間變化，以 SkillHub 頁面爲準。
- 含個人身份信息的圖片與識別結果應遵守最小必要、加密存儲與訪問控制等要求。
結尾¶
@tencent-adm/tencentcloud-ocr-idcard 把騰訊雲 IDCardOCR 封進 Agent Skill：在需要二代證結構化字段時，用 Base64 或 URL 供圖、由技能引導完成識別與字段整理。安裝與優先源配置見 skillhub.md；技能詳情與版本見 SkillHub：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-ocr-idcard，API 入口：https://api.skillhub.cn/tencent-adm/tencentcloud-ocr-idcard。
