# 在 Beancount 中设置自动价格

使用[实时价格](/live-prices)为托管 Beancount.io 账本添加自动刷新的估值价格。托管价格源会为支持的加密货币、股票、基金和外币提供带日期的 `price` 指令。你仍然像往常一样记录买入、卖出和转账。

## 选择价格源

1. 打开[价格源选择器](/live-prices#price-picker)。
2. 选择你想用来为资产估值的货币。
3. 从快捷选项中选择你的资产，或按符号搜索，例如 `BTC` 或 `AAPL`。你也可以粘贴一段账本片段来查找其中的资产；该片段会保留在你的浏览器中。
4. 检查每个资产符号是否与账本中的 commodity 一致。选择器会为已收录的交易对生成 include。未收录的交易对可能支持按需推导，但在确认支持之前，选择器不会将其列出。
5. 复制生成的 include。登录 Beancount.io 以使用你的托管账本，并查看需要身份验证的价格源。

请为你的账本选择估值货币，而不是根据本页面的语言来选择。选择计价货币不会重命名 commodity，也不会改变你的交易。

## 在托管账本中包含价格源

将生成的行粘贴到 `main.bean`，或你的账本已经包含的其他文件中。每一行标识一个价格源。例如，比特币兑美元的托管 include 在下面以注释形式展示，以便该示例在使用上游 Beancount 时仍可安全加载：

```beancount
; Hosted Beancount.io ledger: remove the leading semicolon to enable this feed.
; include "https://beancount.io/prices/BTC-USD"
```

在将这一行添加到托管账本时，去掉开头的 `;`。URL include 是 Beancount.io 的扩展功能。普通的本地 include 仍然使用文件名，如[多文件支持](https://beancount.io/zh/docs/Tips/multi-file-support)中所述。

像往常一样打开你的账本。其加载器会将托管价格源解析为只读的价格条目。当账本在五分钟刷新窗口之后加载时，它会检查新数据。刷新价格不会重写你的源文件，也不会创建账本提交。托管价格条目不计入账本的条目数量限制。

## 读取价格和估值

价格源包含带日期的价格，并可能带有 `price-source`、`price-kind`、`observed-at` 和 `provisional` 元数据。在判断报价时，检查观测时间和价格类型。加载器的刷新时间不是提供商的观测时间。

这些是自动刷新的估值价格，而不是实时交易报价。报告需要相关 commodity 交易对在其估值日期当天或之前的价格。今天的价格无法填补更早报告中的空白。

价格使使用 price 指令的工具和报告能够进行市场估值。显示成本的账户视图仍然会显示成本；连接价格源不会将该视图切换为市场价值。关于成本和市场估值之间的区别，请参阅[查询指南](https://beancount.io/zh/docs/Basics/beancount-query-language)。

价格刷新不会改变你账本中记录的数量、购买成本、现金流、费用或已实现收益。它也不会填充交易的 `@` 价格或 `{cost}`。这些需要根据交易本身来记录。房产估价、虚构的示例 commodity 以及没有支持价格源的资产仍然需要你自己提供带日期的价格。

## 覆盖托管价格

当你需要特定的估值时，在可编辑的账本文件中写下你自己的带日期的 `price` 指令。对于相同的日期和 commodity 交易对，你的价格优先于托管价格源。这也适用于反向交易对，并且不依赖于 include 的顺序。

手动价格不是永久锁定：较晚日期的托管报价仍可用于较晚的估值。托管条目本身是只读的。编辑你自己的 price 指令，或移除 include 以停止使用该价格源。

## 在本地工具中使用价格

| 加载账本的位置 | 如何提供价格 |
| --- | --- |
| 托管 Beancount.io | 使用选择器生成的托管 URL include。 |
| 兼容的 `bea` CLI 版本 | 按照 CLI 的托管价格说明进行 URL 解析和导出本地价格文件。 |
| 上游 Beancount 或 Fava | 加载本地价格文件；这些工具本身不会获取 URL include。 |

关于特定版本的 CLI 行为，请使用 [bea 托管价格指南](https://github.com/bex-co/beancount-io/blob/main/cli/docs/USAGE.md#managed-price-includes)。兼容版本提供 `bea price status`、`bea price refresh` 和 `bea price export --output audit`。使用 `bea --offline balance` 进行仅缓存的读取，或使用 `bea --strict-prices check` 拒绝过时或不可用的价格源。详情请参阅 [CLI 参考](https://beancount.io/zh/docs/bea-cli-reference)以及备选的本地 Beanprice 工作流。

CLI 在获取时不带凭证，并拒绝重定向。如果某个价格源重定向到托管登录页面，则全新的 CLI 获取无法使用它，即使你已通过浏览器登录。请改用可访问的受支持价格源或本地带日期的价格。较旧的 CLI 版本可能会将任何 URL include 视为未匹配的文件通配符。

当你需要可复现的离线报告时，请保留本地带日期的价格文件。仅凭账本提交无法捕获过去估值所使用的托管价格源修订版本。请将账本和报告所使用的价格一并保存。

关于与价格服务的集成，请参阅[价格 API 参考](https://beancount.io/zh/docs/prices-api-reference)。其端点与向托管账本添加 include 是分开的。

## 排查缺失或意外的估值

| 症状 | 需要检查的内容 |
| --- | --- |
| 目录无法加载 | 重试选择器。不要从不支持的符号猜测 include URL。 |
| 选定的资产未包含在复制的 include 中 | 检查该资产在你所选计价货币中的支持情况，并与账本的符号匹配。 |
| 打开价格源时重定向到登录页面 | 登录以在托管工作流中进行查看。CLI 不会发送该会话，并拒绝重定向。 |
| 价格看起来过时 | 将观测时间与报告日期进行比较。刷新失败可能会保留先前验证过的缓存价格源；缓存数据可能已过时。 |
| 没有可用价格 | 在没有经过验证的缓存价格时，账本仍可加载，但持仓可能缺少市场估值。如有需要，请提供合适的手动价格。 |
| 你的手动价格似乎被忽略 | 检查确切的日期和交易对。较晚的托管报价可能适用于较晚的报告。 |
| 本地加载器报告未匹配的 include | 使用兼容的 `bea` 版本，或将 URL include 替换为本地价格文件。 |
| 账户价值没有变化 | 检查视图是否显示成本，以及报告是否有覆盖其估值日期的价格。 |

关于手动指令，请参阅[价格语法参考](https://beancount.io/zh/docs/Basics/syntax)；关于静态、可复现的投资记录，请参阅[可运行的账本示例](https://beancount.io/zh/docs/examples)。
