setup-ai-bookkeeping

Setup AI Bookkeeping

Prepare the same ledger for the other 3 bookkeeping Skills.

When to trigger

• "Start bookkeeping / initialize ledger / create bookkeeping table"
• "Connect AI bookkeeping to Feishu Bitable"
• "Check bookkeeping configuration / whether the ledger works"
• "Make me a reproducible local Demo"

Shared entry point

First determine the repository root directory and configuration file. It is recommended to save the repository root directory as AI_BOOKKEEPING_HOME, and for the real configuration it is recommended to use config.json：

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

Do not display the Feishu app secret in replies, logs, or committed files.

Execution flow

1. Ask about or determine the storage location:

   • The user wants to try it out first, use it offline, or run a Demo: choose SQLite.
   • The user has app credentials and connects to an existing table: choose Feishu HTTP.
   • The user already has a lark-cli profile on this machine: choose lark_cli user authorization mode.

2. From config.example.json copy a real configuration, and fill in the base currency, time zone, and large-amount confirmation threshold.

3. In SQLite mode run setup, then confirm that 9 business tables are returned.

4. In Feishu mode, first check:

   • The "Transactions" table has been created according to schema/data-model.md .
   • app_token and table_ids.transactions have been filled in.
   • FEISHU_APP_ID and FEISHU_APP_SECRET exist only as environment variables.
   • The app has read and write permissions for the Bitable, and has been added as a collaborator of that Bitable.

5. Run setup to check the connection. When encountering Feishu errors, keep the error code and give directly executable repair suggestions.

6. Use a small transaction as a preview, keeping it uncommitted:

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

7. Report to the user the ledger location, backend, currency, time zone, and the 3 available follow-up Skills.

Create a Feishu workspace from scratch

When the user explicitly requests creating a new workspace, use the generic table creation script. First do a dry run:

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

Confirm with the user that 1 Base, 9 tables, and the corresponding fields will be created. After obtaining explicit confirmation, execute the same command, changing --dry-run to --apply。

The script uses the lark-cli profile and user identity from the configuration, and serially calls +base-create、+table-create and +field-create. After completion, take the Base token and the table ID of "Transactions" from the local results, put them respectively into protected environment variables and an ignored local configuration, then run setup. Resource identifiers themselves do not grant permissions, and should not be committed to public repositories, articles, or chat records.

Table creation conventions

The local ledger includes: Transactions, Pending Inputs, Accounts, Categories, Budgets, Project Ledgers, Recurring Plans, Income Goals, and Settings.

The field names in Feishu HTTP mode use schema/feishu-field-map.example.jsonby default. lark-cli mode adapts by default to the existing workspace fields in schema/ai-bookkeeping-workbench-v1.json . If the user has changed field names, override the corresponding mappings in the configuration's field_map .

Repeated execution

setup Can be run repeatedly. SQLite only fills in missing tables and default dictionaries; it does not clear old entries. The two Feishu connection backends only check the target tables and do not modify the table structure; creating a blank workspace uses a separate provision script.

Boundaries and Security

• Without the user's explicit consent, do not delete the database, clear the multi-dimensional table, or overwrite existing configuration.
• Do not write keys directly into JSON.
• If the Feishu table is missing fields, list the missing items and have the user or administrator fill them in before retrying.
• If the user only wants to research the approach, stop at the configuration and field list, and do not perform online writes.
• If the user already has a ledger, back it up first or use a new table for a migration drill.

Completion Check

• setup Return success.
• SQLite can see 9 business tables, or the Feishu "Transactions" table is accessible.
• The base currency, time zone, and large-amount threshold have all been confirmed.
• The trial entry command only produces a preview.
• The user knows that the next step can be to directly say "Record an entry...".