yinguobing Suanpan 记账助手
Suanpan（算盘）是 Rust 编写的个人财务管理 CLI 工具，使用 SurrealDB 嵌入式数据库存储。
安装与依赖
依赖
- Rust 1.82+ (从源码编译时需要)
快速安装（推荐）
curl -sSL https://raw.githubusercontent.com/yinguobing/suanpan/main/install.sh | bash
从源码编译
git clone https://github.com/yinguobing/suanpan.git
cd suanpan
cargo build --release
sudo cp target/release/suanpan /usr/local/bin/
快速记账流程
- 提取交易要素（从用户自然语言中）
- 构建命令（使用
suanpan add） - 执行并反馈
命令模板
# 支出（默认类型，可省略 -t expense）
suanpan add -a <金额> -f <来源账户> -c "<分类路径>" -d "<描述>"
# 收入
suanpan add -a <金额> -t income -f <来源> -c "收入/<子分类>" -d "<描述>"
# 转账
suanpan add -a <金额> -t transfer -f <来源账户> -o <去向账户> -c "转账"
交易类型判断
| 关键词 | 类型 | 示例 |
|---|---|---|
| 花了、买了、支付 | expense（默认） |
"午餐花了35" |
| 工资、收到、收入 | income |
"收到工资8500" |
| 转、充值、提现 | transfer |
"转1000到余额宝" |
| 借入、借款 | debtchange |
"借入5000" |
| 借出、借钱给 | creditchange |
"借给朋友2000" |
分类路径格式
使用 "一级/二级" 格式，如 "餐饮/午餐"、"交通/地铁"。
常用分类：
- 餐饮：早餐、午餐、晚餐、零食
- 交通：地铁、公交、打车、加油
- 购物：服装、数码、日用
- 居住：房租、水电、物业
- 收入：工资、奖金、投资
账户名称映射
直接使用用户提到的账户名（如"支付宝"、"招行卡"）。注意：账户需已存在，如不确定先执行 suanpan account list 查看。
Gotchas（常见问题）
- 模糊搜索限制：
--search在内存中过滤，大数据量时配合--limit 500或日期范围使用 - 分类路径格式：必须使用
"一级/二级"，不是"一级-二级"或"一级:二级" - 账户存在性：
add命令中的账户必须已存在，不存在时先用suanpan account add创建 - ID 格式：
remove和update使用短 ID（list输出最后一列，前12位） - 货币默认：CNY，其他货币需显式指定
-y USD - 转账必须有两个账户：
-f（来源）和-o（去向）缺一不可 - 日期格式：
--from和--to使用YYYY-MM-DD，不是YYYY/MM/DD
查询与统计
# 最近流水
suanpan list --limit 20
# 按日期范围统计
suanpan stats --from 2026-04-01 --to 2026-04-30
# 趋势分析
suanpan trend --period month
管理操作检查清单
添加账户
- 确认账户名称
- 选择账户类型：
e-wallet、bank-card、cash、investment、credit、debt - 执行
suanpan account add "<名称>" -a <类型>
修改/删除交易
- 执行
suanpan list找到短 ID（最后一列） - 更新：
suanpan update <短ID> -a <新金额> - 删除：
suanpan remove <短ID>
批量导入
- 先使用
--dry-run模拟导入 - 检查输出无错误后再正式导入
完整命令参考
根据场景选择参考文档：
| 场景 | 参考文档 |
|---|---|
| 添加、查询、修改、删除交易记录 | references/commands.md |
| 统计分析、趋势、报表 | references/analytics.md |
| 账户/分类/标签管理、数据导入 | references/management.md |
使用示例
支出记录
用户："今天午餐35块，用的支付宝"
suanpan add -a 35 -f 支付宝 -c "餐饮/午餐" -d "午餐"
收入记录
用户："昨天发工资8500到工资卡"
suanpan add -a 8500 -t income -f 公司 -c "收入/工资" -d "三月工资"
转账记录
用户："从招行卡转5000到余额宝"
suanpan add -a 5000 -t transfer -f 招行卡 -o 余额宝 -c "转账" -d "理财"
查询本周支出
用户："这周花了多少钱"
suanpan stats --from 2026-04-06 --to 2026-04-12