# Ausgleich

> 两人 AA 记账与结算。上传一批支付凭证截图（微信支付/支付宝/银行卡/香港电子钱包），逐张识别事项、日期、币种、金额，写入一份飞书多维表格（含原图附件），表格用公式自解算出谁该转给谁多少人民币。两个人各用各的飞书、各跑各的 agent，往同一个账本里记。触发词：A钱、AA 记账、ausgleich、平账、分账、对账、室友记账、分账表。不用于：三人及以上多人分账、自定义分摊比例、企业报销/审批、单人预算管理；当前仅支持 CNY/HKD 两种原币与固定 50/50 结算，香港以外的多币种混算不要触发本技能。

- Skill: `baymaxstudio/ausgleich` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add baymaxstudio/ausgleich`
- Raw SKILL.md: https://api.skillmd.com/api/skills/baymaxstudio/ausgleich/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: BaymaxStudio (https://skillmd.com/u/baymaxstudio)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/baymaxstudio/ausgleich

---


# AUSGLEICH — 两人 AA 记账

## 这是什么

一个**小而美**的 A 钱工具。一轮 = 一份新建的飞书多维表格。吃完火锅/旅行结束/月底，把一堆支付截图丢进来，表格自己算出谁该转给谁多少 CNY。

**默认场景是双边协作**：你用你的飞书 + 你的 agent 记你的支出，朋友用他的飞书 + 他的 agent 记他的。两边都往同一个账本写，谁都不用看对方的脸色录数据。

## 红线（不要越界）

- **只做两个人、只做 AA（50/50）**。不加多人、不加自定义比例、不加"不计入"。
- **结算币种固定 CNY**。原币只记 CNY / HKD 两种。
- **一轮 = 一个新 Base**。不做结算锁定、不做跨轮累计、不做历史归档。下一轮直接新建。
- **表格里不放工作流、不放按钮、不放表单**。智能全在 agent 侧，表格只存事实 + 三个公式。
- **不做共享录入入口**。不做表单、不做共用机器人。两个入口，各自独立。
- **skill 里不写死任何人的名字或任何 base_token**。账本是运行时产生的，不是这个 skill 自带的。开源出去，别人装了就是他自己的账。

---

## 一、账本与接头文件

### ledger.json

一份账本的信息全在一个 JSON 里，叫**接头文件**：

```json
{
  "v": 1,
  "name": "2026-09",
  "base_token": "Xxxx...",
  "url": "https://xxx.feishu.cn/base/Xxxx",
  "tables": {"expense": "tbl...", "settle": "tbl..."},
  "payers": ["Alice", "Bob"],
  "me": "Alice",
  "peer": "Bob",
  "rate": 0.8568,
  "currency": "CNY"
}
```

**它不含任何密钥。** 飞书的鉴权靠各人自己的 lark-cli 登录态。谁拿到这个文件 + 在 Base 里有编辑权限，谁就能写。所以可以随手用微信/飞书发给对方，传丢了也不怕。

### 存在哪

```
~/.ausgleich/me.json              我是谁（默认身份，第一次运行时建）
~/.ausgleich/ledgers/<slug>.json  每轮账本的接头文件
~/.ausgleich/current              当前在用哪个账本
```

这些都不随 skill 分发，也不进 git。

### 我是谁

第一次用要先设身份，之后 `--me` 可以省：

```bash
mkdir -p ~/.ausgleich && echo '{"name":"Alice"}' > ~/.ausgleich/me.json
```

---

## 二、开一轮（建账方做一次）

1. **问清两件事**：对方叫什么；他的飞书邮箱或 openid（用来开权限）。

2. **查汇率**：`python3 scripts/rate.py`

3. **建账 + 给对方开编辑权限**：

```bash
python3 scripts/new_base.py --name "2026-09" --me "Alice" --peer "Bob" \
    --peer-contact "bob@example.com" --rate 0.8568
```

建表 → 建结算两行 → `drive +member-add --perm edit` 把对方加进来 → 存好本地 ledger。

4. **把输出的 ledger JSON 发给对方**（微信/飞书随便）。

> 如果 `member-add` 失败（比如双方不在同一个飞书组织），脚本会警告但不中断。这时手动在飞书里把这份 Base 分享给对方、给可编辑权限即可。

## 三、加入一轮（对方做一次）

```bash
python3 scripts/ledger.py save --json '<粘贴对方发来的 ledger JSON>' --me "Bob"
```

之后他的所有操作都自动指向这个账本。`--me` 必须从 `payers` 里选，填错会直接报错。

## 四、记账（两边随时做）

1. 拿到支付截图，逐张识别（规范见 `references/parse-prompt.md`），每条得到：
   `事项 / 日期 / 币种 / 金额 / 置信度 / 疑点`

2. **先给用户看汇总再写**，把 `confidence < 0.8` 和有 `疑点` 的行挑出来问。

3. 确认后写入：

```bash
python3 scripts/post.py --ledger 2026-09 --records records.json
```

`records.json`：

```json
[
  {"事项":"海底捞","日期":"2026-09-01","币种":"HKD","金额":428.00,"付款人":"Alice","备注":"","image":"/abs/path/shot1.png"}
]
```

- `付款人` 和 `汇率` 可以省略：默认取 ledger 里的 `me` 和 `rate`，CNY 自动填汇率 1
- `image` 可选，有就传原图到「凭证」列

## 五、结算（两边都能跑）

```bash
python3 scripts/settle.py --ledger 2026-09
```

```
本轮共同支出 CNY 453.11，人均 226.56
  Alice  实付 366.71   净额 +140.15
  Bob    实付  86.40   净额 -140.16
→ Bob 转给 Alice ¥140.16
```

**两边各自跑一次，数字应当一致。** 对不上就说明有人漏记了——这正是双入口记账最实用的地方。

---

## 已知坑（都是踩过的）

| 坑 | 表现 | 解法 |
|---|---|---|
| 公式异步计算 | 刚写完读回来是空 | `settle.py` 内置重试（等 3 秒再读，最多 3 次） |
| 附件 `--file` 只收相对路径 | 报 `unsafe file path` | 必须 `cd` 到图片目录（`post.py` 已处理） |
| 公式字段创建 | CLI 直接拒绝 | 必须带 `--i-have-read-guide` |
| 公式依赖顺序 | 建 `净额` 时 `实付合计` 还不存在 | 先建前两个，再建 `净额` |
| select 传值 | 写入失败 | 传数组，单选用 `["CNY"]` |
| datetime 传值 | 写入失败 | 传 `"2026-09-01 12:00"` |
| 表名不能改 | 公式失效 | 公式里硬编码了 `支出明细`，改名就断 |

## 其他

- 表结构、建表命令序列、公式原文见 `references/schema.md`
- 截图识别规范见 `references/parse-prompt.md`
- 一分钱舍入差：`应承担` 是总额一半四舍五入，两人净额可能差 0.01。正常，按正值方的数转，不要为此改公式。

## 硬约束

- 建表、写入都是**写操作**，只做用户明确要求的，不主动改已有的表。
- 不在表格里加工作流/按钮/表单——那是上一个版本把自己做死的地方。
- 一轮结束就结束，不追加、不修改历史轮次的表。

## 安全边界（面向第一次用的人）

**它只在你明确要求时才做：** 新建一份飞书多维表格账本、写入支出记录、上传凭证原图、读取结算公式结果、用 `--peer-contact` 给对方开编辑权限。

**它不会做什么：**

- 不会碰你已有的表，不会改历史轮次的账本；
- 不会在识别后直接写账——先把汇总给你看，`confidence < 0.8` 或有 `疑点` 的行一定先问你；
- 不会擅自给任何人开权限；只有你传了 `--peer-contact` 并确认后才会加协作者；
- 不落盘任何 token / 密钥；`ledger.json` 不含密钥，鉴权靠各自的 lark-cli 登录态；
- 不自动执行转账，不做结算锁定，不跨轮累计。

**什么时候会停下来问你：** 识别置信度低、遇到转账/红包/提现、一图多笔、金额或日期缺失、要给对方开权限、汇率查不到。