mcpField
T
tax-loss-harvest-scanner

tax-loss-harvest-scanner

github.com/lyndonkl其他18738 次安装10 周前更新
代码仓库

关于 tax-loss-harvest-scanner

用于扫描应税经纪账户亏损持仓的财务 Skill，会核查家庭各账户的洗售窗口并生成建议，不会执行交易。

主要功能

  1. 01按未实现亏损筛选持仓
  2. 02核查全家庭账户洗售窗口
  3. 03建议替代证券
  4. 04估算节税金额
  5. 05列出受阻候选项及日期

适用场景

  1. 01筛查应税持仓中的收割候选项
  2. 02卖出亏损资产前核查计划买入
  3. 03查看替代证券和节税估算

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lyndonkl/claude --skill tax-loss-harvest-scanner

安装后在 Claude Code 中输入/tax-loss-harvest-scanner确认已加载。

详细介绍

Tax-Loss Harvest Scanner

目录

概述

税损收割会在应税经纪账户中实现亏损，以抵消资本利得（每年最多可抵消 $3,000 的普通收入），同时不改变家庭的经济状况——出售所得会用于购买相似但不完全相同的证券，从而维持市场敞口。最棘手的是洗售规则：如果在亏损卖出前后 30 天内于*任何家庭账户（包括配偶的 IRA）*买入实质上相同的证券，这笔亏损将不被认可。

此功能会扫描应税经纪账户，寻找可收割的候选标的，并根据所有家庭账户中的洗售窗口逐一验证。

输入约定

调用方需提供：

  • taxable_holdings — 应税经纪账户中的批次，最好按批次提供：{symbol, shares, cost_basis_cents, value_cents, acquisition_date}。如果只有汇总的持仓级数据，请标记 lot_resolution: aggregate 并说明此限制。
  • all_account_transactions_60d — 过去 60 天内所有家庭账户（应税账户、401k、IRA、配偶的 IRA、HSA）中的每笔买入、卖出和股息再投资记录。用于检测洗售。
  • planned_buys_30d（可选）— 股息再投资计划、401k 缴款、自动存款等所有将在未来 30 天内买入的安排。
  • loss_threshold_cents — 纳入考虑的最低未实现亏损；默认值为 50000（$500）。
  • today — ISO 日期。

洗售规则

根据 IRS 规定，如果以亏损卖出的证券被在以卖出日为中心的 61 天窗口（卖出日前 30 天至卖出日后 30 天）内买入的“实质上相同”证券替代，即会触发洗售。

对于此功能：

  1. 同一股票代码。 始终属于实质上相同。没有例外。
  2. 同一基金家族、同一指数。 VTI ↔ VFIAX ↔ FXAIX（不同基金家族的 S&P 500 / 全美市场追踪基金）根据 IRS 指引通常不被视为相同——但此功能会保守地将追踪同一指数的两只基金视为实质上相同。
  3. 不同指数、相似敞口。 VTI（全美市场）↔ ITOT（不同基金家族的全美市场基金）——不属于实质上相同。这些是有效的 TLH 配对。
  4. 所有家庭账户均计入。 配偶的 IRA、401k 自动买入、HSA 自动买入——均在范围内。
  5. 股息再投资。 30 天窗口内的股息再投资属于会触发洗售的买入。在卖出前，请在拟收割的证券上关闭 DRIP。

工作流

TLH Scan Progress:
- [ ] Step 1: Filter taxable lots with unrealized loss >= loss_threshold
- [ ] Step 2: For each candidate, check 30-day backward wash-sale window
- [ ] Step 3: For each candidate, check 30-day forward planned-buys window
- [ ] Step 4: Identify substitute security (similar exposure, not identical)
- [ ] Step 5: Compute realized loss and tax savings estimate
- [ ] Step 6: Emit harvest proposals with explicit wash-sale guard
- [ ] Step 7: Surface candidates blocked by wash sale with the unblock date
第 1 步 — 亏损筛选

unrealized_loss_cents = value_cents − cost_basis_cents（负数）。保留满足 |unrealized_loss_cents| ≥ loss_threshold_cents 且 unrealized_loss_cents < 0 的批次。

如果无法按批次解析，则使用 weighted_avg_cost_basis 回退到持仓级数据。记录 lot_resolution: aggregate，并警告某些批次可能盈利、另一些可能亏损；只有汇总结果呈现亏损。

第 2 步 — 向前回溯窗口

对于每个候选股票代码，在 all_account_transactions_60d 中回溯 30 天，检查是否买入过相同或实质上相同的证券。如果找到，卖出会被部分或完全洗售——在最近一次买入后 30 天内不得卖出。将结果标记为 blocked_until: YYYY-MM-DD。

步骤 3 — 前瞻窗口

查看 planned_buys_30d 中是否有相同或实质上相同的证券。常见情况：

  • 每 2 周通过 401k 工资缴款买入标普 500 指数基金 → 如果在应税账户中收割标普 500 的损失，下一笔 401k 买入会触发洗售。
  • 已安排股息再投资。
  • 自动按月向经纪账户存款。

解决办法：

  • 对于 401k 工资缴款：如果可行，将 401k 买入的资产类别更改一个周期；否则收割其他证券。
  • 对于 DRIP：在卖出前至少 1 天关闭收割目标的 DRIP。
  • 对于自动存款：延后或转投其他标的。
步骤 4 — 替代组合

选择能够维持市场敞口的替代标的。该技能提供默认映射（见替代组合）。替代标的必须：

  • 跟踪相似但不同的指数。
  • 可在目标账户中买入。
  • 费用比率较低（理想情况下 ≤ 0.10%）。
步骤 5 — 估算节税金额

tax_savings_cents ≈ |realized_loss_cents| × marginal_rate，其中边际税率由用户提供，或默认为抵扣不超过 $3,000 的普通收入时为 24%，抵扣长期资本利得时为 15%。请同时列出两项。

步骤 6 — 输出方案

每项方案包括：

  • 卖出方：账户、代码、税务批次、份额、已实现亏损。
  • 买入方：账户、替代代码、份额、金额。
  • 洗售防护：已确认前后 ±30 天无冲突。
  • 节税金额估算。
  • 关闭 DRIP 的步骤（如适用）。
步骤 7 — 被阻止的候选项

对于被阻止的亏损，将其放入 blocked[] 列表并附上 unblock_date，以便用户知道何时可以收割该候选项。

替代组合

合理的起始组合（技能会将这些作为建议输出，而非权威结论）：

卖出买入替代标的理由
VTI（美国全市场）ITOT（美国全市场，iShares）不同系列，敞口相似
VOO（标普 500）VTI（美国全市场）指数不同
VXUS（国际全市场）IXUS（国际全市场，iShares）不同系列
BND（美国综合债券）AGG（美国综合债券，iShares）不同系列，敞口相同 — 存在争议；更倾向于选择 SCHZ 这类指数略有不同的标的
IEFA（发达国际市场）VEA（发达国际市场）不同系列
FXAIX（Fidelity 标普 500）FSKAX（Fidelity 全市场）指数不同

务必将替代标的注明为建议 — 用户应自行确认其适合自己的投资计划。

输出约定

{
  "as_of": "2026-04-25",
  "candidates_total": 5,
  "harvest_proposals": [
    {
      "id": "tlh_20260425_001",
      "sell": {
        "account_id": "acc_inv_fid_001",
        "symbol": "VTI",
        "lots": [
          { "acquisition_date": "2024-09-12", "shares": 35, "cost_basis_cents": 985250, "value_cents": 935500 }
        ],
        "realized_loss_cents": -49750
      },
      "buy": {
        "account_id": "acc_inv_fid_001",
        "symbol": "ITOT",
        "shares": 38,
        "value_cents": 935500,
        "rationale": "Substantially similar exposure to VTI, different index family — not substantially identical per common interpretation"
      },
      "wash_sale_check": {
        "backward_30d_clear": true,
        "forward_30d_clear": false,
        "blockers": [
          { "type": "401k_payroll_buy", "symbol_substantially_identical": "FSKAX", "buy_date": "2026-05-02" }
        ],
        "remediation": "Change 401k allocation away from FSKAX for the 2026-05-02 cycle, or harvest a different security"
      },
      "tax_savings_estimate_cents": 11940,
      "drip_disable_required": true,
      "status": "remediation_required"
    }
  ],
  "blocked": [
    {
      "symbol": "VXUS",
      "reason": "spouse_ira_buy_within_30d",
      "unblock_date": "2026-05-12"
    }
  ],
  "warnings": []
}

防护措施

  • 检查所有家庭账户中的洗售情况。 配偶的 IRA 也计入。401k 自动买入也计入。DRIP 也计入。
  • 优先按税务批次处理。 只有汇总数据时，应降低置信度并提示风险。
  • 替代标的是建议。 用户必须确认按其理解，该标的并非“实质上相同”；IRS 尚未对所有指数组合给出明确界定。
  • 卖出前关闭 DRIP。 如果收割的证券启用了 DRIP，下一笔股息会使亏损触发洗售。
  • 不要不加区分地跨账户类型配对。 在应税账户中收割的亏损，不能通过在 401k 中买入相同证券来替代 — 这仍然属于洗售。
  • 跟踪年初至今的已实现亏损。 显示累计金额 — 用户有 $3,000 的净已实现亏损可抵扣普通收入后，额外收割的亏损只会结转（仍有用，但边际收益较低）。
  • 绝不执行交易。 仅提供方案。

评论

支持 Markdown