fins：幫我月底對帳的個人+公司財務 Agent

做什麼

每到月底,對帳、查帳、把預計支出算進來,本來都是我手動慢慢核的繁瑣事——而且我的個人帳和公司帳互相相依,一邊動到另一邊,分開算更容易對不起來。fins 就是我做來自動化這件事的財務 Agent:吃銀行 CSV 自動對帳、管預計支出、跑財務假設。

底層是個人與公司雙帳本:單一 SQLite 用 owner 欄位區分兩個帳本,不另開兩個資料庫、不分兩個 app——帳務數字跑在同一個地方,對帳才不會對到一半找不到對口。

功能面有四塊：銀行 CSV 匯入（可插拔 adapter，換銀行格式不動核心邏輯）、現金流預測（未來 n 個月 in-memory 展望）、負債追蹤（應付 / 應收，每筆還款拆本金 / 利息）、以及一支 finance validate 完整性驗證器——月結前必須全綠才算過關。

操作介面有兩層：PC 端跑 finance CLI，手機端透過 6 個 Claude Skills 用自然語言操作。兩層共用同一份 fins.skills.api 純函式，邏輯不重複寫。

為什麼這樣做

這套系統讓我想清楚一件事：讓 AI 幫你記錢，比讓 AI 幫你寫 code 還需要更嚴格的閘。 設計上做了四個決定——整數金額加 view 重算餘額、append-only 帳本以反向交易改錯、匯入原子驗證整批 commit 或 rollback、AI 寫入一律先 preview 人確認再 commit——每一個都把可能出錯的地方變成 DB constraint 或純函式，讓壞狀態不合法。錢的操作要確定性，不靠「AI 應該沒問題吧」的信念。

這六條工程紀律的完整邏輯，見讓 AI 安全記帳：碰錢的工程紀律。

怎麼用 · repo 導覽

快速上手（本地）：

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python3 -c "from fins.core.db import init_db; init_db('data/fins.db')"
.venv/bin/finance validate

6 個 Claude Skills 一覽：

Skill	問什麼
`fins-status`	現在帳戶餘額、淨資產
`fins-entry`	自然語言登一筆交易（preview → confirm）
`fins-cashflow`	未來 n 個月現金流展望（唯讀）
`fins-debt`	負債 / 應收餘額
`fins-recent`	最近 N 筆交易
`fins-forecast-add`	登預期未來收支（preview → confirm）

Skills 透過 bin/fins-skill wrapper 呼叫，JSON 輸出，在 Claude app 用自然語言觸發就好。

repo 結構重點：

fins/
├── finance.py        # Click CLI 路由
├── fins/
│   ├── core/         # db, models, units (MinorUnits)
│   ├── flows/        # import, link, transfer, debt, validate, report
│   │   └── adapters/ # 各銀行 / CC 可插拔 adapter
│   └── skills/api.py # CLI 與 Skills 共用的核心純函式
├── skills/           # 6 個 Claude Skills
└── docs/superpowers/specs/  # 設計規格（v1 + import adapter 設計）

月結標準流程：validate → import-bank → roll-forward → link → validate → report → commit。全程靠 CLI，validate 是唯一需要全綠才能繼續的閘。

背後的工程取捨與六條完整碰錢紀律，見讓 AI 安全記帳：碰錢的工程紀律。