Files

Knowit a7ba4f313f Rewrite README install section as a 6-step walkthrough

Replace the terse install summary with a click-by-click guide that
covers the full setup in both README.md and README.zh-CN.md:
clone+pip, GCP service account, moving the key out of the repo,
creating the sheet with header row, writing config.json, and a
sanity check. Flag the zh-CN tab-name gotcha (工作表1 vs Sheet1)
that causes HTTP 400 Unable to parse range.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-20 15:33:36 +08:00

5.3 KiB

Raw Blame History

AutoACCT — Claude Code 记账 Skill

English | 简体中文

一个 Claude Code skill，把小票照片（可附文字说明）自动变成 Google Sheet 里结构化的一行记录，并按当日 ECB 汇率换算为港币。

目前在 Claude Code 中手动调用；后续计划接入 WhatsApp webhook 实现真正的"发张图就记账"。

功能

用视觉识别读取小票 / 发票 / 支付截图。
提取：日期、商家、分类、金额、币种、支付方式、商品明细、原始 OCR 文本、用户备注。
通过 frankfurter.app（免费，无需 API key）按当日 ECB 参考汇率换算为 HKD。
向已配置好的 Google Sheet 追加一行（14 列，具体见 schema.md）。
回复记账结果，并标注任何靠推测填入的字段。

安装

按下面 6 步操作，整个过程约 10 分钟。

Step 1 — Clone 仓库 + 装 Python 依赖

git clone https://git.deepknow.site/Knowit/AutoACCT.git ~/.claude/skills/bookkeeping
pip install google-api-python-client google-auth

Step 2 — 建 Google Cloud 服务账号

打开 https://console.cloud.google.com/，左上角下拉 → New Project → 随便起名（如 autoacct）→ Create
顶部搜索框搜 Google Sheets API → 点进去 → Enable
左侧菜单 IAM & Admin → Service Accounts → + Create Service Account
- Name 填 bookkeeping（随意）
- 点 Create and Continue → Done（中间可选的 role 步骤跳过）
点进刚建好的服务账号 → 顶部 Keys 标签 → Add Key → Create new key → 选 JSON → Create 浏览器会自动下载一个 .json 文件到你的 Downloads
复制服务账号的 email（形如 bookkeeping@<项目名>.iam.gserviceaccount.com），Step 4 要用

Step 3 — 把 key 文件挪出 repo

千万不要把 key 留在 repo 目录里。挪到 ~/.config/gcp/：

mkdir -p ~/.config/gcp
mv ~/Downloads/<你下载的文件名>.json ~/.config/gcp/bookkeeping-sa.json
chmod 600 ~/.config/gcp/bookkeeping-sa.json

Step 4 — 建 Google Sheet

打开 https://sheets.new（直接创建空白 sheet）
给 sheet 起个标题（如 AutoACCT Expenses）
记住左下角 tab 的名字 — 英文界面默认 Sheet1，中文界面默认 工作表1。Step 5 要用这个精确字符串

点进 A1 单元格，粘贴下面这一整行（中间是 Tab 分隔，粘进去会自动拆到 A1–N1）：

Date	Merchant	Category	Amount	Currency	Amount (HKD)	FX Rate	FX Date	Payment Method	Line Items	Raw OCR	Note	Receipt	Logged At

右上角 Share → 粘贴 Step 2 复制的服务账号 email → 权限选 Editor → Send（"Notify people" 可以不勾）
从 URL 里复制 Sheet ID —— /d/ 和 /edit 之间那一长串： https://docs.google.com/spreadsheets/d/1abc...xyz/edit

Step 5 — 写 config.json

cd ~/.claude/skills/bookkeeping
cp config.example.json config.json

用编辑器打开 config.json，把 Step 4 拿到的 sheet_id 和 worksheet（tab 名）填进去：

{
  "sheet_id": "1abc...xyz",
  "worksheet": "Sheet1",
  "service_account_path": "~/.config/gcp/bookkeeping-sa.json",
  "hkd_fx_provider": "frankfurter"
}

⚠️ 常见坑：如果你的 Google Sheets 界面是中文，默认 tab 名是 工作表1，不是 Sheet1。必须写成 "worksheet": "工作表1"。tab 名不对会报 HTTP 400: Unable to parse range。

Step 6 — 冒烟测试

echo '{"date":"2026-04-20","merchant":"TEST","category":"Other","amount":1,"currency":"HKD","amount_hkd":1,"fx_rate":1,"fx_date":"2026-04-20"}' | python3 ~/.claude/skills/bookkeeping/scripts/append_row.py

看到 OK 'Sheet1'!A2:N2（或中文 tab 名）并且 sheet 第 2 行出现 TEST，就全通了。完事记得把这行测试数据删掉。

遇到报错可以参考 scripts/setup.md 的详细版。

使用

在 Claude Code 会话里把小票图片拖进来，然后说 "log this" / "记一下" 之类即可。Skill 会根据"小票/记账"类请求自动触发，不需要 slash command。

文字说明可选，可用来补充上下文（支付方式、AA、分类提示、备注等）。

文件结构

文件	作用
`SKILL.md`	入口文件 — Claude 读它来决定如何执行 skill
`categories.md`	固定的 14 个分类列表
`schema.md`	Google Sheet 列顺序（A–N）
`config.example.json`	配置模板 → 复制为 `config.json`（已 gitignore）
`scripts/fx_convert.py`	原币种 → HKD 换算（frankfurter.app）
`scripts/append_row.py`	向 Google Sheet 写入一行
`scripts/setup.md`	一次性配置步骤

Roadmap

WhatsApp webhook 接入层（Meta Cloud API 或 Twilio），实现手机端直接发图记账
可选的 Google Drive 上传，让 Receipt 列直接变成可点的图片链接
月度汇总脚本（按分类、按币种统计）

License

私有 — 仅供内部使用。

5.3 KiB Raw Blame History Unescape Escape