Tax Invoice Validator

InvoiceGuard · Invoice Compliance Guardian — AI-driven invoice deduplication, verification, and compliance report generation. Handles: invoice upload/scan re...

Security Scan

The skill's code and runtime instructions ask it to call external services (billing, tax-verification, Feishu, and a miaoda CLI) and reference environment variables and endpoints that are not declared in the registry metadata — this mismatch and external-network behavior warrant caution.

Purpose & Capability

The skill claims invoice OCR/deduplication/official verification/Feishu report generation, which is reasonable. However, SKILL.md and the Python scripts expect external tools and services (miaoda-studio-cli for OCR, State Tax Administration verification, Feishu Bitable/docs, and a SkillPay billing endpoint). The registry metadata lists no required binaries or environment variables despite the code calling network APIs and reading SKILL_BILLING_API_KEY and SKILL_BILLING_SKILL_ID. Those undeclared dependencies are inconsistent with the claimed purpose and should be declared and justified.

Instruction Scope

SKILL.md instructs use of external CLI (miaoda-studio-cli), web verification against the tax portal, and uploading/writing reports to Feishu. The code will parse invoice contents and can include original invoice file paths/attachments in reports. The instructions and code therefore direct potentially sensitive invoice data to multiple external endpoints (tax portal, Feishu, billing). The SKILL.md and references claim 'no sensitive tax information is stored', but the code structures (file_path, attachments, network calls) permit transmission or storage of invoice data — this is a scope/privacy risk that is not justified in the metadata.

Install Mechanism

There is no install spec (no arbitrary download/install). That lowers installer risk. However the bundle includes Python scripts that will run and perform network calls; absence of an install step does not prevent runtime network behavior or data transmission.

Credentials

Registry says 'required env vars: none', but scripts reference environment variables (e.g., SKILL_BILLING_API_KEY, SKILL_BILLING_SKILL_ID and the code expects Feishu app tokens when creating Bitable/docs). The tax verification flow and Feishu integration both require credentials in practice. The mismatch (undeclared secrets) is a significant proportionality and transparency issue. Additionally, changelog references an external deployment server IP (124.220.60.10) and billing uses https://skillpay.me — network endpoints that will see metadata or calls.

Persistence & Privilege

The skill is not marked always:true and does not request to modify other skills or global agent settings. It appears not to require permanent system presence beyond running its included scripts.

What to consider before installing

Do not install blindly. The package contains Python scripts that will call external services (a billing endpoint at skillpay.me, the State Tax Administration verification portal, and Feishu APIs) and the runtime docs instruct use of an external OCR CLI (miaoda-studio-cli). Yet the registry metadata declares no required binaries or environment variables. Ask the publisher to: (1) explicitly list all required environment variables and their exact names (Feishu app_token/app_secret, tax API credentials, billing API key), (2) document every external endpoint the skill will contact and the data sent, (3) explain how invoice files/attachments are stored/transmitted and confirm retention/ deletion policy, and (4) remove or clearly justify the developer-mode billing fallback that silently succeeds when no SKILL_BILLING_API_KEY is set. If you must test, run in an isolated environment with dummy credentials and network monitoring, and avoid submitting real invoices until you have written assurances about data handling and a contact/ homepage for the author.

InvoiceGuard · Invoice Compliance Guardian

AI-driven invoice deduplication, verification, and full compliance reporting workflow.

Workflow

User uploads invoice
    │
    ├── Image / Screenshot / Photo
    │   → miaoda-studio-cli image-understanding for text extraction
    │
    ├── PDF / OFD / XML
    │   → miaoda-studio-cli doc-parse for content extraction
    │
    ▼
Parse key fields (invoice number, date, amount, buyer/seller)
    │
    ▼
AI Deduplication Engine
    │  • Image fingerprint hash comparison
    │  • Key field consistency validation
    ▼
Official Verification (Pro)
    │  • Connect to State Tax Administration verification platform
    │  • Invoice status query (normal/voided/red-flushed)
    ▼
Generate Compliance Report → Write to Feishu Doc (Pro)
    │
    ▼
Return structured results

Feature Details

1. Invoice Upload & Recognition

Supported formats: Image (JPG/PNG), PDF, OFD, XML

# Image invoice → OCR
miaoda-studio-cli image-understanding -i invoice.png

# PDF/OFD/XML invoice → text extraction
miaoda-studio-cli doc-parse --file invoice.pdf --output json

Key fields extracted:

• Invoice type (VAT special / regular / electronic / train ticket / air ticket, etc.)
• Invoice code + invoice number
• Invoice date
• Total amount (tax included)
• Buyer name + tax ID
• Seller name + tax ID
• Goods or service description

2. AI Deduplication Engine

Available in Free + Pro tiers

Triple-validation for duplicate detection:

1. Exact Match: Invoice code + number identical → mark as duplicate
2. Field Hash: Amount + date + buyer/seller generates fingerprint → hash collision detection
3. Image Similarity: Structural similarity comparison (for screenshots/forged tickets)

# Core deduplication logic (see scripts/duplicate_checker.py)
# Returns: {is_duplicate: bool, match_type: str, confidence: float}

3. Official Verification (Pro)

Pro tier only

Connects to State Tax Administration VAT invoice verification platform:

• Real-time invoice authenticity verification
• Invoice status: normal / voided / red-flushed / out of control
• Verify invoiced amount against system records

Note: Tax authority verification API requires a business taxpayer developer account. See references/tax-api.md for setup.

4. Compliance Report (Pro)

Pro tier only

Generates structured compliance reports per Ministry of Finance [Cai Hui Ban [2023] No.18]. Now with Feishu native solution:

• Compliance Report → Generate shareable, commentable Feishu cloud documents
• Invoice Details → Auto-import to Feishu Bitable for filtering and analysis

Report Structure (6 sections, per Cai Hui Ban [2023] No.18):
├── 1. Basic Info (company name, tax ID, report date)
├── 2. Invoice Summary (total count, amount, by type/month)
├── 3. Deduplication Results (duplicate invoice list)
├── 4. Verification Results (abnormal status invoices)
├── 5. Compliance Conclusion (summary + risk alerts)
└── 6. Attachment List

Standard Markdown Report

Generate Markdown report via scripts/compliance_report.py:

python3 scripts/compliance_report.py <summary_json> <records_json> [buyer_name] [buyer_tax_id]

Feishu Native Solution (Recommended for Pro)

Step 1: Generate Feishu Document Report

Call generate_feishu_compliance_report_markdown() to get Lark-flavored Markdown, then use feishu_create_doc to create a shareable, commentable Feishu document:

from scripts.compliance_report import generate_feishu_compliance_report_markdown

markdown = generate_feishu_compliance_report_markdown(
    records=invoice_records,
    summary=report_summary,
    buyer_name="XX Company Ltd",
    buyer_tax_id="91440000XXXXXXXXXX"
)

Step 2: Import Invoice Details to Feishu Bitable

Create a Bitable app and table, define fields, then batch import invoice data:

from scripts.compliance_report import create_feishu_bitable_schema, prepare_invoices_for_feishu_bitable

# 1. Create Bitable app
# feishu_bitable_app action="create" name="Invoice Compliance Details"

# 2. Get app_token, create table with preset fields
fields = create_feishu_bitable_schema(app_token)
# feishu_bitable_app_table action="create" app_token="<app_token>" name="Invoice Details" fields=fields

# 3. Prepare and batch import
bitable_records = prepare_invoices_for_feishu_bitable(invoice_records)
# feishu_bitable_app_table_record action="batch_create" app_token="<app_token>" table_id="<table_id>" records=bitable_records

Bitable Fields:

Field	Type	Description
Invoice Code	Text
Invoice Number	Text
Invoice Date	Date	Millisecond timestamp, filterable
Amount	Number	Sortable and aggregatable
Issuer	Text
Status	Single-select	Normal/duplicate/suspicious/abnormal
Verification Status	Single-select	Not verified/normal/voided/red-flushed/out of control

Bitable Benefits:

• Filter by status, date, amount
• Generate pivot tables and charts
• Team collaboration, centralized invoice data

5. Batch Processing

Pro tier only (Free tier limited to 20/month)

Upload hundreds of invoices for automatic queued processing:

• Batch recognition → batch deduplication (cross-batch supported) → batch verification → summary report

Usage Examples

Example 1: Single Invoice Deduplication

User: Check if this invoice is a duplicate reimbursement
[Upload invoice image]

→ Call image-understanding → extract key fields → deduplication engine → return result

Example 2: Invoice Verification (Pro)

User: Verify this invoice's authenticity
[Upload invoice image]

→ Recognition → call tax authority API → return authenticity status

Example 3: Generate Compliance Report (Pro)

User: Generate a compliance report for these invoices
[Upload multiple invoices]

→ Batch recognition → batch deduplication → batch verification → generate Feishu doc

Example 4: Batch Processing

User: Process these 50 invoices
[Upload zip or batch files]

→ Extract → recognize → concurrent deduplication → aggregate results

Field Extraction Rules

Invoice Type	Key Fields	Extraction Difficulty
VAT Special Invoice	Code, number, amount, tax, buyer/seller	★★☆
VAT Regular Invoice	Code, number, amount, buyer/seller	★★☆
Electronic Invoice (PDF/OFD/XML)	Complete structured fields	★☆☆
Train Ticket	Date, origin/destination, amount	★☆☆
Air Itinerary	Flight, date, amount, passenger	★☆☆
Taxi Receipt	Date, time, amount	★☆☆

FAQ

Question	Answer
What does tax verification API require?	Business taxpayer status + developer account, limited free quota
How to parse OFD format?	miaoda-studio-cli doc-parse --file invoice.ofd
How is privacy protected?	No invoice raw data stored; processed and discarded immediately
How to distinguish Free vs Pro?	Determined by user selection or context; core logic is consistent
What if image is unclear?	Prompt user to retake or scan; ensure invoice number and amount are visible

References

• Invoice format specs: references/invoice-types.md
• Tax verification API: references/tax-api.md
• Compliance report template: references/compliance-report.md
• Deduplication engine: scripts/duplicate_checker.py

Tiered Features

Feature	FREE	PRO
Invoice OCR / text extraction	Yes	Yes
AI deduplication (triple-check)	Yes	Yes
Batch processing	Up to 20/month	Unlimited
Tax authority verification	—	Yes
Feishu compliance report doc	—	Yes
Feishu Bitable import	—	Yes
Price	Free	$0.01/call

---

Billing

Pay-per-call: $0.01 USDT per analysis run.

• Billing via skillpay.me/api/v1/billing/charge
• User data transmitted to SkillPay for billing identification
• Insufficient balance → payment URL returned

Required Environment Variables

Variable	Description
SKILL_BILLING_API_KEY	SkillPay Builder API Key
SKILL_BILLING_SKILL_ID	SkillPay Skill ID (default: tax-invoice-validator)
FEISHU_USER_ID	User ID for billing