你已经把代码库、终端和最难的调试会话交给了你的 AI 代理。现在把账本也交给它——它起草的每笔分录都会经过你批准的预览和一个检查数学的验证器。bea 命令行工具用两条命令即可安装，在你自己的机器上处理纯文本账本文件，本地记账无需任何账户。
用两条命令安装
有两种发布方式可以获得同一个命令。选择适合你机器的那种，然后确认它能返回版本号：
$ uv tool install beancount-io
$ brew install bex-co/tap/bea
$ bea --version
bea 0.1.0Python 发行版是 beancount-io，它安装的可执行文件是 bea，当前版本为 0.1.0。uv 路径适用于任何装有 Python 3.12 或更高版本的环境；Homebrew 路径覆盖 macOS 和 Linux。完整教程在安装页面上，CLI 快速入门中有相同步骤。
你代理的第一个任务只需几分钟
你不需要新代理、插件或平台迁移。把这段内容粘贴到你已经在用的、支持 shell 的 AI 代理中，放在一个新的空演示目录里：
你有 shell 权限，且已安装
beaCLI。首先运行bea --help并阅读它提供了什么。然后，在一个新的空演示目录中（不要碰任何现有账本）：1) 创建一个美元账本，在 2026-08-01 开设 Assets:Checking，余额为 1000；2) 在 2026-08-02 添加一笔 12.50 美元、记账说明为 "Coffee" 的购买，记入 Expenses:Dining；3) 运行bea check；4) 报告 Assets:Checking 的余额，以及你使用的确切 BQL 查询。预期结果：987.50 美元。
同样的步骤用普通命令表示：
$ bea --no-input init demo-books --currency USD --date 2026-08-01 --opening-balance "Assets:Checking 1000"
$ cd demo-books
$ bea add transaction --date 2026-08-02 --narration "Coffee" --posting "Expenses:Dining 12.50" --posting "Assets:Checking"
$ bea check
$ bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"预期结果：Assets:Checking 持有 987.50 美元——1000 减去 12.50，由 check 验证，并通过计算结果的那个查询报告回来。当你的代理把那个数字交给你时，它就完成了第一次闭环：起草、验证、报告。代理指南在这个闭环上构建了两个更完整的配方——先预览再审查地导入银行 CSV，以及从查询输出回答余额问题。
你需要什么，这适合谁
一个终端、一个网络连接，以及 Homebrew 或带 Python 3.12 或更高版本的 uv。本地导入、查询、报告和检查命令不需要 Beancount.io 账户，你的账本文件留在你选择的目录中，作为可以 diff、备份和版本控制的纯文本。
这适合自己管理创业公司账簿的技术创始人、已经生活在终端中的独立开发者，以及寻找一个 AI 可以针对其起草更改而不会静默写入的账本的代理构建者。如果你的账本已经在云产品中，诚实的答案是另一回事——请参阅下面的比较部分。
托管路径是可选的，并且是独立的
以上内容都不需要账户，也不会把你的账本发送到任何地方。有两项额外功能需要，而且两者都刻意与安装 CLI 分开：
bea ask通过托管 AI 服务回答有关本地账本的问题。它需要 ask 附加组件——uv tool install 'beancount-io[ask]'——以及你的 Beancount.io 凭据。默认安装会省略 AI 依赖项，直到你明确要求。- MCP 服务器和托管账本同样使用你的 Beancount.io 账户登录以授权访问。Beancount 的代理技能位于产品仓库中，并单独加载到你的代理中——安装 CLI 并不会安装或配置它们。
从本地开始；只有在你想要时才连接托管。
证明：一个代理，三行，已验证的账本
发布声明只有可复现才有价值。因此，CLI 附带了一个合成的三行挑战，其答案在任何报告运行之前就从算术推导出来：账本在 2026-09-01 开设，支票账户中有 1000 美元，账单上有一笔 2000.00 美元的客户付款、一笔 −29.00 美元的托管费用和一笔 −12.50 美元的咖啡馆消费，预期答案是支票账户中有 2958.50 美元（1000 + 2000 − 29 − 12.50）和 1958.50 美元的九月份利润（2000 − 29 − 12.50）。
一个已安装 CLI 的验证器在一个全新的临时目录中运行整个闭环：预览报告 3 条就绪且不写入任何内容，第一次应用写入 3 条分录，相同的重新导入写入 0 条且账本字节保持不变，一笔不平衡的写入（−5 支票对 +4 餐饮）以退出码 1 结束且字节保持不变，check 返回有效。确切输入可下载为 main.bean、statement.csv 和 rules.toml。
然后一个真实的代理运行了相同的挑战：客户端 muse 1.1.1（Muse Code），模型 muse-spark-1.3-contributor，无头模式，22 次工具调用，退出码 0，没有人工干预——而且关键的是，没有提供 rules.toml，所以代理自己推导了分类规则。它预览了 3 条就绪，应用了 3 条分录，运行了干净的检查，并报告了 2958.50 美元支票余额和 1958.50 美元九月份利润，两者随后都对照独立的预期值重新验证。完整记录——实际提示词、每次工具调用，以及它自己诊断出的一个真实失败（沙盒缓存锁，通过将 XDG_CACHE_HOME 指向工作目录内解决）——发布为记录运行，并有原始转录在旁边。
下面的终端会话是该运行工作路径的确定性重放，由 demo-replay.sh 从规范下载重建——它重新执行命令，因此嵌入了分类规则以保证确定性，而不是重新推导它们。demo-replay.txt 中的捕获输出与观看它承载相同信息：
$ bea --version
bea 0.1.0
$ bea import (preview)
csv → Assets:Checking: 3 ready, 0 exact duplicates, 0 possible duplicates
$ bea import --apply
Wrote 3 entries to $WORK/books/main.bean.
$ bea check
$WORK/books/main.bean: no errors
$ bea balance Assets:Checking
Checking 2,958.50 USD
$ bea report income-statement -t 2026-09
Net Profit: 1,958.50 USD
checking: 2958.50 USD (expected)
profit: 1958.50 USD (expected)
REPLAY OK: preview 3/0, applied 3, check clean, 2958.50 / 1958.50 USD.这个证据带有两个诚实的局限。它是针对合成数据上单客户端单次运行的 CLI 输出验证——不是模型基准，也不声称适用于其他客户端或无人值守的生产使用。通过 check 只证明账本平衡，绝不证明代理为咖啡馆选择了正确的账户：分类判断是代理的，结构验证是 bea 的。三行玩具测试的是闭环，而不是判断。
在工具之间选择
如果你在为代理工作流挑选账本而不是认准这一个，请阅读五工具比较：Beancount.io、Xero、QuickBooks Online、Puzzle 和 hledger 在相同的七个代理工作流标准上评分——安装、认证、读写范围、本地与云端数据、预览和验证、结构化输出，以及重复导入行为——有 2026-09-10 检查的带日期官方来源。Beancount.io 是那里唯一有观察到的端到端运行背后的工具；该页面说明了这一点，点名了其发布者，并标注了它未测试的内容。
下一步去哪里
- 安装页面——两条命令、第一个任务和挑战下载集中在一处。
- CLI 快速入门——安装以及 987.50 美元的工作示例。
- 代理指南——两个配方：带先预览后审查的 CSV 导入，以及从查询输出回答余额问题。
- 记录运行——包含方法论、失败和局限的完整证明故事。
- 五工具比较——哪种工具适合哪种代理工作流。
简化你的财务管理
判断这一切的最快方式是上面的演示：安装 bea，把任务粘贴到你已经在用的代理中，然后自己检查 987.50 美元。Beancount.io 提供纯文本记账，让每个余额都可复现、每个更改都可审查——没有黑盒，没有供应商锁定。给你的代理第一个账本，看它会交回什么。
