tax-filing

报税技能

准备联邦和州所得税申报表：读取源文件、计算税款并填写官方 PDF 表格。

不受年份限制——始终查询当年的税率档次、扣除额和抵免额。切勿重复使用往年数值。

文件夹结构

将所有工作整理到工作目录的子文件夹中：

working_dir/
  source/              ← user's source documents (W-2, 1099s, prior return, CSVs)
  work/                ← ALL intermediate files (extracted data, field maps, computations)
    tax_data.txt       ← extracted figures from source docs
    computations.txt   ← all tax math (federal, state, capital gains)
    f1040_fields.json  ← field discovery dumps
    f8949_fields.json
    f1040sd_fields.json
    ca540_fields.json
    expected_*.json    ← verification expected values
  forms/               ← blank downloaded PDF forms
    f1040_blank.pdf
    f8949_blank.pdf
    f1040sd_blank.pdf
    ca540_blank.pdf
  output/              ← final filled PDFs + fill script
    fill_YEAR.py       ← the fill script
    f1040_filled.pdf
    f8949_filled.pdf
    f1040sd_filled.pdf
    ca540_filled.pdf

在开始时创建这些文件夹。保持工作目录整洁——不要放置散乱文件。

上下文预算规则

这些规则可避免上下文过载导致的压缩：

1. 绝不要使用 Read 工具读取 PDF。 每一页都会变成约 250KB 的 Base64 图像（9 页的申报表 = 1.8 MB）。请改为提取文本：

   python3 -c "
   import pdfplumber
   with pdfplumber.open('source/document.pdf') as pdf:
       for p in pdf.pages: print(p.extract_text())
   "
   

2. 绝不要重复读取同一份文件。 首次读取时，将提取的数值保存到 work/tax_data.txt。
3. 每种表格只运行一次字段发现，将结果批量导出为 JSON 并保存到 work/。不要反复使用 --search。
4. 将所有计算结果保存到 work/computations.txt，以便在上下文压缩后保留。

工作流

第 1 步：收集源文件

询问用户有哪些文件。读取 source/ 中的文件（如有需要，将文件移入该目录）。PDF 使用 pdfplumber，CSV 使用 Read 工具。

立即将提取的所有数值保存到 work/tax_data.txt——每份文件单独成节，并包含所有相关数字。

第 2 步：确认申报信息——必需

**必须向用户询问以下每一个问题，并在继续前等待答复。**即使你认为自己能从记忆或源文件中得知答案，也不要跳过这一步。税务申报表是法律文件。

• 申报身份（Single、MFJ、MFS、HOH、QSS）
• 被抚养人（人数、姓名）
• 居住州
• 标准扣除还是逐项扣除
• 数字资产／加密货币交易（是／否）——股票交易不属于数字资产
• 医疗保险覆盖情况（适用于 CA）
• 是否缴纳过预估税款
• 是否有其他抵免额或调整项

在用户答复前，不要继续第 3 步。“与去年相同”也算确认。

第 3 步：查询当年适用数值

从 IRS.gov 和 FTB.ca.gov 查询：

• 联邦税率档次、标准扣除额、QDCG 0%／15%／20% 门槛
• 州税率档次、标准扣除额、个人免税抵免额

保存到 work/computations.txt。

第 4 步：计算联邦申报表

1. 总收入：W-2 工资（1a）+ 利息（2b）+ 股息（3b）+ 资本利得／损失（7）
2. 调整项 → AGI（第 11 行）
3. 扣除额 → 应税收入（第 15 行）
4. 税款：若有符合条件的股息／资本利得，使用 QDCG 工作表
5. 抵免额、其他税款 → 总税款（第 24 行）
6. 已付款项（预扣税、预估税）→ 退税／欠税金额
7. 如有退税：收集直接存款信息（路由号码、账号、账户类型）

将所有行数值保存到 work/computations.txt。

第 5 步：计算资本利得（如适用）

1. Form 8949：单笔交易（Part I 短期，Part II 长期）
2. Schedule D：汇总、$3,000 损失限额、结转金额计算
3. 净利得／损失 → 1040 第 7 行

取整规则：Form 8949 和 Schedule D 必须使用与 1099-B／1099-DA 源文件完全一致的精确到美分的金额。只有 Form 1040 取整到最接近的整数美元（第 7 行 = Schedule D 第 16 行取整后的金额）。不要对 8949 或 Schedule D 中的金额取整。

第 6 步：计算州申报表（CA Form 540）

1. 联邦 AGI → CA 调整项 → CA 应税收入
2. 按税率档次计算税额 − 免税抵免额 → 总税款
3. 预扣税 → 退税／欠税金额

第 7 步：下载空白 PDF 表格

保存到 forms/ 目录。

IRS：往年表格使用 /irs-prior/（/irs-pdf/ 始终提供当年表格）：

https://www.irs.gov/pub/irs-prior/f1040--YEAR.pdf
https://www.irs.gov/pub/irs-prior/f8949--YEAR.pdf
https://www.irs.gov/pub/irs-prior/f1040sd--YEAR.pdf

CA：州表格位于 ftb.ca.gov/forms/YEAR/。

确认每个下载文件都包含 %PDF- 文件头（而不是 HTML 错误页面）。

第 8 步：发现字段名称并填写表格

发现字段 — 每种表格只执行一次，使用 --compact

python scripts/discover_fields.py forms/f1040_blank.pdf --compact > work/f1040_fields.json
python scripts/discover_fields.py forms/f8949_blank.pdf --compact > work/f8949_fields.json
python scripts/discover_fields.py forms/f1040sd_blank.pdf --compact > work/f1040sd_fields.json
python scripts/discover_fields.py forms/ca540_blank.pdf --compact > work/ca540_fields.json

--compact 会输出最简的 {field_name: description} 映射——每个字段名都与其工具提示／朗读描述配对，因此你可以直接将行号映射到字段名，无需手动检查。单选按钮会包含其选项值（例如 {"/2": "Single", "/1": "MFJ"}）。

切勿反复使用 --search，也不要使用 --json（它会转储原始元数据并浪费上下文）。

严重失败：如果发现结果中没有任何人类可读的描述，立即停止。不要猜测字段名。

填写脚本

使用 scripts/fill_forms.py 编写 output/fill_YEAR.py：

• add_suffix(d) — 为文本字段键追加 [0]。IRS 表格必须使用。
• fill_irs_pdf(in, out, fields, checkboxes, radio_values) — 用于 IRS 表格。radio_values 用于申报身份、是／否、支票／储蓄账户。
• fill_pdf(in, out, fields, checkboxes) — 用于 CA 表格。根据 /Parent 链和 /AP/N 键匹配。

将填写后的 PDF 输出到 output/。

第 9 步：验证

python scripts/verify_filled.py output/f1040_filled.pdf work/expected_f1040.json

修复所有失败项，然后重新运行填表脚本。

第 10 步：展示结果

先展示汇总表、验证清单和资本亏损结转（如有），然后：

• 签署报税表 — 未签名的报税表会被拒收
• 付款说明（如需缴税）— IRS Direct Pay、FTB Web Pay，截止日期为 4 月 15 日
• 直接存款 — 建议退款时使用；如果未提供银行信息，请询问
• 申报选项 — 电子申报（Free File、CalFile）或邮寄地址

第 11 步：MFJ 与 Single 对比（如果采用已婚联合申报）

完成 MFJ 报税表后，计算配偶双方若分别采用 Single 申报，各自需要缴纳多少税款。这有助于夫妻了解选择不同申报身份会产生怎样的税务影响。

为每位配偶计算一份假设的 Single 报税表：

1. 收入：仅使用该配偶的 W-2、1099-INT、1099-DIV 和 1099-B/1099-DA
2. 标准扣除额：采用 Single 金额（通常为 MFJ 的一半）
3. QBI 扣除额：仅根据该配偶的 199A 股息计算
4. 税款：使用 Single 税率档和 QDCG 工作表，以及 Single 的 0%／15%／20% 门槛
5. 抵免额：仅在该配偶缴纳了外国税款时计入外国税收抵免
6. 额外 Medicare 税：使用 Single 的 200,000 美元门槛（而非 MFJ 的 250,000 美元）
7. 预扣税款：仅使用该配偶 W-2 第 2 栏的金额

并排展示对比表：

	MFJ（实际）	双方分别 Single	差额
合并税款
合并预扣税款
合计应缴

列出关键要点，尤其要说明额外 Medicare 税门槛的差异（MFJ 为 250,000 美元；每位配偶分别采用 Single 时为 200,000 美元），这通常是 MFJ 与 Single 税款差额的最大因素。

关键注意事项

上下文

• 切勿对 PDF 使用 Read 工具——使用 pdfplumber
• 切勿重复读取同一文档——保存到 work/tax_data.txt
• 每种表格只发现一次字段，并使用 --compact——不要使用 --json（会浪费上下文），也不要反复使用 --search

字段发现

• 字段名会随年份变化——每次都要重新发现
• XFA 模板位于 /AcroForm → /XFA 数组中，不能通过穷举 xref 扫描获取
• 不要使用 xml.etree 处理 XFA——应使用正则表达式（IRS XML 的命名空间有问题）

PDF 填写

• 从 AcroForm 中移除 XFA，将 NeedAppearances 设为 True，并使用 auto_regenerate=False
• 复选框：将 /V 和 /AS 都设为 /1 或 /Off
• IRS 字段需要 [0] 后缀——使用 add_suffix()
• IRS 复选框直接按 /T 匹配；单选按钮组通过 radio_values 按 /AP/N 键匹配

舍入

• Form 8949 和 Schedule D：报告精确到美分的金额（例如「11.36」「-240.00」），以匹配 1099-B／1099-DA 来源文件。切勿舍入这些金额。
• Form 1040：根据 IRS 说明，将所有金额舍入到最接近的整数美元。第 7 行（资本利得）＝Schedule D 第 16 行舍入到最接近的整数美元。
• CA 540：舍入到最接近的整数美元。

特定表格

• 1040：前几个字段（f1_01-f1_03）是财年表头，不是姓名字段。SSN = 9 位数字，不带连字符。数字资产仅指加密货币，不包括股票。
• 8949：A/B/C 框复选框是三选一的单选按钮。汇总字段位于较大的字段编号处（例如 f1_115-f1_119），而不是最后一行数据之后。Schedule D 第 1b/8b 行（来自 8949），而非第 1a/8a 行。
• Schedule D：部分字段带有 _RO 后缀（只读）——跳过这些字段。
• CA 540：字段名称格式为 540-PPNN（页码+序号，不是行号）。复选框以 " CB" 结尾，单选按钮使用命名的 AP 键。
• 下载：往年 IRS 文件位于 irs.gov/pub/irs-prior/，当年文件位于 irs.gov/pub/irs-pdf/