希斯·莱杰
- 作者仓库星标 39
- 作者仓库 awesome-omni-skill
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @diegosouzapw · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 需要 · Stripe
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Heath Ledger
AI bookkeeping skill for Mercury bank accounts.
## Quick Start
1. `scripts/init_db.mjs` — creates DB + seeds ~90 universal vendor→category rules
2. `scripts/connect_mercury.sh <MERCURY_API_TOKEN> [entity_name]` — discovers accounts
3. *(Optional)* `scripts/connect_stripe.sh <entity_id> <stripe_api_key>` — connect Stripe for exact revenue + fees
4. *(If Stripe connected)* `scripts/pull_stripe_revenue.sh <entity_id> <start_date> <end_date>` — pull monthly revenue data
5. `scripts/pull_transactions.sh <entity_id> <start_date> <end_date>`
5. `scripts/categorize.sh <entity_id>` — rule-based first, AI for unknowns
6. Review ambiguous items, correct with `scripts/set_category.sh`
7. `scripts/generate_books.sh <entity_id> <start_date> <end_date> [output_path]`
## Setup Flow
### Mercury API Key (Required)
Get from Mercury Dashboard → Settings → API Tokens. The token gives read-only access to transactions.
### Stripe API Key (Optional but Recommended)
Without Stripe API: Mercury shows **net** Stripe deposits (revenue minus fees). The system estimates gross revenue using a configurable fee rate (default 2.3% + $0.30).
With Stripe API: You get **exact** gross revenue, exact fees, and proper refund tracking. Always prefer this when available.
To connect: `scripts/connect_stripe.sh <entity_id> <stripe_api_key>`
Then pull data: `scripts/pull_stripe_revenue.sh <entity_id> <start_date> <end_date>`
The P&L generator automatically uses Stripe data when available, falling back to Mercury estimates otherwise.
### Entity Settings
Configure per-entity via the `entity_settings` table:
| Setting | Default | Description |
|---------|---------|-------------|
| `accounting_basis` | `accrual` | `accrual` or `cash` — cash basis uses posted dates only |
| `month_offset` | `1` | Fiscal year month offset (1 = calendar year) |
| `stripe_fee_rate` | `0.023` | Stripe percentage fee for gross-up calculation |
| `stripe_fee_fixed` | `0.30` | Stripe fixed fee per transaction |
| `amortization_monthly` | `null` | Monthly amortization amount for acquired assets |
## Workflow
1. **Connect Mercury** — `scripts/connect_mercury.sh <token> [name]` discovers accounts, creates entity
2. **Pull transactions** — `scripts/pull_transactions.sh <entity_id> <start_date> <end_date>`
3. **Categorize** — `scripts/categorize.sh <entity_id> [max_transactions]` — rule-based first, then AI for unknowns
4. **Review ambiguous** — Script outputs low-confidence items. Ask user, then update with `scripts/set_category.sh <transaction_id> <category> [subcategory]`
5. **Generate books** — `scripts/generate_books.sh <entity_id> <start_date> <end_date> [output_path]`
## Scripts Reference
All scripts are in `scripts/`. Run with bash or node. Database is SQLite at `data/heath.db`.
| Script | Purpose |
|--------|---------|
| `init_db.mjs` | Create/migrate SQLite database + seed rules |
| `connect_mercury.sh` | Connect Mercury API, discover accounts |
| `pull_transactions.sh` | Pull transactions for date range |
| `categorize.sh` | Categorize transactions (rules + AI) |
| `set_category.sh` | Manually set category for a transaction |
| `add_rule.sh` | Add/update a categorization rule |
| `generate_books.sh` | Generate Excel workbook |
| `list_entities.sh` | List all entities |
| `connect_stripe.sh` | Connect Stripe API to an entity |
| `pull_stripe_revenue.sh` | Pull Stripe balance transactions by month |
| `status.sh` | Show entity status (accounts, tx counts) |
## Chart of Accounts
See `references/chart-of-accounts.md` for the full chart with P&L sections and cash flow classifications.
## Learning & Compounding System
Heath Ledger gets smarter over time through a layered rule system:
### Rule Hierarchy
1. **Entity-specific rules** (highest priority) — per-company overrides
2. **Global rules** (`entity_id = NULL`) — apply to all entities
3. **Seed rules** — universal vendor mappings shipped with the skill
4. **AI categorization** — used when no rule matches
### How Learning Works
- Every manual correction creates or updates a categorization rule
- Rules track `usage_count` — heavily-used rules are more reliable
- `source` field tracks provenance: `seed`, `ai`, `human`, `manual`
- Human-confirmed rules get `confidence: 0.95-1.0`
- AI-generated rules start at `0.85` and can be promoted
- Entity-specific rules can be promoted to global when they prove universal
### The Compounding Effect
After categorizing ~5,000 transactions across 2 entities, the system now auto-categorizes **~95%** of transactions without AI. Each new entity benefits from all previous learnings.
## Known Limitations
### Stripe Net vs Gross (Without Stripe API)
Mercury deposits from Stripe are **net** amounts (revenue minus ~2.9% + $0.30 fees). Without the Stripe API:
- We estimate gross revenue using configurable fee rates
- This creates "synthetic" Stripe Fee entries
- Accuracy depends on your actual Stripe fee rate (varies by plan, card type, international)
- **Solution**: Connect Stripe API for exact numbers
### Deel Fee Splitting
Deel combines platform fees and contractor payroll in one transaction stream. Pattern:
- **Small fixed amounts** (~$2-5) → Deel Platform Fee → categorize as "Software expenses"
- **Larger variable amounts** → Contractor Payroll → categorize as "Wages & Salaries"
- The system learns this pattern but may need initial human guidance
### Mercury API Limitations
- Only returns posted transactions (not pending)
- Some counterparty names are truncated or normalized differently
- Wire descriptions may include reference numbers that create duplicate rules
### Multi-Currency
- Wise transfers create both a debit (USD) and may show FX fees separately
- International wire fees from Mercury appear as separate line items
- FX gains/losses are not tracked (would need multi-currency ledger)
## AI Categorization
The `categorize.sh` script calls the host agent's model via stdin/stdout JSON protocol. It sends transaction batches and expects category assignments back. The script writes a prompt to stdout that the agent should process and return results for.
When AI confidence < 0.85, transactions are flagged as ambiguous for user review.
## Key Details
- **Cash or accrual basis** — configurable per entity
- **Multiple entities supported** — each with own connections and rules
- **Rules persist** — categorization rules saved to SQLite, reused across runs
- **Seed rules** — ~90 universal vendor mappings loaded on init
- **Excel output** — 4-tab workbook: P&L, Balance Sheet, Cash Flow, Transaction Detail
章节与文件索引
按说明文件中的顺序排列。
快速入门
Mercury API 密钥(必需)
Stripe API 密钥(可选但推荐)
实体设置
工作流程
文件/命令 -> scripts/init_db.mjs · scripts/connect_mercury.sh <MERCURY_API_TOKEN> [entity_name] · scripts/connect_stripe.sh <entity_id> <stripe_api_key> · scripts/pull_stripe_revenue.sh <entity_id> <start_date> <end_date> · scripts/pull_transactions.sh <entity_id> <start_date> <end_date> · scripts/categorize.sh <entity_id> · scripts/set_category.sh · scripts/generate_books.sh <entity_id> <start_date> <end_date> [output_path]
内容校验值 -> 39d088b37ee5
当前原文的自动摘译,尚未人工审校。
快速入门
scripts/init_db.mjs— 创建数据库 + 种子 ~90 个通用供应商→类别规则scripts/connect_mercury.sh <MERCURY_API_TOKEN> [entity_name]— 发现帐户 (可选)scripts/connect_stripe.sh <entity_id> <stripe_api_key>— 连接 Stripe 以获取准确的收入 + 费用 (如果 Stripe 连接)scripts/pull_stripe_revenue.sh <entity_id> <start_date> <end_date>— 提取每月收入数据scripts/pull_transactions.sh <entity_id> <start_date> <end_date>Mercury API 密钥(必需)
从 Mercury 仪表板 → 设置 → API 令牌获取。该令牌提供对交易的只读访问权限。
Stripe API 密钥(可选但推荐)
没有 Stripe API:Mercury 显示 Stripe 净存款(收入减去费用)。系统使用可配置的费率(默认 2.3% + 0.30 美元)估算总收入。使用 Stripe API:您可以获得准确的总收入、准确的费用和正确的退款跟踪。如果有的话,总是更喜欢这个。连接:
scripts/connect_stripe.sh <entity_id> <stripe_api_key>然后拉取数据:scripts/pull_stripe_revenue.sh <entity_id> <start_date> <end_date>实体设置
通过
entity_settings表配置每个实体: 设置 · 默认 · 描述accounting_basis·accrual·accrual或cash— 收付实现制仅使用发布日期month_offset·1· 会计年度月份偏移(1 = 日历年)stripe_fee_rate·0.023· 总金额计算的条纹百分比费用工作流程
连接 Mercury —
scripts/connect_mercury.sh <token> [name]发现账户,创建实体 拉取交易 —scripts/pull_transactions.sh <entity_id> <start_date> <end_date>分类 —scripts/categorize.sh <entity_id> [max_transactions]— 首先基于规则,然后针对未知进行 AI 审查不明确 — 脚本输出低置信度项目。询问用户,然后用scripts/set_category.sh <transaction_id> <category> [subcategory]更新