autonomous-bookkeeper

通过编排 gmail、deepread-ocr、stripe-api 和 xero 实现预会计自动化的元技能。当用户需要从电子邮件获取发票、结构化字段提取、付款验证以及在对账就绪状态下创建会计分录时使用。

## 概述（中文）

通过编排 gmail、deepread-ocr、stripe-api 和 xero 实现预会计自动化的元技能。当用户需要从电子邮件获取发票、结构化字段提取、付款验证以及在对账就绪状态下创建会计分录时使用。

## 原文

# Purpose

Automate preparatory bookkeeping from incoming email to accounting records.

Core objective:
1. detect invoice email,
2. extract structured invoice data,
3. verify payment event,
4. create accounting entry and reconciliation status.

This is orchestration logic across upstream tools; it is not a replacement for financial controls.

# Required Installed Skills

- `gmail` (inspected latest: `1.0.6`)
- `deepread-ocr` (inspected latest: `1.0.6`)
- `stripe-api` (inspected latest: `1.0.8`)
- `xero` (inspected latest: `1.0.4`)

Install/update:

```bash
npx -y clawhub@latest install gmail
npx -y clawhub@latest install deepread-ocr
npx -y clawhub@latest install stripe-api
npx -y clawhub@latest install xero
npx -y clawhub@latest update --all
```

# Required Credentials

- `MATON_API_KEY` (for Gmail, Stripe, Xero through Maton gateway)
- `DEEPREAD_API_KEY` (for OCR extraction)

Preflight:

```bash
echo "$MATON_API_KEY" | wc -c
echo "$DEEPREAD_API_KEY" | wc -c
```

If missing, stop before any bookkeeping action.

# Inputs the LM Must Collect First

- `company_base_currency`
- `invoice_keywords` (default: invoice, rechnung, receipt, quittung)
- `vendor_rules` (for example AWS -> Hosting expense account)
- `date_tolerance_days` for matching (default: 3)
- `amount_tolerance` (default: exact, or configurable small tolerance)
- `auto_post_policy` (`manual-review`, `auto-if-high-confidence`)
- `attachment_policy` (`store-link`, `attach-binary-if-supported`)

Do not auto-post financial records without explicit policy.

# Tool Responsibilities

## Gmail (`gmail`)

Use for intake and attachment discovery.

Relevant behavior:
- query messages with Gmail operators (for example `has:attachment`, `subject:invoice`, sender filters)
- fetch message metadata and full payload for parsing
- label/update messages after processing (for traceability)

## DeepRead OCR (`deepread-ocr`)

Use for extracting structured fields from invoice PDFs/images.

Relevant behavior:
- async processing (`queued` -> `completed`/`failed`)
- schema-driven extraction
- field-level `hil_flag` and reason for uncertainty
- webhook or polling modes

## Stripe (`stripe-api`)

Use for payment-side verification.

Relevant behavior:
- query charges/payment_intents/invoices/balance transactions
- verify amount, currency, status, and date proximity

## Xero (`xero`)

Use for accounting record creation and payment/reconciliation visibility.

Relevant behavior:
- create contacts if missing
- create invoices/bills (`ACCPAY` for payable bills)
- list payments and bank transactions

# Canonical Signal Chain

## Stage 1: Inbox detection

Scan Gmail for candidate invoice emails.

Recommended query pattern:
- `has:attachment (subject:invoice OR subject:rechnung OR subject:receipt OR subject:quittung)`
- optional sender constraint for known vendors (for example `from:aws`)

Output:
- message ID
- sender
- received date
- attachment candidates

## Stage 2: Attachment extraction

For each invoice candidate attachment:
1. send file to DeepRead OCR with invoice schema
2. wait for async completion (webhook preferred; polling fallback)
3. parse structured result

Minimum extracted fields:
- vendor
- invoice_date
- invoice_number
- total_amount
- tax_amount
- currency

Quality gate:
- if critical fields have `hil_flag=true`, route to review queue before posting.

## Stage 3: Payment verification

Use Stripe to check whether corresponding payment occurred.

Matching policy:
- amount equals invoice total (within tolerance)
- currency matches
- date within tolerance window
- status is successful/paid

If multiple candidates match, mark as `ambiguous_match` and require review.

## Stage 4: Accounting write

Use Xero for booking.

Default payable flow:
1. ensure vendor contact exists (create if needed)
2. create bill entry (`Type: ACCPAY`) with line item category (for example Hosting)
3. mark as paid/reconciled state only when Stripe verification is confident
4. include reference fields: invoice number, source message ID, payment reference

Attachment handling:
- if binary attachment endpoint/path is available in the active integration, attach file
- otherwise store durable file reference and include link/reference in description/metadata

## Stage 5: Traceability updates

After successful processing:
- apply Gmail processed label
- store processing log (source email, extraction confidence, matching evidence, xero IDs)
- keep idempotency key to avoid duplicate posting

# Scenario Mapping (AWS Invoice)

For the scenario "AWS invoice by email -> Xero + card match":

1. Gmail finds AWS email with PDF attachment.
2. DeepRead OCR extracts structured fields (vendor/date/total/tax/invoice number).
3. Stripe check confirms payment event around invoice date and amount.
4. Xero creates payable entry (`ACCPAY`) under Hosting category.
5. Record is marked paid only after confident match; source PDF linked/attached per policy.

# Data Contract

Normalize to one transaction record before posting:

```json
{
  "source": {
    "gmail_message_id": "...",
    "sender": "billing@aws.amazon.com",
    "attachment_name": "invoice.pdf"
  },
  "invoice": {
    "vendor": "AWS",
    "invoice_number": "INV-123",
    "invoice_date": "2024-05-01",
    "total": 53.20,
    "tax": 0.00,
    "currency": "USD",
    "ocr_confidence_ok": true
  },
  "payment_match": {
    "provider": "stripe",
    "matched": true,
    "transaction_id": "ch_...",
    "amount": 53.20,
    "date": "2024-05-01"
  },
  "accounting": {
    "system": "xero",
    "entry_type": "ACCPAY",
    "category": "Hosting",
    "status": "Paid"
  }
}
```

# Output Contract

Always return:

- `IntakeSummary`
  - emails scanned, invoice candidates found

- `ExtractionSummary`
  - extracted fields and `hil_flag` status

- `PaymentVerification`
  - matched/not matched + evidence

- `AccountingAction`
  - created/updated records and IDs

- `ReviewQueue`
  - any records requiring manual validation

# Quality Gates

Before auto-posting:
- vendor identified
- invoice number/date/total present
- no critical `hil_flag` unresolved
- payment match confidence above policy threshold
- duplicate check passed (same vendor + invoice number + total)

If any gate fails, return `Needs Review` and do not auto-post.

# Guardrails

- Never mark invoice as paid without payment evidence.
- Never silently overwrite existing accounting records.
- Never drop uncertain OCR fields; surface them explicitly.
- Prefer manual review when amount/date ambiguity exists.
- Preserve source audit trail for every booking action.

# Failure Handling

- Gmail unavailable: stop intake and report connection issue.
- OCR job failed/timeout: keep email queued for retry.
- Stripe no match: post as unpaid bill or route to review per policy.
- Xero write failed: keep normalized record and retry safely with idempotency key.

# Known Limits from Inspected Upstream Skills

- DeepRead OCR is asynchronous and may require webhook/polling orchestration.
- The inspected Xero skill docs emphasize core accounting endpoints but do not fully document attachment upload flow; attachment behavior depends on supported endpoint path in active integration.
- Stripe/Xero matching is orchestration logic here, not a single native "auto-reconcile" endpoint in these inspected skill docs.
- QuickBooks is not part of this researched stack; this meta-skill is Xero-first.

Treat these limits as mandatory operator disclosures.