portfolio-drift-rebalancer

投资组合偏离再平衡

目录

• 概述
• 输入约定
• 工作流
• 税务高效的再平衡逻辑
• 输出约定
• 防护措施

概述

家庭通常在三种账户中持有投资：应税经纪账户（例如 Fidelity）、401k 和 HSA 的投资部分。家庭层面会设定目标配置（例如 55/20/20/5 的美国/国际/债券/现金）。此技能汇总所有三个账户的当前配置，计算其与目标配置的偏离，并提出具体的买入和卖出建议以恢复目标配置——优先在税收优惠账户（401k、HSA）中交易，因为已实现收益不会产生税务影响。

它绝不会执行交易。 它只为用户生成建议。

输入约定

调用方提供：

• accounts — 投资账户数组：{id, type, institution, holdings[]}，其中每项持仓包含 {symbol, shares, value_cents, cost_basis_cents, asset_class}。
• target_allocation — { asset_class: target_pct }，总和为 1.0。
• drift_threshold_pct — 默认值为 5 个百分点（5.0）。低于此阈值时，不提出再平衡建议。
• cash_to_deploy_cents — 可选的新增现金金额（例如，工资存款）。
• tax_rate_long_term — 用于成本比较估算（默认值为 15%）。

工作流

Drift / Rebalance Progress:
- [ ] Step 1: Aggregate holdings by asset_class across all accounts
- [ ] Step 2: Compute current allocation percentages
- [ ] Step 3: Compute drift vs target
- [ ] Step 4: Check drift threshold; if all classes within threshold, return no-op
- [ ] Step 5: If new cash, allocate it preferentially to under-target classes
- [ ] Step 6: For remaining drift, plan trades
- [ ] Step 7: Order trades by tax cost (advantaged-account first)
- [ ] Step 8: Verify proposal nets to zero cash impact (or matches new-cash deposit)
- [ ] Step 9: Emit proposal with per-trade rationale

步骤 1 — 汇总

对于目标配置中的每个 asset_class，将所有账户中所有持仓的 value_cents 相加。将经纪账户中的现金头寸也计入（通常 asset_class 为 cash）。

步骤 2 — 计算配置

current_pct[class] = total_value[class] / total_value_all。保留两位小数。

步骤 3 — 计算偏离

drift_pp[class] = current_pct[class] − target_pct[class]，单位为百分点。

步骤 4 — 检查阈值

如果 max(|drift_pp|) < drift_threshold_pct，则输出 rebalance_needed: false 并停止。显示偏离值供参考，但不提出交易建议。

步骤 5 — 投入新增现金

如果 cash_to_deploy_cents > 0，优先将资金分配给低于目标配置的类别。每投入 1 美元新增现金至低于目标配置的类别，就会减少步骤 6 中所需的交易量。

分配顺序：先处理 drift_pp 负值最大的类别。

步骤 6 — 制定交易计划

投入现金后，剩余偏离需要通过交易调整。对每个高于目标配置的类别，计算 excess_cents；对每个低于目标配置的类别，计算 shortfall_cents。通过贪心配对（将最大超额与最大缺口配对）生成 (sell_class, buy_class, amount_cents) 交换列表。

步骤 7 — 按税务效率排序

在每笔交换中，选择具体持仓：

卖出优先级（从最优先到最不优先）：

1. 401k 或 hsa 中的持仓（任何卖出都免税）。
2. 应税经纪账户中有未实现亏损的持仓（卖出可产生可抵税亏损——与 tax-loss-harvest-scanner 协同处理）。
3. 应税经纪账户中有最小未实现收益的持仓（税务成本最低）。
4. 应税经纪账户中有长期收益的持仓（按 15% 纳税）。
5. 应税经纪账户中有短期收益的持仓（按边际税率纳税）。

买入优先级：

1. 401k 或 hsa 中属于目标资产类别的持仓（无交易税务摩擦）。
2. 应税经纪账户中属于目标资产类别的现有持仓（避免洗售，不买回刚刚卖出的资产）。
3. 新持仓（优先选择宽基市场指数基金）。

对于每笔拟议的应税账户卖出，计算并显示预估税务成本：(value − cost_basis) × tax_rate_long_term。用户可自行判断再平衡带来的收益是否超过税务成本。

步骤 8 — 验证

建议必须满足：Σ buys = Σ sells + cash_to_deploy_cents。若不满足，说明计划存在错误——输出 proposal_invalid 警告并停止。

步骤 9 — 输出

每笔交易的输出包括：账户、代码、操作（买入/卖出）、份额、金额、资产类别变化、预估税务成本、理由（低于目标配置/高于目标配置/投入新增现金）。

税务优化再平衡逻辑

账户	卖出税务成本	备注
401k	$0	所有卖出均免税
HSA（已投资）	$0	所有卖出均免税
券商账户（长期收益）	15% × 收益	持有 > 1 年
券商账户（短期收益）	边际所得税率 × 收益	持有 < 1 年 — 通常应避免
券商账户（亏损）	节税额（税损收割收益）	与 tax-loss-harvest-scanner 协同处理

留意洗售规则。 如果卖出后 30 天内（在任何账户中，包括配偶的账户）买入了实质上相同的证券，则该亏损不得抵扣。当再平衡方案建议以亏损卖出应税账户中的 ETF 时，买入时必须使用不同但相似的 ETF（例如，卖出 VTI，买入 ITOT）。在每笔交易中记录洗售规则防护措施。

免费收益标记 — 即使无需再平衡，也要发出：

• 401k 缴款比例 < 雇主匹配上限 → free_money_alert: missed_employer_match。
• HSA 现金余额 > 投资门槛但尚未投资 → free_money_alert: idle_hsa_cash。

输出约定

{
  "as_of": "2026-04-25",
  "totals": {
    "portfolio_value_cents": 49250000,
    "by_account": {
      "acc_inv_fid_001": 18750000,
      "acc_401k_001": 22500000,
      "acc_hsa_001": 8000000
    }
  },
  "current_allocation": {
    "us_equity": 0.625,
    "intl_equity": 0.155,
    "us_bond": 0.180,
    "cash": 0.040
  },
  "target_allocation": {
    "us_equity": 0.55,
    "intl_equity": 0.20,
    "us_bond": 0.20,
    "cash": 0.05
  },
  "drift_pp": {
    "us_equity":  7.5,
    "intl_equity": -4.5,
    "us_bond":    -2.0,
    "cash":       -1.0
  },
  "rebalance_needed": true,
  "max_drift_pp": 7.5,
  "trades": [
    {
      "account_id": "acc_401k_001",
      "action": "sell",
      "symbol": "FXAIX",
      "asset_class": "us_equity",
      "value_cents": 1850000,
      "shares": 18.5,
      "tax_cost_cents": 0,
      "rationale": "Reduce US equity overweight using tax-advantaged account"
    },
    {
      "account_id": "acc_401k_001",
      "action": "buy",
      "symbol": "FSPSX",
      "asset_class": "intl_equity",
      "value_cents": 1850000,
      "shares": 41.0,
      "tax_cost_cents": 0,
      "rationale": "Increase intl equity to target via tax-advantaged account"
    }
  ],
  "alerts": [],
  "free_money": [
    {
      "type": "missed_employer_match",
      "account_id": "acc_401k_001",
      "current_contribution_pct": 3,
      "match_cap_pct": 4,
      "annual_dollars_left_cents": 200000,
      "action": "increase 401k contribution from 3% to 4%"
    }
  ]
}

防护措施

• 绝不执行。 此技能只生成方案。
• 漂移阈值具有实际意义。 小于 5 个百分点的漂移属于噪声；对其进行再平衡会产生摩擦成本（税费、交易开销）。
• 税务成本透明。 每笔应税卖出都必须明确列出预估税务成本。用户必须能够看到。
• 洗售规则防护。 将亏损卖出与买入不同（非实质上相同）的证券配对。并记录下来。
• 持仓不支持碎股时，只买卖整股 — 四舍五入到最接近的整股，并列出剩余现金。
• 不要自动将新增现金投入已超出目标比例的类别。 即使这样能减少交易，也会扩大漂移；应投入低于目标比例的类别。
• 遵守账户级限制。 401k 可能只提供特定基金；绝不要建议买入账户不支持的基金。Agent 层会读取每个账户的合格基金列表。