前言¶

财税、报销、对账流程里，发票往往以拍照图、扫描件或 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