发票识别

SKILL.md

---
name: invoice-ocr
description: 发票识别技能。上传发票文件进行 OCR 识别，返回发票票面信息。适用于从发票图片或文件中提取结构化数据的场景。
---

# 发票识别技能

使用此技能通过上传发票文件进行 OCR 识别，自动提取发票票面结构化信息。

## 使用场景

满足以下需求时使用：

- 上传发票图片或文件（PDF/OFD/JPEG/JPG/PNG/XML）进行 OCR 识别。
- 从发票图片中提取发票号码、金额、销购方等结构化信息。
- 批量处理发票文件的自动识别。

## 触发语句示例

以下用户输入应触发此技能：

- 帮我识别这张发票 / 发票识别 / 识别发票
- 这张发票里有什么信息
- 提取发票信息 / 发票 OCR
- 读取发票内容
- 这个发票文件帮我识别一下
- 识别发票文件

## 输入参数

执行前准备以下参数：

- apiKey（必填）：通过 https://skill.quandianfapiao.com/ 申请。

### 发票识别 (ocr)

- 发票文件路径（必填，支持 PDF、OFD、JPEG、JPG、PNG、XML）

## 执行流程

**前置检查（最高优先级）：检查环境变量 `ZXT_API_KEY` 是否已设置。**

注意：当前 shell 会话可能未继承 Windows 用户级环境变量，必须按以下方式检查，不能仅依赖 `$ZXT_API_KEY`：

- Windows：执行 `powershell -Command "[System.Environment]::GetEnvironmentVariable('ZXT_API_KEY', 'User')"` 获取用户级环境变量值，同时检查 `$ZXT_API_KEY`。
- macOS/Linux：检查 `$ZXT_API_KEY` 即可。

如果以上检查结果均为空，禁止执行任何后续操作，立即向用户输出以下提示并停止：

> 您需要完成以下三步，即可自动配置并执行技能：
>
> 1. **注册账号**
>    访问中兴通简税Skill平台：https://skill.quandianfapiao.com/ 完成注册。
>
> 2. **申请 apiKey**
>    登录后进入"技能中心"，复制您的 apiKey。
>
> 3. **提供 apiKey**
>    将复制的 apiKey 发送给我，我将为您完成配置并立即执行技能。

**严格限制：前置检查未通过时，禁止执行任何其他动作，包括但不限于：**

- 禁止读取文件（Excel、PDF、图片等）
- 禁止调用任何 API
- 禁止执行任何脚本或命令
- 禁止进行参数解析或预处理

**只允许输出提示信息，然后停止，等待用户提供 apiKey。**

用户提供 apiKey 后，写入系统环境变量并使当前会话生效：

- Windows：`setx ZXT_API_KEY <apiKey>` 写入用户级环境变量，然后执行 `export ZXT_API_KEY=<apiKey>` 使当前会话生效。
- macOS/Linux：将 `export ZXT_API_KEY=<apiKey>` 追加到 `~/.bashrc` 或 `~/.zshrc`（根据用户使用的 shell），同时执行 `export ZXT_API_KEY=<apiKey>` 使当前会话生效。

环境变量就绪后，继续以下步骤：

1. 校验必填参数存在且非空。**任何必填参数缺失时必须立即停止，禁止跳过或使用空值继续执行。**
   - 缺少发票文件路径：停止并提示用户提供文件。
   - 文件不存在或不支持该文件类型：停止并提示用户。
2. 通过 python 执行脚本调用远程 API（Windows 下使用 `python`，macOS/Linux 使用 `python3`），脚本优先使用 `--api-key` 参数，未传则回退读取环境变量 `ZXT_API_KEY`。
3. 检查返回的 status 字段，非 200 时停止并将错误信息展示给用户，禁止重试或忽略。
4. 解析返回结果并以可读格式输出。

## 请求参数说明

### 发票识别 — POST /api/jxplus/zxtSkill/discern/invoiceDiscern

请求头：`Content-Type: multipart/form-data`

| 参数   | 类型   | 必填 | 说明                             |
| ------ | ------ | ---- | -------------------------------- |
| apiKey | string | 是   | apiKey                           |
| file   | file   | 是   | 发票文件（pdf/ofd/jpeg/jpg/png/xml） |

## 返回说明

### 外层返回字段

| 字段    | 类型   | 说明                 |
| ------- | ------ | -------------------- |
| status  | string | 返回接口状态码       |
| message | string | 返回接口状态描述信息 |
| data    | object | 业务数据体           |

### data 业务数据体

| 字段           | 类型   | 说明               |
| -------------- | ------ | ------------------ |
| invoiceType    | string | 发票种类           |
| invoiceCode    | string | 发票代码           |
| invoiceNumber  | string | 发票号码           |
| invoiceDate    | string | 开票日期           |
| hjje           | string | 合计金额           |
| hjse           | string | 合计税额           |
| jshj           | string | 价税合计           |
| xsfMc          | string | 销售方名称         |
| xsfNsrsbh      | string | 销售方纳税人识别号 |
| xsfAddressTel  | string | 销售方地址、电话   |
| xsfBankAccount | string | 销售方开户行及账号 |
| gmfMc          | string | 购买方名称         |
| gmfNsrsbh      | string | 购买方税号         |
| gmfAddressTel  | string | 购买方地址、电话   |
| gmfBankAccount | string | 购买方开户行及账号 |
| payee          | string | 收款人             |
| reviewer       | string | 复核人             |
| invoicer       | string | 开票人             |
| machineNo      | string | 机器编号           |
| checkCode      | string | 校验码             |
| passwordArea   | string | 密码区             |
| remark         | string | 备注               |
| item           | List   | 发票明细列表       |
| otherInfo      | string | 其他信息           |

### item 明细数据体

| 字段           | 类型   | 说明     |
| -------------- | ------ | -------- |
| projectName    | string | 项目名称 |
| ggxh           | string | 规格型号 |
| projectUnit    | string | 单位     |
| projectCount   | string | 数量     |
| projectPriceEt | string | 单价     |
| projectJeEt    | string | 金额     |
| sl             | string | 税率     |
| se             | string | 税额     |

## 异常状态码

| 状态码 | 说明                   |
| ------ | ---------------------- |
| 400    | 请求参数错误           |
| 300    | 参数为空或格式错误     |
| 305    | 无权访问该接口         |
| 307    | 消费失败，授权余次不足 |
| 308    | 超出接口调用次数       |
| 500    | 系统异常               |

## 接口请求示例

### 发票识别 — POST /api/jxplus/zxtSkill/discern/invoiceDiscern

请求方式：`multipart/form-data`，包含 `apiKey` 字段和 `file` 文件字段。

成功返回：

```json
{
  "status": "200",
  "message": "成功",
  "data": {
    "invoiceType": "82",
    "invoiceCode": "数电票",
    "invoiceNumber": "23622000000012981281",
    "invoiceDate": "2023-10-18",
    "hjje": "34.65",
    "hjse": "0.35",
    "jshj": "35.00",
    "xsfMc": "金昌市安行征途汽车运输有限公司",
    "xsfNsrsbh": "91620302MA71XY3022",
    "xsfAddressTel": "",
    "xsfBankAccount": "",
    "gmfMc": "北京中兴通融资产管理股份有限公司",
    "gmfNsrsbh": "911101087582285868",
    "gmfAddressTel": "",
    "gmfBankAccount": "",
    "payee": null,
    "reviewer": null,
    "invoicer": "张玉芳",
    "machineNo": null,
    "checkCode": "23622000000012981281",
    "passwordArea": null,
    "remark": "车人1 00****00 2023-10-16 武威- 金川机场- 长途汽车\n价税合计（大写） 叁拾伍圆整 （小写）¥35.00\n线路：武威-金川机场日期：2023-10-1608:30\n",
    "otherInfo": null,
    "item": [
      {
        "projectName": "*运输服务*客运服务",
        "ggxh": null,
        "projectUnit": null,
        "projectCount": "34.65",
        "projectPriceEt": "1",
        "projectJeEt": "34.65",
        "sl": "1%",
        "se": "0.35"
      }
    ]
  }
}
```

异常返回：

```json
{
  "status": "400",
  "message": "文件不能为空",
  "data": ""
}
```

## 命令示例

发票识别：

```bash
python .claude/skills/invoice-ocr/invoice_ocr.py ocr --file "E:\\invoices\\test.pdf"
```