invoice-verify

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，无法进行发票查验。

请选择以下任一方式配置：

方式一：环境变量（推荐）

1. 登录汇联易 PC 端系统

2. 进入 个人设置 → MCP 服务

3. 复制您的个人 API Key

4. 在终端执行：

   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（货物/服务明细） — 仅在以下条件同时满足时展示：

1. invoiceGoods 字段存在且为数组
2. 数组中至少有一条记录的 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 个参数的完整校验规则