Actual Budget 25.7.0 版本深度解析收入自动结转、银行余额对账与 Ctrl-K 命令栏【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual本文围绕 Actual Budgetlocal-first 个人财务应用25.7.0 正式版展开系统梳理该版本三大核心特性——收入类别自动保留到下月、对账时展示银行同步余额、以及 Ctrl-K/Cmd-K 快捷命令栏并逐一深入到仓库源码前端 React 组件与后端 budget 服务验证其实现原理同时覆盖银行同步解析增强、CLI 新增命令与工程维护项。读完本文你将掌握这些新功能的完整使用方式、底层调用链与配置要点并能快速定位到对应源码继续深入。版本总览Actual Budget 25.7.0Docker tag25.7.0是一次功能密度很高的版本官方发布说明列出了三大亮点选择收入类别自动将其中的资金保留Hold至下一个月对账Reconcile账户时展示最近一次银行同步的余额通过Ctrl-KmacOS 上为Cmd-K打开命令栏实现快速键盘导航。此外从该版本开始所有 NPM 包开始每晚发布 nightly 版本为希望提前试用新功能的用户提供更稳定的测试渠道对应 发布说明 中的描述与 PR #5047 的 nightly 发布工作流。以下逐一展开分析。核心特性一收入类别自动保留到下月Hold for Next Month信封预算法Envelope Budget中本月有剩余收入、希望留到下个月再用是很常见的诉求。25.7.0 将这一操作自动化你可以为收入类别开启自动保留当月的待预算To Budget资金会自动缓冲到未来月份无需每月手动操作。使用入口To Budget 菜单在信封预算的月度预算摘要区域To Budget 面板右键/点击菜单可以看到ToBudgetMenu提供的多个操作项ToBudgetMenu.tsxMove to a category将待预算资金移动到某个类别toBudget 0时显示Hold for next month手动把当前待预算资金全部保留到下月要求autoBuffered 0且toBudget 0Cover from a category待预算为负超支时从某个类别挪用资金覆盖Disable current auto hold存在自动保留forNextMonth 0且手动缓冲为 0时可一键关闭自动保留Reset next months buffer重置下个月的缓冲金额。从源码可见菜单项的显示完全由四个电子表格spreadsheet绑定值驱动toBudget、forNextMonth、manualBuffered、autoBuffered分别代表当前待预算下月可用来自结转手动缓冲与自动缓冲。底层调用链三个后端 action选中Hold for next month后前端会同时触发两个后端方法见 ToBudgetMenu.tsx 的onMenuSelect分支budget/hold-for-next-month→ 后端holdForNextMonthbudget/reset-income-carryover→ 后端resetIncomeCarryover。这两个方法均注册在 app.ts 的 RPC 层并通过mutator(undoable(...))包装因此可被撤销Undo。核心实现位于 actions.tsexport async function holdForNextMonth({ month, amount }) { const row await db.first(SELECT buffered FROM zero_budget_months WHERE id ?, [month]); const sheetName monthUtils.sheetForMonth(month); const toBudget await getSheetValue(sheetName, to-budget); if (toBudget 0) { const bufferedAmount calcBufferedAmount(toBudget, (row row.buffered) || 0, amount); await setBuffer(month, bufferedAmount); return true; } return false; } export async function resetHold({ month }) { await setBuffer(month, 0); }要点holdForNextMonth会先读取zero_budget_months表中的buffered字段即当前月份已缓冲金额再结合实时计算的to-budget值通过calcBufferedAmount计算最终缓冲额并写回数据库。如果toBudget 0本月没有可保留资金方法直接返回false不会产生任何副作用resetHold将缓冲清零对应Reset next months buffer菜单resetIncomeCarryoveractions.ts会遍历所有is_income 1且未删除的类别将其当月收入结转carryover标志批量重置为false从而解开此前收入类别的自动结转状态配合自动保留实现完整闭环。前端配套HoldBufferModal除菜单外前端还有独立的HoldBufferModal组件HoldBufferModal.tsx用于输入/确认缓冲金额并在 modalsSlice.ts 中注册。25.7.0 的一个修复PR #5245还专门同步了HoldBufferModal与TransferModal组件中amount状态与外部值的联动避免金额显示不一致。核心特性二对账时显示银行同步余额月度对账是财务应用的高频操作。此前用户需要手动输入银行当前余额启用银行同步GoCardless 等的用户往往已经同步过最新余额重复输入既繁琐又容易出错。25.7.0 将对账模态框与银行同步数据打通对账时直接展示最近一次同步得到的余额并可一键填入。源码实现Reconcile.tsx对账弹窗组件位于 Reconcile.tsx关键逻辑const clearedBalance useSheetValue({ name: balanceQuery.name -cleared, ... }); const lastSyncedBalance account.balance_current;clearedBalance从电子表格绑定中读取该账户的已清算余额作为默认输入值lastSyncedBalance account.balance_current账户实体上的balance_current字段即最近一次银行同步返回的余额。弹窗中会显示一行上次同步余额lastSyncedBalance非空时渲染并提供Use last synced total使用上次同步总额按钮点击后把该值填入输入框25.7.0 的修复 PR #5241 将这一按钮的样式统一为默认按钮主题视觉上更一致。整个流程由 Account.tsx 驱动用户在弹窗提交金额后调用reconciliation.finishReconciliation(account.id, reconcileAmount, ...)完成对账并更新账户的last_reconciled时间戳Account.tsx。相关修复对账与同步相关的稳定性也得到提升PR #5124 重构了accountsSlice中的账户同步逻辑并改进了syncAndDownload的处理减少对账过程中的同步异常。核心特性三Ctrl-K / Cmd-K 命令栏25.7.0 引入了类似编辑器/IDE 的命令栏Command Bar在任何页面按下Ctrl-KmacOS 为Cmd-K即可呼出一个搜索式导航面板输入关键字即可快速跳转。实现细节基于 cmdk 的 CommandBar组件位于 CommandBar.tsx基于cmdkCommand Menu 组件库实现核心结构快捷键监听CommandBar.tsxif (e.key k (e.metaKey || e.ctrlKey)) { e.preventDefault(); // 若已有模态框打开则不再弹出命令栏 if (modalStack.length 0) return; setOpen(true); }注意一个细节当其他模态框如新建交易弹窗已打开时命令栏会被抑制避免导航状态冲突。可搜索的分组SectionsCommandBar.tsx分组内容NavigationBudget、Reports、Schedules、Payees、Rules、Tags、Settings、All AccountsAccountsOn Budget / Off Budget 汇总行 每个未关闭账户每项右侧实时显示该账户当前余额Reports仪表盘页面Dashboard PagesCustom Reports用户自定义报表HelpTake a tour of Actual启动新手引导账户与报表列表均来自真实数据useAccounts、useReports、useDashboardPages余额则通过CellValue绑定电子表格实时值渲染因此命令栏本身就是一个余额速查面板。搜索为不区分大小写的子串过滤item.name.toLowerCase().includes(searchLower)支持键盘上下选择与 Enter 跳转还开启了vimBindings以便习惯 vim 导航的用户使用CommandBar.tsx。入口挂载CommandBar在 FinancesApp.tsx 中作为应用级组件挂载因此对所有页面全局生效。相关联动修复命令栏之外本版本还修复了若干导航/UI 体验问题底部导航栏滚动时遮挡内容PR #5166、移动端交易列表未占满全高PR #5179、通知显示在模态框之下避免被遮挡PR #5165、iOS 底部 Home Indicator 遮挡按钮PR #5121、交易预览在多账户视图中不显示PR #5135。CLI 新增命令reset-password25.7.0 为 Actual 的 CLI 工具新增了reset-password命令PR #5185允许通过命令行重置服务器/实例的登录密码方便自托管用户在忘记密码或需要应急恢复时使用。该命令属于 packages/cli 中的命令集与accounts、budgets、sync、server等命令并列具体用法可在 CLI 工具的 README 中查看。与此同时桌面端配置服务器界面新增了指向官方文档的引导链接PR #5107降低自托管配置门槛。银行同步与导入增强25.7.0 在银行同步生态上投入了大量工作主要分三类1. 有限历史银行名单扩充GoCardless 等聚合服务对部分银行仅提供有限的交易历史Actual 维护了一张limited history名单本版本新增/更新了LCL法国PR #5087Belfius与KBC Brussels比利时PR #5183BNP_BE_GEBABEBB比利时 BNP Paribas FortisPR #5187。2. 新增/改进银行解析器Boursobank法国GoCardless 交易解析改进PR #5202Raiffeisen Bank Austria奥地利新增 GoCardless 解析器PR #5244修复KBC Brussels使用了错误的payeeNamePR #5193为丹麦Danske Bank分行补充EndToEndID字段裁剪逻辑此前仅挪威分行有此处理PR #5101。3. 导入与链接稳定性改进OFX/QFX 文件兼容性PR #5203并修复YNAB4 拆分交易导入PR #5226GoCardless 初始链接失败时改用后备链接参数重试PR #5150修复交易全选操作在拆分交易子项全部选中时未包含父交易的问题PR #5086。预算、报表与交易修复预算模板修复模板应用到分组PR #5112与目标模板应用PR #5120的问题净资产图修复多个正负值图表并存时的颜色显示PR #5129余额历史图性能优化提速PR #5229侧边栏账户悬停提示新增余额历史变化展示PR #5085跨月与预算类型修复切换预算类型信封/追踪后需硬刷新才生效的问题PR #5253追踪预算的收入预算字段在移动端缺失PR #5251金额输入在appendDecimals前重新应用千位分隔符PR #5220调度Schedules修复调度名称含方括号时与增减修饰符解析冲突PR #5189元数据修复账户属性被元数据中的空值覆盖PR #5115。工程与维护nightly 发布与工具链升级25.7.0 引入了若干影响开发者与高级用户的工程变更Nightly NPM 包新增 GitHub Actions 工作流每晚自动发布所有 NPM 包的 nightly 版本PR #5047且仅在定时调度触发时发布PR #5144fork 仓库不会误触发PR #5213Docker edge 构建的 nightly 测试环节同步修复PR #5123依赖升级uuid9.0.1 → 11.1.0、tar-fs2.1.2 → 2.1.3、vitest3.1.4 → 3.2.4、react-i18next14.1.3 → 15.5.3、csv 相关包升至新主版本移除body-parser、snapshot-diff/jest依赖分别以jest-diff取代类型与结构继续推进.d.ts文件迁移为.tsPR #5060、#5204为交易导入补充 TypeScript 类型PR #4720电子表格绑定移至 spreadsheets 特性目录、hooks 统一收归src/hooksPR #5007工程自动化新增月度贡献者积分统计工作流PR #5147、自动代码格式化工作流PR #5157、基于 GitHub Actions 与 OpenAI API 的 PR 发布说明自动生成PR #5182、needs info标签 issue 7 天自动关闭与陈旧管理PR #5109、#5110Docker 与测试新增 Docker 镜像构建与 sync-server CLI 的测试PR #4952。如何升级与使用Docker 自托管将镜像 tag 更新为25.7.0即可对应发布说明中的 Docker tag升级后即可使用收入自动保留、对账同步余额与命令栏三项新特性桌面端更新桌面应用后在任意页面按Ctrl-KmacOSCmd-K即可体验命令栏信封预算的 To Budget 面板中找到Hold for next month启用自动保留对账在账户页点击对账若该账户启用了银行同步对账弹窗会直接显示上次同步余额可一键填入CLI 用户使用reset-password命令重置密码详细参数见 packages/cli 文档。小结25.7.0 是 Actual 在自动预算与键盘效率两条主线上迈出的一大步收入自动保留把信封预算的月度滚动从手动操作变为可配置策略命令栏则把导航、余额速查与新手引导统一收进一次按键交互中。加上对账与银行同步的打通、一大批银行解析器与交易导入修复以及 nightly 发布管线的落地这个版本无论对普通用户、自托管管理员还是插件/包维护者都极具升级价值。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Actual Budget 25.7.0 版本深度解析：收入自动结转、银行余额对账与 Ctrl-K 命令栏
Actual Budget 25.7.0 版本深度解析收入自动结转、银行余额对账与 Ctrl-K 命令栏【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual本文围绕 Actual Budgetlocal-first 个人财务应用25.7.0 正式版展开系统梳理该版本三大核心特性——收入类别自动保留到下月、对账时展示银行同步余额、以及 Ctrl-K/Cmd-K 快捷命令栏并逐一深入到仓库源码前端 React 组件与后端 budget 服务验证其实现原理同时覆盖银行同步解析增强、CLI 新增命令与工程维护项。读完本文你将掌握这些新功能的完整使用方式、底层调用链与配置要点并能快速定位到对应源码继续深入。版本总览Actual Budget 25.7.0Docker tag25.7.0是一次功能密度很高的版本官方发布说明列出了三大亮点选择收入类别自动将其中的资金保留Hold至下一个月对账Reconcile账户时展示最近一次银行同步的余额通过Ctrl-KmacOS 上为Cmd-K打开命令栏实现快速键盘导航。此外从该版本开始所有 NPM 包开始每晚发布 nightly 版本为希望提前试用新功能的用户提供更稳定的测试渠道对应 发布说明 中的描述与 PR #5047 的 nightly 发布工作流。以下逐一展开分析。核心特性一收入类别自动保留到下月Hold for Next Month信封预算法Envelope Budget中本月有剩余收入、希望留到下个月再用是很常见的诉求。25.7.0 将这一操作自动化你可以为收入类别开启自动保留当月的待预算To Budget资金会自动缓冲到未来月份无需每月手动操作。使用入口To Budget 菜单在信封预算的月度预算摘要区域To Budget 面板右键/点击菜单可以看到ToBudgetMenu提供的多个操作项ToBudgetMenu.tsxMove to a category将待预算资金移动到某个类别toBudget 0时显示Hold for next month手动把当前待预算资金全部保留到下月要求autoBuffered 0且toBudget 0Cover from a category待预算为负超支时从某个类别挪用资金覆盖Disable current auto hold存在自动保留forNextMonth 0且手动缓冲为 0时可一键关闭自动保留Reset next months buffer重置下个月的缓冲金额。从源码可见菜单项的显示完全由四个电子表格spreadsheet绑定值驱动toBudget、forNextMonth、manualBuffered、autoBuffered分别代表当前待预算下月可用来自结转手动缓冲与自动缓冲。底层调用链三个后端 action选中Hold for next month后前端会同时触发两个后端方法见 ToBudgetMenu.tsx 的onMenuSelect分支budget/hold-for-next-month→ 后端holdForNextMonthbudget/reset-income-carryover→ 后端resetIncomeCarryover。这两个方法均注册在 app.ts 的 RPC 层并通过mutator(undoable(...))包装因此可被撤销Undo。核心实现位于 actions.tsexport async function holdForNextMonth({ month, amount }) { const row await db.first(SELECT buffered FROM zero_budget_months WHERE id ?, [month]); const sheetName monthUtils.sheetForMonth(month); const toBudget await getSheetValue(sheetName, to-budget); if (toBudget 0) { const bufferedAmount calcBufferedAmount(toBudget, (row row.buffered) || 0, amount); await setBuffer(month, bufferedAmount); return true; } return false; } export async function resetHold({ month }) { await setBuffer(month, 0); }要点holdForNextMonth会先读取zero_budget_months表中的buffered字段即当前月份已缓冲金额再结合实时计算的to-budget值通过calcBufferedAmount计算最终缓冲额并写回数据库。如果toBudget 0本月没有可保留资金方法直接返回false不会产生任何副作用resetHold将缓冲清零对应Reset next months buffer菜单resetIncomeCarryoveractions.ts会遍历所有is_income 1且未删除的类别将其当月收入结转carryover标志批量重置为false从而解开此前收入类别的自动结转状态配合自动保留实现完整闭环。前端配套HoldBufferModal除菜单外前端还有独立的HoldBufferModal组件HoldBufferModal.tsx用于输入/确认缓冲金额并在 modalsSlice.ts 中注册。25.7.0 的一个修复PR #5245还专门同步了HoldBufferModal与TransferModal组件中amount状态与外部值的联动避免金额显示不一致。核心特性二对账时显示银行同步余额月度对账是财务应用的高频操作。此前用户需要手动输入银行当前余额启用银行同步GoCardless 等的用户往往已经同步过最新余额重复输入既繁琐又容易出错。25.7.0 将对账模态框与银行同步数据打通对账时直接展示最近一次同步得到的余额并可一键填入。源码实现Reconcile.tsx对账弹窗组件位于 Reconcile.tsx关键逻辑const clearedBalance useSheetValue({ name: balanceQuery.name -cleared, ... }); const lastSyncedBalance account.balance_current;clearedBalance从电子表格绑定中读取该账户的已清算余额作为默认输入值lastSyncedBalance account.balance_current账户实体上的balance_current字段即最近一次银行同步返回的余额。弹窗中会显示一行上次同步余额lastSyncedBalance非空时渲染并提供Use last synced total使用上次同步总额按钮点击后把该值填入输入框25.7.0 的修复 PR #5241 将这一按钮的样式统一为默认按钮主题视觉上更一致。整个流程由 Account.tsx 驱动用户在弹窗提交金额后调用reconciliation.finishReconciliation(account.id, reconcileAmount, ...)完成对账并更新账户的last_reconciled时间戳Account.tsx。相关修复对账与同步相关的稳定性也得到提升PR #5124 重构了accountsSlice中的账户同步逻辑并改进了syncAndDownload的处理减少对账过程中的同步异常。核心特性三Ctrl-K / Cmd-K 命令栏25.7.0 引入了类似编辑器/IDE 的命令栏Command Bar在任何页面按下Ctrl-KmacOS 为Cmd-K即可呼出一个搜索式导航面板输入关键字即可快速跳转。实现细节基于 cmdk 的 CommandBar组件位于 CommandBar.tsx基于cmdkCommand Menu 组件库实现核心结构快捷键监听CommandBar.tsxif (e.key k (e.metaKey || e.ctrlKey)) { e.preventDefault(); // 若已有模态框打开则不再弹出命令栏 if (modalStack.length 0) return; setOpen(true); }注意一个细节当其他模态框如新建交易弹窗已打开时命令栏会被抑制避免导航状态冲突。可搜索的分组SectionsCommandBar.tsx分组内容NavigationBudget、Reports、Schedules、Payees、Rules、Tags、Settings、All AccountsAccountsOn Budget / Off Budget 汇总行 每个未关闭账户每项右侧实时显示该账户当前余额Reports仪表盘页面Dashboard PagesCustom Reports用户自定义报表HelpTake a tour of Actual启动新手引导账户与报表列表均来自真实数据useAccounts、useReports、useDashboardPages余额则通过CellValue绑定电子表格实时值渲染因此命令栏本身就是一个余额速查面板。搜索为不区分大小写的子串过滤item.name.toLowerCase().includes(searchLower)支持键盘上下选择与 Enter 跳转还开启了vimBindings以便习惯 vim 导航的用户使用CommandBar.tsx。入口挂载CommandBar在 FinancesApp.tsx 中作为应用级组件挂载因此对所有页面全局生效。相关联动修复命令栏之外本版本还修复了若干导航/UI 体验问题底部导航栏滚动时遮挡内容PR #5166、移动端交易列表未占满全高PR #5179、通知显示在模态框之下避免被遮挡PR #5165、iOS 底部 Home Indicator 遮挡按钮PR #5121、交易预览在多账户视图中不显示PR #5135。CLI 新增命令reset-password25.7.0 为 Actual 的 CLI 工具新增了reset-password命令PR #5185允许通过命令行重置服务器/实例的登录密码方便自托管用户在忘记密码或需要应急恢复时使用。该命令属于 packages/cli 中的命令集与accounts、budgets、sync、server等命令并列具体用法可在 CLI 工具的 README 中查看。与此同时桌面端配置服务器界面新增了指向官方文档的引导链接PR #5107降低自托管配置门槛。银行同步与导入增强25.7.0 在银行同步生态上投入了大量工作主要分三类1. 有限历史银行名单扩充GoCardless 等聚合服务对部分银行仅提供有限的交易历史Actual 维护了一张limited history名单本版本新增/更新了LCL法国PR #5087Belfius与KBC Brussels比利时PR #5183BNP_BE_GEBABEBB比利时 BNP Paribas FortisPR #5187。2. 新增/改进银行解析器Boursobank法国GoCardless 交易解析改进PR #5202Raiffeisen Bank Austria奥地利新增 GoCardless 解析器PR #5244修复KBC Brussels使用了错误的payeeNamePR #5193为丹麦Danske Bank分行补充EndToEndID字段裁剪逻辑此前仅挪威分行有此处理PR #5101。3. 导入与链接稳定性改进OFX/QFX 文件兼容性PR #5203并修复YNAB4 拆分交易导入PR #5226GoCardless 初始链接失败时改用后备链接参数重试PR #5150修复交易全选操作在拆分交易子项全部选中时未包含父交易的问题PR #5086。预算、报表与交易修复预算模板修复模板应用到分组PR #5112与目标模板应用PR #5120的问题净资产图修复多个正负值图表并存时的颜色显示PR #5129余额历史图性能优化提速PR #5229侧边栏账户悬停提示新增余额历史变化展示PR #5085跨月与预算类型修复切换预算类型信封/追踪后需硬刷新才生效的问题PR #5253追踪预算的收入预算字段在移动端缺失PR #5251金额输入在appendDecimals前重新应用千位分隔符PR #5220调度Schedules修复调度名称含方括号时与增减修饰符解析冲突PR #5189元数据修复账户属性被元数据中的空值覆盖PR #5115。工程与维护nightly 发布与工具链升级25.7.0 引入了若干影响开发者与高级用户的工程变更Nightly NPM 包新增 GitHub Actions 工作流每晚自动发布所有 NPM 包的 nightly 版本PR #5047且仅在定时调度触发时发布PR #5144fork 仓库不会误触发PR #5213Docker edge 构建的 nightly 测试环节同步修复PR #5123依赖升级uuid9.0.1 → 11.1.0、tar-fs2.1.2 → 2.1.3、vitest3.1.4 → 3.2.4、react-i18next14.1.3 → 15.5.3、csv 相关包升至新主版本移除body-parser、snapshot-diff/jest依赖分别以jest-diff取代类型与结构继续推进.d.ts文件迁移为.tsPR #5060、#5204为交易导入补充 TypeScript 类型PR #4720电子表格绑定移至 spreadsheets 特性目录、hooks 统一收归src/hooksPR #5007工程自动化新增月度贡献者积分统计工作流PR #5147、自动代码格式化工作流PR #5157、基于 GitHub Actions 与 OpenAI API 的 PR 发布说明自动生成PR #5182、needs info标签 issue 7 天自动关闭与陈旧管理PR #5109、#5110Docker 与测试新增 Docker 镜像构建与 sync-server CLI 的测试PR #4952。如何升级与使用Docker 自托管将镜像 tag 更新为25.7.0即可对应发布说明中的 Docker tag升级后即可使用收入自动保留、对账同步余额与命令栏三项新特性桌面端更新桌面应用后在任意页面按Ctrl-KmacOSCmd-K即可体验命令栏信封预算的 To Budget 面板中找到Hold for next month启用自动保留对账在账户页点击对账若该账户启用了银行同步对账弹窗会直接显示上次同步余额可一键填入CLI 用户使用reset-password命令重置密码详细参数见 packages/cli 文档。小结25.7.0 是 Actual 在自动预算与键盘效率两条主线上迈出的一大步收入自动保留把信封预算的月度滚动从手动操作变为可配置策略命令栏则把导航、余额速查与新手引导统一收进一次按键交互中。加上对账与银行同步的打通、一大批银行解析器与交易导入修复以及 nightly 发布管线的落地这个版本无论对普通用户、自托管管理员还是插件/包维护者都极具升级价值。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考