# Setup AI Bookkeeping

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

- Skill: `tjxj/setup-ai-bookkeeping` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tjxj/setup-ai-bookkeeping`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tjxj/setup-ai-bookkeeping/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tjxj (https://skillmd.com/u/tjxj)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tjxj/setup-ai-bookkeeping

---


# Setup AI Bookkeeping

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

## 何时触发

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

## 共用入口

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

```bash
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. 用一条小额流水做预览，保持不提交：

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

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

## 从空白创建飞书工作台

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

```bash
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 张业务表，或飞书“流水”表可访问。
- 本位币、时区和大额线都已确认。
- 试录命令只产生预览。
- 用户知道下一步可以直接说“记一笔……”。