setup-ai-bookkeeping

name	setup-ai-bookkeeping
description	初始化或检查 AI 记账账本。当用户说“开始记账”“初始化账本”“创建记账表”“连接飞书多维表”“配置 AI 记账”或“重建演示账本”时触发。支持本地 SQLite 和已有飞书多维表，检查字段、凭据与基础设置，并明确告诉用户后续如何录入。

Setup AI Bookkeeping

为另外 3 个记账 Skill 准备同一份账本。

何时触发

• “开始记账 / 初始化账本 / 创建记账表”
• “把 AI 记账连到飞书多维表”
• “检查记账配置 / 账本能不能用”
• “给我做一个可复现的本地 Demo”

共用入口

先确定仓库根目录和配置文件。仓库根目录建议保存为 AI_BOOKKEEPING_HOME，真实配置建议用 config.json：

python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
  --config "/absolute/path/to/config.json" setup

不要在回复、日志或提交文件中展示飞书应用密钥。

执行流程

1. 询问或判断保存位置：

   • 用户要先试用、离线使用、跑 Demo：选择 SQLite。
   • 用户有应用凭据并连接已有表：选择 Feishu HTTP。
   • 用户本机已有 lark-cli profile：选择 lark_cli 用户授权模式。

2. 从 config.example.json 复制一份真实配置，填写本位币、时区和大额确认线。

3. SQLite 模式运行 setup，然后确认返回 9 张业务表。

4. Feishu 模式先检查：

   • “流水”表已按 schema/data-model.md 创建。
   • app_token 与 table_ids.transactions 已填写。
   • FEISHU_APP_ID 和 FEISHU_APP_SECRET 只存在环境变量。
   • 应用拥有多维表读写权限，并已被添加为该多维表的协作者。

5. 运行 setup 检查连接。遇到飞书错误时保留错误码，给出直接可执行的修复建议。

6. 用一条小额流水做预览，保持不提交：

   python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
     --config "/absolute/path/to/config.json" \
     record "今天午饭 1 元，支付宝"
   

7. 向用户汇报账本位置、后端、币种、时区、可用的 3 个后续 Skill。

从空白创建飞书工作台

用户明确要求创建新工作台时，使用通用建表脚本。先干跑：

python3 "$AI_BOOKKEEPING_HOME/scripts/provision_lark_base.py" \
  --config "/absolute/path/to/config.json" \
  --name "AI 账本工作台" \
  --dry-run

向用户确认将创建 1 个 Base、9 张表和对应字段。得到明确确认后执行同一命令，把 --dry-run 改成 --apply。

脚本使用配置中的 lark-cli profile 与 user 身份，串行调用 +base-create、+table-create 和 +field-create。完成后从本地结果取出 Base token 与“流水”的 table ID，分别放入受保护的环境变量和被忽略的本地配置，再运行 setup。资源标识本身不授予权限，也不要提交到公开仓库、文章或聊天记录。

建表口径

本地账本包含：流水、待处理输入、账户、分类、预算、项目账本、周期计划、收入目标和设置。

飞书 HTTP 模式的字段名默认使用 schema/feishu-field-map.example.json。lark-cli 模式默认适配 schema/ai-bookkeeping-workbench-v1.json 中的现有工作台字段。用户改过字段名时，在配置的 field_map 中覆盖对应关系。

重复执行

setup 可以重复运行。SQLite 只补齐缺失的表和默认字典，不清空旧账。两个飞书连接后端只检查目标表，不修改表结构；创建空白工作台使用独立 provision 脚本。

边界与安全

• 没有用户明确同意时，不删除数据库、不清空多维表、不覆盖已有配置。
• 不把密钥直接写进 JSON。
• 飞书表缺字段时，列出缺项，让用户或管理员补齐后重试。
• 用户只想研究方案时，停在配置与字段清单，不执行在线写入。
• 用户已有账本时，先备份或使用一张新表做迁移演练。

完成检查

• setup 返回成功。
• SQLite 能看到 9 张业务表，或飞书“流水”表可访问。
• 本位币、时区和大额线都已确认。
• 试录命令只产生预览。
• 用户知道下一步可以直接说“记一笔……”。