核心用法
Actual Budget 技能基于官方 @actual-app/api Node.js 包，为用户提供完整的个人财务管理自动化能力。核心工作流程包括：初始化 API 连接 → 下载预算文件 → 执行查询或修改操作 → 按需同步 → 安全关闭连接。所有敏感凭证均通过环境变量注入，确保密码、同步 ID 和加密密钥不会硬编码在脚本中。
API 采用整数分（cents）作为金额单位，日期格式为 YYYY-MM-DD，支持通过 getIDByName 按名称查找 UUID 资源。主要功能模块涵盖：多账户余额查询与创建、交易批量导入导出（支持拆分交易）、分类与收款人管理、预算金额设定与月度结转、自动化规则引擎（基于条件的交易分类）、定期账单计划（Schedules）以及银行同步接口。
ActualQL 查询语言提供类似 MongoDB 的过滤语法，支持 $eq、$like、$regex 等操作符，可进行分组聚合与复杂筛选。对于迁移场景，runImport 辅助函数支持批量创建账户并导入历史交易数据。
显著优点
隐私优先的自托管架构：与云端财务软件不同，Actual Budget 完全运行于用户自有服务器，杜绝第三方数据收集风险，适合对数据主权敏感的用户。
官方 API 保障稳定性：直接调用官方维护的 npm 包，而非逆向工程或第三方封装，API 行为与官方文档一致，长期兼容性有保障。
全面的功能覆盖：从基础的增删改查到复杂的规则引擎、拆分交易、定期账单管理，功能深度接近专业会计软件，满足进阶用户需求。
环境变量安全模型：强制通过 ACTUAL_SERVER_URL、ACTUAL_PASSWORD 等环境变量传递凭证，配合文件权限控制，降低密钥泄露风险。
ActualQL 灵活查询：声明式查询接口避免了大量样板代码，复杂财务分析（如按分类月度汇总、模糊搜索收款人）可单行实现。
潜在缺点与局限性
Node.js 运行时依赖：必须在具备 Node.js 的环境中执行，无法直接在浏览器或纯 Python 环境中运行，增加了部署复杂度。
自托管运维成本：用户需自行维护 Actual Budget 服务器，包括备份、SSL 证书配置、版本更新，技术门槛高于 SaaS 方案。
同步机制的理解成本：downloadBudget 与 sync 的调用时机需严格遵循文档，误用可能导致数据冲突或丢失，尤其在多客户端并发场景。
金额单位易出错：整数分的表示方式（$50.00 → 5000）与常规浮点运算习惯相悖，转换疏忽会导致数量级错误。
银行同步的稳定性：依赖 Actual Budget 内置的银行聚合服务，支持范围与稳定性受第三方银行接口制约，部分金融机构可能不兼容。
适合人群
- 隐私敏感型用户：拒绝将财务数据存储于云端，具备自托管技术能力的个人或小家庭
- 自动化爱好者：希望通过脚本实现定期报表生成、交易自动分类、预算超支警报等 workflow 的用户
- 多账户复杂场景用户：拥有投资、信用卡、现金等多账户，需要统一视图与跨账户转账追踪的进阶预算管理者
- 数据迁移需求者：从 Mint、YNAB 等平台迁出，需要批量导入历史数据的用户
常规风险
凭证管理风险：虽然环境变量模型较安全，但若 ACTUAL_PASSWORD 或 ACTUAL_ENCRYPTION_PASSWORD 泄露，攻击者可完全访问预算数据。建议配合专用 secrets 管理工具（如 1Password CLI、Bitwarden Secrets Manager）而非裸存于 dotfiles。
数据备份缺失：自托管意味着数据丢失责任自负，需建立独立于 Actual 服务器的异地备份策略（如每日加密快照至对象存储）。
脚本误操作风险： mutating 操作（如批量导入、规则批量创建）缺乏原生撤销机制，生产执行前务必在测试预算验证逻辑。
同步冲突：多设备同时修改预算可能引发合并冲突，自动化脚本应尽量缩短 downloadBudget 到 sync 的时间窗口，避免长时间持有写锁。
依赖供应链风险：@actual-app/api 包及其间接依赖可能引入漏洞，建议通过 npm audit 与锁定文件（package-lock.json）控制版本。