前言¶

財稅、報銷、對賬流程裏，發票往往以拍照圖、掃描件或 PDF 形式出現。若要在程序或對話式 Agent 裏穩定拿到結構化字段（代碼、號碼、購銷方、稅額、明細行等），常見做法是手寫 SDK 調用、自己拼參數和解析返回。騰訊雲文字識別團隊把 VatInvoiceOCR（通用票據識別高級版） 封裝成 SkillHub 技能 @tencent-adm/tencentcloud-ocr-vatinvoice，讓 Agent 在「識票、抽全字段、處理 PDF」等需求下按 SKILL.md 指引調用官方接口，而不是每次從零查文檔。

下面介紹該 Skill 的定位、能力與安裝方式，並給出可復現的腳本調用示例。

這是什麼¶

騰訊雲通用票據識別（高級版） 是面向 Agent 的 OCR 調用技能，座標爲 @tencent-adm/tencentcloud-ocr-vatinvoice，當前 SkillHub 版本 1.0.3，來源 enterprise，分類 professional，由 騰訊雲文字識別團隊 發佈。頁面標註 requires_api_key=true，需配置騰訊雲 API 密鑰後方可使用。

技能封裝的是騰訊雲 OCR VatInvoiceOCR 接口：當需要識別增值稅專用發票、增值稅普通發票、增值稅電子專票、增值稅電子普票、電子發票（普通/增值稅專用）等票種的全字段信息時，應使用此技能。接口說明見 騰訊雲文檔。

SkillHub 展示數據（以頁面抓取爲準）：評分 100000，下載 2664，安裝 197。

核心功能¶

結合 SkillHub 簡介與技能包 SKILL.md（與發佈方倉庫 TencentCloud/tencentcloud-ocr-skills 中同名技能一致），已覈實能力包括：

1. 多票種全字段識別：覆蓋增值稅專用/普通、電子專票/普票、全電發票等；支持發票代碼、發票號碼、開票日期、合計金額、校驗碼、稅率、合計稅額、價稅合計、購買方/銷售方信息、明細條目等。
2. 結構化輸出：默認可輸出中文分組的 JSON（發票基本信息、購銷方、金額、人員、明細條目等）；加 --raw 可拿到 VatInvoiceInfos、Items 等原始結構。
3. PDF：通過 IsPdf 開啓 PDF 識別，可用 PdfPageNumber 指定頁碼。
4. 輸入方式：ImageUrl 與 ImageBase64 二選一；兩者同時提供時僅使用 ImageUrl。
5. 業務側約束（接口層）：編碼後不超過 10M，像素介於 20–10000px；支持 PNG/JPG/JPEG/PDF；默認請求頻率限制 10 次/秒；識別 PDF 需顯式設置 IsPdf=true。

安裝與啓用¶

1. 安裝 SkillHub CLI（若尚未安裝）¶

按 SkillHub 安裝說明 檢查或安裝：

command -v skillhub && skillhub --version

未安裝時可執行：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

2. 安裝本技能到當前 Agent 的 skills 目錄¶

安裝時必須用 --dir 指向當前客戶端識別的 skills 目錄，否則默認裝到 ./skills/ 可能不會被加載。常見路徑示例：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下的 .agents/skills/

skillhub install @tencent-adm/tencentcloud-ocr-vatinvoice --dir ~/.cursor/skills/

也可將下面提示交給 AI，由其按安裝文檔完成安裝：

請根據 https://skillhub.cn/install/skillhub.md，安裝 `@tencent-adm/tencentcloud-ocr-vatinvoice`。

3. 環境與密鑰¶

技能腳本依賴 Python 3.6+ 與 tencentcloud-sdk-python：

pip install tencentcloud-sdk-python

在環境中配置：

• TENCENTCLOUD_SECRET_ID：騰訊雲 API 密鑰 ID
• TENCENTCLOUD_SECRET_KEY：騰訊雲 API 密鑰 Key

安裝技能後，在對應 skills 目錄下可找到 SKILL.md 與 scripts/main.py，Agent 按 SKILL.md 觸發與傳參即可。

典型用法¶

在技能目錄內運行 scripts/main.py 完成識別（示例來自官方 SKILL.md）。

通過圖片 URL：

python scripts/main.py --image-url "https://example.com/invoice.jpg"

通過本地文件（自動 Base64）：

python scripts/main.py --image-base64 ./invoice.jpg

PDF 發票（需開啓 PDF 模式）：

python scripts/main.py --image-base64 ./invoice.pdf --is-pdf

指定 PDF 頁碼、輸出原始 JSON、指定地域：

python scripts/main.py --image-base64 ./invoice.pdf --is-pdf --pdf-page-number 2
python scripts/main.py --image-url "https://example.com/invoice.jpg" --raw
python scripts/main.py --image-url "https://example.com/invoice.jpg" --region ap-beijing

在 Cursor、Claude Code 等客戶端中，用戶用自然語言描述「識別這張發票並列出明細」時，Agent 應在已安裝本技能的前提下讀取 SKILL.md，再調用上述腳本或等價 SDK 邏輯。

適用場景與注意¶

適合：報銷自動化、發票臺賬入庫、對賬前字段抽取、需要明細行（貨物/服務列表）的結構化 OCR、PDF 版式發票識別。

注意：

1. 屬騰訊雲計費能力，需開通增值稅發票識別相關服務；錯誤碼中包含欠費、資源包耗盡、服務未開通等，需在控制台與賬單側排查。
2. IsPdf 默認爲 false，PDF 必須顯式 --is-pdf。
3. 圖片模糊、爲空、尺寸超限等會觸發文檔列出的 FailedOperation.* 等錯誤，應保證素材質量與大小限制。
4. 官方建議圖片存放於騰訊雲 COS，以利於下載速度與穩定性（見 SKILL.md 業務說明）。
5. 技能標籤要求 API Key，請勿將 SECRET_ID / SECRET_KEY 寫入倉庫或對話日誌。

結尾¶

@tencent-adm/tencentcloud-ocr-vatinvoice 把 VatInvoiceOCR 的票種覆蓋、字段清單、PDF 參數和腳本入口收斂進標準 Skill 形態，適合在 Agent 工作流裏做發票全字段識別。安裝與優先源配置以 SkillHub 文檔爲準；技能詳情與 API 說明見：

• SkillHub：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-ocr-vatinvoice
• 官方入口：https://api.skillhub.cn/tencent-adm/tencentcloud-ocr-vatinvoice
• 騰訊雲 VatInvoiceOCR：https://cloud.tencent.com/document/api/866/36210