Actual Budget API 技术评估
核心用法
Actual Budget 是一款开源的本地优先个人财务管理工具，本 Skill 通过官方 @actual-app/api Node.js 包提供程序化访问能力。主要功能涵盖：预算月度数据查询、多账户管理（创建/关闭/余额查询）、交易记录的批量导入导出与更新、分类与收款人管理、预算金额设定与月度结转、自动化规则引擎配置、周期性账单（Schedule）设置，以及可选的银行同步功能。
技术实现上，Skill 要求用户通过环境变量提供服务器地址、密码和 Sync ID 等凭证，初始化后下载预算文件到本地缓存进行操作。所有金额以整数分（cents）处理，日期遵循 YYYY-MM-DD 格式，支持通过 getIDByName 进行名称到 UUID 的转换。ActualQL 提供类 MongoDB 的查询语法，支持过滤、分组、聚合等复杂数据分析。
显著优点
1. 官方 SDK 保障：使用 npm 官方 @actual-app/api 包，接口稳定性与长期维护有项目背书
2. 本地优先架构：数据完全自托管，规避云服务隐私风险，适合对财务隐私敏感的用户
3. 完整功能覆盖：涵盖个人财务管理的全生命周期，从交易记录到预算分析再到自动化规则
4. 结构化查询能力：ActualQL 支持复杂的数据分析场景，如按分类汇总支出、模糊搜索收款人等
5. 环境隔离设计：强制要求凭证通过环境变量注入，避免硬编码泄露，符合安全最佳实践
潜在局限与风险
- 部署门槛：需自行搭建 Actual Budget 服务器并维护 Node.js 运行时环境，技术门槛高于纯 SaaS 方案
- 凭证管理负担：Sync ID、加密密码等多凭证体系要求用户建立完善的本地 secrets 管理机制
- 无内置回滚机制：API 操作直接修改预算文件，误操作可能导致数据损坏，建议配合 Actual 的备份策略
- 自签名证书复杂性：私有部署场景下 TLS 证书配置可能增加使用摩擦
- 银行同步依赖：该功能需用户自行配置银行连接器，非开箱即用
适合人群
- 已使用或计划迁移至 Actual Budget 的自托管用户
- 需要批量处理历史交易数据、自动化分类规则的效率型用户
- 具备基础 Node.js 运维能力、重视财务数据主权的开发者与技术爱好者
- 希望将个人财务分析集成到自有数据管道的数据工程师
常规风险提示
使用本 Skill 时，务必确保 ACTUAL_PASSWORD 和 ACTUAL_ENCRYPTION_PASSWORD 的存储安全，避免提交至版本控制。执行写入操作（importTransactions、createAccount、setBudgetAmount 等）前，建议先通过只读查询验证数据范围。定期备份 Actual Budget 数据文件，以防 API 操作异常导致预算损坏。对于银行同步功能，需评估银行凭证的存储安全与服务商的合规性。