mcpField
B
Beancount Accounting

Beancount Accounting

github.com/ouachitalabs其他2206 次安装39 周前更新
代码仓库

关于 Beancount Accounting

为使用 Beancount 的个人财务记账者提供技能指南，涵盖纯文本复式记账文件的创建、编辑和查询，并说明常见指令、BQL 与验证命令。

主要功能

  1. 01编写与编辑 Beancount 文件
  2. 02遵循复式记账平衡规则
  3. 03使用账户、交易与元数据指令
  4. 04通过 BQL 查询账务数据
  5. 05使用 bean-check 验证文件

适用场景

  1. 01记录日常收支与账户转账
  2. 02按类别汇总月度支出
  3. 03核对银行账户余额
  4. 04验证修改后的账务文件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ouachitalabs/skills --skill beancount-accounting

安装后在 Claude Code 中输入/beancount-accounting确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
bql.md
examples.md
syntax.md

详细介绍

Beancount 会计技能

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

核心概念

复式记账

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

  • 借方增加资产／费用，减少负债／收入／权益
  • 贷方减少资产／费用，增加负债／收入／权益
五种账户类型
类型用途正常余额
Assets你拥有的资产（银行账户、投资）正数
Liabilities你欠下的款项（信用卡、贷款）负数
Income收入（薪水、利息）负数
Expenses支出（食品、房租）正数
Equity净资产、期初余额负数
账户命名

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

Type:Country:Institution:Account:SubAccount

示例：

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

交易语法

基本格式
YYYY-MM-DD flag "Payee" "Narration"
  Account1    Amount Currency
  Account2    Amount Currency  ; optional comment
标记
  • * - 已结清／已完成的交易
  • ! - 待处理／需要审核
示例

简单支出：

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

包含多个分录的薪资：

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

账户间转账：

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

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

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

必备指令

open / close

声明账户的生命周期：

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

断言账户在当天开始时的余额（用于发现错误）：

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

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

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

拆分文件以便整理：

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

配置 Beancount 的行为：

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

元数据和标签

元数据

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

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

将相关交易分组：

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 查询

Beancount 查询语言（BQL）提供类似 SQL 的查询。使用 bean-query 运行：

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

账户余额：

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

按类别统计每月支出：

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

某个账户的交易：

SELECT date, narration, payee, position, balance
WHERE account = 'Assets:Checking:Centennial:Joint'
ORDER BY date
常用 BQL 函数
函数用途
SUM(position)汇总金额
YEAR(date), MONTH(date)提取日期部分
COST(position)获取成本基础
account ~ 'pattern'正则匹配账户

使用 Beancount 文件

读取文件

编辑之前，先阅读 Beancount 文件，了解：

  • 现有账户结构
  • 使用的命名惯例
  • 交易模式
  • include 文件的组织方式
添加交易
  1. 完全匹配现有账户名称
  2. 统一收款方／摘要的风格
  3. 确保交易借贷平衡为零
  4. 添加到时间顺序合适的位置或 include 文件中
验证

运行 bean-check 验证语法：

bean-check finances/2026.beancount
常见模式

信用卡还款：

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

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

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

房贷还款明细：

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

最佳实践

文件组织
  • 使用 include 按月份或类别拆分文件
  • 在主文件中保留账户定义
  • 将交易添加到合适的 include 文件中
账户层级
  • 保持命名层级一致
  • 使用具体的子类别以便查看
  • 按逻辑对相关账户分组
余额断言
  • 为银行账户添加每月余额断言
  • 对照实际账单进行核对
  • 及早发现数据录入错误
预防错误
  • 编辑后始终运行 bean-check
  • 经常使用余额断言
  • 按时间顺序排列交易

其他资源

参考文件

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

  • references/syntax.md - 完整的指令参考，包含所有选项
  • references/bql.md - 完整的 BQL 查询语言文档
  • references/examples.md - 常见交易模式和工作流
Command Line Tools
CommandPurpose
bean-check file.beancountValidate syntax
bean-query file.beancount "QUERY"Run BQL query
bean-report file.beancount balancesBalance report
bean-web file.beancountWeb interface

评论

支持 Markdown