前言¶
财务、报销、对账流程里，常见需求是：用户提供发票代码、号码、开票日期和金额（或校验码），系统要判断票面是否真实、状态是否仍有效，并拿到结构化票面字段。若自行对接国税查验页面或各家接口，字段规则按票种变化、批量上限和错误码处理都容易踩坑。下面介绍 SkillHub 社区 Skill「票据和发票验真」（@user_bbae3f97/qixiangyun-bill-verification-skill），把企享云票据查验能力封装成 Agent 可执行的 CLI 与约定，便于在 Cursor、Claude Code 等环境里做验真与批量查验。
这是什么¶
「票据和发票验真」是基于通用 SKILL.md 格式的 Agent Skill，当前版本为 1.0.7，在 SkillHub 上归类为 professional，来源为 community，发布者为 user_bbae3f97。
一句话定位：通过发票四要素（及按票种扩展的字段）调用企享云发票查验服务，返回全票面数据与当日最新发票状态；官方简介说明与国家税务总局全国增值税查验平台保持一致。
SkillHub 页面：https://www.skillhub.cn/skills/user_bbae3f97/qixiangyun-bill-verification-skill
技能包地址：https://api.skillhub.cn/user_bbae3f97/qixiangyun-bill-verification-skill
核心功能¶
以下能力均来自该 Skill 的 SKILL.md 与简介，已核实支持范围：
- 数电票查验：电子发票普通/专票、铁路客票、航空客票、机动车销售发票、二手车统一发票、通行费发票等。
- 增值税发票四要素查验：增值税专用/普通发票、机动车销售统一发票等。
- 全电纸质发票查验。
- 财政票据查验（见 SkillHub 简介）。
- 本地格式预检：
validate-invoice-info在正式查验前校验参数格式。 - 批量查验：通过
batch-verify或cyList多张提交，每次最多 50 张。 - 后端协议：经 MCP HTTP Streamable 调用企享云端点
https://mcp.qixiangyun.com/mcp/invoice_verification-http，对应工具包括verify_tax_control_invoice、verify_digital_invoice、verify_digital_paper_invoice。
查验成功时业务码为 code=2000；非 2000 视为失败。Skill 明确要求代理不得编造四要素，且 je、jym、jshj 按票种条件必填，不能一律当作硬必填。
安装与启用¶
安装 SkillHub CLI（若尚未安装）¶
先确认本机是否已有 skillhub：
command -v skillhub && skillhub --version
未安装时，可按 SkillHub 官方安装文档执行完整安装（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
安装本 Skill¶
安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。SkillHub 页面提示参考：https://skillhub.cn/install/skillhub.md
skillhub install @user_bbae3f97/qixiangyun-bill-verification-skill --dir <你的 Agent skills 目录>
常用目录示例（来自 SkillHub 安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
SkillHub 标签为 requires_api_key=true，使用前需配置企享云访问凭证。
凭证配置¶
统一使用完整访问凭证，格式为 QXY_API_KEY=<appkey>.<secret>。读取顺序为：进程环境 → 当前 Skill 目录下的 .env → qixiangyun-skill/.env。凭证可从企享云开放平台获取（Skill 内 .env.example 指向：https://open.qixiangyun.com/#/productRelated/aiProduct）。
示例（勿将真实密钥提交到仓库）：
# 在 Skill 目录复制 .env.example 后填写
QXY_API_KEY=your_appkey.your_appsecret
可选覆盖 MCP 基地址（默认已指向企享云）：
# QXY_MCP_BASE_URL=https://mcp.qixiangyun.com
本地单用户 Agent 首次使用可运行配置检查（托管/多租户环境应使用平台 Secret 注入，不宜走交互配置）：
cd <Skill 安装目录>/@user_bbae3f97/qixiangyun-bill-verification-skill
python3 scripts/cli.py check-config
依赖见 Skill 包内 requirements.txt，需在运行 CLI 前安装 Python 依赖。
典型用法¶
以下命令均在 Skill 根目录执行，路径以你本机 --dir 安装结果为准。
1. 预检发票信息格式¶
正式查验前先做本地格式校验：
python3 scripts/cli.py validate-invoice-info \
--invoice-type-code '发票代码' \
--invoice-number '发票号码' \
--billing-date '开票日期' \
--amount '金额，可选' \
--check-code '校验码后6位，可选'
2. 单张税控发票查验¶
单张命令至少提供 --amount 或 --check-code 之一：
python3 scripts/cli.py verify-invoice \
--invoice-type-code '发票代码' \
--invoice-number '发票号码' \
--billing-date '开票日期' \
--amount '金额，可选' \
--check-code '校验码后6位，可选'
3. 税控发票批量 / cyList¶
多张税控票使用 JSON 数组 cyList：
python3 scripts/cli.py verify-tax-control \
--cy-list '[{"fpdm":"发票代码","fphm":"发票号码","kprq":"开票日期","je":"不含税金额","jym":"校验码后6位"}]'
批量兼容命令（同样最多 50 张）：
python3 scripts/cli.py batch-verify \
--cy-list '[{"fpdm":"3200222130","fphm":"12345678","kprq":"2024-01-15","je":"100.00","jym":"123456"}]'
4. 数电票查验¶
数电票核心字段为发票号码、开票日期、价税合计 jshj：
python3 scripts/cli.py verify-digital \
--cy-list '[{"fphm":"发票号码","kprq":"开票日期","jshj":"330.00"}]'
5. 数电纸质发票查验¶
python3 scripts/cli.py verify-digital-paper \
--cy-list '[{"fpdm":"发票代码","fphm":"发票号码","kprq":"开票日期","je":"不含税金额","jym":"校验码后6位"}]'
cyList 字段速查¶
| 字段 | 说明 |
|---|---|
fpdm |
发票代码 |
fphm |
发票号码 |
kprq |
开票日期，yyyy-MM-dd 或 yyyyMMdd |
je |
不含税金额；部分专票、机动车等场景必填 |
jym |
校验码后 6 位；部分普票、卷票等场景必填 |
jshj |
价税合计；数电票查验必填 |
fpdm、fphm、kprq 为基础必填；税控与数电纸质场景下 je 与 jym 按票种二选一或条件必填，数电票走 jshj 规则。
在对话式 Agent 中，启用本 Skill 后，可由模型按用户提供的票面信息选择上述子命令，并遵守 Skill 内关于凭证配置、授权终态（如产品测试期/次数超限等 505069 文案）的用户提示规则，避免泄露密钥或原始错误堆栈。
适用场景与注意¶
适合谁
- 需要在 AI 编程或办公 Agent 中做报销初审、发票真伪核对、票面结构化落库的团队。
- 已使用或计划使用企享云开放平台 APIKEY，希望减少手写 MCP 调用与票种字段判断成本的开发者。
限制与注意
- 必须持有有效的
QXY_API_KEY；免费版测试期或生产授权用尽时，Skill 规定需返回固定用户文案并停止重试，需自行在开放平台续费或增购。 - 批量查验硬上限为每次 50 张；超过应分批。
- 旧版环境变量
QXY_CLIENT_APPKEY/QXY_CLIENT_SECRET若仍存在，Skill 要求停止调用，应迁移到完整 APIKEY 格式。 - SkillHub 统计（以抓取资料为准）：评分 100000，下载 1174，安装 4；实际体验以你方票种、授权与网络为准。
结尾¶
经过上面的步骤，你可以在 Agent 的 skills 目录安装 @user_bbae3f97/qixiangyun-bill-verification-skill，配置 QXY_API_KEY 后，用 scripts/cli.py 完成从格式预检到税控、数电、纸质及批量查验的闭环。详情与安装入口见 SkillHub：https://www.skillhub.cn/skills/user_bbae3f97/qixiangyun-bill-verification-skill ，技能包：https://api.skillhub.cn/user_bbae3f97/qixiangyun-bill-verification-skill 。
