使用 bea import 预览银行导出文件，审查重复项，并将验证通过的条目追加到你本地的账本。
你需要一个现有的账本，以及一个针对你银行确切导出格式编写的Python导入器。如果你是刚开始记账，请遵循命令行快速入门。保留原始银行导出文件，以便与预览进行比较。
1. 选择导入器
导入器负责读取银行文件并提供交易账户。Bea不会猜测格式，也不会使用AI模型对购买进行分类。
你的 importers.py 配置导出 CONFIG = [importer, ...]。导入器使用当前的Beangulp接口：identify(filepath)、account(filepath) 和 extract(filepath, existing)。源账户的分录需要明确的金额，以便进行重复匹配。
对于首次练习运行，将示例分类CSV配置保存为 importers.py，放在你的根账本旁边。它只使用Beancount和Python标准库，因此适用于Homebrew安装。
将以下示例保存为同一目录下的 bank.csv：
Date,Payee,Narration,Amount,Currency,Category,BankID
2026-08-02,Cafe,Coffee,-5.25,USD,Expenses:Dining,bank-001
2026-08-03,Employer,Salary,1000,USD,Income:Salary,bank-002该示例使用带符号的支票账户金额：支出为负数，存款为正数。Category 提供另一个账户。这两个类别都在由 bea init 创建的USD模板中。
导入你银行的原生CSV、OFX或QIF文件时，请使用为你的银行编写的导入器。示例配置期望的正是上述列。只执行你信任的Python配置。
2. 预览条目
从包含 main.bean 的目录运行以下命令：
bea import bank.csv --config importers.py此时不会向账本写入任何内容。请审查预览中的日期、收款方、带符号的源金额、目标账户、重复匹配项以及提议的文件差异。
对于示例，预览应包含一笔5.25美元的餐饮支出和一笔1,000美元的工资存款。如果在导入器或源数据中发现分类错误，请修正后再次预览。在应用导入之前，打开任何缺失的账户。
如果有多个导入器识别该文件，请按名称选择其中一个：
bea import bank.csv --config importers.py --importer categorized-checking未知的名称会列出已配置的名称。已知但未识别该文件的导入器会单独报告。
3. 应用审查后的条目
bea import bank.csv --apply
bea check
bea list transaction --limit 10命令行会记住此根账本的配置路径。后续运行会优先使用显式的 --config，然后是记住的路径，最后是根目录旁边的 importers.py。输出会指明路径及其来源。
--apply 会根据当前文件重新计算预览。在写入之前，它会验证完整的候选账本。如果验证失败，原始账本保持不变，并退出码1。如果账本并发修改，则退出码4；请检查修改内容，并在重试前运行一次新的预览。
4. 解决可能的重复项
重复运行相同的示例导入会跳过其现有条目。重叠的导出文件也可能包含需要你决策的行：
| 预览状态 | 含义 | 应该怎么做 |
|---|---|---|
new | 未找到重复证据 | 检查金额和分类 |
duplicate | 稳定ID和交易详情匹配，或存在相同的非交易指令 | 已跳过 |
possible_duplicate | 日期、标准化后的收款方以及带符号的源金额/货币匹配 | 将预览与现有条目进行比较 |
conflict | 稳定ID匹配到不同的交易详情 | 解决ID或数据差异，然后再次预览 |
不同的银行ID并不能排除重复项。银行在后续下载中可能会更改ID。两笔真实的购买也可能共享相同的日期、收款方和金额。
在审查了每一个可能的匹配项之后，选择以下替代方案之一：
bea import bank.csv --apply --duplicates skipbea import bank.csv --apply --duplicates include该决定适用于该次调用中的所有可能匹配项。完全重复项仍会被跳过。ID冲突仍会阻止写入。
默认的 --duplicates review 会拒绝应用未解决的匹配项。它退出码4，并指出受影响的预览行。--no-input 和 --yes 不会绕过该审查。有意的跳过每个行的决定会以退出码0结束，且不向账本添加任何内容。
保持导入可重复
默认情况下，重复匹配会检查导入器源账户内的 bank_id、fitid、transaction_id 和 imported_id 元数据。使用重复的 --id-key KEY 选项来替换该集合。
命令行还会写入 bea_import_id 元数据，以标识原始导出中的行。在编辑导入的条目时请保留它。可能的匹配项会与现有交易以及同一批次中已接受的行进行检查。
收款方、叙述和字符串元数据在预览和写入之前会将换行符替换为空格。引号和反斜杠保留其内容。因此，导入的商家文本在账本的单行上保持可读。
导入会添加条目；它不会更新或删除现有交易。请在你的账本中进行有意的更正，并随后运行 bea check。通过 bea add transactions 进行批量JSON条目录入没有重复检测功能。
写入包含的文件
将 --file 指向根文件，并使用 --into 选择目标文件：
bea --file ~/my-books/main.bean import bank.csv --into 2026.bean
bea --file ~/my-books/main.bean import bank.csv --into 2026.bean --apply2026.bean 必须已存在，并由根文件包含。其路径相对于根目录。导出路径仍相对于你的工作目录。预览会指明将要更改的文件。
在脚本中使用导入功能
bea --json --no-input import bank.csv --apply --duplicates skip仅在 skip 确实是你对可能匹配项的政策时才选择它。JSON会在 data 中返回预览和写入计数。被拒绝的应用会将预览放在stderr上的 error.result 中，并带有 written: 0。始终检查退出状态。在安排无人值守的导入之前，请参阅 JSON和退出码参考。
排除导入器故障
如果配置导入了第三方包，这些包必须位于运行 bea 的Python环境中。例如：
uv run --with beancount-io --with beangulp \
bea --file ~/my-books/main.bean import bank.ofx --config importers.py为单独安装的银行导入器添加 --with YOUR_IMPORTER_PACKAGE。这使用的是与Homebrew分离的环境。
如果导入器出现异常，请在命令前加上 --debug 以显示其回溯信息：
bea --debug import bank.csv --config importers.py导入器输出会捕获在 importer_output 中，以免破坏JSON。在JSON调试模式下，回溯位于 error.traceback。
如需一次性转换且不使用Python导入器，请尝试 CSV转换器 或 OFX和QIF转换器。在将这些生成的条目添加到你的账簿之前，请审查它们。