Actual Budget

核心用法

Actual Budget API 是开源记账软件 Actual Budget 的官方 Node.js SDK，采用无头模式运行，通过环境变量配置服务器连接后，可在本地缓存预算数据并执行各类财务操作。主要功能模块包括：预算概览查询（getBudgetMonths/getBudgetMonth）、账户管理（创建/关闭/余额查询）、交易处理（导入支持自动去重和规则匹配、更新、ActualQL 复杂查询）、分类与商家管理、预算金额设定、自动规则（Rules）与定期账单（Schedules），以及 GoCardless/SimpleFIN 银行同步。

显著优点

1. 官方维护：由 Actual Budget 核心团队开发，API 与产品功能同步更新
2. 完整功能覆盖：涵盖个人财务管理的全链路操作，从数据导入到自动化规则
3. ActualQL 查询语言：类似 MongoDB 的链式查询语法，支持分组聚合、模糊搜索等复杂分析
4. 自托管友好：专为私有化部署设计，支持端到端加密和自签名证书
5. 交易去重机制：importTransactions 内置重复检测，适合银行数据自动化导入

潜在缺点与局限性

• 部署门槛高：必须自建 Actual Budget 服务器，配置同步 ID、密码等环境变量
• Node.js 专用：仅限 JavaScript/TypeScript 生态，无 Python/Go 等语言官方支持
• 本地状态管理：需手动处理 init → downloadBudget → shutdown 生命周期，易因遗漏 shutdown 导致资源泄漏
• 金额单位为分：所有金额需整数转换（$1.23 → 123），增加开发心智负担
• 错误处理不透明：部分操作失败时返回信息较简略，需结合服务器日志排查

适合人群

• 已使用或计划自托管 Actual Budget 的技术用户
• 需要将银行数据自动导入预算系统的开发者
• 希望构建个人财务自动化工作流（如定时同步、支出分析报表）的工程师

常规风险

• 凭据泄露风险：ACTUAL_PASSWORD、ACTUAL_ENCRYPTION_PASSWORD 等敏感信息需妥善保管
• 自签名证书误配：若不当禁用 TLS 验证或配置错误的 CA 证书，存在中间人攻击风险
• 数据同步冲突：多客户端同时修改预算可能导致同步冲突，需遵循 sync() 调用规范
• 预算数据本地缓存：ACTUAL_DATA_DIR 目录需设置适当权限，避免其他用户读取财务数据

核心用法

Actual Budget API 是知名开源个人财务管理软件 Actual Budget 的官方 Node.js SDK。该 Skill 为纯文档类型，提供完整的 API 参考和代码示例，涵盖：

• 初始化连接：通过 api.init() 配置服务器地址、密码及本地缓存目录，使用 api.downloadBudget() 加载预算数据
• 预算管理：查询预算月份 (getBudgetMonths)、设置分类预算金额 (setBudgetAmount)、启用余额结转 (setBudgetCarryover)
• 账户操作：创建/关闭账户、查询余额、获取交易列表，支持初始余额设置
• 交易处理：导入交易时自动去重并应用规则，支持拆分交易 (Split Transactions) 和转账操作
• 自动化功能：创建分类规则 (Rules) 实现自动分类，设置定期账单 (Schedules)，运行银行同步 (GoCardless/SimpleFIN)
• 高级查询：ActualQL 支持复杂筛选、分组聚合、模糊搜索，类似 MongoDB 的查询语法

显著优点

1. 官方权威性：来自 Actual Budget 核心团队维护，API 与产品同步更新
2. 本地化优先：预算数据下载到本地缓存，操作后同步回服务器，兼顾性能与数据安全
3. 完整功能覆盖：从基础 CRUD 到银行同步、规则引擎、定期账单，覆盖个人财务全场景
4. 类型安全友好：金额统一使用整数分 (cents)，避免浮点精度问题
5. 银行级同步：原生支持 GoCardless 和 SimpleFIN 开放银行协议
6. 纯文档零风险：无动态代码执行，仅提供参考文档和示例

潜在局限

• Node.js 专属：需 JavaScript/TypeScript 环境，Python 等其他语言用户需自行封装
• 自托管依赖：必须拥有 Actual Budget 服务器实例，无法直接连接云端服务
• 同步 ID 要求：需手动从 Actual Budget 设置中获取 ACTUAL_SYNC_ID，配置门槛较高
• 无内置错误处理：示例代码缺少 try-catch，生产环境需自行完善健壮性
• 版本锁定风险：未注明兼容的 API 版本范围，Actual Budget 更新后可能需要适配

适合人群

• 使用 Actual Budget 进行个人/家庭财务管理的自托管用户
• 希望自动化财务数据导入（如从银行 CSV 或第三方服务）的开发者
• 需要定制财务报告、预算分析或与其他系统集成的技术用户
• 熟悉 Node.js 且重视数据隐私（拒绝云端 SaaS）的隐私敏感型用户

常规风险

• 环境变量泄露：ACTUAL_PASSWORD 和 ACTUAL_ENCRYPTION_PASSWORD 属于高敏感凭证，需在 Claude Code settings.json 或安全环境变量中配置，避免提交到版本控制
• 自签名证书风险：文档提及使用 NODE_EXTRA_CA_CERTS 处理自签名证书，错误配置可能导致中间人攻击
• 数据同步冲突：多客户端同时修改预算时可能产生冲突，需遵循 downloadBudget → 操作 → sync → shutdown 的完整流程
• Amount 单位混淆：所有金额单位为分（5000 = $50.00），混淆可能导致 100 倍误差