通过官方 Node.js API 管理自托管 Actual Budget 实例，支持预算查询、交易导入/导出、账户管理、分类规则及银行同步，适合注重隐私的个人财务管理自动化。
说明：
## 核心用法
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`）控制版本。
会员专属
