SMB — Sutady Moneybook

SMB (Sutady Moneybook) 2.4.1 是一款基于 SQLite 和 MCP (Model Context Protocol) 的全栈个人记账系统。它原生支持本地单机运行与离线保存，也可通过 Cloudflare Tunnel 实现跨网安全访问；账本唯一数据源为本机 SQLite，不依赖外部云端数据库，数据完全自主掌控。

已实现

• 快速收入/支出记账，只记录发生日期，金额以整数“分”保存。

• 完全自定义分类、停用、迁移或永久删除分类、月/年账单、搜索筛选、全局 30 天回收站、CSV/JSON 导出。

• 周、月、年趋势，分类明细、分类构成和上一周期同进度比较。

• DeepSeek 消费概览、异常增长、节省建议、分类结构和自定义问题；程序负责数字，模型只负责解释，当前不会向外部模型发送账目备注。

• 标准 Streamable HTTP MCP；可由网页在“确认模式”和“直接接管模式”间切换。直接模式可管理账目、分类、借款、订阅、AI、备份和时区，并保留 30 天可撤销操作记录。

• SQLite WAL＋synchronous=FULL、迁移前快照、每日完整性/外键备份、age 公钥加密和 Google Drive 上传。

• Cloudflare Access 双层保护、PWA 安装、Windows 登录自启动与失败重启辅助脚本。

• 四套主题、四种内置页面背景，以及仅保存在当前设备的个人背景图片。个人图片会在浏览器内压缩并去除元数据，可暂时切换回内置背景而不会被删除。

• 查询优先的洞察首页：周期与收支类型保存在网址中，刷新或从分类账单返回后仍保持原来的查看位置。

• 手机端采用紧凑摘要、明细/构成切换、贴底导航和账单筛选抽屉；搜索期间保留旧列表，避免内容闪烁。

• 全站日期以设置中的账本时区为准，电脑和 Android 所在时区不同时，“今天”、默认月份与 AI 分析周期仍保持一致。

• 独立“事项”模块管理别人欠我的借款、分次还款和 CNY/USD 订阅。事项默认不进入消费统计；只有主动关联或同时创建的普通账目才会影响图表。

• 借款支持借款人停用、部分还款、自动结清和 30 天回收站；订阅支持首期优惠、月/年/自定义周期、到期确认、付款历史与应用内提醒。

• 每月可设置人民币总预算和分类预算；预算不结转、不阻止记账，洞察页会显示已用、剩余、预测和分类风险。

• “账本体检”用确定性规则提示疑似重复、大额支出、预算风险、待确认续费和关联异常；核对不会自动改账，AI 只解释程序发现的事实。

• Android/Windows 安装后的应用菜单提供“记一笔”快捷入口；OpenClaw 支持一次原子写入最多 20 笔账目并整批撤销。

• 记录借款使用可搜索的单一借款人选择器；新借款人与借款同事务保存。同名活跃记录会复用，停用记录需先恢复。

• OpenClaw 提案重试不会重复创建待确认项；操作中心可按需查看字段变化和失败状态。账本体检也可由 MCP 只读查询，且不返回备注。

• 可选的“资金”模块记录人民币账户、余额流水、账户间转账、手续费、余额校准和全额退款；总资金不包含待收借款、投资或未来收入。

• 资金追踪启用前的历史账目不会被追溯；启用后的普通收支绑定账户，余额由初始余额与追加式资金流水计算，不维护第二份余额真相。

• OpenClaw 可精确查询和管理账户、转账、校准与退款；所有直接写入继续使用幂等 requestId，歧义账户名称会被拒绝。

“事项”的实际操作、启用资金前后的联动规则和 OpenClaw 权限见 借款与订阅使用指南。账户启用、资金影响、退款和体检提示见 资金追踪使用与维护指南。

Related MCP server: ExpenseTracker MCP Server

洞察与账单

• 洞察中的“分类明细”用于比较分类名次、金额和相对上期变化；“分类构成”用于查看环形图、金额和占比，两者不会同时显示。

• 分类构成会完整展示本期所有有金额的分类，不再合并为“其他”；每个扇区和图例都可下钻到对应账单。

• 账单页有四个平级入口：“最近录入”“月账单”“年账单”“回收站”。回收站跨全部日期按删除时间排列，不会继承上次查看的月份。

• 旧网址继续兼容：/bills 打开最近录入；/bills?view=ledger&period=month&anchor=... 打开月账单；将 period 改为 year 即打开年账单；/bills?view=trash 打开全局回收站。

• 普通删除会保留 30 天并允许恢复。回收站中的账目可永久删除；设置中的分类管理也可在展示影响范围并确认名称后，永久删除分类及其全部账目。永久删除不可撤销，但关联的借款或订阅事项会保留并自动解除账本关联。

页面更新与个人背景

• 页面处于打开状态时，每 30 秒同步当前页面的账本数据；重新聚焦窗口或网络恢复时也会立即同步。

• PWA 每分钟检查一次新版本，发现新版本后会在没有正在编辑的表单时自动更新。也可以在“设置 → 运行状态”点击“检查并刷新”。

• Cloudflare 登录过期时使用页面上的“重新登录”，不要删除网站 Cookie 或清除网站数据。“重新登录”和“检查并刷新”只替换 PWA 程序缓存，保留登录 Cookie、外观偏好和 IndexedDB 中的个人背景；清除整个网站数据才会删除当前设备的个人图片。

• 选择“纯净、纸张、织纹、薄雾”会暂时停用个人图片，但图片仍保留在当前设备，可随时点击“使用图片”恢复。

• 每个浏览会话首次冷启动会短暂显示一次 SMB 品牌开屏；刷新数据和页面切换不会重播，系统开启“减少动画”时直接跳过。

快速上手与本地运行

需要 Node.js 22 或更高版本。

方式一：Windows 一键启动（最推荐）

直接双击项目根目录下的 打开 SMB.cmd。

• 首次运行会自动检查依赖、自动根据模板生成 .env 默认配置并完成编译打包；

• 随后会自动启动服务并在默认浏览器中打开记账首页（默认访问 http://127.0.0.1:8788，免登录单机模式）。

方式二：命令行手动启动（跨平台通用：Windows / Linux / macOS）

在项目根目录打开终端：

# 1. 安装项目依赖
npm install

# 2. 初始化本地配置（默认开启免登录单机模式）
cp .env.example .env

# 3. 运行开发模式（推荐本地体验，支持代码热重载）
npm run dev
# 浏览器访问 http://127.0.0.1:5173

# 或者编译并启动正式生产服务：
npm run build
npm start
# 浏览器访问 http://127.0.0.1:8788

质量检查

npm test
npm run typecheck
npm run build

正式更新前可额外创建一份经过完整性检查的快照：

npm.cmd run backup:snapshot -- manual-update
npm.cmd run backup:verify-restore

进阶功能与部署指南

如果你仅在个人电脑上单机记账，无需配置任何外部服务，开箱即用。

若需要以下进阶能力，可参考对应指南按需配置：

• 手机跨网远程记账：通过 Cloudflare Tunnel 实现免公网 IP 穿透与 Access 身份验证，详见 部署指南。

• AI 智能消费分析：双击根目录 配置DeepSeek密钥.cmd 或在 .env 中填入 DeepSeek API Key 即可启用消费洞察与节省建议。

• 异地加密自动云备份：配置 Google Drive 与 age 加密密钥，实现每日自动快照上传，详见 恢复指南。

• 资金与账户管理：多账户资产流水、转账与余额校准，详见 资金追踪指南。

• 借款与订阅管理：跟进外部欠款、分次归还与周期订阅扣费，详见 事项使用指南。

目录

• src/：手机与电脑共用的 React PWA。

• server/：Node API、MCP、DeepSeek、资金、财务事项与备份服务。

• db/：SQLite 表结构与迁移。

• tests/：金额、日期、事项、界面、AI 和 MCP 测试。

• scripts/：初始化、自启动、备份密钥和恢复脚本。

• deploy/：Cloudflare 与 OpenClaw 的无密钥配置模板。

私密文件 .env、正式数据库、备份、日志和构建产物都已排除在版本控制之外。

版本号只在 package.json 中维护。修复和视觉精修递增补丁版本，向后兼容的新能力递增次版本，产品身份或不兼容契约变化递增大版本；发布记录见 CHANGELOG.md。Logo 规范与可编辑源稿见 品牌指南。

已明确延后的账单导入、第三方余额同步和更复杂账户能力见 ROADMAP.md。