MoneyWiz-API

一个用于访问 MoneyWiz SQLite 数据库的 Python API，支持读取账户/分类/交易，并提供 CLI 工具。 Fork的分支支持写入账单，配合Agent功能让记账体验起飞！

功能概览

读取 MoneyWiz 数据库中的账户、交易、分类、收付款对象、投资持仓等信息
提供 moneywiz-cli 交互式 shell 用于数据查看
支持通过 CLI 自动写入简单收支账单（收入/支出）
支持写入去重（按金额+时间窗口）避免重复记账
支持自动记账审计日志（JSONL），方便后续追踪与 AI 查询

安装

pip install moneywiz-api

开发环境安装：

pip install -e ".[dev]"

快速开始（Python）

from moneywiz_api import MoneywizApi

moneywiz_api = MoneywizApi("<你的sqlite文件路径>")

(
    accessor,
    account_manager,
    payee_manager,
    category_manager,
    transaction_manager,
    investment_holding_manager,
) = (
    moneywiz_api.accessor,
    moneywiz_api.account_manager,
    moneywiz_api.payee_manager,
    moneywiz_api.category_manager,
    moneywiz_api.transaction_manager,
    moneywiz_api.investment_holding_manager,
)

record = accessor.get_record(1001)
print(record)

CLI 使用

1) 启动交互式只读 Shell

moneywiz-cli "/path/to/ipadMoneyWiz.sqlite"

2) 自动写入一条账单（收入/支出）

moneywiz-cli "/path/to/ipadMoneyWiz.sqlite" \
  --add-transaction \
  --kind expense \
  --account-id 4928 \
  --amount 39.9 \
  --desc "午餐" \
  --notes "工作日午餐" \
  --datetime "2026-03-06 12:30:00"

安全保护说明：

默认会做写锁预检查（BEGIN IMMEDIATE），若无法获取写锁会拒绝写入

默认会在写入前自动备份数据库

默认禁止直接写 MoneyWiz 主库（容器目录下的数据库）

若你确认风险并要写主库，需要显式加 --allow-main-db-write

参数说明（自动记账）：

--add-transaction：启用写入模式
--kind：expense（支出）或 income（收入）
--account-id：目标账户 ID
--amount：金额（传正数）
--desc：账单描述
--desc：账单描述（可为空字符串，建议尽量提供可读内容）
--notes：备注（可选）
--category：分类名称（可选，会匹配现有分类并写入分类关联）
--datetime：交易时间（可选，格式 YYYY-mm-dd HH:MM:SS 或 YYYY-mm-dd）
--input-timezone：--datetime 的输入时区（默认 Asia/Shanghai），写库统一按 UTC0 计算
--dedupe-window-seconds：去重窗口秒数（默认 600）
--audit-log-path：审计日志路径（默认 ~/.moneywiz_api/auto_bookkeeping.jsonl）
--allow-main-db-write：允许写主库（默认禁用）
--skip-sidecar-check：跳过写锁预检查（不建议）
--backup-before-write / --no-backup-before-write：写前是否备份（默认开启）
--backup-dir：备份目录（默认 ~/.moneywiz_api/backups）
--trigger-sync：写入成功后触发同步命令
--sync-command：同步命令（可不传，读取环境变量 MONEYWIZ_SYNC_COMMAND）
--sync-timeout-seconds：同步命令超时时间（默认 60 秒）
--sync-mode：同步模式，applescript（默认）或 command
--sync-wait-seconds：applescript 模式下打开 MoneyWiz 后等待秒数（默认 20）
--sync-wait-mode：applescript 等待模式，stateful（默认）或 fixed
--sync-poll-interval-seconds：stateful 模式轮询间隔（默认 2 秒）
--sync-stable-cycles：stateful 模式判定完成所需连续稳定次数（默认 3）

3) 查看自动记账审计日志

moneywiz-cli "/path/to/ipadMoneyWiz.sqlite" --show-auto-logs --last 50

4) 写入后触发同步

你可以在写入成功后自动执行一个本机同步命令，把新增账单同步到云端，再让其他设备拉取。

moneywiz-cli "/path/to/ipadMoneyWiz.sqlite" \
  --allow-main-db-write \
  --add-transaction \
  --kind expense \
  --account-id 1683 \
  --amount 12.8 \
  --desc "午餐" \
  --trigger-sync \
  --sync-mode applescript \
  --sync-wait-mode stateful \
  --sync-timeout-seconds 60

applescript 模式会自动执行：打开 MoneyWiz -> 等待 -> 退出。

stateful 等待模式会轮询同步状态（ZSYNCCOMMAND.ZISPENDING），尽量在“同步空闲”后立即关闭，而不是固定睡眠。若超时仍未空闲，则按失败处理并保留审计信息。

CLI 写入交易时会同步写入 ZSYNCCOMMAND 交易对象命令（ZOBJECTTYPE=1），用于更接近 MoneyWiz 的同步队列行为。

applescript 模式会自动探测本机已安装的 MoneyWiz（优先 Setapp 版本），无需用户手动提供 app 名称或 bundle id。

如需自定义命令，可切换到 command 模式：

moneywiz-cli "/path/to/ipadMoneyWiz.sqlite" \
  --allow-main-db-write \
  --add-transaction ... \
  --trigger-sync \
  --sync-mode command \
  --sync-command "open -a MoneyWiz"

也可通过环境变量提供同步命令：

export MONEYWIZ_SYNC_COMMAND="open -a MoneyWiz"

然后写入时只传 --trigger-sync。

注意：--sync-command 是本机 shell 命令，请只配置你信任的命令。

安全保护：写账单前会检查 MoneyWiz 进程是否正在运行；若在运行会拒绝写入，避免库冲突。

去重与审计机制

写入前按“同时间窗口 + 同金额（容差 0.01）”做去重（不区分账户）
命中重复时不会写入新记录，会返回并记录已有交易 ID
每次写入（成功/失败）都会写入 JSONL 审计日志

审计日志字段示例：

status：success / failed
action：inserted / deduplicated
created_id、created_gid
kind、account_id、amount、description、notes
transaction_datetime、db_path

安全建议

建议先在数据库副本上测试自动记账流程
正式写主库前请先备份
自动化场景建议保留审计日志，便于复盘与问题排查

质量检查与测试

ruff check .
ruff format .
mypy src
pytest tests

单个测试示例：

pytest tests/unit/test_dummy.py::test_dummy

贡献

项目仍在持续完善，欢迎 Issue 和 PR。

AI 调用专用模板

下面内容可直接提供给 AI 助手（如你的自动化 Agent）作为执行规范。

1) 固定执行原则

只使用 --add-transaction 写入“收入/支出”两类账单
金额始终传正数，支出/收入由 --kind 决定
默认带上去重参数，避免重复截图导致重复入账
默认写审计日志，确保每次写入都有留痕
对无法确认的信息（如账户 ID）先报错并提示，不要猜测写入

2) 建议命令模板

moneywiz-cli "/path/to/ipadMoneyWiz.sqlite" \
  --add-transaction \
  --kind "<expense|income>" \
  --account-id <账户ID> \
  --amount <正数金额> \
  --desc "<账单描述>" \
  --category "<分类名，可选>" \
  --notes "<备注，可为空>" \
  --datetime "<YYYY-mm-dd HH:MM:SS，可选>" \
  --dedupe-window-seconds 600 \
  --audit-log-path "~/.moneywiz_api/auto_bookkeeping.jsonl"

建议流程（OCR 场景）：

由 Agent 先读取数据库并做分类预测
若置信度高，写入时传 --category
若置信度低，不传 --category，后续手工补分类
如需多设备同步，在写入命令中增加 --trigger-sync

多条账单批量写入规则（重要）：

当同一张截图识别出多条账单时，AI 应逐条执行写入命令
前 N-1 条写入命令不要带 --trigger-sync
仅最后一条写入命令带 --trigger-sync（并按需带 --sync-mode applescript）
这样可减少重复拉起/关闭 MoneyWiz，提高稳定性并降低冲突概率

3) AI 输出规范（建议）

AI 在执行后应输出：

本次操作：inserted 或 deduplicated
交易 ID：created_id
关键参数回显：kind/account_id/amount/desc/datetime
审计日志路径

如果失败，输出：

错误原因
未写入确认
建议修复动作（例如账户 ID 不存在、时间格式错误等）

4) 常见错误处理

--amount must be a positive number：金额需传正数
Account <id> not found or has no currency：账户 ID 不存在或账户币种为空
--kind/--account-id/--amount/--desc is required：缺少必填参数
Skipped duplicate...：命中去重，未重复写入，属于正常行为
检测到你正在写 MoneyWiz 主库...：默认安全策略阻止主库写入，可先用副本验证
数据库当前无法获取写锁...：库可能仍被占用，请先关闭 MoneyWiz 后重试

5) 日志查询模板

moneywiz-cli "/path/to/ipadMoneyWiz.sqlite" \
  --show-auto-logs \
  --last 50 \
  --audit-log-path "~/.moneywiz_api/auto_bookkeeping.jsonl"

可据此让 AI 做二次分析（例如统计最近 7 天自动记账金额、查找失败记录、筛选重复命中记录等）。

AI 使用规范流程（推荐）

适用于“截图 OCR -> AI 解析 -> 调用 CLI 自动记账”的端到端流程。

字段抽取

从截图中提取：kind（收入/支出）、amount、description/merchant、time、account
若缺失关键字段（如金额或账户），AI 应终止写入并返回缺失信息

分类处理

由 Agent 读取 DB 后进行分类预测
若置信度高：写入命令带 --category
若置信度低：不传 --category，备注中标记“待分类”

写入执行

单条账单：直接执行 --add-transaction
多条账单：按时间顺序逐条执行，依赖内置去重保护

同步触发（多条场景重点）

前 N-1 条写入命令：不要带 --trigger-sync
最后一条写入命令：带 --trigger-sync
推荐 --sync-mode applescript --sync-wait-seconds 20

审计与回执

每次写入后记录审计日志（JSONL）
AI 回执至少包含：action（inserted/deduplicated）、created_id、amount、desc、category、sync_status
失败时返回：错误原因 + 未写入确认 + 建议修复动作

Agent 初始化问询流程（首次接入）

用于让 AI Agent 在第一次接入你的记账流程时完成必要配置，减少后续反复确认。

数据库与环境确认

确认 MoneyWiz 主库绝对路径
确认是否允许写主库
可选：先用测试库演练 1~3 笔

写入安全策略

写入前若检测到 MoneyWiz 正在运行，默认中止并提醒关闭
开启写前自动备份（推荐）
确认备份目录（默认 ~/.moneywiz_api/backups）

账户映射设置

设置默认支出账户（账户名或 ID）
设置默认收入账户（账户名或 ID）
OCR 未识别到账户时是否自动用默认账户（推荐：是）

分类处理策略

分类预测由 Agent 端读取数据库后完成
置信度高时传 --category
置信度低时不传 --category，在备注标记“待分类”

去重参数设置

当前规则：同时间窗口内金额相同即判重
确认 --dedupe-window-seconds（默认 600）

同步策略设置

是否启用写后自动同步
推荐：--sync-mode applescript
确认 --sync-wait-seconds（默认 20）
多条账单场景：仅最后一条带 --trigger-sync

审计与回执规范

确认审计日志路径（默认 ~/.moneywiz_api/auto_bookkeeping.jsonl）
成功回执最少包含：action、created_id、amount、desc、category、sync_status
失败回执必须包含：错误原因、未写入确认、修复建议

OCR 输入执行规则

同一截图多条账单：按时间顺序逐条写入
前 N-1 条不触发同步，最后一条触发同步
关键字段缺失（金额/账户）时，中止该条并输出缺失项

首次联调步骤

先做 1 笔单条写入联调（含同步与审计）
再做 1 次多条批量联调（仅最后一条同步）
通过后切换正式自动化

初始化配置模板（可让 Agent 持久化）

moneywiz:
  db_path: "/ABS/PATH/ipadMoneyWiz.sqlite"
  allow_main_db_write: true
  backup_before_write: true
  backup_dir: "~/.moneywiz_api/backups"
  audit_log_path: "~/.moneywiz_api/auto_bookkeeping.jsonl"

defaults:
  expense_account_id: 1683
  income_account_id: 1683
  dedupe_window_seconds: 600

classification:
  mode: "agent_predict"
  low_confidence_action: "skip_category"
  low_confidence_note_tag: "待分类"

sync:
  enabled: true
  mode: "applescript"
  wait_seconds: 20
  trigger_on_last_item_only: true

execution:
  stop_if_moneywiz_running: true
  require_fields: ["kind", "amount", "account_id", "description"]

CLI 与 Agent 责任划分

为保证稳定性与可维护性，建议采用“Agent 负责智能决策，CLI 负责安全执行”的边界。

CLI 负责（执行层）

参数化写入账单（收入/支出）
账单字段落库：账户、金额、描述、备注、时间、收付款对象、分类（可选）
去重控制（同时间窗口 + 同金额）
写入安全保护：
- 检查 MoneyWiz 进程是否运行
- 写锁预检查
- 主库写入显式开关
- 写前备份
审计日志落盘（成功/失败/去重/同步结果）
同步触发（applescript 或 command）

Agent 负责（智能层）

OCR 结果解析与结构化（商家、金额、时间、账户线索）
交易类型判断（收入/支出）
账户映射（自然语言到账户 ID）
分类预测（读取数据库后推断，支持模糊场景）
多条账单编排（前 N-1 条不触发同步，最后一条触发同步）
失败重试策略与用户交互（缺失字段、冲突、人工确认）

交互契约（推荐）

Agent 给 CLI：只传“确定字段”，不做越权数据库操作
CLI 给 Agent：返回结构化执行结果（inserted/deduplicated/failed + id + 错误）
Agent 再给用户：人类可读总结 + 下一步建议

已验证可同步模板（推荐给 Agent）

以下模板已在本机（Setapp 版 MoneyWiz）验证可触发云端同步，可作为 Agent 默认命令。

PYTHONPATH="/Users/dengxuhui/Work/Personal/moneywiz-api/src" \
python3 -m moneywiz_api.cli.cli \
  "/Users/dengxuhui/Library/Containers/com.moneywiz.personalfinance-setapp/Data/Documents/.AppData/ipadMoneyWiz.sqlite" \
  --allow-main-db-write \
  --add-transaction \
  --kind "<expense|income>" \
  --account-id <账户ID> \
  --amount <正数金额> \
  --payee-id <收付款对象ID> \
  --desc "<描述，可空字符串>" \
  --category "<分类名，可选>" \
  --datetime "<YYYY-mm-dd HH:MM:SS>" \
  --input-timezone "Asia/Shanghai" \
  --trigger-sync \
  --sync-mode applescript \
  --sync-wait-mode stateful \
  --sync-timeout-seconds 90

说明：

PYTHONPATH=.../src 是为了在未全局安装 CLI 的环境中直接调用模块。
--sync-wait-mode stateful 优先按同步状态关闭应用，而非固定等待。
--sync-timeout-seconds 90 建议作为默认超时，兼容慢网络。

批量多条账单执行规范（强制）

同一截图识别出多条账单时，按顺序逐条写入。
前 N-1 条：不要加 --trigger-sync。
最后一条：加 --trigger-sync --sync-mode applescript --sync-wait-mode stateful。

批量模式（一次性传多条给 CLI）

可通过 --batch-file 或 --batch-json 一次提交多条账单， CLI 内部会逐条写入，并按 --batch-sync-last-only（默认）仅在最后触发一次同步。

示例（文件方式）：

PYTHONPATH="/Users/dengxuhui/Work/Personal/moneywiz-api/src" \
python3 -m moneywiz_api.cli.cli \
  "/Users/dengxuhui/Library/Containers/com.moneywiz.personalfinance-setapp/Data/Documents/.AppData/ipadMoneyWiz.sqlite" \
  --allow-main-db-write \
  --add-transaction \
  --batch-file "/path/to/batch.json" \
  --input-timezone "Asia/Shanghai" \
  --trigger-sync \
  --sync-mode applescript \
  --sync-wait-mode stateful \
  --sync-timeout-seconds 90

batch.json 格式：

[
  {
    "kind": "expense",
    "account_id": 1683,
    "amount": 12.8,
    "payee_id": 3856,
    "desc": "午餐",
    "category": "餐饮",
    "notes": "第一条",
    "datetime": "2026-03-07 12:30:00"
  },
  {
    "kind": "expense",
    "account_id": 1683,
    "amount": 8.5,
    "payee_id": 3856,
    "desc": "咖啡",
    "category": "饮品",
    "notes": "第二条",
    "datetime": "2026-03-07 15:20:00"
  }
]

失败重试规范（推荐）

写入失败：修复参数后重试该条，不要跳过。
写入成功但同步失败：仅重试“最后一条同步步骤”。
若连续 2 次同步失败：停止自动化并提示人工检查 MoneyWiz 状态/网络。

Agent 回执字段（建议）

bookkeeping_status: success|failed
sync_status: success|failed|skipped
action: inserted|deduplicated
created_id
amount
desc
category
audit_log_path

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github		.github
.vscode		.vscode
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MoneyWiz-API

功能概览

安装

快速开始（Python）

CLI 使用

1) 启动交互式只读 Shell

2) 自动写入一条账单（收入/支出）

3) 查看自动记账审计日志

4) 写入后触发同步

去重与审计机制

安全建议

质量检查与测试

贡献

AI 调用专用模板

1) 固定执行原则

2) 建议命令模板

3) AI 输出规范（建议）

4) 常见错误处理

5) 日志查询模板

AI 使用规范流程（推荐）

Agent 初始化问询流程（首次接入）

初始化配置模板（可让 Agent 持久化）

CLI 与 Agent 责任划分

CLI 负责（执行层）

Agent 负责（智能层）

交互契约（推荐）

已验证可同步模板（推荐给 Agent）

批量多条账单执行规范（强制）

批量模式（一次性传多条给 CLI）

失败重试规范（推荐）

Agent 回执字段（建议）

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

MoneyWiz-API

功能概览

安装

快速开始（Python）

CLI 使用

1) 启动交互式只读 Shell

2) 自动写入一条账单（收入/支出）

3) 查看自动记账审计日志

4) 写入后触发同步

去重与审计机制

安全建议

质量检查与测试

贡献

AI 调用专用模板

1) 固定执行原则

2) 建议命令模板

3) AI 输出规范（建议）

4) 常见错误处理

5) 日志查询模板

AI 使用规范流程（推荐）

Agent 初始化问询流程（首次接入）

初始化配置模板（可让 Agent 持久化）

CLI 与 Agent 责任划分

CLI 负责（执行层）

Agent 负责（智能层）

交互契约（推荐）

已验证可同步模板（推荐给 Agent）

批量多条账单执行规范（强制）

批量模式（一次性传多条给 CLI）

失败重试规范（推荐）

Agent 回执字段（建议）

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages