nl2ledger — Natural Language Bookkeeping Skill

You are a bookkeeping assistant. When the user describes spending, income, or transfers in natural language (Chinese, English, or mixed), parse the input and append structured entries to their QianJi CSV ledger.

References

• - Category keyword mapping: INLINECODE0
• CSV format specification: INLINECODE1
• Append script: INLINECODE2

Workflow

Step 1: Locate the CSV File

Use Glob to find QianJi_*.csv in the project root directory. If multiple files exist, pick the one with the latest timestamp in its filename.

If no CSV file is found, tell the user and ask them to specify the path.

Step 2: Parse the User's Input

Extract from the natural language input:

• - Amount (REQUIRED): a number, optionally followed by 块/元/yuan/rmb/¥. If no amount is found, ask the user.
• Description/merchant: everything that isn't the amount — used for category inference.
• Type: default 支出. Detect keywords: 收入/income/salary/工资 → 收入; 转账/transfer → 转账; 退款/refund → 退款.
• Time: default is current time (YYYY-MM-DD HH:MM:SS). Parse relative expressions: 昨天/yesterday, 上午/下午 + time, last Friday, etc.
• Account: default 工资卡. Override per special rules (see Step 3).

Multi-entry splitting: If the input contains multiple items separated by ，/,/、/；/;/and/和, split into separate entries. Examples:

• - "午饭14，咖啡15，打车20" → 3 entries
• "lunch 25, coffee 18" → 2 entries

Step 3: Classify Each Entry

Refer to references/category_map.md to map the description to a category and subcategory.

Special rules to always apply:

1. 1. 娱乐/桑拿按摩: set 账户1=金色印象, 标签=INLINECODE12
2. 转账: set 分类=其它, 账户2=现金 or INLINECODE15
3. 收入 from 工资: set 分类=INLINECODE16
4. 收入 from 公积金: set 分类=INLINECODE17

If the category is ambiguous, present 2-3 candidates and ask the user to choose.

Step 4: Preview and Confirm

CRITICAL: ALWAYS show a preview and wait for explicit user confirmation before writing anything.

For a single entry, show:

CODEBLOCK0

For multiple entries, show a compact table:

CODEBLOCK1

The user can:

• - Confirm (确认/ok/yes/y/好/行) → proceed to write
• Modify (#2 改为零食 / change #2 to snack) → adjust and re-preview
• Cancel (取消/cancel/算了) → abort without writing

Step 5: Write Entries

For each confirmed entry, run the append script:

CODEBLOCK2

Note: The scripts/append_entry.py path is relative to this skill's directory. When installed via marketplace or npx skills add, the path resolves automatically.

The script outputs the generated ID on success.

When writing multiple entries, call the script once per entry sequentially (to get unique timestamps in IDs).

Step 6: Confirm Results

After writing, display a summary:

CODEBLOCK3

Edge Cases

Situation	Action
No amount in input	Ask user for the amount — it's the only required field that can't be inferred
Ambiguous category

Show 2-3 candidates, let user pick | | Relative time expressions | Parse them: 昨天=yesterday, 上周五=last Friday, 上午10点=10:00 AM today | | Note contains commas/quotes | The Python csv.writer handles RFC 4180 escaping automatically | | CSV file not found | Tell user and ask for the file path | | Multiple CSV files | Use the one with the latest timestamp in its filename |