Actual 预算 API
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/sundial-org-awesome-openclaw-skills-actual-budget。
技能介绍
要解决什么问题
不少团队和个人用 Actual Budget 做本地优先的记账,但日常自动化往往卡在「只能点 Web UI」:批量改分类、按规则对账、从别的 App 迁数据,或把预算快照交给 AI/脚本做分析,都需要可编程入口。官方 Node.js SDK 可以无头运行,在本地缓存与服务器同步后的预算库上操作,而不必为了一个小改动长期挂着浏览器。
技能如何工作
技能围绕 Actual Budget 官方 Node.js API 的用法组织,典型流程是:配置 ACTUAL_SERVER_URL、ACTUAL_PASSWORD、ACTUAL_SYNC_ID 等环境变量 → 完成 Sync 拉取/更新本地数据 → 用 UUID 或 getIDByName(type, name) 解析账户、分类、收款方 → 读写业务对象。
核心能力大致包括:
- 预算与账户:预算总览、各账户余额与明细
- 交易流水线:入账、拆分交易(splits)、账户间 Transfers(通过
transfer_acct找对应 payee) - 分类体系:Categories、Payees,以及 Budget Amounts(月份格式
YYYY-MM) - 规则与排程:Rules、Schedules,配合 Bank Sync 与关停前的 Sync & Shutdown
- ActualQL:复杂筛选时用
$eq、$regex、$oneof等算子,以及.options({ splits: 'inline' | 'grouped' | 'all' }) - 迁移:Bulk Import (New Budget) 从其他应用迁入新账套
金额一律用 分(整数) 表示,例如 $50.00 → 5000;可用 api.utils.amountToInteger(123.45) 转换。日期为 YYYY-MM-DD。
适用边界与注意点
这是 Node.js 环境下的 API 集成技能,不是替代品产品的 SaaS 控制台。自签名证书需视情况设置 NODE_TLS_REJECT_UNAUTHORIZED;若账套启用端到端加密,还要提供 ACTUAL_ENCRYPTION_PASSWORD。本地缓存目录默认当前工作目录,可由 ACTUAL_DATA_DIR 指定。细粒度接口与 ActualQL 语义以官方 API 文档为准;复杂查询另见 ActualQL 文档。
使用场景
- 自建 Actual 服务器后,用脚本在同步后的本地库批量修正错标分类的交易
- 每月关账前用 ActualQL 按账户与日期区间导出待对账流水清单
- 从其他记账 App 导出数据后,通过 Bulk Import 迁入新的 Actual 账套
- 按 Rules 与 Schedules 核对排程入账是否与银行 Sync 结果一致
适合人员
- 自托管 Actual Budget、希望用 Node 脚本改账而不依赖 Web UI 的个人记账者
- 要把多家银行流水按分类规则写入同一 Actual 账套的副业/freelance 记账人
- 负责家庭或小型团队预算、需要按月拉取 Budget Amounts 做汇报的财务协作者
- 从 YNAB/其他工具迁到 Actual、需要 Bulk Import 与 ID 映射文档的迁移实施者