Family Bookkeeping

Overview

Use this skill as the default workflow for household bookkeeping tasks.

This skill assumes the primary ledger is provided by environment variables unless the user explicitly asks to change it:

• App token env: FAMILY_BOOKKEEPING_APP_TOKEN
• Table ID env: FAMILY_BOOKKEEPING_TABLE_ID
• Bitable URL env: FAMILY_BOOKKEEPING_BITABLE_URL

Primary goals:

1. Record income and expenses from natural language
2. Support update, query, and delete flows safely
3. Prepare for WeChat and Alipay batch bill import
4. Keep category and statistics logic consistent

Core Ledger Schema

Use these fields as the canonical schema:

• 日期
• 金额
• 记账人
• 一级类型
• 二级类型
• 备注
• 收支类型
• 支付平台
• 导入来源
• 流水号
• 创建时间
• 更新时间

Normalization rules:

• Store 金额 as a positive number
• Batch imports must skip rows where 金额 = 0
• Use 收支类型 to distinguish 收入 vs 支出
• Use 流水号 as the preferred dedupe key for imported bills
• If classification is unclear, use 一级类型=其他 and 二级类型=暂未分类

Trigger Phrases

Prefer this skill when the user says or implies any of the following:

• 记账
• 记一笔
• 入账
• 今天花了 28
• 今天午饭 32，记王某
• 帮我查下这个月花了多少
• 看下 3 月餐饮支出
• 把昨天那笔改成交通
• 删掉今天那杯咖啡
• 导入支付宝账单
• 导入微信账单
• 统计一下今年总支出
• 按类别看本月开销

Default Category System

Use this default mapping unless the user later overrides it.

餐饮

• 早饭
• 午饭
• 晚饭
• 外卖
• 饮料
• 咖啡
• 零食
• 聚餐

交通

• 打车
• 地铁
• 公交
• 火车
• 高铁
• 机票
• 加油
• 停车
• 过路费
• 共享单车

日用购物

• 买菜
• 超市
• 日用品
• 家居用品
• 清洁用品
• 母婴用品
• 宠物用品

生活缴费

• 房租
• 水费
• 电费
• 燃气费
• 物业费
• 宽带
• 维修
• 家电
• 话费

医疗健康

• 挂号
• 药品
• 检查
• 治疗
• 保健
• 运动

教育成长

• 学费
• 书籍
• 课程
• 培训
• 文具

娱乐休闲

• 电影
• 游戏
• KTV
• 演出
• 景点
• 旅游
• 酒店
• 兴趣消费

人情社交

• 红包
• 礼物
• 聚会
• 请客
• 孝敬父母
• 人情往来

服饰美妆

• 衣服
• 鞋包
• 配饰
• 护肤
• 彩妆
• 理发

孩子 / 家庭专项

• 奶粉
• 尿不湿
• 玩具
• 学习用品
• 家庭公共支出

金融支出

• 信用卡还款
• 手续费
• 利息支出
• 保险

收入

• 工资
• 奖金
• 报销
• 兼职
• 红包收入
• 转账收入
• 理财收益
• 退款
• 其他收入

其他

• 暂未分类
• 其他支出
• 其他收入

Workflow Decision Tree

1. New record flow

Use when the user wants to add a new transaction.

Extract these fields if possible:

• 日期
• 金额
• 记账人
• 收支类型
• 一级类型
• 二级类型
• 支付平台
• 备注

Rules:

• If amount is missing, ask for it
• If date is missing, infer from user wording like 今天/昨天/前天; otherwise ask
• If 收支类型 is not explicit, infer from wording; if ambiguous, ask
• If category is unclear, add the record with 其他 / 暂未分类 rather than blocking
• If platform is unknown, leave empty or set 其他
• Prefer concise confirmation after successful creation

Example interpretations:

• 今天午饭 32 → 支出 / 餐饮 / 午饭
• 老婆买菜 86 → 支出 / 日用购物 / 买菜 / 记账人=老婆
• 报销到账 500 → 收入 / 收入 / 报销

2. Update flow

Use when the user wants to change an existing transaction.

Locate the target record using the smallest reliable candidate set based on:

• 日期
• 金额
• 备注关键词
• 记账人
• 平台

Rules:

• If one record matches, update directly
• If multiple plausible records match, present candidates and ask the user to choose
• If the request is vague, ask one short clarifying question
• Preserve untouched fields

Example requests:

• 把昨天那笔咖啡改成 28
• 把今天那笔买菜改成日用购物
• 备注改成请同事喝咖啡

3. Delete flow

Use when the user wants to delete a transaction.

Safety rule:

• Always confirm before deletion unless the user already identified the exact single record and explicitly reaffirmed deletion in the same turn

Process:

1. Find candidate records
2. If none, say so clearly
3. If one, describe it briefly and ask for confirmation if needed
4. If many, list short candidates and ask which one to delete

4. Query and statistics flow

Use when the user asks for summaries or breakdowns.

Common query intents:

• Monthly total income / expense / net balance
• Yearly total income / expense / net balance
• Breakdown by 一级类型
• Breakdown by 二级类型
• Breakdown by 记账人
• Filter by date range, member, platform, category, income/expense

Response style:

• Lead with the answer first
• Then show the main breakdown
• Keep it compact unless the user asks for detail

Suggested summary format:

• 时间范围
• 总支出
• 总收入
• 结余
• Top 3 categories
• Optional member breakdown

5. Import flow

Use when the user wants to import WeChat or Alipay bills.

Current policy:

• Do not pretend there is direct account access
• The expected workflow is: user exports a statement file, then provides it for processing

Import rules:

• Prefer using bill platform transaction id as 流水号
• Deduplicate by 流水号
• If no transaction id exists, fallback to 日期 + 金额 + 交易对方/备注 + 支付平台
• Preserve original source in 导入来源
• Auto-classify conservatively; unclear rows should fall back to 其他 / 暂未分类

WeChat mapping

• 日期 ← 交易时间
• 金额 ← 金额(元)
• 收支类型 ← 收/支
• 支付平台 ← 微信
• 流水号 ← 交易单号
• 导入来源 ← 微信账单
• 备注 ← 商品 + 交易对方 + 原备注（可拼接）

Alipay mapping

• 日期 ← 优先交易付款时间，没有则用交易创建时间
• 金额 ← 金额（元）
• 收支类型 ← 收/支
• 支付平台 ← 支付宝
• 流水号 ← 交易订单号
• 导入来源 ← 支付宝账单
• 备注 ← 商品名称 + 交易对方 + 原备注（可拼接）

Classification Heuristics

Read references/category-system.md when detailed category mapping is needed. Read references/usage.md when practical command examples or operator-facing usage details are needed.

If confidence is low, prefer 其他 / 暂未分类.

Operational Notes

• Use Feishu Bitable as the source of truth for this household ledger
• Default live ledger should be read from environment variables:
  • FAMILY_BOOKKEEPING_APP_TOKEN
  • FAMILY_BOOKKEEPING_TABLE_ID
  • FAMILY_BOOKKEEPING_BITABLE_URL
• Default Feishu credentials should be read from environment variables:
  • FEISHU_APP_ID
  • FEISHU_APP_SECRET
• Those variables are expected to be available in the runtime environment so cross-channel runs do not need to pass explicit credentials each time
• Keep user-visible replies short and practical
• For deletions, require confirmation
• For ambiguous updates, ask one precise question instead of guessing
• Do not silently invent fields outside the canonical schema
• When a future classification dictionary table exists, prefer it over hardcoded keyword rules

Scripts

scripts/normalize_bills.py

Use this script to normalize exported WeChat or Alipay bill files into the canonical family-bookkeeping schema.

Example usage:

python3 skills/family-bookkeeping/scripts/normalize_bills.py bill.xlsx --bookkeeper 张三 --format json --output normalized.json
python3 skills/family-bookkeeping/scripts/normalize_bills.py bill.csv --platform alipay --bookkeeper 李四 --format csv --output normalized.csv

Behavior:

• Detect or accept platform type (wechat / alipay)
• Support .csv and .xlsx
• For WeChat Excel exports, skip the descriptive preface area and locate the real header row automatically
• For Alipay CSV exports, support GB18030 encoding and descriptive prefaces before the real header row
• Normalize source columns into canonical output fields
• Keep 金额 as positive numbers
• Infer 收支类型
• Skip 不计收支 Alipay rows by default
• Apply lightweight keyword classification
• Deduplicate rows within the import batch

scripts/export_feishu_import_csv.py

Use this script to convert normalized rows into a CSV that Feishu Bitable can import directly.

Example usage:

python3 skills/family-bookkeeping/scripts/export_feishu_import_csv.py normalized.json --output feishu-import.csv

Read references/feishu-import.md for the end-to-end import flow and the target ledger mapping.

Future Expansion

This first version can later be extended with:

• A dedicated category dictionary table
• Direct Feishu batch-write helper scripts
• Saved monthly/yearly reporting templates
• Better duplicate detection and fuzzy merchant normalization
• Shared household member profiles and defaults