算盘

将用户自然语言交易描述转换为 suanpan CLI 命令。当用户提到记账、消费、支出、收入、转账、查账、统计等财务相关描述时触发。

Security Scan

文档、命令和所需权限总体上与“把自然语言转换为 suanpan CLI 命令”这一目的相符，但包含一个通过 curl | bash 安装远端脚本的建议，值得谨慎对待。

Purpose & Capability

技能声明是将自然语言的财务描述转换为 suanpan CLI 命令；SKILL.md 和 references 文档均仅描述 suanpan 的命令、参数和使用场景，所需项（无环境变量、无外部凭据）与目的匹配。包含的安装与使用说明与 suanpan 工具本身相关，未请求与功能不相干的权限或凭据。

Instruction Scope

运行时指令集中主要是提取交易要素并构建/展示 suanpan 命令，未直接要求读取系统中与任务无关的敏感文件或外发用户数据。但文档建议用户安装并运行 suanpan（包括 curl | bash 安装脚本、从源码编译、sudo cp 到 /usr/local/bin），这些操作会在本地主机上执行并改变系统状态——这是与工具使用相关的合理行为，但属于需要用户审查的风险点（见下文）。

Install Mechanism

技能为 instruction-only，但文档推荐使用 curl -sSL https://raw.githubusercontent.com/yinguobing/suanpan/main/install.sh | bash 来安装。该 URL 是 GitHub raw（常见托管），但以管道方式直接执行远端脚本会执行任意远端代码；另提供从源码编译的替代方法（git clone + cargo build）。建议在信任源码和发布者前避免无审查地执行 curl|bash。

Credentials

manifest 未声明任何环境变量或凭据，SKILL.md 也未要求访问额外的密钥或跨服务凭证。技能只涉及本地命令和本地数据导入路径（如导入 CSV/XLSX），请求的权限与其陈述的功能相称。

Persistence & Privilege

技能没有 always:true，也不请求修改其他技能或系统范围的 agent 配置。文档中有建议将二进制复制到 /usr/local/bin（常见的本地安装步骤），这是安装行为并不等同于越权持久化。

Assessment

这是一个将自然语言转成 suanpan CLI 命令的本地工具说明集，整体与它的目的相符。注意事项： - 切勿盲目运行文档中的 curl | bash 安装命令：该命令会下载并执行远端脚本，存在任意代码执行风险。优先选择从源码编译或在可审查的包管理器中安装，或先在安全环境中打开并审查 install.sh 的内容。 - 安装步骤会涉及 sudo cp 到 /usr/local/bin、cargo build 等系统级操作，请确保你理解并接受这些操作对主机的更改。 - 技能本身不会请求或需要你的云/第三方 API 密钥，但生成的命令会操作本地 suanpan 数据库（包含你的财务项）。在导入 CSV/XLSX 或执行批量写入前使用 --dry-run 并备份数据库。 - 如果你担心供应链风险，请在隔离环境（容器或虚拟机）中测试安装脚本，并优先从源码构建或从受信任的发行渠道获取二进制。

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/

快速记账流程

1. 提取交易要素（从用户自然语言中）
2. 构建命令（使用 suanpan add）
3. 执行并反馈

命令模板

# 支出（默认类型，可省略 -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