taxtrace

taxtrace

使用你自己的文件，在自己的设备上准备美国联邦和州税表，每个数字都能追溯到它的来源页面。

taxtrace 不会提交任何税表。它会读取你文件夹中的文件（W-2、1099、1098、物业管理公司报表、收据、外国银行对账单、去年的税表），并生成一份录入清单，供你输入消费级税务软件；还会生成一份 FBAR 账户清单，以及一份待你解答的问题清单：也就是仅凭文件无法确定的事项。

如果 taxtrace 对你的报税有帮助，欢迎在 GitHub 上点个 ⭐，让我知道：taxtrace 不会向外发送任何信息，因此星标是我唯一能知道有多少人使用它的方式。如果它帮你省下了报税员的费用，也可以请我喝杯 $1 咖啡。

以下三条原则贯穿始终：

1. 绝不猜测。 每个值都附有文件、页码和读取该值的原文；确定性校验会拒绝任何引文与对应页面不符的值。
2. 你的文件绝不会离开你的设备。 语言模型读取文件时（例如整理文件、读取潦草的收据），使用的是 Mac 上本地运行的 MLX 模型。聊天功能可以使用云端模型，但它只能看到经过屏蔽的文本（见聊天）。
3. 绝不暗中做决定。 一张可能属于维修或改造的收据、一份缺失的 1099、一个税率选择：每一项都会作为问题交给你，并附上相关证据。

状态

尚处于早期阶段。目前可用的功能：

• taxtrace redact：将文档脱敏为仅保留版面布局，这样就可以在不显示其中数值、姓名或地点的情况下，由人或协助编写解析器的 AI 助手研究版面。每个数字都会变成 #，而 IRS 自己的出版物中没有以小写形式出现的每个单词都会变成一串 *，因此姓名、街道和城镇都不会暴露，无需逐一列出。
• taxtrace import、outline 和 unlock：将报税人员导出的文件归入工作区、列出每份文档中的表格，并检查钥匙串中保存的密码。
• taxtrace prior：读取已提交报税表中的结转项（见结转项）。
• taxtrace k1：读取每份 Schedule K-1 (Form 1065) 首页上的内容、每个方框和代码、附表、Schedule K-3，以及 North Carolina 的 D-403 NC K-1（见K-1 表）。
• taxtrace passive：读取每项被动活动的年份和结转亏损（见被动活动）。
• taxtrace 1098：读取每份 Form 1098 住房贷款利息声明（见Form 1098）。
• taxtrace 1099：读取经纪商合并 1099 声明中的 1099-DIV 和 1099-INT（见Forms 1099-DIV 和 1099-INT）。
• taxtrace rental：逐行整理出租房产的 Schedule E（见Schedule E）。
• taxtrace qbi：读取 Form 8995，即合格营业收入扣除额（见Form 8995）。
• taxtrace paystub：读取工资单上预扣的所得税，并预测全年的金额（见预估税款）。
• taxtrace estimates：按季度将全年的预扣税和预估税款与安全港标准进行比较（见预估税款）。
• taxtrace ira：读取每位配偶的 IRA 扣除额，以及根据全年预测收入计算的 Roth IRA 限额（见IRA）。
• taxtrace itr：读取印度所得税申报表 (ITR-2)：房产出售、利息以及印度预扣的税款（见印度申报表）。
• taxtrace bank：读取外国银行的账户对账单：利息、退税和余额（见银行对账单）。
• taxtrace ui：在浏览器中打开工作区，并提供聊天功能（见聊天）。

按计划顺序开发：外国部分（按财政部利率计算利息、外国税收抵免、FBAR、Form 8938 检查）、录入表，以及年度间核对。

安装

pip install -e ".[dev,mcp]"

taxtrace[chat] 会添加聊天功能所需的 Claude SDK，taxtrace[local] 会添加在 Mac 上运行的模型，而 taxtrace[mcp] 会添加一个 MCP 服务。

使用

taxtrace import ~/Downloads/portal-export.zip  # filed returns to prior-returns/, the rest by tax year
taxtrace redact ~/TaxData/prior-returns        # writes ~/TaxData/redacted/*.txt

对于不在当前所在位置的路径，程序会在工作区中查找：taxtrace k1 2025 会读取 <workspace>/2025。

taxtrace outline <files> 会列出每一页经过脱敏的标题：按顺序显示文档包含哪些表格（--match '1116|4562' 只会列出标题中含这些内容的页面）。taxtrace words <pdf> --page 2 --rows 会显示页面上经过脱敏的文字及其位置（使用 --x 300:450 和 --top 70:240 可缩小到某个区域）：这能显示印刷表格的几何布局，以便编写读取器。--marks 会显示绘制的形状，因此能看到用绘制标记勾选的复选框。--page 19-20,69、--page all 和多个文件都可以在一次运行中处理，因此共用同一钥匙串条目的文件只需一次授权。taxtrace show 'prior-returns/2025*' --page 19 会在 Chrome 中打开文档的指定页面，供你自行阅读。扫描版 PDF（页面图片，没有文本）会通过你电脑上的 ocrmypdf 读取（只需运行一次 brew install ocrmypdf）；可搜索副本会按原文件的 sha256 保存于 <workspace>/ocr-cache 下，因此引用的文本值不会发生变化。图片（.jpg、.png：例如聊天中收到的手机拍摄的声明照片或截图）也会以相同方式处理。不过，聊天应用会压缩发送的图片，模糊表格中的行可能无法读取：此时 bank 不会为该账户保存任何内容，最好改用银行提供的 PDF（或将图片作为文档发送，避免压缩）。 import 接受一个文件夹或 zip 文件，例如报税服务门户导出的文件，其中每年一个文件夹。它会跳过身份证明文件（驾照、社会保障卡、护照）和已导入的文件，并将放入的每个文件及其 sha256 记录在 imports.jsonl 中。

你的文档及其所有衍生内容都存放在工作区文件夹中，即 ~/TaxData 或 $TAXTRACE_HOME；taxtrace 拒绝将工作区放在 git 仓库内。也可以是普通单词的姓名（Will、Grace）应逐行写入 <workspace>/redact-terms.txt。

读取受密码保护的 PDF 时，密码保存在 macOS 钥匙串中，绝不会存入文件或出现在命令行中。一个 default 条目适用于所有共用同一密码的报税表；针对文件名设置的条目优先用于该文件；名称中第一个 - 之前的条目则适用于某家银行的月结单（例如 quillbank-4410-2026-01.pdf、quillbank-4410-2026-02.pdf 等对应 quillbank）。security 会在不回显的情况下询问密码，而 -T "" 表示不信任任何应用，因此每次有程序读取密码时，macOS 都会询问你（允许 / 拒绝），包括 taxtrace：

security add-generic-password -s taxtrace -a default -T "" -w
security add-generic-password -s taxtrace -a "2024 Return.pdf" -T "" -w   # just this file
security add-generic-password -s taxtrace -a quillbank -T "" -w           # quillbank-*.pdf

点击 允许，不要点 始终允许：后者会将读取程序加入受信任列表，并让提示不再出现。

该提示只需输入密码。若要改用 Apple Watch 或 Touch ID 批准每次读取：

taxtrace keychain setup                              # the default entry and the chat's key
taxtrace keychain setup --account "2024 Return.pdf"  # and a file's own entry

setup 会构建一个小型辅助程序（taxtrace/macos/keychain_gate.swift，使用 Xcode 命令行工具编译），并将每个条目转交给它。macOS 会按原来的方式再询问你一次该条目的权限，密码不会被重新输入或显示。此后，该条目只信任这个辅助程序；只有经过 macOS 自己的批准（Apple Watch、Touch ID，或两者均未设置时使用密码），辅助程序才会释放密码。每次读取仍由你决定是否允许。只有 setup 转交的条目会通过辅助程序读取；其他条目仍按传统方式读取，并显示一次提示。如果你在 setup 期间拒绝传统提示，它会告知你并保持该条目原样：重新运行 setup 即可。辅助程序构建完成后，使用 taxtrace keychain store <name> 存储新密码（文件名、发行方名称（例如 quillbank），或 default）：security 会在不回显的情况下询问密码，然后辅助程序会像 setup 一样将其转交过去，并显示一次传统提示。若使用裸命令 security add-generic-password -T <helper> 存储条目，该条目仍由 security 管理：macOS 会在辅助程序每次读取时另外显示自己的提示，除了 Apple Watch 或 Touch ID 的批准之外还需要这一步。taxtrace 每条目每条命令最多读取一次，因此一整个共用 default 密码的报税表文件夹只会触发一次提示。taxtrace unlock 会说明每个锁定文件由哪个条目解锁，以及每个已存储密码的格式（aaaa99999），但不会显示密码本身。如果 pdfminer 拒绝某个密码，会再用 qpdf 尝试一次（brew install qpdf）：密码会通过标准输入传给 qpdf，qpdf 会将副本解密到临时文件夹供读取。如果 qpdf 也拒绝该密码，说明存储的密码有误，而不是读取程序有问题。

其他工具也可以读取由 setup 转交的条目（例如与聊天工具共用的 API 密钥），而无需让该条目也信任该工具：

taxtrace keychain read anthropic --for jobwatch   # the secret on stdout, once approved

提示会显示条目名称和工具名称。密码会传给运行该命令的程序，绝不会传到终端；未由 setup 转交的条目不能通过这种方式读取。

如果某个工具需要无人值守地读取密钥（例如重启后运行的后台服务），就没有人可以批准，批准请求最终会超时。对于保护力度较低的密钥（例如设有消费限额的密钥），可使用 taxtrace keychain release anthropic 将其永久移回：批准一次后，security 会再次保存该密钥（密码通过标准输入传递，绝不会出现在命令行中），之后读取时不会出现任何提示，包括 taxtrace 的聊天功能。文档密码不能移回。 读取时如果要求输入密码，而不是使用 Apple Watch 或 Touch ID（如果 Watch 超出范围、处于睡眠或锁定状态，就会回退到密码），taxtrace keychain check 会说明 macOS 当前提供哪些方式，以及哪些方式不可用的原因；check --try 会显示一个 Watch / Touch ID 提示，并打印返回结果。两者都不会重新构建辅助工具，也不会触碰任何条目。

除了 PDF 和文本文件（.txt、.csv），还会读取 Word 文档（.docx：每个段落和每个表格行各占一行）及 Excel 工作簿（.xlsx：每张工作表一页，每行占一行），使用的是 Python 自带的 zip 和 XML 模块。不会读取受密码保护的 Office 文件：请将未受保护的副本保存到工作区。

不指定路径运行 redact、outline 和 unlock 时，会读取整个工作区，但会排除 taxtrace 自己写入的内容（redacted/、ocr-cache/）。

结转项目

taxtrace prior            # every return in <workspace>/prior-returns
taxtrace prior --layout   # also each line a value came from, masked
taxtrace prior --words 23-26,71   # also those pages' masked words, in the same run (one Keychain approval)

下一年的申报从上一年的申报开始：每项资产截至目前的折旧额，以及每项尚无法扣除的被动活动亏损。prior 会从报税员自己的打印件中读取这些内容：联邦折旧明细表（Drake 的 "Federal Depreciation Schedule"，或其中土地行以成本结转、不计折旧的 "Depreciation Detail Listing"），以及 Form 8582 的 Worksheets 5 和 6。如果申报表中打印了 "Next Year's Depreciation Worksheet"，则会逐项核对其中的扣除额与滚动到下一年的数值。数据会写入 <workspace>/carryforwards/<return>.json，并为每项数据记录其所在页码和读取时对应的原文行。终端会显示数量、未通过的核对项和问题，输出内容会像 redact 一样进行遮蔽。

绝不盲目信任任何内容：

• 将每行与附表的合计行核对，并将每项资产截至目前的折旧与其计税基础核对。
• 在 Form 8582 上，将每项活动的比例与其损失份额核对，将未获准扣除的损失与其占总额的比例核对，并将 Worksheet 6 与 Worksheet 5 核对。
• Worksheets 1 和 3 列出每项被动活动，包括收入和损失：其净收入、净损失、带入的未获准扣除损失，以及总收益或损失。某行不适用的列留空，因此要根据金额所在位置，也就是列标题，来识别每个金额。每行的金额必须得出其总收益或损失，各行金额也必须与合计行相符。
• 同一份附表打印了两次时，只保留一份；若第二份副本与之不符，则标记为问题。
• 跳过替代性最低税和账簿副本。也跳过下一年的预计附表，但会检查其起点是否为本年的累计折旧。
• Section 179、奖金折旧或残值金额，或低于 100% 的商业用途比例，都需要向你提出问题，而不是猜测。
• Schedule B (Form 1116) 按收入类别（被动、一般……）列出结转至下一年的外国税额，并另列替代性最低税的金额，按税款产生年份区分：列出本年之前的十年、本年以及总额。每列各行都必须计算正确（第 3 行为第 1 行和第 2 行之和；第 8 行为第 3 行至第 7 行之和），小计必须从第 1 页结转至第 2 页，总额必须等于各列之和。AMT 副本的第 2 页没有注明它是 AMT 副本，因此会与最近的第 1 页配对。未勾选的方框会标记为问题。终端只显示发生过结转的年份。
• Carryover Worksheet（Drake 的 “List of items that will carryover to the next tax return”）逐行读取：已缴州税和地方税、QBI 损失、外国税收抵免（常规和 AMT）、上一年的预估税安全港税额，以及配偶双方各自的 IRA 计税基础。其外国税收抵免必须与 Schedule B 的结转金额相符，标题也必须写明下一年。“Passive Activity” 或 “At Risk Limitations” 下的任何内容都会标记为问题，因为目前见过的副本中这些部分都没有行。--layout 会列出每行的标签以及包含哪些金额（常规、AMT、纳税人、配偶），但不会列出金额。
• Form 8995（简化 QBI 扣除）列出每家企业的合格营业收入（第 1 行；超过五家企业时会在单独页面上续列），以及第 2 至 17 行。逐行核对其计算结果；结转的 QBI 和 REIT/PTP 损失（第 16 行和第 17 行）必须与 Carryover Worksheet 中的金额以及下一年的第 3 行和第 7 行相符。
• Form 1040 提供下一年预估税所依据的各行：调整后总收入、总税额、预扣税额、预估税付款、可退还抵免、付款总额、超额付款、转入下一年的金额，以及预估税罚款。每项都按行号和标签文字查找，且各项付款必须合计正确。
• 将相隔多年的报税表相互核对。每项资产的折旧按完整年度逐年结转，并且必须与较晚报税表中的先前折旧相符。差额会以折旧年数表示偏差程度（0.46 年表示漏掉了第一个不完整年度），不显示金额。某年的外国税额结转至下一年后，必须与下一年逐年列示的上年结转金额相符。

taxtrace prior --project 2025   # roll the latest schedule forward, for returns not in hand yet

--project 会写入 <workspace>/carryforwards/projected-<year>.json：列出自最近一份报税表以来每项资产每年的折旧，并将其标记为预计金额，直到收到该年的报税表进行确认。 --layout 还会以年数显示每项资产的先前折旧和本期折旧。无需看到具体金额，也足以发现缺失或不完整的年度。

K-1

taxtrace k1 2025            # every K-1 face in <workspace>/2025
taxtrace k1 2025 --layout   # also each value's text, masked, and where it sits

K-1 的表面是一张印刷表格：每个金额都在对应编号的方框中，旁边标有代码，因此按顺序读取时，金额会与页面上紧邻的标签对应。k1 则按位置读取。它根据 Part III 两列各自的首个方框找到这两列，并将每个金额对应到所在列上方最近的方框编号。Part I 和 Part II 按标签读取：EIN、合伙企业、合伙人（TIN 的后四位）、每个勾选标记、利润、亏损和资本份额、负债以及资本账户。数值会写入 <workspace>/k1/<document>.json，并附上页码、位置和准确文本。终端会显示承载金额的方框和代码，以及未通过的检查和问题，但不会显示金额或姓名。

• 项目 L 的资本账户必须平衡：期初余额加上出资、本年度收入和其他变动，再减去提款，等于期末余额。每项份额都必须在 0% 到 100% 之间，且每个带有代码的方框都必须有金额。
• 同一合伙人的表格重复出现时只计一次。另一位合伙人（例如配偶）的相同金额属于该合伙人自己的 K-1。
• IRA 的 K-1（勾选了项目 I2）会标记为 IRA K-1：其收入留在账户中，不计入纳税申报表。
• 如果表格要求从合伙企业的报表中读取某个金额（“STMT”、“See statement”），则会从表格之后的报表页读取。像“Line 20, Code Z”或“Box 19C”这样的引用，或方框表格中的代码，会将其下方的每个金额行与对应方框和代码关联，并附上说明；如果标签被金额打断（如 Statement A 的 199A 表格），则会重新组合。合计和项目 L 的对账内容会排除在外，因为它们重复了其他位置给出的金额。若报表页未提供某个报表金额，则会列为问题。
• 每项 Section 199A 金额都会标明其类型（合格营业收入、W-2 工资、UBIA、REIT 股息、PTP 收入）及所属的贸易或业务。汇总组的总额会保留，但标记为组级金额，因此不会重复相加；每个总额都必须等于其所属各项业务金额之和。
• 最终 K-1，或包含多个活动的 K-1（方框 22、23），会列为问题。

North Carolina 合伙人 K-1（Form D-403 NC K-1）也按相同方式读取，即根据内容所在位置读取。其 11 行的金额都位于行标签正上方；合伙企业的 FEIN、合伙人的编号（仅保留后四位）以及三个 Yes/No 答案则按标签读取。结果写入同一文件夹，并标明 D-400 各行的对应位置。

• 第 1 行必须等于同一合伙企业联邦 K-1 Part III 第 1 至 11 行的总和，正如表格所述。联邦 K-1 可以在同一轮或更早一轮读取；若尚未读取，则会列为问题。
• 第 6 至 9 行适用于非居民合伙人，第 10 和 11 行适用于应税合伙企业：如果某份 K-1 上的答案表明其不属于此类，却在这些行中填有金额，则会判定为未通过。
• 加项和扣除项（第 2、3 行）以及抵免额（第 4 行）会列为问题：表格未说明每项对应哪个 Schedule S 或 D-400TC 行。

读取 Schedule K-3（合伙人的国际项目）以用于 Form 1116：读取 E 栏中表明适用部分的标记，以及 Part II 中的每个金额（按来源和类别划分的总收入与扣除额），并记录其行号、所在国家/地区行及国家/地区代码，以及其所在列，范围从 (a) 美国来源到各外国类别，再到总计。Part III 的外国税额也会予以记录。

• 每行各列的金额之和必须等于该行的总计；每个总计行也必须等于标签所列各行的计算结果（“combine lines 1 through 23”、“subtract line 54 from line 24”）。
• Part II 的利息、股息、收益和 Section 1231 行必须与同一合伙企业 K-1 方框中的内容一致；若 K-1 的方框 16 表明附有 K-3，则必须在本轮或更早一轮读取该 K-3。
• 终端会说明 Part II 是否包含外国来源金额，以及这些金额属于哪些类别。外国税额暂列为问题：目前尚未读取其表格。

被动活动

taxtrace passive            # the latest year of the K-1s read
taxtrace passive --year 2025

Form 8582 限制被动损失，未获允许的部分会按活动逐项结转到下一年。passive 会从最新纳税申报表的工作表开始，采用 prior 保存的内容（Worksheets 1 和 3 上的每项活动，以及 Worksheet 5 上每项活动的结转额），再使用 k1 保存的本年度 K-1。它不会打开任何文档。每项活动都按 名称中的文字与其合伙企业的 K-1 匹配，其年度金额为 K-1 第 1、2、3 和 10 栏的金额减去第 12 栏金额。 利息、股息和投资组合扣除额不属于该活动。没有匹配到活动的 K-1 即代表一项新活动。账本会写入 <workspace>/passive/<year>.json；终端会显示每项活动的脱敏名称、其年度金额的来源，以及它是收入还是亏损，但绝不显示金额。

• 本年度没有 K-1 的活动需要确认：是已出售、已结束，还是文件夹中缺少 K-1？全部处置（最终 K-1） 可释放其结转亏损。
• 每项活动的结转额来自上一年的 Worksheet 5。如果上一年的副本中没有结转额，则 Carryover Worksheet 的 Passive Activity 部分为空白，表示没有结转；否则，参考上一年的账本（剔除上一年已出售的活动） 和据此计算的 Form 8582 passive。这些都只是需要对照已提交的 Worksheet 5 确认的备注；如果这些资料都没有， 则每项活动的结转额均记为未知。
• 某份纳税申报表的 Worksheet 5 显示亏损结转，但下一份申报表的 Carryover Worksheet 却没有列出任何结转额， 这需要确认：是下一年的被动收入已允许抵扣全部亏损，还是这些亏损被遗漏，导致之后每一年都无法抵扣。
• 租赁活动的年度金额来自 Schedule E（rental）；如果第 13 栏的扣除代码无法确定该金额是否属于此活动， 则需要确认。

已知每项活动的年度金额和结转亏损后，passive 会计算本年度的 Form 8582，并与账本一同保存：

• 每项活动列入 Part IV（积极参与的出租房地产：最新纳税申报表的 Worksheet 1）或 Part V（其他所有活动，包括合伙企业的新活动）。Line 3 汇总这些金额；金额为零或正数时，所有亏损 均可抵扣。
• Part II 的特别扣除额（最高 $25,000，在修正后调整后总收入介于 $100,000 和 $150,000 之间时逐步 减少）需要提供 --confirm magi=AMOUNT；已婚单独申报还需提供 lived_apart=yes|no。该扣除额优先用于 Part IV 的活动（Part VI）。
• Line 3 剩余的亏损不予允许，并按整体亏损活动的亏损比例分摊（Part VII），结转到下一年。以整体亏损 全部处置的活动不列入表格：其亏损，包括结转亏损，均可全额抵扣。
• 对每份已读取其工作表的已提交纳税申报表，都会根据该申报表自己的 Worksheets 1 和 3 重新计算， 并与其 Worksheet 5 核对：使用相同的算术方法，根据报税准备人员提供的数字重新演算。

终端会说明每项活动的亏损如何处理（允许抵扣、部分结转、不列入表格），但不会显示金额。

表格 1098

taxtrace 1098 2025            # every Form 1098 in <workspace>/2025
taxtrace 1098 2025 --layout   # also each value's text, masked, and where it sits

贷款方的 1098 也是一份纸质表格。每个方框都根据其编号和标签开头的几个词来查找，匹配时会去掉空格，因为贷款方打印时可能会把一个词拆开（“M ortgage”）。方框的值是标签下方的内容，从方框编号开始，到旁边或下方的下一个方框标签为止。贷款方的 TIN、借款人的 TIN（仅末四位数字）、账号和日历年度均根据其标签读取。值会写入 <workspace>/forms/<document>.json；终端会显示哪些方框包含金额、检查结果和问题。

• 方框 1 必须存在，且必须低于方框 2 本金的 15%：超过此比例表示误读，而不是抵押贷款利息。
• 方框 10（其他）不是利息。贷款方在其旁边打印的内容（通常是从托管账户支付的税款或保险费）决定其归属，因此这属于问题；利息退款（方框 4）、保险费（方框 5）、点数（方框 6）、不止一处房产（方框 9）以及更正后的表格也同样属于问题。
• 方框 8 中的地址或方框 7 中的标记说明利息对应哪处房产：出租房产的利息填入附表 E 第 12 行，自住房产的利息填入附表 A。两者都没有的 1098 属于问题。

表格 1099-DIV 和 1099-INT

taxtrace 1099 2025            # every consolidated 1099 statement in <workspace>/2025
taxtrace 1099 2025 --layout   # also the account and each box's label, with its value masked
taxtrace 1099 2025 --unlock   # also ask the Keychain for locked documents' passwords

经纪商的对账单很少加密，因此遇到加密文档时会跳过，不会询问 Keychain，除非指定 --unlock：文件夹中其他加密文件（W-2、税表）不会触发提示。

经纪商的综合对账单会将每份表格打印为其标题下的一列行（“1099-DIV Dividends and Distributions - 2025 ...”），各份表格并排排列：方框编号、标签和远在标签右侧的金额。若方框编号打印在标签所在行稍下方，则它属于该行。年度取自标题；付款方的 TIN 和账号根据其标签读取。重复打印的对账单只计一次。值会写入 <workspace>/forms/<document>.json；终端会显示哪些方框包含金额、检查结果和问题。

• 会检查表格本身的算术关系：合格股息（1b）、第 897 条普通股息（2e）和第 199A 条股息（5）分别是普通股息（1a）的一部分；2b、2c、2d 和 2f 则是资本利得分配额（2a）的一部分。
• 方框 5 是表格 8995 第 6 行（qbi）。
• 会改变金额归属的方框均属于问题：已缴外国税款（以及方框 8 中的国家）、资本返还（方框 3）、预扣税、清算分配、免税利息股息；对于 1099-INT，还包括提前支取罚金、国债利息（北卡罗来纳州不对此征税）、免税利息和债券溢价。更正后的表格也属于问题。

Schedule E

taxtrace prior                 # also reads the filed returns' Schedule E: the property, lines 3 to 20, line 19's list
taxtrace 1098 2025
taxtrace rental --year 2025    # reads the answers and policies in <workspace>/2025, writes schedule-e/2025.json

rental 根据已读取的内容，整理出一处房产的 Part I，并标明每一行的数据来源：

• 租金和费用来自报税员问题中填写的答案（“Rental income = $1,200/month”、“Repairs = $400/year”），归在租赁项目下。月金额会按 12 个月计入，这一点需要询问。
• 抵押贷款利息（第 12 行）来自箱 8 中地址为该房产地址的 1098；如果贷款机构的说明表明托管账户支付了税款或保险费，则相应金额记在第 16 行或第 9 行。
• 保险费（第 9 行）来自该房产出租屋保单的声明页：即年度保费。今年新投保的保单需要询问；今年支付的旧保单保费也计入。
• 折旧（第 18 行）来自保存的最新已申报折旧表 prior，向前结转，不会再次打开报税表（如果 prior --project 的记录更新，则使用该记录）。如果结转了不止一年，就需要询问。

当本年度报税表已申报并读取后，会将每一行与其 Schedule E 对照：这是一场演练，用来显示构建结果与报税员分别填了哪些行，以及 taxtrace 的金额是更多还是更少，但绝不显示差额。

只有你知道的信息通过 --confirm 确认，并保存到 schedule-e/<year>-confirmed.json，供之后每次运行使用：fair_rental_days=365、personal_use_days=0、rent_all_year=yes、rent=AMOUNT（该年度所有租户合计支付的租金，用来替代答案中的月金额）、earlier_policy=AMOUNT（本年度为读取的保单之前的保单支付的保费；没有则填 0）、dues=AMOUNT（协会会费，第 19 行），以及 cleaning=AMOUNT 和 repairs=AMOUNT（本年度收据金额总和，分别填入第 7 行和第 14 行；其中包括租户从租金中支付的维修费）。

地址中的门牌号和街道相同，文件就归属于该房产。最新已申报的 Schedule E 中有一行，而本年度没有对应信息（例如第 19 行的协会会费），这类项目需要询问；公平出租天数和自用天数也需要询问。锁定的文件会跳过，不会弹出 Keychain 提示：答案和保单不会被锁定。

Form 8995

taxtrace qbi --year 2025            # writes qbi/2025.json from what k1, rental and prior saved
taxtrace qbi --year 2025 --layout   # also each K-1's Section 199A statement rows: what each is and its sign
taxtrace qbi --year 2025 --confirm k1_4567=business --confirm rental=not

qbi 根据已保存的信息整理简化版 Form 8995，不会打开任何文档：

• 每个合伙企业的合格营业收入，是其 K-1 中的被动收入或亏损（第 1、2、3 和 10 栏，减去第 12 栏）， 也就是报税员在 Form 8995 中填报的数额，而不是 Section 199A 报表本身的总额。
• 租赁业务的数额是 rental 中 Schedule E 的净额。
• Form 8582 不允许扣除的被动亏损，在后续年份获准扣除之前不属于合格营业收入。每项活动的数额是当年 Form 8582 允许扣除的数额（其总收益或亏损，减去结转额）： 如果读取当年的报税表，就用已提交的报税表中的数额；否则用 passive 算出的数额。若两者都没有，所列数额是尚未应用该限制前的数额，这一点需要确认。
• 哪些企业计入，依据上一年的已提交 Form 8995：其中列出的、今年有收入或亏损的合伙企业（按其 EIN 的后四位识别），以及其中列出 Schedule E 的租赁业务。上一年未列出的企业需要通过 --confirm k1_<last four>=business|not（或 rental=）确认，结果保存在 qbi/<year>-confirmed.json 中。
• 第 6 行是 K-1 中的 REIT 股息和 PTP 收入，以及当年 1099-DIV 中的 Section 199A 股息（第 5 栏，来自 taxtrace 1099）。上一年的结转亏损（第 16 和 17 行）填入第 3 和 7 行。第 11 至 15 行需要应税收入，因此只有第 10 行为零时才能确定扣除额。简化表格的门槛依据已通过 foreign --confirm filing= 保存的申报身份；超过门槛则适用 Form 8995-A，taxtrace 目前还不支持该表格。

当年报税表已提交并读取后，会将每一行和每家企业与其 Form 8995 核对。如果某家企业的数额不一致，系统会指出已提交的 Form 8995 与哪个其他数额相符（Section 199A 报表的总额、合并组的数额，或已提交的 Schedule E 净额），以便在演练中看出系统计算结果与报税员的处理有何出入。终端会显示哪些企业有收入或亏损、核对结果和待确认事项，但不会显示任何数额。

预估税款

taxtrace prior                                   # reads last year's Form 1040 and Carryover Worksheet
taxtrace paystub 2026/payslip.pdf                # the latest pay stub: the year's withholding, projected
taxtrace estimates --year 2026 --confirm paid_2026-09-15=2500

工资单的表头列出工资周期和付款日期，税款表则列出本次工资中各项税款的金额，以及年初至今的金额（“FIT Withheld”“SIT Withheld (NC)”）。今年的预扣税额是年初至今的金额加上之后每次工资的对应金额：工资周期的长度说明了发薪频率，而之后每次工资的付款时间与本次相同，都是在周期结束后这么久，因此，12 月的工资周期如果在 1 月支付，就计入下一年。奖金或新的 W-4 会改变这一情况，所以这只是个问题。

taxtrace paystub --rate 47 会计算假设每次工资都按 47% 的税前 401(k) 缴款率递延时，到手金额会是多少：用本次工资的净工资，减去递延额带来的变化，再加上递延额对联邦预扣税的影响（百分比法：扣除标准扣除额后，按当年的税率档，对本次工资的应税工资乘以一年中的发薪次数计算），以及按州的固定税率计算的州税影响，直到达到当年的缴款上限。终端会显示每次工资的到手金额占本次到手金额的比例，以及每递延 1 美元会减少多少美分的到手金额；金额会写入文件，而 --show 只会在你自己的终端中显示这些金额。

如果当年的缴款达到以下两者中较小者，就无需缴纳预缴不足罚金：当年实际税款的 90%，以及去年的税款的 100%（如果去年的调整后总收入超过 150,000 美元，则为 110%；已婚单独申报者的门槛为 75,000 美元）。去年的税款是《结转工作表》中的联邦税务责任，或 Form 1040 第 24 行减去第 32 行的金额。

每个季度的税款应于 4 月 15 日、6 月 15 日、9 月 15 日和 1 月 15 日之前缴纳，并且每个季度单独检查。预估税款按实际缴纳日期计入，因此 1 月的付款无法补足更早的季度。不过，预扣税款会视为全年均匀缴纳，无论实际缴纳时间多晚，因此 12 月 31 日之前增加预扣税款可以补足所有季度；estimates 会告知需要缴纳多少。去年多缴并结转到今年的金额计入 4 月份。

只有你知道的信息保存在 estimates/<year>-confirmed.json 中：withheld=AMOUNT（全年联邦预扣税款总额；如果有多份工作，或 1099 也预扣税款，就用它代替工资单的预测值）、paid_YYYY-MM-DD=AMOUNT（每笔预估税款）以及 tax=AMOUNT（算出当年实际税款后填写）。终端会显示哪些季度已达标或还差多少；金额保存在 estimates/<year>.json 中。

IRA

taxtrace ira --year 2026                       # from the latest pay stub and last year's Form 1040
taxtrace ira --year 2026 --confirm other=9000  # the year's income besides the wages, once it's known

联合申报的夫妻双方都可以各自向 IRA 缴入当年的限额；没有工资收入的一方可以根据另一方的收入缴款。可抵扣的金额会随收入逐步减少：如果一方参加了 401(k)，收入适用较低的区间；如果一方未参加，但其配偶参加了 401(k)，则适用较高的区间。Roth IRA 有其自己的收入区间。ira 会根据工资单上的联邦应税工资，预测截至 12 月 31 日的当年收入，分别计算现有缴款和填满 401(k) 可用额度（这会降低收入）两种情况，并加上去年的利息、股息和 Schedule 1 收入；随后会给出两种情况下每位配偶的抵扣额和 Roth IRA 缴款上限。收入本身会被隐藏。

待办事项

taxtrace todo            # open items by due date, undated last
taxtrace todo --due      # overdue, plus what's due in the next 7 days
taxtrace todo --due 14   # ... the next 14 days

清单是工作区根目录下的 todo.md，由手动编写（taxtrace 不会将其作为税务文件读取）。页面会在文档上方按分组显示清单（逾期、今天、本周、稍后、无日期），勾选卡片上的复选框即可将事项标记为完成。

## Estimated tax
Any line that isn't an item, like this one, is ignored.
- [ ] **Thu 1/14/2027** Pay the fourth-quarter estimate, from `estimates`
  - the amount is in estimates/2026.json
  - [ ] check the account balance
- [ ] **Wed 10/28, time TBD** Call the plan administrator about the **rollover**
- [x] Order the tax software

事项应写在 ## Section 下，格式为 - [ ] text（未完成）或 - [x] text（已完成）。开头的粗体日期表示到期日，可以带年份（**Fri 1/15/2027**），也可以不带（**Wed 10/28**，日期范围为 2 个月前至 10 个月后）；也可以不写日期。缩进的 - text 行是备注，缩进的 - [ ] text 行是子任务。将事项标记为完成时，只会把该行的 [ ] 改为 [x]，不会改动其他内容；如果页面加载后该行已被编辑，则操作会被拒绝。

印度报税表

taxtrace itr 2025    # writes forms/itr-<assessment year>.json

在印度出售房产的美国人士以非居民身份提交印度 ITR-2：买方在登记时预扣 TDS，报税表会结算这笔税款，通常会产生退税。itr 会逐行读取打印的报税表（金额采用印度分组格式，即 12,34,567）：

• Schedule CG，每处房产：购买和出售日期、收到的对价、印花税价值、成本、改良支出（注明每项支出的财政年度）、转让费用、免税额和收益。
• Schedule OS：利息，以及其中有多少是储蓄账户利息。
• Part B-TTI：税款、总纳税义务、已缴税款（预缴税、TDS、TCS、自行评税税款）和退税。印度实际留存的金额，即已缴税款减去退税额，是 Form 1116 可以抵免的金额。

印度的财政年度从 4 月到次年 3 月（评税年度 2025-26 对应 2024 年 4 月至 2025 年 3 月），因此，出售日期决定了它属于哪个美国纳税年度。核对事项：已缴税款总额相符；退税额等于已缴税款减去总纳税义务（印度会四舍五入到十卢比）；总纳税义务等于净纳税义务加利息和费用；TDS 附表与 Part B-TTI 相符；每笔出售的收支余额和收益计算相符；出售日期处于报税表对应的年度内。需要确认的问题：改良支出的日期（打印件只列出财政年度，而且每项支出都要按其发生日的汇率换算成美元）、印花税价值高于实际售价（美国报税表使用实际售价），以及此人是否拥有整处房产。不保留任何可识别此人身份的信息：无 PAN、确认编号或地址。

银行对账单

taxtrace bank 2025           # writes forms/bank-<last four digits>-<period start>.json
taxtrace bank --rows 2025    # also each row's date, kind and description, masked

印度分行的账户对账单是一张表格：日期、提款或存款金额、余额（“Cr.” 或 “Dr.”），以及可能延伸到多行的说明。bank 会根据每个词的位置进行归类：金额归入其起始位置所在的列，说明行则与距离最近的日期行对应（多行说明以该行居中对齐）。每行都会标注类型：利息（说明中会注明对应的计息期间）、退税、利息预扣的 TDS，或 TDS 退税。这些记录为 Schedule B 和 Form 1116 提供利息信息，为 Form 8938 和 FBAR 提供余额信息，并用于核对印度的退税是否到账。

银行的月度“Account Statement”也会读取：行号、格式为 05 Jan 2026 的日期、金额左侧的说明、印度格式的逗号（1,23,456.78）、Opening Balance 行和 Account Summary。季度利息会在扣除 TDS 后入账（Int:1234.56 and TAX:123.45），并读取为两行，先是利息，再是预扣的 TDS。

如果收到的只有一张模糊的对账单图片（聊天应用会把图片压缩到超出 OCR 的读取能力），请将内容逐行照录到旁边的 .csv 文件中。系统会像核对打印的对账单一样逐一核对余额，录错的余额不会保存：

account,000123459876
currency,INR
period,01-04-2026,27-10-2026
opening,"1,02,410.00"
date,withdrawal,deposit,balance,description
05-05-2026,,25000.00,127410.00,Cash Deposit
30-06-2026,,1234.56,128644.56,Int.Pd From:01-04-2026 to 30-06-2026
30-06-2026,123.45,,128521.11,TDS on interest

银行针对客户持有的所有账户提供的月度电子对账单也会读取（“As on 31-01-26”）：余额汇总、定期存款，以及每个储蓄账户各一页，其中列出当月交易（日期格式为 31-01-26，金额在 Credit、Debit 和 Balance 列下右对齐），并显示期初和期末余额行。每个账户都会单独保存为一份对账单，并记录持有方式（个人持有、“前任持有人或存活者”）。定期存款的余额包括本金及其应计利息；境外部分将其年度利息视为该金额的增值：累积存款中计入本金的利息属于计入当年的收入，即使没有支付出去；续存时，利息也会并入新的本金。若金额减少（印度年末从利息中扣除了 TDS），系统会提示确认。核对事项：每个账户的余额都应从期初余额推算得出；期末余额应等于可用余额；各账户余额之和应等于余额汇总。 银行出具的存款利息证明（“截至 2026 年 3 月 31 日的财年”）也通过 bank 处理：逐个账户核对 3 月 31 日的余额、已付和应计利息，以及扣缴的税款总额，并与其 TOTAL 行核对。它提供了定期存款对账单中没有的信息：3 月 31 日从利息中扣缴的 TDS。境外部分会将其视为当天预扣的税款（Form 1116），也视为存款价值未体现的利息，但仅当它与存款当天价值的下降相符时才计入（最多为价值下降额加上四分之一年的利息）。在印度上一年较早时间扣缴的税款属于较早的美国税年，因此，如果证明不符，就会提出核查，而不会全额计入。

印度的季度 TDS 证明（截至 2026 年 3 月使用 Form 16A，自 2026 年 4 月起使用 Form 131）也通过 bank 处理：核对季度、银行、每笔利息付款、扣缴的税款，以及向政府缴纳税款的 challan，并与总额核对。印度的季度落在日历季度之内，因此境外部分会将 2026 年每个季度的税款与其为该银行找到的 TDS（对账单中的 TDS 行和利息证明中的 TDS）进行比较：匹配的部分会记下，剩余税款会提出核查，而不会单独计入，因为这是在没有对账单显示的情况下扣缴的。Form 26AS 会列出每笔扣缴的日期和账户。对较早年度入账的利息所扣税款（证明可能会列出这类入账），在 Form 1116 申报已缴税款时仍计入扣缴当年的税款，这是通常使用的栏位。随后，foreign --confirm tds_<季度最后一天，YYYYMMDD>=taken 会将其计入一次，作为季度最后一天预扣的税款，以及存款价值未体现的利息；=not 则会将其排除。发现的税款少于预期时也会提出核查。银行名称按证明上打印的名称匹配，使用 foreign --confirm bank_<对账单文件名的第一个词>=<名称>; <地址>。

taxtrace fbar --year 2026 会将境外部分逐项整理成每位配偶的 FBAR（FinCEN Form 114）：<workspace>/foreign/fbar-2026.txt 是填写 BSA 电子申报表的核对清单。每个账户列在 Part II（单独持有）或 Part III（与他人共同持有：对账单上的账户操作方式会说明这一点，或使用 foreign --confirm joint_<后四位>=yes|no）。其最高价值按财政部 12 月 31 日汇率换算，并向上取整至美元；在覆盖完整个年度前会标记为估算值。银行名称来自 foreign --confirm bank_<对账单文件名的第一个词>=<名称>; <地址>。账户号码不会填入其中：需从对账单上手动填写。

核对内容：每个余额都等于期初余额加存款或减取款，且各行合计与对账单的总额相符（或者，如果是月度对账单，其期初和期末余额与摘要一致，净利息等于利息减去 TDS）。对账单按印度的年度周期（4 月至次年 3 月）编制，因此一个日历年通常需要两份。 账户号码只保留后四位，不保留任何能指明持有人身份的信息。

境外部分

taxtrace foreign --year 2025                        # writes foreign/2025.json
taxtrace foreign --year 2025 --confirm owner=spouse

foreign 会将境外出售的房产以美元列入 Form 8949，每笔金额都按各自日期的汇率换算：售价按出售日汇率，成本按购买日汇率，改良支出按付款日汇率。货币相对美元贬值，会使美元收益远低于境外征税的收益（也可能形成亏损，而个人住宅的亏损不可抵扣）。其他国家扣留的税款，即已缴税款减去退款，会按扣缴当日的汇率换算后，作为被动类别收入列入 Form 1116（退款则按缴税当日的汇率换算）。 Form 1116 要求申报已缴或已计提的税款，其 Part II 下方的选框，以及去年的报税表会注明采用哪种方式： foreign --confirm method=paid|accrued。一旦选择计提法，之后每年都必须采用。已缴法按每笔税款被预扣的年份计算，并使用预扣当日的汇率。计提法按印度纳税年度（4 月至次年 3 月）申报该年度的印度税款，计入该年度结束所在的美国纳税年度；金额按该年度报税表最终确认的数额计算，并采用该美国纳税年度的 IRS 平均汇率（section 986(a)）：2026 年申报 2025 年 4 月至 2026 年 3 月的报税表（assessment year 2026-27）。因此，美国纳税年度内预扣的 TDS 会单独列出（输出中的 tds），因为该报税表会抵免这笔税款；4 月起预扣的 TDS 则属于下一年的 Form 1116。

因抵免限额而未能抵免的外国税款可结转十年。foreign 会按上一年报税表中的信息读取结转金额：Schedule B (Form 1116) 第 8 行，按类别和替代性最低税分别列出，并按每笔税款产生的年份区分，这些金额会成为本年 Form 1116 第 10 行（输出中的 carryovers）。如果没有读取去年的报税表，就需要确认相关情况（若没有结转，请使用 --confirm carryover=none）。处于第十年的税款会被标记：本年未能抵免的部分将过期。

汇率公开可查，会获取一次并存入 <workspace>/fx，每条汇率都会保留其来源：

• 单日汇率：美联储的中午买入汇率（FRED，卢比使用 DEXINUS）；周末或节假日则使用此前最近一个工作日的汇率；
• 年平均汇率，用于利息：IRS 年度平均货币汇率；
• 12 月 31 日汇率，用于 Form 8938 和 FBAR：财政部的 Reporting Rates of Exchange。

只有你才知道的信息，可通过 --confirm 确认，并保存在 foreign/<year>-confirmed.json 中：owner=self|spouse|joint|other（联合报税时，任一配偶的出售额都按全额计算）、improvement_dates=YYYY-MM-DD,...（在这些日期之前，改良支出按其所在财年的平均汇率计算；如果日期未知，average 会保留该汇率）、use=investment|personal|rental（美元计算结果为亏损时会询问）、filing=joint|single|separate|head（用于确定 Form 8938 的申报门槛），以及 account_<last four digits>=self|spouse|joint（账户属于谁）。每位配偶都要为本人名下的账户单独提交 FBAR，因此 FBAR 按个人判断；与报税表之外的人（如父母）共同持有的账户全额视为你的账户。联合报税时，Form 8938 会合并计算双方配偶的账户。

保存 bank 的银行对账单后，foreign 还会给出每个账户当年的以下信息：

• 日历年度内计入的利息，按 IRS 年平均汇率换算（Schedule B；Form 1116 上的被动收入），以及该利息上预扣的 TDS，按每个预扣日的汇率计算（Form 1116 可抵免的税款）；
• 最高余额和 12 月 31 日余额，按财政部 12 月 31 日汇率换算，并汇总所有账户，判断是否需要提交 FBAR（年内任一时点超过 $10,000）和 Form 8938（对于居住在美国的人，按申报身份判断）；直接持有的住宅不属于 Form 8938 资产，但房款存入的账户属于；
• 在存款中发现的印度退税：收到金额中超出退税本金的部分，是印度退税利息，须在收到当年作为 Schedule B 收入申报。

印度的对账单按 4 月至次年 3 月记录，因此一个日历年度需要两份对账单。在两份对账单都读取之前，系统会询问未覆盖的日期；除非已覆盖部分的余额已经超过门槛，否则 FBAR 和 Form 8938 的结果仍无法确定。在年度尚未结束时，年平均汇率和 12 月 31 日汇率尚不可用：两者都会暂用最新单日汇率，FBAR 和 Form 8938 的结果也会标明为估算值。

聊天

pip install -e ".[chat,local]"   # Claude's SDK, and the model that runs on your Mac
taxtrace ui                      # opens http://taxtrace.localhost:8766/

此页面按文件夹列出你的工作区，并提供聊天功能，可询问税务规则、表格以及文档的用途。 它会使用 --models 中第一个可用的模型（默认为 claude,agy,local）回答，并在某个模型不可用时（没有密钥、配额已用完、未安装）转而使用下一个：

• claude：Anthropic 的 API，使用 ANTHROPIC_API_KEY，或使用存有密钥的 Keychain 项（--keychain，默认为 anthropic）。
• agy：Google 的 Antigravity CLI，使用其订阅，在空文件夹中运行。
• local：Mac 上的 MLX 模型。

Claude 和 agy 只能看到经过遮蔽的文本。每条消息和你的文档列表都会先经过与 taxtrace redact 相同的遮蔽处理：数字会变成 #，不属于 IRS 自有词汇的词语会变成 *。如果问题中包含金额，或包含来自 redact-terms.txt 的姓名，就不会发送给它们：由 Mac 上的模型回答，并由页面说明原因。对于由云端模型回答的每个问题，页面都会显示实际发送给模型的内容。聊天功能只读取文档列表和你输入的内容：它无法打开文档、修改文件或提交任何文件。

始终运行（macOS）

已安装的应用（通过浏览器将页面添加到 Dock）仅在服务运行时可用。 若要在登录时启动，并在服务停止时重新启动：

taxtrace service install     # same --port, --models and --keychain as `ui`
taxtrace service status      # running or not, the address, the log
taxtrace service uninstall

请在设置了 TAXTRACE_HOME 的 shell 中运行 install：登录项不会读取你的 shell 配置文件，因此安装程序会将工作区路径，以及能够找到 agy 和 Homebrew 的 ocrmypdf 的 PATH，写入 ~/Library/LaunchAgents/io.github.taxtrace.ui.plist。其中不会存储密钥或密码；Claude 的密钥仍从 Keychain 读取。日志位于 ~/Library/Logs/taxtrace-ui.log。

若要将页面安装为应用，请在 Chrome 中打开 http://taxtrace.localhost:8766/，然后点击地址栏右侧的安装图标（或选择 ⋮ → 投放、保存并分享 → 将页面安装为应用）。它会拥有独立窗口和 Dock 图标。SVG 更改后，运行 python scripts/make_icons.py 可重新生成应用的 PNG 图标。

MCP 服务和 Agent 技能

taxtrace-mcp 可让 Claude Code、Claude Desktop 或任何 MCP 客户端查看你的工作区：其中有什么内容、每份文档是什么、哪些表格能顺利读取，以及你的待办事项。它只返回已屏蔽文本。

pipx install 'taxtrace[mcp]'      # or: pip install 'taxtrace[mcp]'
claude mcp add taxtrace -s user -e TAXTRACE_HOME=~/TaxData -- taxtrace-mcp

无需先安装，uv 即可获取并运行它：claude mcp add taxtrace -s user -e TAXTRACE_HOME=~/TaxData -- uvx --with 'mcp>=2.2' taxtrace mcp。taxtrace mcp 运行的服务与 taxtrace-mcp 相同。对于 Claude Desktop，请将以下内容添加到 claude_desktop_config.json（如果 which taxtrace-mcp 不在应用的 PATH 中，请使用 taxtrace-mcp 的完整路径，例如 pipx 对应的 ~/.local/bin/taxtrace-mcp）：

{
  "mcpServers": {
    "taxtrace": {
      "command": "taxtrace-mcp",
      "env": { "TAXTRACE_HOME": "/Users/you/TaxData" }
    }
  }
}

工具	提供的内容
get_status	统计信息：纳税年度、文件夹、文档数量、已读取的文档数量、从中保存的内容，以及是否存在待办事项清单
list_documents	每份文档的 ID、文件夹和名称（已屏蔽）、类型，以及是否已读取；可筛选已读或未读文档
get_document_outline	按已屏蔽的标题列出文档页面：其中包含哪些表格及其顺序（会报告锁定的 PDF，但不会打开）
get_form_checks	对每份 Form 1098、1099-DIV 或 1099-INT，或 K-1：通过的检查项占总数的比例、未通过的检查项，以及尚未回答的问题
get_todo	按到期日列出 todo.md：部分、日期、剩余天数、分组，以及已屏蔽的文本、备注和子任务

所有工具都只读。屏蔽方式与聊天向云端大模型发送内容时使用的方式相同，也与 taxtrace redact 写入的方式相同： 数字会变成 #，不属于 IRS 自有词汇的词语会变成 *，而 redact-terms.txt 中的名称会优先屏蔽。 工具不会返回金额、姓名、ID、账号或工作区路径；日期、计数和通过／失败结果会保留。锁定的文档绝不会打开，也不会访问 Keychain，因此客户端无法触发提示，也无法获取密码。taxtrace 一如既往地在你的计算机上读取文档；客户端只能获取屏蔽后剩余的内容。测试会创建一个填满虚构金额和姓名的工作区，并检查这些内容是否出现在任何工具的输出中。

skills/taxtrace/SKILL.md 是一项 Agent 技能，用于告知助手何时以及如何使用这些工具，并说明它看到的始终只有已屏蔽文本。将该文件夹复制到 ~/.claude/skills/，或将其压缩后上传到 Claude Desktop（Settings、Capabilities、Skills）：cd skills && python -m zipfile -c taxtrace-skill.zip taxtrace。 发布后，它将在 MCP Registry 中以 io.github.vinayvobbili/taxtrace 列出。

开发

git config core.hooksPath .githooks   # once: every push first runs scripts/check
scripts/check                         # ruff + pytest on Python 3.10 and 3.13, as CI does
python scripts/build_vocab.py         # rebuild the redaction vocabulary from IRS publications

将 PRE_PUSH_AUDIT 设为一个扫描代码仓库中个人数据并在发现数据时以非零状态退出的命令；scripts/check 也会运行该命令，并附加代码仓库的路径。

所有测试样例都是虚构的：此代码仓库中不包含任何真实人物、地点或金额。