Mail Invoice Archiver

Read supported mailbox providers such as 126, 163, and Gmail, identify invoice attachments or invoice download links, archive invoices by month, deduplicate...

Security Scan

The skill appears to implement the advertised mailbox invoice-archiving capabilities, but registry metadata and packaging omit several important credentials, config paths, and runtime behaviors the code actually requires — review before installing or granting secrets.

Purpose & Capability

The code implements an IMAP-based invoice archiver for 126/163/Gmail and related delivery features (Feishu). Those capabilities justify reading mail and storing archive files and metadata. However the registry metadata claims no required credentials or config paths while the runtime clearly needs mailbox credentials (or system keychain access), may use environment variables, and reads/writes config under the user's home — the published metadata is incomplete.

Instruction Scope

SKILL.md instructs the agent to run the packaged Python CLI (doctor, setup, sync, report, deliver) and to prompt or guide the user through setup. The instructions stay within the stated purpose (setup, sync, report, pack). They explicitly require asking the user about credential storage and waiting for confirmation before proceeding, which constrains the agent's actions.

Install Mechanism

The registry declares no install spec / 'instruction-only', but the bundle contains substantial Python source (17 files). There is no automated installer, which reduces remote-install risk, but the packaging/metadata mismatch (instruction-only vs. included runtime code) is a transparency issue and warrants caution.

Credentials

Registry metadata lists no required environment variables or primary credential, yet the code expects mailbox credentials (via system keychain, env vars MAIL_INVOICE_ARCHIVER_EMAIL and MAIL_INVOICE_ARCHIVER_AUTH_CODE, or a config file), can read Feishu app_id/app_secret from env or ~/.config, and will write a local archive (~ /Documents/invoice-archive) and SQLite DB (~/.config state). The skill therefore needs secrets and home-directory access that are not declared in the registry entry — this is a meaningful mismatch.

Persistence & Privilege

The skill is not 'always:true' and does not auto-enable itself outside invocation. It will create persistent artifacts: archive files under ~/Documents/invoice-archive, a .state/index.sqlite3 DB, and may write config under ~/.config. It also integrates with OS system credential stores (macOS Keychain / Windows Credential Manager) and can make outbound network requests (IMAP and HTTP for link downloads and Feishu API). These privileges are reasonable for the described functionality but should be accepted consciously.

Scan Findings in Context

[pre-scan-none] expected: No regex-based scan flags were detected. That does not mean there are no risks: the code performs credential handling, network I/O (IMAP, HTTP downloads, Feishu token exchange), and filesystem writes, all of which require manual review.

What to consider before installing

Before installing or running this skill, note these concrete points: (1) The skill actually contains Python code and will ask for your mailbox credentials (email + auth code/app-password) and may store them in the system keychain, an env var, or a plain-text config file in your home directory — the registry metadata does not declare these needs. (2) It will create ~/Documents/invoice-archive and a SQLite index under that state dir; expect persistent files. (3) The runtime can follow download links found in emails (it will fetch arbitrary URLs), and can call Feishu if you provide app_id/app_secret; only provide these secrets if you trust the skill. (4) If you have concerns, prefer interactive 'prompt' auth (no persistence), or use provider-specific app passwords and limit exposure (avoid your primary Google password). Inspect the code (imap_client, system_credentials, feishu_delivery) or run the CLI's doctor/setup in a controlled environment first. If the packaging metadata (no required envs/configs) worries you, ask the publisher why credentials/config paths were omitted before granting access.

Quick Start

• In the first session after installation, ask the user which credential storage mode they want before doing anything else.
• Run python3 {baseDir}/scripts/cli.py providers --json when you need to show the currently supported mailbox providers and their setup notes.
• Run python3 {baseDir}/scripts/cli.py doctor --json first. If it returns setup_required: true, guide the user through setup and wait for confirmation.
• Use python3 {baseDir}/scripts/cli.py setup for an interactive setup wizard, or pass --mail-provider 126|163|gmail|custom plus --provider system|env|config|prompt for scripted setup.
• Use python3 {baseDir}/scripts/cli.py sync --month YYYY-MM --json to pull a month into the local archive.
• Use python3 {baseDir}/scripts/cli.py report --month YYYY-MM --json to inspect totals, duplicates, conflicts, and failures.
• Use python3 {baseDir}/scripts/cli.py deliver --month YYYY-MM --json to prepare a zip plus summary for the current chat.

Workflow

1. Run doctor.
2. If doctor reports setup_required, ask the user which mailbox provider they want first: 126, 163, gmail, or custom.
3. Ask the user which auth mode they want: system credential store, environment variables, config file, or prompt-each-session.
4. Run setup with the chosen mailbox provider and auth mode, then wait for the user to confirm they completed any external steps, such as exporting environment variables.
5. Run doctor again to confirm the setup works.
6. Run list --month YYYY-MM --limit 20 --json when you need a quick mailbox preview without downloading files.
7. Run sync --month YYYY-MM --json to archive candidate invoices into ~/Documents/invoice-archive/YYYY-MM/.
8. Run report --month YYYY-MM --json after sync and summarize: total amount, canonical invoice count, high-value invoices, duplicates, conflicts, and failures.
9. Run deliver --month YYYY-MM --json, then attach the returned zip file in the current chat and paste the summary.

Windows Env Setup

• If the user chooses env on Windows, offer one of these exact snippets and wait for confirmation before rerunning doctor.

$env:MAIL_INVOICE_ARCHIVER_EMAIL = "[e-mail]"
$env:MAIL_INVOICE_ARCHIVER_AUTH_CODE = "your-provider-secret"
python "{baseDir}/scripts/cli.py" doctor --json

set MAIL_INVOICE_ARCHIVER_EMAIL=[e-mail]
set MAIL_INVOICE_ARCHIVER_AUTH_CODE=your-provider-secret
python "{baseDir}\scripts\cli.py" doctor --json

• For Gmail, MAIL_INVOICE_ARCHIVER_AUTH_CODE must be a Gmail app password, not the normal Google account password.

Rules

• Prefer system auth on macOS and Windows, env on Linux, CI, or headless sessions, and prompt only when the user does not want to persist the secret anywhere.
• system currently means macOS Keychain on macOS and Windows Credential Manager on Windows.
• First-phase built-in providers are 126, 163, and gmail.
• Treat appleimap.126.com as the preferred 126 IMAP host.
• Send the provider-configured IMAP client ID only when that provider needs it. Today that means 126 and 163; Gmail does not need it.
• Gmail is implemented today through IMAP app passwords for personal Gmail accounts. Some Google Workspace tenants may still require admin-side IMAP changes or OAuth, which is a future enhancement and not part of the current runtime.
• Deduplicate in two layers: storage duplicates by message UID / part / SHA256; business duplicates by invoice number + amount.
• If invoice number matches but amount differs, keep the file and report it as a conflict instead of auto-merging.
• Keep invoice amount and OCR results in SQLite metadata, not in file names.
• If a link download fails and the message still looks like an invoice, report that failure back to the user.
• When the same invoice appears in multiple attachment formats in one mail, prefer user-friendly formats for the canonical saved file. Default priority should be: image (png/jpg/jpeg) or PDF first, then XML, then OFD, and ZIP last. Do not prefer OFD or ZIP when a readable PDF or image version of the same invoice is available.
• Treat OFD as a fallback archival format, not the default user-facing format, unless it is the only available canonical representation.
• For PDF invoice amount extraction, do not blindly take the first ¥ amount. PDF text extraction may reorder the invoice area and expose tax base amount, tax amount, and total amount in the wrong sequence.
• For PDF invoices, prefer a dedicated total-amount extractor over generic regex fallback. Use the invoice total area first, then fall back only when that area is missing.
• Buyer and seller names in PDF invoices may collapse into repeated 名称： 名称： layouts after text extraction. Prefer layout-aware extraction over a single regex when distinguishing buyer and seller.
• Month summaries must be stable even when a current-month row is marked as duplicate against an older canonical row outside the month window. Summaries should aggregate by current-month business keys, not only by status='saved' rows inside the month.
• If the user specifies a business rule for a specific invoice family, such as using 价税合计 for totals, record and honor that rule consistently in later extraction and reporting.

Resources

• Runtime: scripts/cli.py
• Detailed findings and pitfalls: references/compatibility-notes.md
• Feishu local config example: config/feishu/config.example.yaml

Local Secret Config Convention

When this skill needs Feishu app credentials for local delivery helpers or follow-up integrations, do not store real secrets inside the published skill directory.

Use this split instead:

• committed example inside the skill: config/feishu/config.example.yaml
• local real config outside the skill: ~/.config/openclaw/mail_invoice_archiver/feishu.config.yaml

Why this rule exists:

• .gitignore reduces Git commit risk, but should not be treated as the security boundary for skill publishing.
• Publishing flows may not behave exactly like Git, so real secrets must live outside the skill folder.
• The skill should only ship examples, docs, and secret-loading logic, never the real credential file.

Recommended loading order for Feishu credentials:

1. explicit environment variables
2. local private config at ~/.config/openclaw/mail_invoice_archiver/feishu.config.yaml
3. prompt the user

Environment variable names:

• MAIL_INVOICE_ARCHIVER_FEISHU_APP_ID
• MAIL_INVOICE_ARCHIVER_FEISHU_APP_SECRET
• MAIL_INVOICE_ARCHIVER_FEISHU_RECEIVE_ID_TYPE
• optional override path: MAIL_INVOICE_ARCHIVER_FEISHU_CONFIG

Never publish or share the real local config file.

If config/feishu/config.yaml appears inside the skill directory, treat it as an unsafe misconfiguration. The runtime should fail fast and require moving that file out of the skill.