Kelly Invoice Sheet

Kelly Invoice Sheet

Overview

Use this skill to turn invoice files or extracted invoice text into a structured batch that the user can review in a Busabase-backed spreadsheet-style UI. The skill owns extraction, reasoning, validation, and export; the AirApp only reads/writes its own Busabase Bases and records human decisions.

Default interaction mode: App UI. Unless the user explicitly asks for chat-only handling, ensure Busabase resources are provisioned (the AirApp does this lazily on first run), write extracted invoices with scripts/import_batch.mjs, and give the actual AirApp URL (or the local preview URL when local preview is explicitly requested).

App UI Screenshots

Mandatory Dependencies

1. Read and follow $kelly-app-skill-creator for product behavior, visual quality, responsive layout, and the complete canonical content/kelly-invoice-sheet-app/ artifact.
2. Read and follow $busabase for connection, target Space, node discovery, ChangeRequests, review, and merge behavior.
3. Read and follow $busabase-app-creator for resource modeling, AirApp runtime limits, security, validation, and deployment.

If a dependency is unavailable, preserve this skill's artifact and product contracts, stop before the unavailable Busabase operation, and report the exact missing dependency. Do not invent a second data backend.

Workflow

1. Accept invoice source files or source text from the user. Supported workflow inputs include PDFs, images, Word docs, CSV/XLS/XLSX exports, OCR text, email attachments, and pasted invoice text.
2. Extract invoice header fields, line items, totals, currency, dates, vendor identity, bill-to, payment terms, and source snippets. If OCR or document parsing needs another installed skill or tool, use it, then normalize the result into this skill's batch schema.
3. Read references/invoice-batch-schema.md before writing a batch file.
4. Write a batch JSON file (an object with an invoices array, or a bare array of invoice objects), keeping stable id and ref values such as Review #1.
5. Run node scripts/import_batch.mjs --file <batch.json> --apply to validate and write the batch into Busabase's invoices Base.
6. Give the user the AirApp URL (or start local preview with pnpm --dir content/kelly-invoice-sheet-app dev if explicitly requested).
7. After the user approves rows in the app, run node scripts/export_decisions.mjs --apply to export approved invoices to CSV and JSON and mark them done.

Use chat-only mode only when the user says "chat only", "no UI", "纯聊天", "不要打开 UI", or similar.

Boundary

• The AirApp reads and writes its own Busabase Bases only; it never mutates an external system, uploads an invoice file, pays a vendor, emails anyone, or imports into accounting software. Parent decisions (approve/request-changes/block/revise) write straight onto the invoice record through busabase-sdk.
• The skill performs extraction, reasoning, and validation, then records the result to Busabase via scripts/import_batch.mjs. It never sends invoice files to an external service from the app itself — any external OCR/API use belongs to the skill workflow and should be explicit.
• Export only happens through the trusted scripts/export_decisions.mjs after explicit approval in the UI or chat.

Busabase Resources

Two Bases under one application Folder (kelly-invoice-sheet), declared in content/kelly-invoice-sheet-app/app/js/config.js and the generated template sidecars under content/:

• invoices: one row per extracted invoice/receipt/credit note/statement — header fields, field confidence (JSON), line items (JSON array, shares the invoice's own lifecycle), risk/warning flags (JSON arrays), and the reviewer's decision (decision-action/decision-note/decided-at) written directly onto the same row. Written by scripts/import_batch.mjs when the agent finishes extracting a batch; status is set directly by a human decision in the app.
• settings: sanitized config summary (default currency, extraction preferences, review policy, export preferences — no secrets), one row keyed by kind.

Resources provision lazily through an idempotent Busabase ChangeRequest the first time the app runs in a Space; see references/invoice-batch-schema.md for exact field shapes.

Workflow Statuses

• needs_review: extracted row needs human review.
• changes_requested: user asked the agent to revise extraction.
• approved: row is ready for export.
• done: row has been exported or intentionally completed.
• blocked: row cannot proceed without missing information or source correction.

Extraction Rules

• Preserve source values. Do not invent invoice numbers, dates, tax ids, vendors, totals, or payment instructions.
• Keep original currency. Do not convert currencies unless the user explicitly asks and provides rates.
• Treat money fields as high-risk: totals, tax, amount due, currency, and bank/payment hints should be reviewed when confidence is low.
• Use field_confidence and warnings for ambiguous OCR, cropped images, handwritten values, missing references, negative totals, credit notes, duplicate invoice numbers, or total/line-item mismatches.
• Mark rows blocked if required fields are missing: vendor name, invoice number, invoice date, currency, or total.
• Never send invoice files to external services from the app. Any external OCR/API use belongs to the skill workflow and should be explicit.

Scripts

• node scripts/import_batch.mjs --file <batch.json> [--apply] Validates a batch of extracted invoices and upserts each one into Busabase's invoices Base (matched by invoice-id, so re-running after a correction updates existing rows). Dry run by default.
• node scripts/export_decisions.mjs [--apply] [--out <dir>] Reads invoices with status approved from Busabase, grouped by batch_id, and exports each batch to exports/<batch-id>/invoices.csv, line_items.csv, and approved_invoices.json, then marks each exported invoice done. Dry run by default.

Local App

Default behavior is AirApp-first — give the user the clickable AirApp URL. Start pnpm --dir content/kelly-invoice-sheet-app dev only when local preview/debugging is explicitly requested.

Demo Mode

?demo=1#/invoices/all opens the deterministic offline dataset (3 invoices: 2 needs_review, 1 blocked) for screenshots and review. Demo mode never reads or writes Busabase; demo decisions are read-only.

Safety Defaults

• Treat invoice data as sensitive. Never commit a local credential file.
• The app only edits its own Busabase records. It does not upload invoices, import into accounting systems, send email, pay vendors, or mutate remote systems.
• Export only after explicit approval in the UI or chat, via scripts/export_decisions.mjs.

Useful Commands

node skills/kelly-invoice-sheet/scripts/import_batch.mjs --file batch.json --apply
node skills/kelly-invoice-sheet/scripts/export_decisions.mjs --apply
pnpm --dir skills/kelly-invoice-sheet/content/kelly-invoice-sheet-app dev