| name | invoice-verify |
| version | 1.0.0 |
| description | 发票真伪查验。通过 Python 脚本调用汇联易查验服务，支持增值税发票、全电发票、区块链发票等 17 种类型的真伪核验。当用户提供发票信息要求查验真伪时使用。 |
发票查验 (Invoice Verify)
文件地图 (File Map)
invoice-verify/
├── SKILL.md # ▶ 技能主入口（当前文件）：触发规则、工作流程、参数矩阵、输出规范
├── scripts/
│ └── verify_invoice.py # ⚙️ 核心执行脚本：构建参数 → HTTP 调用 → SSE 解析 → 格式化结果
└── references/
└── parameters.md # 📖 参数参考手册：参数定义、发票类型×必填字段矩阵、判参逻辑
文件职责说明
| 文件 | 用途 | 调用时机 |
|---|
SKILL.md | 定义触发条件、工作流程阶段、参数校验规则、输出规范和错误处理策略 | 每次技能触发时全文加载 |
scripts/verify_invoice.py | 执行实际查验调用：构建 JSON-RPC 负载 → POST → 解析 SSE → 格式化结果文本（API Key 优先级：--apikey > .apikey > HELIOS_KEY） | 阶段 1 Step 4 调用 |
references/parameters.md | 参数定义细节、发票类型代码说明和条件必填对照矩阵 | WorkBuddy 在参数校验阶段按需引用 |
Overview
对用户提供的发票信息进行真伪核验。通过 Python 脚本调用汇联易查验服务，支持查验增值税专用发票、增值税普通发票、全电发票、区块链电子发票等 17 种发票类型。
触发场景
当用户表达以下意图时使用此技能：
- "帮我查验这张发票"
- "验一下发票真伪"
- "查发票"
- "帮我验证发票是否真实"
- 提供了发票代码、发票号码、开票日期等信息要求查验
- 上传或提供了发票图片，要求核实真伪
工作流程
阶段 0：配置 API Key
此阶段为所有查验操作的前置条件，每次触发技能时必须首先执行。
0.1 检查 HELIOS_KEY 环境变量
检查当前环境中 HELIOS_KEY 变量是否已设置且非空：
echo "${HELIOS_KEY:?}" 2>/dev/null
- 如果已设置且非空 → 直接进入 阶段 1
- 如果未设置或为空 → 进入 0.2
0.2 引导用户配置 API Key
停止后续所有流程，向用户输出以下引导信息（三种方式任选其一）：
⚠️ 尚未配置汇联易 API Key，无法进行发票查验。
请选择以下任一方式配置：
方式一：环境变量（推荐）
-
登录汇联易 PC 端系统
-
进入 个人设置 → MCP 服务
-
复制您的个人 API Key
-
在终端执行：
export HELIOS_KEY=您复制的API密钥
方式二：.apikey 文件
在 scripts/ 上级目录创建 .apikey 文件，写入 API Key：
echo "您复制的API密钥" > skills/invoice-verify/.apikey
方式三：命令行参数
使用 Python 脚本时通过 --apikey 参数传入：
python scripts/verify_invoice.py --apikey YOUR_KEY --invoiceTypeNo ... --invoiceNo ... --billingDate ...
设置完成后，重新发起查验请求即可。
⚠️ 注意：请使用您自己的 API Key，不要借用他人的 Key。
等待用户确认已完成配置后，再重新进入阶段 0.1 检查。
阶段 1：收集发票信息
按以下顺序执行，每步完成后才能进入下一步：
1. 提取发票信息
先查看用户当前提供的信息（文本、图片均可）：
- 如果用户上传了发票图片 → 使用 Read 工具读取图片，从中提取发票类型、发票号码、开票日期、发票代码、金额、校验码等关键信息
- 如果用户上传了 PDF → 使用 PDF 读取工具提取发票类型、发票号码、开票日期、发票代码、金额、校验码等关键信息
- 如果用户直接提供了文本 → 直接解析文本中的发票信息
- 如果用户信息不完整 → 仅向用户索要缺少的参数，不强求一次性提供所有参数
2. 判断发票类型
按以下顺序执行：
2.1 先判断发票类型
首先根据前一步中获取到的信息初步判断发票类型；发票类型参考 parameters.md 中列出的发票类型；
2.2 检查是否支持查验
- 如果匹配到的发票类型在已支持的发票类型范围内 → 进入步骤 3
- 如果发票类型不在提供的可查验的发票类型范围内 → 直接返回"该发票类型暂不支持查验"给用户，停止后续流程，不支持的发票类型有：纸质火车票、定额发票
3. 确定必填参数组合
根据判断出的发票类型，在 参数校验规则 表格中找到对应的必填参数组合（即标记 ✅ 的列）。向用户确认这些参数是否齐全：
- 齐全 → 进入阶段 2
- 缺少某参数 → 仅询问缺少的那一项，不要重复确认已有参数
4. 执行脚本并返回结果
执行 Python 脚本进行发票查验：
python scripts/verify_invoice.py --invoiceTypeNo ... --invoiceNo ... --billingDate ... [其他条件必填参数]
脚本自动处理 API Key 读取（优先级：--apikey 参数 > .apikey 文件 > HELIOS_KEY 环境变量）。
注意：
- 数据格式校正：当脚本返回错误码时，仅可调整参数的格式（例如
2024-04-24 → 20240424），绝不能改变参数的实际值（例如不能把 2024-01-24 改为 20240124 以外的值）
- 脚本返回结果后，整理为清晰的可读信息提供给用户
阶段 2：向用户呈现结果
脚本调用返回结果后，整理为清晰的可读信息提供给用户。
查验通过 — 以表格形式展示发票基本信息：
✅ 该发票查验通过，为真实有效的发票
| 字段 | 值 |
|------|-----|
| 发票类型 | 增值税专用发票 |
| 发票号码 | 12345678 |
| 发票代码 | 3100012345 |
| 开票日期 | 2022-04-19 |
| 购买方 | XX公司 |
| 购买方税号 | 91440101MA... |
| 销售方 | YY公司 |
| 销售方税号 | 91440101MA... |
| 价税合计 | ¥1000.00 |
| 不含税金额 | ¥884.96 |
| 税额 | ¥115.04 |
| 税率 | 13% |
| 发票状态 | 正常 |
| 是否作废 | 否 |
invoiceGoods（货物/服务明细） — 单独展示在基本信息下方：
- 仅当
invoiceGoods 存在且 goodsName 不为空/空字符串时展示。
- 如果
goodsName 为空或该结构不存在，不展示整个 invoiceGoods 部分。
- 展示格式：
货物/服务明细：
| 序号 | 货物/服务名称 | 数量 | 单价 | 金额 | 税率 |
|------|-------------|------|------|------|------|
| 1 | 技术服务费 | 1 | 884.96 | 884.96 | 13% |
| 2 | 咨询费 | 2 | 500.00 | 1000.00 | 6% |
查验未通过 → ❌ 该发票查验未通过...，附结果码和错误消息
系统异常 → ⚠️ 系统异常，请稍后重试
注意：当工具返回错误码时，仅可调整参数的格式（如 2024-04-24 → 20240424），绝不能改变参数的实际值（如不能把 2024-01-24 改为 20240124 以外的值）。若格式调整后仍失败，如实告知用户错误信息，不要自行修改参数值重试。
参数校验规则
必填参数：
invoiceTypeNo — 发票类型代码invoiceNo — 发票号码billingDate — 开票日期，格式为 8 位数字如 20220419
条件必填（根据发票类型决定）：
| 发票类型 | invoiceCode | invoiceAmount | checkCode | invoiceFee | totalAmount |
|---|
| 01 增值税专用发票 | ✅ | ✅ | | | |
| 03 机动车销售统一发票 | ✅ | ✅ | | | |
| 04 增值税普通发票 | ✅ | | ✅ | | |
| 08 增值税电子专用发票 | ✅ | ✅ | | | |
| 10 增值税普通发票(卷式) | ✅ | | ✅ | | |
| 10 深圳区块链发票 | ✅ | ✅ | ✅ | | |
| 11 增值税普通发票(卷式) | ✅ | | ✅ | | |
| 14 通行费电子普票 | ✅ | | ✅ | | |
| 112 电子发票(专票) | | | | ✅ | |
| 113 电子发票(普票) | | | | ✅ | |
| CZEI013 二手车销售发票 | ✅ | | | ✅ | |
| CZEI112 铁路电子客票 | | | | ✅ | |
| CZEI113 航空行程单 | | | | |
重点备注：04 增值税普通发票，如果为"全电纸质普通发票"，需要取"全电发票号码"作为"校验码"进行入参。
输出格式参考
脚本返回结果后，按以下规则呈现：
查验通过（code 121800 / "查验成功"）
基本信息 — 以表格形式展示：
| 字段 | 值 |
|------|-----|
| 发票类型 | {type} |
| 发票号码 | {invoiceNo} |
| 发票代码 | {invoiceCode} |
| 开票日期 | {billingDate} |
| 购买方 | {title} |
| 购买方税号 | {draweeNo} |
| 销售方 | {payee} |
| 销售方税号 | {payeeNo} |
| 价税合计 | ¥{fee/100:.2f} |
| 不含税金额 | ¥{feeWithoutTax/100:.2f} |
| 税额 | ¥{tax/100:.2f} |
| 税率 | {taxRate}% |
| 发票状态 | {receiptStatus} |
| 是否作废 | {invalidStatus == 'N' ? '否' : '是'} |
invoiceGoods（货物/服务明细） — 仅在以下条件同时满足时展示：
invoiceGoods 字段存在且为数组- 数组中至少有一条记录的
goodsName 不为空/空字符串
展示格式：
货物/服务明细：
| 序号 | 货物/服务名称 | 数量 | 单价 | 金额 | 税率 |
|------|-------------|------|------|------|------|
| 1 | {goodsName} | {quantity} | {unitPrice} | {amount} | {taxRate}% |
| 2 | ... | ... | ... | ... | ... |
若 invoiceGoods 不存在，或其中所有 goodsName 均为空 → 不展示整个 invoiceGoods 部分。
查验未通过
❌ 该发票查验未通过...
结果码: {code}
消息: {message}
系统异常
⚠️ 系统异常，请稍后重试
错误处理
- HELIOS_KEY 未配置: 进入阶段 0.2 引导用户选择配置方式（环境变量 / .apikey 文件 / --apikey 参数）
- API Key 无效或过期: 提示用户重新登录汇联易获取新的 API Key，重新配置
- 网络错误: 重试或检查网络连接
- 参数错误: 根据错误提示修正参数后重试
- 服务端错误: 汇联易服务异常，稍后重试
Resources
文件结构与职责参见顶部 文件地图 章节。
| 资源 | 路径 | 说明 |
|---|
| API Key 来源 | 三种方式：HELIOS_KEY 环境变量（推荐）/ .apikey 文件 / --apikey 命令行参数 | 用户自行配置，每人使用自己的 Key |
| 参数对照矩阵 | references/parameters.md | 17 种发票类型 × 8 个参数的完整校验规则 |
