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` 变量是否已设置且非空：

```bash
echo "${HELIOS_KEY:?}" 2>/dev/null
```

- 如果已设置且非空 → 直接进入 **阶段 1**
- 如果未设置或为空 → 进入 **0.2**

#### 0.2 引导用户配置 API Key

停止后续所有流程，向用户输出以下引导信息（三种方式任选其一）：

> ⚠️ 尚未配置汇联易 API Key，无法进行发票查验。
>
> **请选择以下任一方式配置：**
>
> **方式一：环境变量（推荐）**
>
> 1. 登录**汇联易 PC 端**系统
> 2. 进入 **个人设置 → MCP 服务**
> 3. 复制您的个人 API Key
> 4. 在终端执行：
>
>    ```bash
>    export HELIOS_KEY=您复制的API密钥
>    ```
>
> **方式二：.apikey 文件**
>
> 在 `scripts/` 上级目录创建 `.apikey` 文件，写入 API Key：
>
> ```bash
> echo "您复制的API密钥" > skills/invoice-verify/.apikey
> ```
>
> **方式三：命令行参数**
>
> 使用 Python 脚本时通过 `--apikey` 参数传入：
>
> ```bash
> 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 脚本进行发票查验：

```bash
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 航空行程单 | | | | | ✅ |
| CZEI212 机动车销售发票(电子) | | | | ✅ | |
| CZEI312 通行费(电子) | | | | ✅ | |
| CZEI313 二手车销售发票(电子) | | | | ✅ | |

> **重点备注**：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 个参数的完整校验规则 |