运行 Beancount & 生成报告
Martin Blais，2014 年 7 月至 9 月
http://furius.ca/beancount/doc/tools
重要提示：本文档适用于已弃用的 v2 分支工具。许多此类工具在 v3 及更高版本中已被删除。
引言
本文档介绍了您用于处理 Beancount 输入文件的工具，以及其中可用的多种报表。该语言的语法在 Beancount 语言语法 文档中描述。本手册仅涵盖从命令行使用 Beancount 的技术细节。
工具
bean-check
bean-check 是用于验证您的输入语法和交易是否正确的程序。它仅加载您的输入文件并运行其中配置的各种插件，以及一些额外的验证检查。它会报告错误（如有），然后退出。您可以通过以下方式在输入文件上运行它：
bean-check /path/to/my/file.beancount
如果没有错误，则不应有任何输出，程序将安静退出。如果存在错误，它们将被打印到 stderr，包含文件名、行号和错误描述（格式与 Emacs 兼容，因此您可以直接使用 next-error 和 previous-error 导航到相应文件）：
/home/user/myledger.beancount:44381: Transaction does not balance: 34.46 USD
2014-07-12 * "Black Iron Burger" ""
Expenses:Food:Restaurant 17.23 USD
Assets:Cash 17.23 USD
在生成报表之前，您应始终修复所有错误。
bean-report
这是用于将专用报表提取到控制台（以文本或其他多种格式）的主要工具。您可通过以下方式调用它：
bean-report /path/to/my/file.beancount <report-name>
例如：
bean-report /path/to/my/file.beancount balances
可用的报表有很多。请参阅报表部分了解主要报表的说明。如需获取完整的报表列表，请请求帮助：
bean-report --help-reports
报表名称有时可以接受参数。目前，参数作为报表名称的一部分指定，通常用冒号（:）分隔，如下所示：
bean-report /path/to/my/file.beancount balances:Vanguard
有几个您应了解的特殊报表：
-
check 或 validate：这与运行 bean-check 命令相同。
-
print：它仅以 Beancount 语法打印出 Beancount 已解析的条目。这可用于确认 Beancount 是否正确读取和解释了您的输入数据（在调试复杂问题时很有用）。
其他报表均为您所预期的：它们打印出各种金额的汇总表格。您可以生成的报表将在下面的专门部分中描述。
| 请注意！ 在当前版本发布时，网页上可用的报表列表与控制台上的列表有所不同。在未来的版本中，我将合并这两个列表，使网页上所有可用的报表也都能在控制台上使用，并支持多种格式。敬请关注。 |
bean-query
Beancount 解析的交易和分录列表类似于内存数据库。bean-query 是一个命令行工具，充当该内存数据库的客户端，您可以在其中输入类 SQL 查询。您可通过以下方式调用它：
bean-query /path/to/my/file.beancount
Input file: "/path/to/my/file.beancount"
Ready with 14212 directives (21284 postings in 8879 transactions).
beancount> _
更多详细信息请参阅其独立文档。
bean-web
bean-web会在您计算机上运行的 Web 服务器上提供所有报表。您可以这样运行它：
bean-web /path/to/my/file.beancount
它将在您的机器的 8080 端口提供所有页面。请在网页浏览器中访问http://localhost:8080，您应该能够轻松地点击浏览所有报表。
Web 界面提供一组全局页面和每个“视图”对应的报表页面。
全局页面
顶级目录页面在顶部提供了指向所有全局页面的链接：
-
目录（您当前查看的页面）
-
您的账本文件中发生的错误列表
-
您的 Ledger 文件源代码视图（当引用输入文件中的位置时，其他链接会使用此功能）
目录提供了指向所有常用视图的便捷链接，例如：
-
“按年份查看”，
-
“按标签查看”，以及当然，
-
“查看所有交易”。
还有其他一些视图。
视图报表页面
当您点击某个视图报表页面时，您将进入该视图对应交易子集的一组页面，可从这里获取各种报表：
-
期初余额（视图开始时的资产负债表）
-
期末余额（视图结束时的资产负债表）
-
损益表（视图期间的损益情况）
-
各账户的各类明细账（只需点击账户名称即可）
-
视图结束时的各种持仓报告
-
视图条目中包含的文档和价格列表
-
关于视图数据的一些统计信息
……以及更多内容。应有一个包含所有可用视图报表的索引。
bean-bake
bean-bake会运行一个bean-web实例，并将所有页面导出到目录中：
bean-bake /path/to/my/file.beancount myfinances
它还支持直接导出到归档文件：
bean-bake /path/to/my/file.beancount myfinances.zip
支持多种压缩方式，例如.tar.gz。
这非常适用于与您的会计师或其他人员共享 Web 界面，因为他们通常无法运行 Beancount。所有页面链接均已转换为相对链接，他们只需将归档文件解压到目录中，即可像您使用bean-web一样浏览所有报表。
bean-doctor
这是一个调试工具，用于执行各种诊断和运行调试命令，并帮助提供报告错误所需的信息。例如，它可以执行以下操作：
-
列出您机器上已安装和缺失的 Beancount 依赖项。它能告诉您需要安装但尚未安装的内容。
-
打印输入文件中解析器的词法分析器标记。如果您报告解析错误，查看词法分析器输出（如果您了解其含义）会很有帮助。
-
它可以对输入文件进行解析-回写循环测试，即输出文件内容并重新读取，然后进行比较。这是一种有用的解析器和输出器测试方法。
-
它可以检查目录层次结构是否与 Beancount 输入文件的科目表一致，并报告不符合要求的目录。如果您决定更改某些账户名称，并需要相应调整对应的文档存档，这将非常有用。
上下文
它可以列出交易应用时的上下文，即交易条目所修改的每个账户在应用前后的库存余额。使用方法如下：
$ bean-doctor context /home/blais/accounting/blais.beancount 28514
/home/blais/accounting/blais.beancount:28513:
; Assets:US:ETrade:BND 100.00 BND {81.968730000000 USD}
; Assets:US:ETrade:Cash 8143.97 USD
2014-07-25 * "(TRD) BOT +50 BND @82.10" ^273755872
Assets:US:ETrade:BND 50.00 BND {82.10 USD}
Assets:US:ETrade:Cash -4105.00 USD
; Assets:US:ETrade:BND 100.00 BND {81.968730000000 USD}
; ! Assets:US:ETrade:BND 50.00 BND {82.10 USD}
; ! Assets:US:ETrade:Cash 4038.97 USD
对应的 Emacs 快捷键是 C-c x，可在光标所在位置调用此功能。
bean-format
这个纯文本处理工具会重新格式化 Beancount 输入文件，使所有数字在相同的最小列位置右对齐，并将所有货币符号左对齐。它仅修改空白字符。该工具接受文件名作为参数，并将对齐后的文件输出到标准输出（类似于 UNIX 的 cat 命令）。
bean-example
此程序会生成一个示例 Beancount 输入文件。有关此示例文件内容的更多详情，请参阅教程。
筛选交易
为了生成财务交易的不同视图，我们会从解析后的完整交易列表中选取一个子集，例如“2013 年发生的所有交易”，然后使用该子集生成 Beancount 提供的各种报告。
目前，网络界面中仅提供一组预设的筛选器作为“视图”。这些视图包括：
-
所有交易
-
特定年份发生的交易
-
带有特定标签的交易
-
涉及特定交易方的交易
-
至少包含一个具有特定名称组成部分的账户的交易
目前，要访问这些交易子集的报告，您需要使用 bean-web 网络界面，并在根全局页面上点击相关关键词，从而进入该视图对应的报告集合。
报告
将交易输入到单个文件中的根本目的，是为了能够对数据的各个子集进行求和、筛选、聚合和整理，从而生成众所周知的报表。Beancount 提供了三种不同的方式来生成报表：通过使用 bean-web 浏览到某个视图，再进入特定报表（这是最简单的方式）；通过使用 bean-report 并指定所需报表的名称（以及可能的报表特定参数）；或通过使用 bean-query 并通过指定 SQL 语句来请求数据。
某些报表可以以不同的文件格式呈现。每种报表类型通常支持多种常见格式，例如控制台文本、HTML 和 CSV。有些报表直接以 Beancount 语法格式输出，我们将其简称为 “beancount” 格式。
目前提供了多种报表类型，未来还将增加更多，因为许多路线图功能都涉及新的输出类型。本节将概述最常见的几种报表。要查看您安装版本支持的完整报表列表，请使用 bean-report 命令查询：
bean-report --help-reports
| 请注意！ 目前，网页界面和命令行界面提供的报表集合有所不同，尽管存在部分重叠。在后续版本中，这些报表列表将被统一，所有报表都将通过网页界面和命令行界面以多种数据格式（文本、CSV、HTML 及可能的其他格式）提供。目前，我们将在下面的章节中分别说明。 |
余额报表
所有余额报表都类似，它们生成包含一组账户及其对应余额的表格：[输出]
|-- Assets
| `-- US
| |-- BofA
| | `-- Checking 596.05 USD
| |-- ETrade
| | |-- Cash 5,120.50 USD
| | |-- GLD 70.00 GLD
| | |-- ITOT 17.00 ITOT
| | |-- VEA 36.00 VEA
| | `-- VHT 294.00 VHT
| |-- Federal
| | `-- PreTax401k
| |-- Hoogle
| | `-- Vacation 337.26 VACHR
| `-- Vanguard
...
以“成本价”持有的商品余额，按其账面价值显示。（未实现收益（如有）由可选插件作为独立交易插入，若在同一账户中显示，结果金额将与成本基础混合。）
如果某个账户的余额包含多种不同货币（非“按成本价”持有的商品，如美元、欧元、日元），每种货币将单独占一行。这可能导致余额列过于拥挤，影响账户名称的垂直整齐性。这在一定程度上是不可避免的折衷，但实践中，用户账本中绝大多数金额通常仅由少数几种货币构成——即本国货币单位。为此，可以使用 “operating_currency” 选项将常见货币的金额拆分到独立列中：
option "operating_currency" "USD"
option "operating_currency" "CAD"
如果您拥有多种此类货币，可以多次使用此选项（例如，我作为外籍人士，在居住国和母国均持有资产）。声明运营货币还有一个优势：无需显示货币名称，从而更便于导入电子表格。
最后，未关闭的账户被视为“活跃账户”。在过滤后的交易集中，若某已关闭账户无任何交易，则不会被显示。
试算平衡表 (balances)
试算平衡表 报表仅生成所有活跃账户的最终余额表格，所有账户均垂直排列。
底部会报告所有余额的总和。与资产负债表不同，它不一定平衡为零，因为可能存在货币兑换差异。（这相当于 Ledger 的 bal 报表。）
等效的 bean-query 命令是：
SELECT account, sum(position)
GROUP BY account
ORDER BY account;
资产负债表 (balsheet)
资产负债表 是在特定时间点上资产、负债和权益账户余额的快照。为了生成此类报表，我们需要将其他账户的余额转移至该表中：
-
计算该时间点收入和费用账户的余额，
-
插入交易，将这些账户的余额清零，并转移至权益账户 (
Equity:Earnings:Current)， -
在左侧呈现资产账户的余额树状结构，
-
在右侧呈现负债账户的余额树状结构，
-
在负债账户下方呈现权益账户的余额树状结构。
参见入门文档中的示例。
请注意，权益账户包含从收入和费用账户报告的金额，这些金额通常也称为“净利润”。
此外，在实际操作中，我们会进行两次转移，因为我们通常关注的是一个报告期，并希望区分在报告期开始前转移的净利润金额 (Equity:Earnings:Previous) 和在报告期内转移的金额 (Equity:Earnings:Current)。同样，为了处理货币兑换，也会执行一对类似的转移（这是一个稍显复杂的话题，但有一个出色的解决方案；如需了解所有细节，请参阅专用文档)。
等效的 bean-query 命令是：
SELECT account, sum(position)
FROM CLOSE ON 2016-01-01
GROUP BY account ORDER BY account;
期初余额 (openbal)
期初余额报表只是在报告期开始时绘制的资产负债表。此报表仅对代表特定时间段（如“2014 年”）的过滤后条目列表有意义。该资产负债表仅使用在筛选交易时合成的汇总条目生成（参见复式记账法文档)。
利润表 (income)
利润表 列出了收入和费用账户的最终余额。它代表了这些账户中瞬时活动的汇总。如果资产负债表是某一时间点的快照，那么利润表就是报告期开始与结束之间的差值（在我们的情况中：即过滤后交易集的差值）。活跃收入账户的余额显示在左侧，活跃费用账户的余额显示在右侧。参见入门文档中的示例。
收入与费用余额的差额即为净利润。
请注意，收入和费用账户的期初余额应已在报告期开始时通过汇总交易清零，因为我们只关注这些账户的变化。
日记账报表
本节中的报表以线性方式呈现交易和其他指令列表。
日记账 (journal)
此报表相当于机构的“账户对账单”，即包含至少一笔该账户过账的交易列表。这等同于 Ledger 的登记报告 (reg)。
您可以通过以下方式生成日记报告：
bean-report myfile.beancount journal …
默认情况下，这会渲染所有交易的日记，但这可能并非您想要的结果。请选中特定账户以如下方式渲染：
bean-report myfile.beancount journal -a Expenses:Restaurant
目前，“-a”选项仅接受完整的账户名称，或其任一父账户的名称。未来我们将扩展其以支持表达式。
按成本价渲染
右侧的数字列显示所选账户的记账变动。请注意，仅渲染影响该账户的记账余额。
变动列会显示受影响单位的变化。例如，如果选中以下记账：
Assets:Investments:Apple 2 AAPL {402.00 USD}
变动值将显示为“2 AAPL”。如果您希望按成本价渲染数值，请使用“--at-cost”或“-c”选项，此时将显示“804.00 USD”。
没有“市价”选项。未实现收益由“beancount.plugins.unrealized”插件自动在历史记录末尾插入。请参阅该插件的选项以添加其未实现收益。
请注意，如果所选记账的总和为零，则变动列中不会显示任何金额。
添加余额列
如果您希望添加一列以累计所报告变动的余额，请使用“--render-balance”或“-b”选项。这并非总是有意义，因此由您决定是否需要累计余额。
字符宽度
默认情况下，报告宽度将与您的终端允许的最大宽度一致。使用“-w”选项可将宽度限制为指定字符数。
精度
数字渲染的小数位数可通过“--precision”或“-k”选项指定。
紧凑、普通或详细模式
默认情况下，Beancount 会在交易之间插入空行，这有助于区分涉及多种货币的交易（它们会分别显示在不同行）。如需更紧凑的显示，请使用“--compact”或“-x”选项。
另一方面，如需在交易行下方显示受影响的记账，请使用“--verbose”或“-X”选项。
摘要
以下是其参数的摘要：
optional arguments:
-h, --help show this help message and exit
-a ACCOUNT, --account ACCOUNT
Account to render
-w WIDTH, --width WIDTH
The number of characters wide to render the report to
-k PRECISION, --precision PRECISION
The number of digits to render after the period
-b, --render-balance, --balance
If true, render a running balance
-c, --at-cost, --cost
If true, render values at cost
-x, --compact Rendering compactly
-X, --verbose Rendering verbosely
等效 SQL 查询
等效的 bean-query 命令是：
SELECT date, flag, description, account, cost(position), cost(balance);
货币兑换（conversions）
此报告列出所选交易产生的货币兑换总额。（大多数人不需要此功能。）
文档（documents）
此报告生成一个 HTML 列表，列出账本中所有外部文档，这些文档可能来自显式指令，或来自自动查找文档并将其添加到交易流的插件。
持仓报告
这些报告对按成本价持有的资产进行汇总。
持仓与汇总 (holdings*)
此报告生成账本中所有持仓的详细列表。您可以使用“-g”选项按商品和账户生成汇总数据。
净资产 (networth)
此报告以每种运营货币为单位，简要总结账本的净资产（权益）。
其他报告类型
现金
此报告呈现以成本以外方式持有的商品余额，即现金：
bean-report example.beancount cash -c USD
Account Units Currency Cost Currency Average Cost Price Book Value Market Value
-------------------------- --------- -------- ------------- ------------ ----- ---------- ------------
Assets:US:BofA:Checking 596.05 USD USD 596.05 596.05
Assets:US:ETrade:Cash 5,120.50 USD USD 5,120.50 5,120.50
Assets:US:Hoogle:Vacation 337.26 VACHR
Assets:US:Vanguard:Cash -0.02 USD USD -0.02 -0.02
Liabilities:US:Chase:Slate -2,891.85 USD USD -2,891.85 -2,891.85
-------------------------- --------- -------- ------------- ------------ ----- ---------- ------------
该报告允许您将所有货币转换为一种通用货币（如上例中的“将所有内容转换为美元”）。此外，还有一个选项仅报告运营货币。我使用此功能来概览所有未投资的现金。
价格 (prices)
此报告以报价货币为单位，列出基础货币的价格点列表，按日期排序。您也可以将此表格以 Beancount 格式输出。这便于将价格数据库保存到文件中，以便后续合并并加载到其他输入文件中。
统计信息 (stats)
此报告提供对已解析条目的各种统计信息。
更新活动 (activity)
此表格为每个账户显示最后一条条目的日期。