beancount-accounting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beancount Accounting Skill

Beancount 会计技能

Beancount is a plain-text double-entry accounting system. This skill provides expertise for creating, editing, and querying beancount files.

Beancount 是一个纯文本复式记账系统。此技能提供创建、编辑和查询Beancount文件的专业指导。

Core Concepts

核心概念

Double-Entry Accounting

复式记账

Every transaction must balance to zero. Money flows between accounts:

Debits increase Assets/Expenses, decrease Liabilities/Income/Equity
Credits decrease Assets/Expenses, increase Liabilities/Income/Equity

每笔交易的收支必须平衡为零。资金在账户间流动：

借方增加资产/支出，减少负债/收入/权益
贷方减少资产/支出，增加负债/收入/权益

Five Account Types

五种账户类型

Type	Purpose	Normal Balance
`Assets`	What you own (bank accounts, investments)	Positive
`Liabilities`	What you owe (credit cards, loans)	Negative
`Income`	Money coming in (salary, interest)	Negative
`Expenses`	Money going out (food, rent)	Positive
`Equity`	Net worth, opening balances	Negative

类型	用途	正常余额
`Assets`	你拥有的资产（银行账户、投资）	正数
`Liabilities`	你欠下的债务（信用卡、贷款）	负数
`Income`	收入（工资、利息）	负数
`Expenses`	支出（食品、房租）	正数
`Equity`	净资产、期初余额	负数

Account Naming

账户命名

Use colon-separated hierarchical names starting with capital letters:

Type:Country:Institution:Account:SubAccount

Examples:

Assets:Checking:Centennial:Joint
Liabilities:Card:Chase:Sapphire
Expenses:Food:Groceries
Income:Salary:Employer

使用以大写字母开头的冒号分隔层级名称：

Type:Country:Institution:Account:SubAccount

示例：

Assets:Checking:Centennial:Joint
Liabilities:Card:Chase:Sapphire
Expenses:Food:Groceries
Income:Salary:Employer

Transaction Syntax

交易语法

Basic Format

基本格式

beancount

YYYY-MM-DD flag "Payee" "Narration"
  Account1    Amount Currency
  Account2    Amount Currency  ; optional comment

beancount

YYYY-MM-DD flag "Payee" "Narration"
  Account1    Amount Currency
  Account2    Amount Currency  ; optional comment

Flags

标记

```
*
```
- Cleared/completed transaction
```
!
```
- Pending/needs review

```
*
```
- 已结清/完成的交易
```
!
```
- 待处理/需审核的交易

Examples

示例

Simple expense:

beancount

2026-01-03 * "Starbucks" "Morning coffee"
  Expenses:Food:Coffee    5.75 USD
  Liabilities:Card:Chase:Sapphire

Paycheck with multiple postings:

beancount

2026-01-15 * "Employer" "Bi-weekly salary"
  Assets:Checking:Main           3500.00 USD
  Expenses:Taxes:Federal          800.00 USD
  Expenses:Taxes:State            200.00 USD
  Expenses:Insurance:Health       150.00 USD
  Income:Salary                 -4650.00 USD

Transfer between accounts:

beancount

2026-01-10 * "Transfer to savings"
  Assets:Savings:Ally     500.00 USD
  Assets:Checking:Main   -500.00 USD

简单支出：

beancount

2026-01-03 * "Starbucks" "Morning coffee"
  Expenses:Food:Coffee    5.75 USD
  Liabilities:Card:Chase:Sapphire

包含多个分录的工资单：

beancount

2026-01-15 * "Employer" "Bi-weekly salary"
  Assets:Checking:Main           3500.00 USD
  Expenses:Taxes:Federal          800.00 USD
  Expenses:Taxes:State            200.00 USD
  Expenses:Insurance:Health       150.00 USD
  Income:Salary                 -4650.00 USD

账户间转账：

beancount

2026-01-10 * "Transfer to savings"
  Assets:Savings:Ally     500.00 USD
  Assets:Checking:Main   -500.00 USD

Amount Interpolation

金额自动计算

One posting amount can be omitted - beancount calculates it:

beancount

2026-01-03 * "Grocery Store" "Weekly groceries"
  Expenses:Food:Groceries    125.43 USD
  Assets:Checking:Main  ; Amount calculated as -125.43 USD

可以省略一个分录的金额，Beancount会自动计算：

beancount

2026-01-03 * "Grocery Store" "Weekly groceries"
  Expenses:Food:Groceries    125.43 USD
  Assets:Checking:Main  ; Amount calculated as -125.43 USD

Essential Directives

关键指令

open / close

Declare account lifecycle:

beancount

2026-01-01 open Assets:Checking:Main USD
2028-12-31 close Assets:Checking:Main

声明账户的生命周期：

beancount

2026-01-01 open Assets:Checking:Main USD
2028-12-31 close Assets:Checking:Main

balance

Assert account balance at start of day (catches errors):

beancount

2026-01-31 balance Assets:Checking:Main 4583.84 USD

在某日开始时断言账户余额（用于捕获错误）：

beancount

2026-01-31 balance Assets:Checking:Main 4583.84 USD

pad

Auto-generate balancing entry between two dates:

beancount

2026-01-01 pad Assets:Checking:Main Equity:Opening-Balances
2026-01-02 balance Assets:Checking:Main 4583.84 USD

在两个日期之间自动生成平衡分录：

beancount

2026-01-01 pad Assets:Checking:Main Equity:Opening-Balances
2026-01-02 balance Assets:Checking:Main 4583.84 USD

include

Split files for organization:

beancount

include "2026-01.beancount"
include "accounts.beancount"

拆分文件以便组织管理：

beancount

include "2026-01.beancount"
include "accounts.beancount"

option

Configure beancount behavior:

beancount

option "title" "Personal Finances"
option "operating_currency" "USD"

配置Beancount的行为：

beancount

option "title" "Personal Finances"
option "operating_currency" "USD"

Metadata and Tags

元数据与标签

Metadata

元数据

Attach key-value pairs to directives or postings:

beancount

2026-01-03 * "Amazon" "Office supplies"
  order-id: "123-456-789"
  Expenses:Office    45.00 USD
    category: "equipment"
  Liabilities:Card:Chase

为指令或分录添加键值对：

beancount

2026-01-03 * "Amazon" "Office supplies"
  order-id: "123-456-789"
  Expenses:Office    45.00 USD
    category: "equipment"
  Liabilities:Card:Chase

Tags and Links

标签与链接

Group related transactions:

beancount

2026-01-15 * "Hotel" "Conference lodging" #work-travel #conference-2026
  Expenses:Travel:Lodging    299.00 USD
  Liabilities:Card:Chase

2026-02-01 * "Expense Report" "Reimbursement" ^conference-2026
  Assets:Checking:Main    299.00 USD
  Income:Reimbursements

对相关交易进行分组：

beancount

2026-01-15 * "Hotel" "Conference lodging" #work-travel #conference-2026
  Expenses:Travel:Lodging    299.00 USD
  Liabilities:Card:Chase

2026-02-01 * "Expense Report" "Reimbursement" ^conference-2026
  Assets:Checking:Main    299.00 USD
  Income:Reimbursements

BQL Queries

BQL 查询

Beancount Query Language (BQL) provides SQL-like queries. Run with

bean-query

bash

bean-query finances/2026.beancount "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY 1"

Beancount查询语言（BQL）提供类SQL的查询功能。使用

bean-query

运行：

bash

bean-query finances/2026.beancount "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY 1"

Common Queries

常见查询

Account balance:

sql

SELECT account, sum(position)
WHERE account ~ 'Assets:Checking'
GROUP BY 1

Monthly expenses by category:

sql

SELECT MONTH(date), account, sum(position)
WHERE account ~ 'Expenses' AND year = 2026
GROUP BY 1, 2
ORDER BY 1, 2

Transactions for an account:

sql

SELECT date, narration, payee, position, balance
WHERE account = 'Assets:Checking:Centennial:Joint'
ORDER BY date

账户余额：

sql

SELECT account, sum(position)
WHERE account ~ 'Assets:Checking'
GROUP BY 1

按类别统计月度支出：

sql

SELECT MONTH(date), account, sum(position)
WHERE account ~ 'Expenses' AND year = 2026
GROUP BY 1, 2
ORDER BY 1, 2

某账户的交易记录：

sql

SELECT date, narration, payee, position, balance
WHERE account = 'Assets:Checking:Centennial:Joint'
ORDER BY date

Key BQL Functions

关键BQL函数

Function	Purpose
`SUM(position)`	Aggregate amounts
`YEAR(date)` , `MONTH(date)`	Extract date parts
`COST(position)`	Get cost basis
`account ~ 'pattern'`	Regex match account

函数	用途
`SUM(position)`	汇总金额
`YEAR(date)` , `MONTH(date)`	提取日期部分
`COST(position)`	获取成本基础
`account ~ 'pattern'`	正则匹配账户

Working with Beancount Files

Beancount 文件操作

Reading Files

读取文件

Before editing, read the beancount file to understand:

Existing account structure
Naming conventions used
Transaction patterns
Include file organization

编辑前，先读取Beancount文件以了解：

现有账户结构
使用的命名规范
交易模式
包含文件的组织方式

Adding Transactions

添加交易

Match existing account names exactly
Use consistent payee/narration style
Ensure transaction balances to zero
Add to chronologically appropriate location or include file

完全匹配现有账户名称
使用一致的付款方/描述风格
确保交易余额为零
添加到按时间顺序对应的位置或包含文件中

Validation

验证

Run

bean-check

to validate syntax:

bash

bean-check finances/2026.beancount

运行

bean-check

验证语法：

bash

bean-check finances/2026.beancount

Common Patterns

常见模式

Credit card payment:

beancount

2026-01-25 * "Chase" "Credit card payment"
  Liabilities:Card:Chase:Sapphire    500.00 USD
  Assets:Checking:Main              -500.00 USD

Investment purchase with cost basis:

beancount

2026-01-20 * "Fidelity" "Buy index fund"
  Assets:Investments:Fidelity:FXAIX    10 FXAIX {150.00 USD}
  Assets:Investments:Fidelity:Cash   -1500.00 USD

Mortgage payment breakdown:

beancount

2026-01-01 * "Rocket Mortgage" "Monthly mortgage"
  Liabilities:Loan:RocketMortgage     800.00 USD  ; Principal
  Expenses:Housing:Interest           900.00 USD  ; Interest
  Expenses:Housing:Escrow             300.00 USD  ; Escrow
  Assets:Checking:Main              -2000.00 USD

信用卡还款：

beancount

2026-01-25 * "Chase" "Credit card payment"
  Liabilities:Card:Chase:Sapphire    500.00 USD
  Assets:Checking:Main              -500.00 USD

包含成本基础的投资购买：

beancount

2026-01-20 * "Fidelity" "Buy index fund"
  Assets:Investments:Fidelity:FXAIX    10 FXAIX {150.00 USD}
  Assets:Investments:Fidelity:Cash   -1500.00 USD

抵押贷款还款明细：

beancount

2026-01-01 * "Rocket Mortgage" "Monthly mortgage"
  Liabilities:Loan:RocketMortgage     800.00 USD  ; Principal
  Expenses:Housing:Interest           900.00 USD  ; Interest
  Expenses:Housing:Escrow             300.00 USD  ; Escrow
  Assets:Checking:Main              -2000.00 USD

Best Practices

最佳实践

File Organization

文件组织

Use
```
include
```
to split by month or category
Keep account definitions in main file
Add transactions to appropriate include files

使用
```
include
```
按月份或类别拆分文件
将账户定义保存在主文件中
将交易添加到对应的包含文件中

Account Hierarchy

账户层级

Be consistent with naming depth
Use specific subcategories for visibility
Group related accounts logically

保持命名深度一致
使用具体的子类别以提高可见性
按逻辑对相关账户进行分组

Balance Assertions

余额断言

Add monthly balance assertions for bank accounts
Reconcile against actual statements
Catches data entry errors early

为银行账户添加月度余额断言
与实际对账单进行对账
及早发现数据录入错误

Error Prevention

错误预防

Always run
```
bean-check
```
after edits
Use balance assertions frequently
Keep transactions in chronological order

编辑后始终运行
```
bean-check
```
频繁使用余额断言
保持交易按时间顺序排列

Additional Resources

额外资源

Reference Files

参考文件

For detailed syntax and patterns, consult:

references/syntax.md
- Complete directive reference with all options
references/bql.md
- Full BQL query language documentation
references/examples.md
- Common transaction patterns and workflows

如需详细语法和模式，请查阅：

references/syntax.md
- 包含所有选项的完整指令参考
references/bql.md
- 完整的BQL查询语言文档
references/examples.md
- 常见交易模式和工作流程

Command Line Tools

命令行工具

Command	Purpose
`bean-check file.beancount`	Validate syntax
`bean-query file.beancount "QUERY"`	Run BQL query
`bean-report file.beancount balances`	Balance report
`bean-web file.beancount`	Web interface

命令	用途
`bean-check file.beancount`	验证语法
`bean-query file.beancount "QUERY"`	运行BQL查询
`bean-report file.beancount balances`	生成余额报告
`bean-web file.beancount`	网页界面