Actual Budget 26.4.0 发布详解同日交易拖拽排序、同心圆环图、Payee 位置实验与 Actual CLI【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActualactual一个 local-first 的个人财务管理应用在 2026 年 4 月发布了 v26.4.0。本次版本延续了 Actual 一贯高频迭代、体验优先的节奏除了大量 Bug 修复与依赖维护外还带来了一批直接影响日常记账体验的功能同日交易的拖拽排序、报表模块的同心圆环图Concentric Donut、更聪明的支付对象/分类自动补全算法以及两个重量级实验特性——Payee Locations按地理位置推荐收款人与Actual CLI命令行访问预算数据。本文以发布说明packages/docs/blog/2026-04-06-release-26-4-0.md为骨架结合仓库源码逐项拆解这些能力的实现原理与使用方式帮助读者快速评估是否升级并掌握新特性的正确打开方式。版本信息Docker Tag26.4.0Versionv26.4.0发布于 2026-04-05。升级前必读本次版本带来的四个核心变化类别能力定位新功能同日交易拖拽排序正式特性新功能同心圆环图分类组外环正式特性增强支付对象/分类自动补全分层排序算法正式特性实验特性Payee Locations按地点推荐支付对象Experimental实验特性Actual CLI命令行预算工具Experimental文档入口见 packages/cli/README.md其中拖拽排序、同心圆环图与自动补全升级属于打开即用的体验改进两个实验特性则需要用户主动在设置中开启或按文档单独部署下面分章节深入。同日交易的拖拽排序更符合直觉的记账顺序调整功能背景在个人记账中同一天的交易先后顺序往往有实际含义例如先消费、后报销。此前 Actual 调整同一天内交易顺序的方式不够直观v26.4.0 引入了拖拽排序能力当多笔交易共享同一天date时可以直接用鼠标拖动调整它们的展示与结算顺序。源码中的实现证据该功能由 PR #6653 合入核心改动位于桌面客户端交易表格相关组件中。从仓库结构看交易表格的渲染与交互集中在 packages/desktop-client/src/components/transactions 目录拖拽能力依赖同一日期分组内的行重排而排序结果最终会写回交易数据随 Actual 的 CRDT 同步机制传播到其他设备。使用要点仅当多笔交易日期完全相同时才可拖拽重排这是设计上为了避免与跨日排序逻辑冲突拖拽排序后请观察排序字段的变化——排序会持久化到该日期分组内若配合显示运行余额running balance使用重排会实时影响余额计算链路。同心圆环图自定义报表中的分类组外环功能背景Actual 的报表模块此前以单层环形图Donut为主。v26.4.0 引入同心圆环图Concentric Donut内环展示分类category的占比外环展示对应分类组category group的聚合占比让用户在一个图里同时看到明细与分组结构适合预算分析、支出结构复盘等场景。该能力仅用于自定义报表Custom Reports。源码实现解析实现集中在 packages/desktop-client/src/components/reports/graphs/DonutGraph.tsx图组件基于 Recharts 的 PieChart 叠加多个环通过outerRadius外半径与chartInnerRadius内半径参数控制同心环的层叠关系分类组外环通过计算聚合值得到报表配置层如 ReportOptions.ts决定内环与外环的数据维度图例与 Tooltip 也随同心结构做了适配选中内环可联动高亮对应的外环分段。使用要点进入报表 → 新建/编辑自定义报表图表类型选择环形图Donut并开启分类组外环Concentric选项内环按分类展示外环按分类组聚合展示若数值较大导致内环拥挤可配合本次同步修复的预算分析报表 padding 优化PR #7118获得更好的排版。更聪明的自动补全分层排序的分支补全算法功能背景支付对象payee与分类category下拉框是 Actual 最高频的交互入口。此前补全结果排序相对简单v26.4.0 引入**分层排序tiered ranking**算法PR #6972显著提升命中率——输入关键词时名称本身命中的结果排在仅组名命中的结果之前并且补全时保持大小写不敏感。源码实现解析以分类补全为例排序逻辑位于 packages/desktop-client/src/components/autocomplete/filterCategorySuggestions.ts使用fzf模糊匹配库对候选做评分rankMatcheslimit: 100、casing: case-insensitive第一层按item.name分类名直接匹配并排名第二层对未命中第一层的候选按item.group.name item.name组名分类名拼接再次匹配排名最终结果 分类名命中 组名命中截取前 100 条并把特殊的split拆分交易入口固定在首位。同样的算法也应用于支付对象补全autocomplete 目录下的PayeeAutocomplete、CategoryAutocomplete等配合针对账户场景的过滤逻辑共同工作。配套测试见 filterCategorySuggestions.test.ts其中明确断言分类名命中应排在仅组名命中的结果之上。使用要点直接输入分类或支付对象关键词即可体验新排序无需任何配置分类名优先、组名兜底的设计意味着输入Food时名为 Food 的分类会排在Food Drink 组其他分类之前本次同步修复了移动端补全需点两次才能选中的 BugPR #7166移动端体验一并改善。实验特性一Payee Locations——基于地理位置的支付对象推荐功能背景这是 v26.4.0 引入的实验特性MVPActual 会记住你在某地使用过的支付对象payee此后当你身处附近时在新增交易时优先推荐附近用过的支付对象。典型场景是线下消费——你在同一商圈反复消费的商户会被智能地优先提示。该能力同时支持YNAB5 数据导入PR #6157。数据模型与迁移位置数据由新迁移 1768872504000_add_payee_locations.sql 引入payee_locations表CREATE TABLE IF NOT EXISTS payee_locations ( id TEXT PRIMARY KEY, payee_id TEXT, latitude REAL, longitude REAL, created_at INTEGER, tombstone INTEGER DEFAULT 0 );并配套三个索引idx_payee_locations_payee_id按支付对象快速查找idx_payee_locations_tombstone_payee_created时间维度查询按tombstone, payee_id, created_at复合索引idx_payee_locations_geo_tombstone地理空间复合索引tombstone, latitude, longitude服务于附近支付对象查询。删除采用软删除tombstone标记与 Actual 同步模型保持一致。服务端 API 与距离计算服务端实现在 packages/loot-core/src/server/payees/app.ts暴露了 4 个新方法方法说明payee-location-create记录一条位置payeeId latitude longitudepayee-locations-get查询某支付对象的位置可按payeeId过滤按created_at倒序payee-location-delete软删除一条位置payees-get-nearby查询附近支付对象关键设计点坐标校验createPayeeLocation与getNearbyPayees都会校验经纬度范围纬度 -90~90经度 -180~180非法坐标直接抛错默认半径getNearbyPayees的默认maxDistance来自 packages/loot-core/src/shared/constants.ts 中的DEFAULT_MAX_DISTANCE_METERS 500即默认检索 500 米范围内的支付对象Haversine 距离附近查询使用 Haversine 公式计算球面距离单位米并用 SQL 窗口函数ROW_NUMBER() OVER (PARTITION BY payee_id ORDER BY distance)为每个支付对象只保留最近的一条位置distance_rank 1最终按距离升序返回最多 10 条返回结果同时携带支付对象实体与其最近位置含distance字段。开启与使用由于是实验特性需要在 Actual 的实验功能设置中开启对应开关后续版本可能调整入口以实际界面为准。启用后系统会在交易发生地自动或按提示记录支付对象位置在新交易输入支付对象时若当前坐标附近存在历史支付对象候选列表会优先展示它们从 YNAB5 导入的数据若包含位置信息会一并写入导入实现在 packages/loot-core/src/server/importers/ynab5.ts。注意位置数据涉及隐私开启前请确认你接受 Actual 在本地存储经纬度信息该数据随预算文件同步仅保存在你自己的服务端。实验特性二Actual CLI——用命令行访问你的预算功能背景Actual CLIPR #7208是 v26.4.0 最受关注的新工具一个独立的命令行程序用于查询和修改预算数据——账户、交易、分类、支付对象、规则、日程、标签等。发布说明特别指出它对 AI Agent 非常有用因为它允许脚本和 Agent 以结构化方式与预算交互。安装与快速开始CLI 以独立 npm 包发布packages/cli需要 Node.js 22npm install -g actual-app/cliCLI 连接的是运行中的 Actual sync server不会直接操作本地预算文件。快速开始# 配置连接信息 export ACTUAL_SERVER_URLhttp://localhost:5006 export ACTUAL_PASSWORDyour-password export ACTUAL_SYNC_IDyour-sync-id # 在 设置 → 高级 → Sync ID 中获取 # 列出账户 actual accounts list # 查询余额 actual accounts balance account-id # 查看某月预算 actual budgets month 2026-03配置体系优先级与环境变量配置解析优先级从高到低CLI flags → 环境变量 → 配置文件cosmiconfig→ 默认值。核心环境变量如下变量说明ACTUAL_SERVER_URLActual sync server 地址必填ACTUAL_PASSWORD服务端密码使用 token 时可省略ACTUAL_SESSION_TOKEN会话 Token密码的替代方案ACTUAL_SYNC_ID预算 Sync ID多数命令必填ACTUAL_DATA_DIR本地缓存目录ACTUAL_CACHE_TTL缓存 TTL秒默认 60ACTUAL_LOCK_TIMEOUT预算目录锁等待超时秒默认 10ACTUAL_NO_LOCK设为1时禁用目录锁配置文件支持.actualrcJSON/YAML、.actualrc.json/.yaml/.yml、actual.config.*、package.json中的actual键以及全局配置目录如 Linux 的~/.config/actual/下的config系列文件。示例 packages/cli/README.md{ serverUrl: http://localhost:5006, password: your-password, syncId: 1cfdbb80-6274-49bf-b0c2-737235a4c81f, cacheTtl: 60, lockTimeout: 10, noLock: false }安全提醒不要在配置文件里存明文密码优先使用ACTUAL_PASSWORD/ACTUAL_SESSION_TOKEN环境变量或会话 Token若必须写入文件请设置 600 权限并加入.gitignore。全局 Flags 与常用命令全局 Flags 与 README 完全对应--server-url、--password、--session-token、--sync-id、--data-dir、--cache-ttl、--refresh/--no-cache、--lock-timeout、--no-lock、--formatjson/table/csv、--verbose这些选项在 packages/cli/src/index.ts 中通过 Commander 注册且支持从ACTUAL_ENCRYPTION_PASSWORD读取端到端加密密码。支持的命令族每个命令可用actual command --help查看子命令命令说明accounts账户管理budgets预算与分配管理categories/category-groups分类 / 分类组管理transactions交易管理payees支付对象管理tags标签管理rules交易规则管理schedules日程交易管理query运行 ActualQL 查询server服务端工具与 ID 查询sync刷新/检查本地缓存实战示例# 列表输出为表格默认排除已关闭账户 actual accounts list [--include-closed] --format table # 按名称查实体 ID actual server get-id --type accounts --name Checking # 新增一笔交易金额为整数分-2500 -$25.00 actual transactions add --account id \ --data [{date:2026-03-14,amount:-2500,payee_name:Coffee Shop}] # 导出交易为 CSV actual transactions list --account id \ --start 2026-01-01 --end 2026-12-31 --format csv transactions.csv # 设置预算金额$500 50000 分 actual budgets set-amount --month 2026-03 --category id --amount 50000 # 运行 ActualQL 查询 actual query run --table transactions \ --select date,amount,payee --filter {amount:{$lt:0}} --limit 10金额约定输入flag / JSON一律使用整数分5000 $50.00-12350 -$123.50table/csv输出会自动转为十进制如1665.00json输出保持原始分供程序使用。缓存与并发模型CLI 会在本地缓存一份预算副本packages/cli/src/cache.tsTTL 内默认 60s的读命令list、balance、query run直接复用缓存不发起网络请求写命令add、update、set-amount等写前写后都会与服务端同步actual sync立即刷新缓存actual sync --status查看缓存新鲜度actual sync --clear删除缓存--refresh/--no-cache单次强制同步。并发安全CLI 对每个预算的缓存目录采用读共享锁 写排他锁packages/cli/src/lock.ts。多个并发读安全写操作串行若锁被占用最多等待--lock-timeout默认 10s后报错。仅在可信的单进程场景下使用--no-lock。常见坑与建议拆分交易统计/求和时过滤is_parent: false避免父子都计入导致总额翻倍父交易持有总金额子交易持有各部分高频脚本先actual sync一次再用长--cache-ttl如 3600做批量读未分类交易category.name为null过滤/分组时需处理AQL 无日期子字段date.month、date.year等不可作为查询字段需要按月份聚合时请取原始交易并在脚本内自行聚合。值得关注的增强与修复速览除上述主线外v26.4.0 还有一批高价值改动功能增强节选拆分交易金额支持公式规则Formula RulesPR #6414月度预算单元格支持添加备注PR #6620自定义报表 widget 新增预算额类型PR #6903报表新增BUDGET_QUERY与QUERY_EXTRACT公式函数PR #7078用于基于公式的预算分析新增新台币TWD币种PR #7095文件导入支持交换 payee/memo 字段PR #7101、支持仅导入自某日期之后的交易PR #7139、支持控制已删除/合并交易是否重新导入PR #6926自定义主题系统主题分离亮/暗选项、支持文本域自定义覆盖、支持自定义字体PR #7145 / #7236 / #7239 / #7194并新增 Notion 风格暗色主题PR #7151Electron 备份改为 zip metadata.json便于直接导入PR #7069修改密码增加管理员与密码认证要求PR #7207并修复了对应的提权漏洞PR #7155合并支付对象增加确认弹窗PR #7188。关键修复节选多标签页同步通过 SharedWorker 共享单一后端修复多标签同步问题PR #7172CSV 导入修复 Excel 导出金额含尾随空白导致解析错误PR #7149数字格式化千位分隔符统一规范为 U2019右单引号消除 Node/ICU 版本差异PR #7179移动端运行余额即将到来的交易按设置显示运行余额PR #7041修复交易日安排跳过周末前进问题PR #7057、合并交易丢失日程链接PR #7177、银行同步后balance_current未同步给 API 客户端PR #7243、OIDC 开启时密码登录失效PR #7334等一批影响日常使用的问题。工程与维护将 loot-core 发布为actual-app/core包PR #7200全面转向 TypeScript 项目引用composite referencesPR #7062 / #7180升级 TypeScript 编译器到 tsgoPR #7183升级 Vite 8PR #7184移除 API 与 loot-core 之间的循环依赖PR #6809、YNAB 导入器不再依赖 API 包PR #7050。升级建议与注意事项升级路径自托管用户将 Docker Tag 更新为26.4.0即可注意本次修复了 Docker 镜像获取迁移文件的 BugPR #7146实验特性谨慎开启Payee Locations 涉及位置数据存储请评估隐私影响后再启用Actual CLI 面向自动化场景建议先在测试预算上验证脚本备份可迁移Electron 备份格式已变为 zip metadata.json旧版本生成的备份仍可导入新格式则让导入更可靠关注依赖与工具链本次同步修复了多个依赖的安全漏洞axios 固定 1.14.0、express-rate-limit、handlebars、node-forge 等升级自托管用户应尽快升级以获得安全修复。无论是普通用户看重的记账体验优化还是面向自动化与 Agent 的 CLI 能力v26.4.0 都交出了一份扎实的答卷。想深入了解 CLI 的全部子命令可直接阅读 packages/cli/README.md想从源码层面理解同心环图、补全算法与附近支付对象查询的实现可分别查看 DonutGraph.tsx、filterCategorySuggestions.ts 与 payees/app.ts。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考