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>
This commit is contained in:
@@ -16,18 +16,78 @@
|
||||
|
||||
## 安装
|
||||
|
||||
把仓库 clone 到 Claude Code 的 skills 目录:
|
||||
按下面 6 步操作,整个过程约 10 分钟。
|
||||
|
||||
### Step 1 — Clone 仓库 + 装 Python 依赖
|
||||
|
||||
```bash
|
||||
git clone https://git.deepknow.site/Knowit/AutoACCT.git ~/.claude/skills/bookkeeping
|
||||
pip install google-api-python-client google-auth
|
||||
```
|
||||
|
||||
然后按 [`scripts/setup.md`](scripts/setup.md) 完成一次性配置:
|
||||
### Step 2 — 建 Google Cloud 服务账号
|
||||
|
||||
- 安装 Python 依赖:`pip install google-api-python-client google-auth`
|
||||
- 在 GCP 建服务账号并下载 JSON key
|
||||
- 新建 Google Sheet,填好 14 列表头,把 sheet 分享给服务账号的 email
|
||||
- `cp config.example.json config.json`,填入 `sheet_id` 和 `service_account_path`
|
||||
1. 打开 https://console.cloud.google.com/,左上角下拉 → **New Project** → 随便起名(如 `autoacct`)→ Create
|
||||
2. 顶部搜索框搜 **Google Sheets API** → 点进去 → **Enable**
|
||||
3. 左侧菜单 **IAM & Admin → Service Accounts → + Create Service Account**
|
||||
- Name 填 `bookkeeping`(随意)
|
||||
- 点 **Create and Continue → Done**(中间可选的 role 步骤跳过)
|
||||
4. 点进刚建好的服务账号 → 顶部 **Keys** 标签 → **Add Key → Create new key → 选 JSON → Create**
|
||||
浏览器会自动下载一个 `.json` 文件到你的 Downloads
|
||||
5. **复制服务账号的 email**(形如 `bookkeeping@<项目名>.iam.gserviceaccount.com`),Step 4 要用
|
||||
|
||||
### Step 3 — 把 key 文件挪出 repo
|
||||
|
||||
**千万不要**把 key 留在 repo 目录里。挪到 `~/.config/gcp/`:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/gcp
|
||||
mv ~/Downloads/<你下载的文件名>.json ~/.config/gcp/bookkeeping-sa.json
|
||||
chmod 600 ~/.config/gcp/bookkeeping-sa.json
|
||||
```
|
||||
|
||||
### Step 4 — 建 Google Sheet
|
||||
|
||||
1. 打开 https://sheets.new(直接创建空白 sheet)
|
||||
2. 给 sheet 起个标题(如 `AutoACCT Expenses`)
|
||||
3. **记住左下角 tab 的名字** — 英文界面默认 `Sheet1`,中文界面默认 `工作表1`。Step 5 要用这个**精确字符串**
|
||||
4. 点进 **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
|
||||
```
|
||||
5. 右上角 **Share** → 粘贴 Step 2 复制的服务账号 email → 权限选 **Editor** → **Send**("Notify people" 可以不勾)
|
||||
6. 从 URL 里复制 **Sheet ID** —— `/d/` 和 `/edit` 之间那一长串:
|
||||
`https://docs.google.com/spreadsheets/d/`**`1abc...xyz`**`/edit`
|
||||
|
||||
### Step 5 — 写 config.json
|
||||
|
||||
```bash
|
||||
cd ~/.claude/skills/bookkeeping
|
||||
cp config.example.json config.json
|
||||
```
|
||||
|
||||
用编辑器打开 `config.json`,把 Step 4 拿到的 **sheet_id** 和 **worksheet**(tab 名)填进去:
|
||||
|
||||
```json
|
||||
{
|
||||
"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 — 冒烟测试
|
||||
|
||||
```bash
|
||||
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`](scripts/setup.md) 的详细版。
|
||||
|
||||
## 使用
|
||||
|
||||
|
||||
Reference in New Issue
Block a user