蓝凌蓝锐锐眼识发票识别

概述

蓝凌发票识别

Overview

该 skill 作为「蓝凌发票识别」服务对外 OCR 接口（/api/v1/ocr/*）的客户端。用户在对话中上传发票/票据图片或 PDF 后，本 skill 将其提交给服务识别，并在对话中返回结构化发票字段（发票号码、价税合计、购买方/销售方、商品明细等）。

对话式使用流程（主代理执行指引）

当用户在对话中上传发票图片/PDF（或说「识别这张发票」）时，主代理按以下步骤执行：

1. 定位文件：从用户消息中拿到上传文件的本地绝对路径（图片或 PDF）。
2. 执行脚本：用 Bash 调用 scripts/ocr_client.py，把文件路径作为参数传入：

   python "C:/Users/Li/.workbuddy/skills/landray-invoice-ocr/scripts/ocr_client.py" "<用户上传文件的绝对路径>"

脚本会自动读取 auth/auth.json 获取服务地址与 Key，并用样例图做连通性验证，无需主代理额外传参。

1. 解读结果：脚本返回 JSON（result_json 已英文化）。主代理应解析后用自然语言向用户呈现关键字段，而不是直接甩原始 JSON。优先呈现：
   • 发票类型（invoice_type / invoice_type_code）
   • 发票号码（data.invoice_number）、开票日期（data.invoice_date）
   • 价税合计（data.grand_total）、合计金额/税额
   • 购买方 / 销售方（data.buyer / data.seller）
   • 商品明细（data.line_items），多票据场景看 data.invoice_items
2. 异常处理：若脚本返回 MISSING_AUTH / CONNECTIVITY_FAILED / AUTH_FAILED，按下方「缺失授权或验证失败时的对话处理」引导用户。

授权配置

授权信息按以下优先级读取（高优先级覆盖低优先级）：

1. 命令行参数：--base-url、--api-key
2. 环境变量：INVOICE_OCR_BASE_URL、INVOICE_OCR_API_KEY
3. skill 内置配置文件：auth/auth.json（字段 address、x-api-key）

服务地址与 Key 默认内置在 auth/auth.json 中，主代理通常无需传参；用户更换地址/Key 时直接编辑该文件即可。

脚本执行方式（底层工具说明）

scripts/ocr_client.py 仅依赖 Python 标准库，用任意 Python 3 运行：

# 同步识别（默认，等待完成后直接返回结构化结果）
python scripts/ocr_client.py <文件路径>

# 异步识别（提交后轮询状态直到完成）
python scripts/ocr_client.py <文件路径> --async --poll-interval 2

# 临时覆盖地址和 Key
python scripts/ocr_client.py <文件路径> --base-url http://127.0.0.1:8001 --api-key sk-xxx

• 脚本输出为 JSON（ensure_ascii=False，保留中文），HTTP 2xx 时退出码为 0。
• 真正识别前，脚本会先用 assets/sample_invoice.png 做一次连通性验证。

缺失授权或验证失败时的对话处理

脚本以结构化 JSON 报错，主代理按以下规则处理。

处理原则

1. 不预置地址选项：不要给“服务在本机 8001 端口”这类固定选项，直接引导用户填写真实地址和 Key。
2. 弹输入框收集：使用 AskUserQuestion 工具提问，问题正文明确让用户在“其他补充”输入框中填写服务地址和 X-API-Key。
3. 自动重试：拿到用户输入后，写入 auth/auth.json，并立即用 assets/sample_invoice.png 重新验证连通性；验证通过后继续识别原始发票文件。
4. 验证失败再试：如果用户输入的地址/Key 验证不通过，再次弹出输入框；用户选择取消或始终未通过验证时，提示“授权验证失败，暂无法使用蓝凌发票识别服务”。

1. 缺少授权信息（退出码 2）

脚本返回示例：

{
  "error": "MISSING_AUTH",
  "message": "缺少 X-API-Key。请在 auth/auth.json 中配置 x-api-key，或通过 --api-key / 环境变量 INVOICE_OCR_API_KEY 提供。",
  "auth_file": ".../landray-invoice-ocr/auth/auth.json"
}

主代理行动：调用 AskUserQuestion 弹出一个输入框问题：

{
  "questions": [
    {
      "question": "蓝凌发票识别服务尚未配置授权信息。请提供服务地址和 X-API-Key，可直接在下方“其他补充”输入框中填写。",
      "header": "服务授权",
      "options": [
        {"label": "填写授权", "description": "在下方输入框填写服务地址和 X-API-Key"},
        {"label": "取消", "description": "不填写，结束本次识别"}
      ]
    }
  ]
}

用户回复后：

• 选择“取消”或未提供有效信息：回复“未获取到有效的服务地址和 X-API-Key，无法继续识别。”
• 提供了地址和 Key：解析出 address 与 x-api-key，写入 auth/auth.json；然后用 assets/sample_invoice.png 调用脚本做连通性验证；验证通过后立即重新识别原始发票文件。

解析用户输入时优先按以下格式提取：

• 地址：以 http:// 或 https:// 开头的 URL。
• Key：地址之后剩余的非空文本（允许 sk- 开头或任意字符串）。

2. 连通性验证失败（退出码 3）

脚本返回示例：

{
  "error": "CONNECTIVITY_FAILED",
  "message": "无法连接发票识别服务: ...",
  "service_url": "http://127.0.0.1:8888"
}

主代理行动：提示用户当前地址无法连通（网络/防火墙/地址错误），并再次弹出 AskUserQuestion 让用户重新填写服务地址和 X-API-Key，流程同“缺少授权信息”。

3. API Key 被服务端拒绝（退出码 4）

脚本返回示例：

{
  "error": "AUTH_FAILED",
  "message": "授权验证失败（HTTP 401）: Invalid or inactive API key",
  "auth_file": ".../landray-invoice-ocr/auth/auth.json"
}

主代理行动：提示用户当前 X-API-Key 已被服务端拒绝（错误/过期/停用），并再次弹出 AskUserQuestion 让用户重新填写服务地址和 X-API-Key，流程同“缺少授权信息”。

结果解读

同步识别返回的 result_json 已经英文化（中文键已翻译），关键字段：

• invoice_type / invoice_type_code：发票类型名 / 类型编码
• data.invoice_number：发票号码
• data.grand_total：价税合计
• data.buyer / data.seller：购买方 / 销售方（对象，含 name、tax_id 等）
• data.line_items：商品明细（列表）
• data.invoice_items：多票据场景的票据列表

详细的字段映射、状态流转、错误码见 references/api_docs.md。

常见问题排查

• 退出码 2（MISSING_AUTH）：auth/auth.json 不存在或 x-api-key 缺失。
• 退出码 3（CONNECTIVITY_FAILED）：服务地址不可达、网络不通或服务端返回非认证类错误。
• 退出码 4（AUTH_FAILED）：auth/auth.json 中的 key 被服务端拒绝（401/403），需要重新输入正确的 key。
• 退出码 1：服务返回非 2xx 的业务错误。
• 400 Invalid base64 content / File too large / 不支持格式：检查文件是否合法、是否超过 20MB、后缀是否支持。

资源

• scripts/ocr_client.py：可直接执行的客户端脚本（同步 + 异步两种模式）。
• auth/auth.json：授权配置文件（address / x-api-key）。
• assets/sample_invoice.png：连通性验证用的样例图片。
• references/api_docs.md：接口契约完整参考（端点、请求/响应示例、字段翻译映射、错误码）。