个人财务

范围与安全

• 默认以只读方式处理导出的银行或信用卡 CSV 文件；除非显式提供 --output 路径，否则不会自动上传、调用 API 或写回数据。
• 所有 CLI 输出中均对账户号码进行掩码处理，仅保留最后四位数字，确保所有命令中的敏感信息（PII）得到保护。
• 离线运行；所有逻辑均位于 personal-finance.sh、config/category-rules.json 及内含的示例 CSV 文件中。

主要操作

所有命令均位于技能根目录下的 personal-finance.sh 中。使用方式如下：

./personal-finance.sh <command> [--csv <path>] [--config <path>] [--output <path>] [--period <period>]

1. validate

检查 CSV 是否包含必需字段（date、description、amount、account_number），并确认每笔金额均为数值类型。在处理新导出文件前使用此命令，可避免字段结构变化带来的问题。

./personal-finance.sh validate --csv sample-data/sample-transactions.csv

2. summarize

按周期聚合收入（正数 amount）和支出（负数 amount）。支持 month、quarter 或 year（默认为 month）。输出各类别总金额及净现金流。

./personal-finance.sh summarize --period month --csv sample-data/sample-transactions.csv

3. categorize

使用本地规则文件（config/category-rules.json）通过关键词匹配将交易描述归类。输出每笔交易的掩码账户及分配的类别。若添加 --output 参数，则生成新的 CSV 文件；否则保持只读状态。

./personal-finance.sh categorize --csv sample-data/sample-transactions.csv --output /tmp/categorized.csv

4. report

生成洞察报告：按消费金额排序的顶级商户和类别，以及交易数量统计。该命令复用相同的规则文件，可在离线环境下运行，并与 categorize 保持一致。

./personal-finance.sh report --csv sample-data/sample-transactions.csv

配置与示例

• config/category-rules.json：categorize 和 report 共享的关键词到类别映射规则。
• sample-data/sample-transactions.csv：最小化 CSV 示例（包含 date、description、merchant、category、amount、account_number），用于快速测试和入门。

请将这两个文件保留在技能目录中。根据自身商户词汇调整 JSON 规则；脚本每次运行时都会重新加载规则文件，且不调用任何外部服务。