vietnam-invoice

越南发票验真 - 识别发票信息并通过越南税务 API 查验真伪

Security Scan

The skill appears to implement Vietnam invoice verification as described, but there are important inconsistencies and privacy risks (undeclared required credentials, image uploads to third parties, and heavy runtime dependencies) that warrant caution.

Purpose & Capability

The code (verify_vl.py + pdf_to_images.py) matches the stated purpose: it extracts invoice fields (via a VL model) and queries the Vietnam tax API. Requiring a VL API key and a captcha-solving account (CJY_USER/CJY_PASS) is coherent with that functionality. However, the skill registry metadata declares no required environment variables while the SKILL.md and code clearly require VL_API_KEY, CJY_USER, and CJY_PASS — this manifest mismatch is an incoherence.

Instruction Scope

Runtime instructions and code send full invoice images (base64 data URLs) to an external VL/model service and send captcha images to a third‑party captcha solving service (upload.chaojiying.net). The script also contacts the Vietnam tax endpoint (hoadondientu.gdt.gov.vn:30000). These operations may exfiltrate sensitive invoice data (including personal/company tax IDs) to external providers. The SKILL.md does instruct the user to set env vars, but does not explicitly warn that invoice images will be uploaded to these external services.

Install Mechanism

There is no package download or remote installer; dependencies are installed via pip and Playwright (msedge). requirements.txt lists standard PyPI packages. No arbitrary remote code downloads or obscure URLs are present in the install process.

Credentials

The code requires credentials named CJY_USER/CJY_PASS (captcha solver account) and VL_API_KEY (model API key), which are sensitive and are used to send image data to external services. While these credentials are functionally required, the registry metadata failed to declare them. Requiring a username/password (CJY) and an API key is proportional to the feature but increases privacy risk because invoice images and captcha images are transmitted off‑site.

Persistence & Privilege

The skill does not request persistent/always-on status and does not modify system-wide settings. It is user-invocable and runs only when invoked.

What to consider before installing

This skill implements the declared task, but be aware of several risks before installing/using it: - Manifest mismatch: the registry lists no required env vars, but the SKILL.md and code require VL_API_KEY, CJY_USER, and CJY_PASS. Expect to set sensitive credentials for operation. - Data leakage: the skill uploads full invoice images (base64) to an external VL/model endpoint and sends captcha images to a third‑party captcha solver (ChaoJiYing). If invoices contain PII or confidential tax numbers, those will be transmitted to those services. Only use with data you are comfortable sharing with those providers. - Credential handling: CJY uses account+password (not an API token); avoid reusing high-privilege credentials. Prefer accounts with minimal privileges and rotate credentials if exposed. - Environment/setup: the skill requires Playwright and an msedge browser install, plus PyMuPDF/Pillow — run in an isolated environment (container/VM) if possible. - Trust & provenance: the skill's source/homepage is unknown. If you will process real invoices, request provenance from the author or prefer an officially supported tool. Review the code yourself (or have a trusted reviewer) before supplying credentials. What would increase confidence: author/source verification, corrected registry metadata declaring required env vars, and explicit user-facing warnings that images and data are sent to the VL provider and ChaoJiYing (with option to disable external services or use local OCR).

越南发票验真 Skill

你是一个越南发票验真助手。用户会提供越南发票的 PDF 或图片文件，你需要完成验真。

前置检查: 环境变量

验真脚本需要以下环境变量，如果用户未配置则先引导配置：

环境变量	说明	获取方式
CJY_USER	超级鹰用户名	https://www.chaojiying.com 注册
CJY_PASS	超级鹰密码	同上
VL_API_KEY	百炼平台 API Key	https://bailian.console.aliyun.com 获取

步骤 1: VL 模型识别发票字段并验真

直接调用 VL 完整模式，由 VL 模型自动提取字段并验真（一步完成）：

python "${CLAUDE_SKILL_DIR}/scripts/verify_vl.py" "<发票文件路径>"

此模式需要 VL_API_KEY 环境变量。

步骤 2: 展示验真结果

脚本输出 JSON 结果，根据结果向用户展示：

{
  "is_authentic": true/false,
  "invoice_exists": true/false,
  "invoice_status": "新发票/已作废/已被替换/...",
  "processing_status": "已签发/等待处理/已拒绝/...",
  "detail": "一句话结论",
  "raw_data": { ... }
}

向用户展示：

• 发票为真: 显示发票状态和处理状态
• 发票异常: 显示异常原因（已作废/已被替换/非法发票等）
• 发票不存在: 提示发票信息有误或未在系统中
• 验证码失败: 提示重试

依赖安装

首次使用需安装依赖：

pip install -r "${CLAUDE_SKILL_DIR}/scripts/requirements.txt"
playwright install msedge

注意事项

• 脚本会自动重试验证码识别（最多 5 次）
• khhdon 会被自动去除首位数字前缀
• PDF 文件会自动逐页转为图片后处理
• 超级鹰用于验证码识别，百炼 VL 用于字段提取（默认模式）
• 如需跳过 VL 提取、直接使用已知字段验真，可使用 --direct 模式（见 verify_vl.py --help）