cn-bill-normalizer

将支付宝、京东白条、招商信用卡、微信支付的账单 CSV/Excel 解析为统一 JSON 结构。提供 REST API 与 MCP 服务，便于 Agent 与个人记账工具集成。

Repository: https://github.com/SolaTyolo/cn-bill-normalizer

统一输出结构

{
  "platform": "alipay",
  "count": 1,
  "transactions": [
    {
      "remark": "餐饮-商户A",
      "date": "2026-01-01 10:00:00",
      "type": "支出",
      "money": 12.5,
      "source": "支付宝"
    }
  ]
}

启动服务

go run ./cmd/server -addr :8080

Docker 部署

make docker-build          # 构建镜像
make docker-up             # compose 启动
curl http://localhost:8080/health
make docker-down

详见 deploy/README.md。

REST API

方法	路径	说明
GET	/health	健康检查
GET	/	服务说明
POST	/api/v1/parse/{platform}/url	JSON {"file_url":"https://..."}，服务端从 OSS 下载后解析

请求示例：

curl -X POST http://localhost:8080/api/v1/parse/alipay/url \
  -H 'Content-Type: application/json' \
  -d '{"file_url":"https://your-oss.example.com/bills/alipay_record.csv"}'

微信建议在 JSON 中附带 filename 以区分 xlsx/csv：

curl -X POST http://localhost:8080/api/v1/parse/wechat/url \
  -H 'Content-Type: application/json' \
  -d '{"file_url":"https://your-oss.example.com/bills/wechat.xlsx","filename":"wechat.xlsx"}'

微信支持 .xlsx 或 .csv。

MCP 服务

使用 官方 Go MCP SDK 的 Streamable HTTP 传输，端点：

POST http://localhost:8080/mcp

工具

工具	说明
parse_bill	解析账单：platform + file_url（公有 OSS 地址）
list_platforms	列出支持的平台与文件格式

Cursor 配置示例

在 MCP 设置中添加（Streamable HTTP）：

{
  "mcpServers": {
    "cn-bill-normalizer": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

项目结构

cmd/server/          # HTTP + MCP 入口
internal/model/      # JSON 结构体
internal/parser/     # 各平台解析逻辑
internal/handler/    # REST API
internal/mcpbridge/  # MCP 工具注册
testdata/            # 各渠道测试样例（单元测试读取本地文件）
deploy/              # Docker 构建与部署
skills/              # 各渠道 Agent Skills（MCP 调用规范）

测试

单元测试直接读取仓库内 testdata/ 本地 CSV，无需外部存储或 Docker：

go test -v ./internal/parser/...
# 或
make test

每个渠道有独立测试文件，覆盖各平台过滤与字段映射规则：

文件	渠道
internal/parser/alipay_test.go	支付宝
internal/parser/jd_test.go	京东白条
internal/parser/cmb_test.go	招商信用卡
internal/parser/wechat_test.go	微信

测试数据：testdata/{alipay,jd,cmb,wechat}/sample.csv。

License

MIT

Cursor 配置

类型	路径	说明
Agent 指南	AGENTS.md	项目总览、架构、常用命令
Agent Skills	skills/	各渠道 MCP 解析技能（豆包/Coze 格式）
Cursor Skill 入口	.cursor/skills/finance-bill-parse/	指向 skills/
Rules	.cursor/rules/*.mdc	项目约定、Go 解析规范
Subagents	.cursor/agents/	bill-parser、parser-tester

在对话中可显式调用 subagent，例如：「用 bill-parser 修改支付宝过滤规则」或「用 parser-tester 补 RustFS 集成测试」。

Topics

go mcp bill-parser alipay wechat-pay personal-finance docker fintech csv excel