金财发票识别与查验

概述

用于发票查验、发票验真、发票核验和发票 OCR 识别。让用户直接上传发票文件，先建立输入账本，再由视觉模型或接口识别票据大类和字段，最后按接口路由查验。不要让用户手工判断票种或抄录四要素，除非识别结果缺失或存在歧义。

工作流

1. 运行 python3 scripts/cli.py check-config。
2. 若返回 configuration_required，保存当前业务命令及其参数，然后运行响应里的固定 user_interaction.argv。配置命令会启动一次性 localhost 服务并主动通过系统默认浏览器打开配置页；调用方不得再调用浏览器或执行 open，避免重复 Tab。只有明确处于无桌面环境时才可显式传 --no-browser，并把返回的 URL 交给具备本机 UI 能力的调用方打开。默认让用户填写金财数科开放平台的 App ID、App Secret 和注册时使用的纳税人识别号；不要要求用户理解或手工生成 JCSK_API_KEY。
3. 配置命令是一个最长运行十分钟的等待进程。若执行工具返回运行中的 session/process ID，每 2 秒轮询一次该进程输出；收到最终 status=saved 后立即运行 check-config 复检，并自动重放第 2 步保存的原业务命令。不要要求用户再发送“好了”“继续”或重新上传文件。
4. 若最终状态为 cancelled 或 timeout，停止原业务任务并向用户说明；不得继续轮询、猜测配置成功或使用旧凭据。
5. 首次配置或权限可能变化时运行 check-access --execute，确认 S1004/S0007/S000102/S1002 的权限和余量。
6. 多文件先建立输入账本：固定输入索引、短文件名、文件头状态和内容哈希。完全重复文件可复用一次结论，但每个文件仍必须输出独立结果。
7. 先判票据大类，再选接口。识别优先级固定为：
   • 正常路径：当前 App ID 已开通时，图片优先调用金财 S1004 OCR；OCR 返回后税务发票逐张路由到 S0007，区块链/财政票据分别路由到 S000102/S1002。
   • PDF（单页或多页，在小于 7MB 且不超过 25 页时）统一直接作为 PDF 文件送 S1004 OCR，不做本地转码；OFD/XML 不再走版式文件直解析查验接口，而是先用本地/AI 结构化识别生成清单，再进入同一逐票查验入口。
   • 备用路径：S1004 未开通、文件超出 OCR 限制、OCR 失败或字段不完整时，才使用 AI 多模态识别。栅格图片超过 7 MB 时先生成压缩副本再送 S1004，不修改原文件。AI 结果必须标记 source=ai_multimodal，经过字段和冲突检查后才能查验。

视觉识别必须读取 [references/ai-extraction.md](references/ai-extraction.md) 并使用其中提示词：税务发票进入 S0007；区块链进入 S000102；财政票据进入 S1002；其他票据返回不支持。

1. 对每个可调用项先 dry-run，检查目标接口、票种、字段种类和脱敏摘要。混合文件中某一项不支持或失败，不得阻断其他项。
2. 用户明确要求“查验”即授权本次列出的文件调用；真实调用不得扩大到其他文件。仅把 code=0000 视为成功；其他结果保留脱敏 uuid/code/msg。
3. 最终校验 results 数量等于输入文件数量，并按 [逐文件小表](references/ai-extraction.md#逐文件交付) 输出。任何文件都不得静默丢失。

python3 scripts/cli.py verify-file --file '/absolute/path/invoice.pdf'
python3 scripts/cli.py verify-file --file '/absolute/path/invoice.pdf' --execute
python3 scripts/cli.py verify-manifest --input '/absolute/path/ai-results.json'
python3 scripts/cli.py verify-manifest --input '/absolute/path/ai-results.json' --execute
python3 scripts/cli.py clear-config

clear-config 只清除当前用户持久化配置中的 JCSK_API_KEY；该值中编码的 App ID、App Secret 和纳税人识别号会一次性移除，不发起任何网络请求。可用 --env-file 指定要清除的本地 .env。

文件路由固定为：

• PDF：单页和多页均直接送 S1004 OCR；小于 7MB、最多 25 页，不做本地转码。
• OFD/XML/ZIP：不调用版式文件解析查验接口；先用本地/AI 结构化识别生成 verify-manifest 清单，再按票据类型逐票查验。识别失败时返回明确的 extract_required，不得静默丢弃。
• XML 可使用 python3 scripts/parse_jcsk_invoice_xml.py <file.xml> 提取号码、日期、购销双方、金额、税额及票据专属字段；解析结果仍需进入 verify-manifest，不能把 XML 解析结果直接当作查验成功。
• JPG/PNG/WEBP/TIF：S1004 OCR，逐票规范化后路由到 S0007/S000102/S1002；不接入批量接口。
• 已知四/五要素：使用 verify-fields，跳过 OCR。
• 大模型已识别多张文件：使用结构化清单入口，逐文件隔离调用；不支持、损坏和缺字段项也保留在结果中。

verify-manifest 接受 JSON 数组，或 {"items":[...]}。每项包含短文件名、第一层 category、具体 type_name、confidence/evidence 和目标接口所需的 fields；可选 file_path 用于本地文件头校验与 SHA-256 重复识别。输出固定包含等长 results[]，且只显示号码尾号、金额和脱敏流水信息。

票据大类、票种、字段和候选映射见 [references/invoice-routing.md](references/invoice-routing.md)。AI 提取提示词与结果表见 [references/ai-extraction.md](references/ai-extraction.md)。接口、签名、计费错误码见 [references/api-contract.md](references/api-contract.md)。

🔴 CHECKPOINT

• 配置检查：没有 API Key 或 Key 格式错误时 STOP，先打开本地配置页。不要让用户在对话里粘贴凭据。
• 候选票种：OCR 类型或关键字段缺失时 STOP；S0007 不需要传 fplx，不再做 S0001 票种候选重试。
• 先分类：未确认是税务、区块链、财政还是其他票据时 STOP。禁止先调用 S0001 再从错误码反推大类。
• 接口范围：当前主路径仅使用 S1004/S0007/S000102/S1002。
• 逐张查验：多张票据由 OCR 后逐张调用对应查验接口，不调用 S000405 批量接口。
• 能力降级：接口未开通时 STOP；多票 OCR 后逐张查验会增加调用次数，必须显式说明。
• OCR 优先级：不能在 S1004 已开通且文件符合限制时跳过金财 OCR 直接使用多模态；多模态只能作为备用，并必须披露识别来源。
• 版式文件：不调用版式文件直解析查验接口；OFD/XML/ZIP 通过“结构化识别 → verify-manifest → 逐票查验”闭环处理。
• 结果未知：网络超时或连接中断时 STOP，返回“结果可能未知”；不得无条件重发。
• 逐文件交付：单项失败只停止该项，不得抹掉或阻断其他输入；最终结果数必须与输入数一致。

失败分支

本地配置页

配置页只监听 127.0.0.1 随机端口，使用一次性 nonce，完成或十分钟超时后关闭。API Key 写入当前用户配置目录的 .env：

• Windows：%LOCALAPPDATA%/JCSK/.env
• macOS：~/Library/Application Support/JCSK/.env
• Linux：${XDG_CONFIG_HOME:-~/.config}/jcsk/.env

历史版本写入的 JCSK* 兄弟目录会被自动扫描并作为只读兼容来源，已有配置无需重新填写。

页面只让用户填写金财数科开放平台的 appid、appsecret 和注册时使用的纳税人识别号。页面保存时自动生成本地 JCSK_API_KEY，用户界面不得展示或要求用户理解该内部格式。保存后可运行 check-access --execute，通过 S001 查询各接口有效期和剩余次数。页面底部使用对称的双区服务支持带：左侧通过礼物图标和“立即获取免费试用”说明未开通用户也可申请，右侧通过微信图标集中展示潘经理、微信号 pmh2162375221 和带二维码图标的“微信二维码”按钮；鼠标悬停或键盘聚焦二维码按钮时显示二维码。浏览器视口最底部固定展示“本 Skill 服务由金财数科（北京）信息技术有限公司提供”。页面不展示客服电话，也不提供外部试用链接。二维码默认使用 scripts/wechat_qr.py 内置的 Base64 数据，不依赖 ZIP 内的 PNG；如有需要，也可通过 JCSK_WECHAT_QR_URL 或 JCSK_WECHAT_QR_PATH 覆盖。姓名和微信号可通过 JCSK_SUPPORT_CONTACT_1_NAME、JCSK_SUPPORT_CONTACT_1_WECHAT 覆盖。

配置完成信号来自正在运行的本地配置进程，不通过聊天消息触发。轮询的是本地进程状态，不是金财业务接口，因此不会产生 OCR 或查验费用。

POSIX 系统将 .env 收紧为 0600。Windows 版本写入当前用户的 %LOCALAPPDATA%，依赖该目录继承的用户 ACL；如果设备是多人共用或由域策略改写 ACL，部署方必须额外检查文件权限。

不要做什么

• 不要把 jcsk1.* 描述成加密存储；它是本地 Base64URL 凭据容器。
• 不要把 API Key、appsecret、signature、文件 Base64 或完整票面数据输出到日志、回复、截图或 Markdown。
• 不要让 Agent 代收税局账号、密码、验证码或手机号；查验不需要数电登录。
• 不要把传统火车票、传统航空行程单、财政票据、区块链票据误送 S0001。
• 不要调用未接入的 S0001、S000405、S0009。
• 不要只依据一个 OCR 类型数字强行判断票种；候选映射必须经过检查点。
• 不要自动重试计费请求，不要把 dry-run 当作真实查验，不要把 OCR 识别成功当作税局验真成功。
• 不要只汇报成功项；每个输入文件都必须有最终状态和一张简短结果表。