使用 Excel 管理个人或家庭账本，支持多账户、收入与支出分类、二级分类、标签、备注、自动分类建议、查账、统计、批量修改、月初月末余额、周期性账单、服务订阅追踪、年度标签额度与月度汇总。Use when Codex needs to 记录账单、维护每月账本、更新 Excel 工作簿、按类别/标签/备注/时间查账、做消费统计、精确修改某笔或某批账单、处理订阅/周期账单、追踪服务订阅起始和续费/到期时间、核对账户余额，或基于既有分类体系自动建议类别但不直接扩充类别。
把账本数据持久化到本地 Excel：
bookkeeping-config.xlsxYYYY/YYYY-MM.xlsxuv run python "$LEDGER_SCRIPT" ... 读写（LEDGER_SCRIPT 必须指向 skill 目录下的 scripts/ledger_excel.py），避免手工改表导致结构漂移除用户明确要求外，不要直接修改工作簿结构；优先用脚本更新。
每次执行前先固定脚本绝对路径（不要依赖当前工作目录）：
BOOKKEEPING_SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/bookkeeping"
LEDGER_SCRIPT="$BOOKKEEPING_SKILL_DIR/scripts/ledger_excel.py"
test -f "$LEDGER_SCRIPT"
若 test -f 失败，先停止并修正路径；不要退回到其他目录下的同名脚本。
Ledger/。uv run python "$LEDGER_SCRIPT" bootstrap --root Ledger --month 2026-03
--date-from YYYY-MM-DD --date-to YYYY-MM-DD，不要把相对时间原样传给脚本。expense / incomecategory_source=autotransfer。query 确认命中的 transaction_idquery/stats 确认范围，再 update --allow-multiplebalances sheet 中；创建新月份时优先承接上月期末余额。--root 下的账本命令必须串行执行；不要并发运行多个 ledger_excel.py 命令。query、stats、month-report、subscription-report 也视为写操作（当前脚本可能触发修复或重建），同样必须串行。bootstrap、add、transfer、set-opening、set-closing、add-recurring、apply-recurring、set-limit、updatequery、stats、month-report、subscription-reportbootstrap（首次或新月份）query --month ... → month-report → subscription-report（按需）*.corrupted-<timestamp>.badzip）bootstrap --month YYYY-MM 重建当月文件现金、银行卡、支付宝、微信招行储蓄卡 -> 银行卡，微信钱包 -> 微信首次使用时执行：
uv run python "$LEDGER_SCRIPT" bootstrap --root Ledger --month 2026-03
这会创建：
Ledger/bookkeeping-config.xlsxLedger/2026/2026-03.xlsx默认配置会预置：
现金、银行卡、支付宝、微信如果用户要修改类别、标签或账户，优先更新配置工作簿而不是直接改月账单。 首次运行时若用户提供了非标准账户名，先确认映射或新增账户，再执行写入。
录入普通支出：
uv run python "$LEDGER_SCRIPT" add \
--root Ledger \
--date 2026-03-11 \
--direction expense \
--amount 32.5 \
--account 支付宝 \
--note "午饭和奶茶" \
--tags 日常,外食
录入收入：
uv run python "$LEDGER_SCRIPT" add \
--root Ledger \
--date 2026-03-11 \
--direction income \
--amount 5000 \
--account 银行卡 \
--level1 收入 \
--level2 工资 \
--note "3 月工资"
用户显式给出分类时，优先使用显式分类并校验是否存在于配置。
录入服务订阅时，优先补充订阅信息：
uv run python "$LEDGER_SCRIPT" add \
--root Ledger \
--date 2026-03-11 \
--direction expense \
--amount 98 \
--account 支付宝 \
--level1 数码数字 \
--level2 服务订阅 \
--merchant "Pixlr" \
--note "Pixlr 月订阅" \
--tags 软件,订阅 \
--subscription-name "Pixlr" \
--subscription-cycle monthly
若用户给出了订阅开始日、续费日或合同到期日，也一起传：
--subscription-start-date--subscription-renewal-date--subscription-end-date账户间转移使用：
uv run python "$LEDGER_SCRIPT" transfer \
--root Ledger \
--date 2026-03-11 \
--amount 1000 \
--from-account 银行卡 \
--to-account 微信 \
--note "日常消费备用金"
这是额外补充的重要能力。若没有转账记录，多账户余额会失真。
新增月订阅或年订阅：
uv run python "$LEDGER_SCRIPT" add-recurring \
--root Ledger \
--name "Notion 年费" \
--direction expense \
--amount 698 \
--account 支付宝 \
--level1 数码数字 \
--level2 服务订阅 \
--tags 软件,订阅 \
--frequency yearly \
--month 9 \
--day 18 \
--start-date 2026-09-18 \
--note "Notion renewal"
把某月应发生的周期账单落到月账本：
uv run python "$LEDGER_SCRIPT" apply-recurring --root Ledger --month 2026-09
同一周期账单同一个月只应用一次。
如果该周期账单属于 服务订阅，脚本会自动把它写入订阅追踪表。
按类别、备注、时间查账：
uv run python "$LEDGER_SCRIPT" query \
--root Ledger \
--direction expense \
--date-from 2026-02-15 \
--date-to 2026-03-14 \
--level1 数码数字 \
--level2 数码产品 \
--note-contains 摄影
常用筛选维度：
--id：按交易 ID 精确定位--month：限定某个月，可重复传多个--date-from / --date-to：限定日期范围--direction--account / --from-account / --to-account--level1 / --level2--tag：可重复传，默认要求全部命中--note-contains--merchant-contains--counterparty-contains--text-contains：跨类别、标签、备注、商户的模糊查找需要改账时，先查再改。
对筛选后的账单做统计：
uv run python "$LEDGER_SCRIPT" stats \
--root Ledger \
--direction expense \
--date-from 2026-02-15 \
--date-to 2026-03-14 \
--level1 数码数字 \
--level2 数码产品 \
--tag 摄影 \
--note-contains 摄影 \
--group-by month
可用分组：
nonemonthdateaccountlevel1level2categorytagmerchantcounterpartydirection按 tag 分组时，一笔多标签账单会分别计入每个命中的标签分组；解释结果时要明确这一点。
先按 ID 精确修改：
uv run python "$LEDGER_SCRIPT" update \
--root Ledger \
--id TX-20260311-xxxxxx \
--set-note "摄影配件" \
--add-tags 器材
批量修改时必须确认范围，再显式允许批量：
uv run python "$LEDGER_SCRIPT" update \
--root Ledger \
--month 2026-03 \
--level1 数码数字 \
--level2 数码产品 \
--tag 摄影 \
--allow-multiple \
--add-tags 器材
支持的修改项：
--set-date--set-amount--set-account--set-from-account / --set-to-account--set-level1 / --set-level2--set-tags--add-tags--remove-tags--set-note--set-merchant--set-counterparty--set-subscription-name--set-subscription-cycle--set-subscription-start-date--set-subscription-renewal-date--set-subscription-end-date修改日期跨月时，脚本会自动把交易移动到目标月份并重算两个月的余额。
设置月初余额：
uv run python "$LEDGER_SCRIPT" set-opening \
--root Ledger \
--month 2026-03 \
--account 支付宝 \
--amount 2400
设置月末实际余额：
uv run python "$LEDGER_SCRIPT" set-closing \
--root Ledger \
--month 2026-03 \
--account 支付宝 \
--amount 1832.55
查看核对结果：
uv run python "$LEDGER_SCRIPT" month-report --root Ledger --month 2026-03
若 closing_balance 与脚本计算出的 computed_closing 不一致，优先提示差额，不要静默改写。
为标签设置年度额度：
uv run python "$LEDGER_SCRIPT" set-limit \
--root Ledger \
--year 2026 \
--tag 摄影 \
--amount 12000 \
--note "器材和出片相关"
查看额度使用情况：
uv run python "$LEDGER_SCRIPT" limit-report --root Ledger --year 2026
额度按标签累计；一笔账单可带多个标签。默认把整笔金额计入命中的每个标签额度，因此给用户解释时要明确这一点。
查看所有订阅：
uv run python "$LEDGER_SCRIPT" subscription-report --root Ledger
查看未来 14 天内到续费/到期日的订阅：
uv run python "$LEDGER_SCRIPT" subscription-report \
--root Ledger \
--status active \
--due-within 14
脚本会把 level2=服务订阅 的支出自动汇总到配置工作簿里的额外表格，并尽量追踪：
若用户没有明确给出订阅周期，脚本会从 note、merchant、tags 中推断 monthly 或 yearly；仍无法判断时保留为空。
自动分类只使用当前配置中的既有类别与关键词：
categories sheetnote、merchant、counterparty、tags 中匹配关键词若无匹配：
level1 / level2 为空建议新增分类 或 建议完善关键词若存在多个接近候选：
需要查看表结构、字段语义和默认分类时，读取：
month / direction / amount / account / category / tags / balance effectmanual、auto、unclassified