Invoice Verification Service

使用发票服务后端 v4 plugin 接口完成 key 初始化、查验额度查询、额度流水查询、发票文本或图片查验。用户提到“发票查验”“剩余额度”“额度流水”“appKey 初始化/失效重绑”等需求，或需要调用 /api/v4/plugin/key/init、/api/v4/plugin/quota、/api/v4...

Security Scan

The skill's code, instructions, and resource usage are internally consistent with an invoice-verification helper that calls a v4 plugin backend and stores an appKey locally.

Purpose & Capability

The name/description (init key, query quota/ledger, verify invoices) matches the included script and SKILL.md. Required binary is only node which is appropriate. No unrelated cloud credentials or unrelated binaries are requested.

Instruction Scope

Runtime instructions call the bundled Node script which performs HTTP calls to /api/v4/plugin/* endpoints, extracts invoice fields, and summarizes responses. The script writes/reads config in the user's home directory (~/.openclaw/invoice-skill/config.json) and will read a legacy path (~/.openclaw/invoice-plugin/config.json) for migration—this is consistent with the migration note but is scope expansion that will read another skill's legacy config file.

Install Mechanism

There is no install spec and no network download; the skill is instruction-only plus a bundled script. That is low-risk compared with remote installers.

Credentials

The skill does not declare required env vars, which is reasonable, but the script will read optional environment variables (INVOICE_API_BASE_URL, OPENCLAW_CLIENT_INSTANCE_ID, OPENCLAW_DEVICE_FINGERPRINT) if present. The script also persists an appKey and related IDs in plaintext under ~/.openclaw/invoice-skill/config.json (and reads legacy config). Storing API keys locally is expected here but users should be aware these secrets are kept on disk unencrypted.

Persistence & Privilege

always is false and the skill does not modify global agent settings. It persists its own config in the user's home directory and may rotate/clear its stored appKey; this is within expected privilege for this utility.

Assessment

This skill appears to do what it says: call your invoice backend endpoints and store an appKey locally. Before installing, verify the apiBaseUrl you will use is a trusted backend (default is localhost/127.0.0.1 in the code; README shows an example private IP). Be aware the script will: (1) call the backend to init keys and perform verifications (so invoice text/images will be sent to that backend), (2) store the returned appKey and identifiers in ~/.openclaw/invoice-skill/config.json in plaintext, and (3) read a legacy config at ~/.openclaw/invoice-plugin/config.json if present (migration behavior). If you don't want local storage of keys, or don't trust the remote host, inspect or modify the script before use. Also note the script will honor optional env vars (INVOICE_API_BASE_URL, OPENCLAW_CLIENT_INSTANCE_ID, OPENCLAW_DEVICE_FINGERPRINT) though they are not declared in the skill metadata; set them deliberately or leave unset. Overall coherence is good, but if you need stronger guarantees (encrypted storage, strict endpoint allowlist), require changes before deploying.

Overview

用这个 skill 把原来的插件能力改成显式脚本调用。 优先执行 {baseDir}/scripts/invoice_service.js，不要直接改写脚本里的 HTTP 逻辑。

Quick Start

先确认 Node.js 可用，然后按需执行以下命令：

node "{baseDir}/scripts/invoice_service.js" help
node "{baseDir}/scripts/invoice_service.js" config set --api-base-url http://localhost:8080
node "{baseDir}/scripts/invoice_service.js" init-key
node "{baseDir}/scripts/invoice_service.js" quota
node "{baseDir}/scripts/invoice_service.js" ledger --page 1 --page-size 20
node "{baseDir}/scripts/invoice_service.js" verify --text "发票代码 033002100611, 发票号码 12345678, 开票日期 2025-05-30, 金额 260.65, 校验码 123456" --format both

安装完成后，先执行一次 init-key。 这一步会调用后端 /api/v4/plugin/key/init，生成并保存 appKey，同时拿到后端发放的免费 5 次额度。

Workflow

1. 配置 apiBaseUrl。 如果还没有可用配置，先运行 config set --api-base-url ...。

2. 直接执行目标动作。 脚本会在没有 appKey 时自动调用 /api/v4/plugin/key/init 初始化，并把 appKey、clientInstanceId、deviceFingerprint 写入 ~/.openclaw/invoice-skill/config.json。

3. 当接口返回 INVALID_KEY 或同义错误时，重试一次。 脚本会删除旧 appKey，轮换 clientInstanceId 后重新初始化并再次发起请求。

4. 把脚本返回的 JSON 摘要化后再回复用户。 保留关键字段，例如剩余额度、额度预警、流水列表、查验结果、状态码和错误信息。

Supported Actions

config

• config show
• config set --api-base-url <url>
• config set --app-key <key>
• config set --client-instance-id <id>
• config set --device-fingerprint <id>
• config clear-app-key

只在需要初始化或排查配置时使用。

init-key

主动初始化 key。

node "{baseDir}/scripts/invoice_service.js" init-key

推荐在 skill 安装完成后立刻执行一次，再开始 quota、ledger 或 verify。

需要轮换客户端标识时：

node "{baseDir}/scripts/invoice_service.js" init-key --rotate-client-instance-id

quota

查询剩余额度。

node "{baseDir}/scripts/invoice_service.js" quota

ledger

查询额度流水。

node "{baseDir}/scripts/invoice_service.js" ledger --page 1 --page-size 20

verify

用于文本查验。把完整文本放进 --text，脚本会尽量提取结构化字段并同时上送原文。

node "{baseDir}/scripts/invoice_service.js" verify --text "<发票文本>" --format both

--format 仅允许 json、base64、base64+json、both。

verify-image

当前后端没有独立 OCR 入口时，只做图片预检，不会从图片里自动识别字段。 要继续查验，必须同时提供 --text 补充发票字段。

node "{baseDir}/scripts/invoice_service.js" verify-image --image-file C:\path\invoice.png --text "<发票文本>"

或：

node "{baseDir}/scripts/invoice_service.js" verify-image --image-base64 "<base64>" --mime-type image/png --text "<发票文本>"

Response Handling

• 优先读取 JSON 中的 ok、action、data、meta。
• 如果 ok 为 false，直接提炼 error.message、error.code、error.status。
• 如果执行了自动绑定，向用户说明已自动注册并复用新的 appKey。
• data 中真正的业务字段来自后端统一返回体：success、code、message、remainingQuota、validUntil、quotaAlert、data。

Notes

• 新 skill 配置文件路径是 ~/.openclaw/invoice-skill/config.json。
• 为兼容插件迁移，脚本会自动读取旧路径 ~/.openclaw/invoice-plugin/config.json 作为回退配置。
• 只在确有需要时才执行 config set --app-key ...；常规情况下优先依赖 /api/v4/plugin/key/init 自动初始化。
• 当前 invoice-api-service 仓库中未看到充值、续费、订单查询 controller；不要再调用旧的 /api/orders/* 接口。