mcpField
C
cash-flow-forecaster

cash-flow-forecaster

github.com/lyndonkl数据与数据库18752 次安装10 周前更新
代码仓库

关于 cash-flow-forecaster

用于按可配置的期限预测各现金账户的每日余额，结合当前余额、定期收支和近期非定期支出。它会标记低于安全线的日期，并估算余额低谷及其不确定范围。

主要功能

  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 cash-flow-forecaster

安装后在 Claude Code 中输入/cash-flow-forecaster确认已加载。

详细介绍

现金流预测器

目录

概述

月平均值无法告诉你：工资要到 5 号才到账，而房租在 3 号扣款时，账户余额是否足够。本技能通过结合以下数据，预测预测期内每个现金账户每天的期末余额：

  • 今天的实际余额。
  • 预测期内所有 next_expected_date 落在该时间段内的计划定期收入和支出。
  • 根据过去 6 个月的非定期支出估算出的可自由支配支出尾项。

它会显示预测余额低于可配置安全下限的日期，以及每个账户余额最低的日期。

输入约定

调用方提供：

  • accounts — 现金账户数组：{id, type, current_balance_cents, safety_floor_cents}。
  • recurring — 按 status: active 筛选后的 recurring.json。
  • transactions — 每个现金账户过去 180 天的已分类交易。
  • today — ISO 日期。
  • horizon_days — 默认为 60。
  • category_overrides（可选）— 用户已知的明确一次性支出（例如，即将支付的旅行定金）。

工作流

Forecast Progress:
- [ ] Step 1: Initialize daily ledger per account with current balance
- [ ] Step 2: Project recurring flows in the horizon window
- [ ] Step 3: Compute discretionary tail (rolling 6-month average)
- [ ] Step 4: Spread discretionary across days
- [ ] Step 5: Apply category_overrides
- [ ] Step 6: Compute daily ending balance
- [ ] Step 7: Flag below-floor days; identify trough
- [ ] Step 8: Compute confidence interval around projection
步骤 1 — 初始化

对每个账户，在 [today, today + horizon_days] 中的每一天创建 ledger[account_id][day] = 0。设置 ledger[account_id][today].opening = current_balance_cents。

步骤 2 — 预测定期收支

对每条有效的定期收支记录，从 next_expected_date 开始，按 cadence 向后推算，直到超出预测期。每次发生时，将 amount_cents_typical 添加到 ledger[recurring.account_id][occurrence_date].flows。

处理工资到账的周末和节假日情况：大多数直接存款会在工作日到账。如果 next_expected_date 落在周末，收入到账日期顺延至下一个工作日；支出仍按日历日期处理。

步骤 3 — 计算可自由支配支出尾项

对每个账户，计算：

discretionary_total_180d = Σ amount_cents over last 180 days
                            where category NOT IN
                            { financial.transfers_internal, savings_investment.*,
                              income.* }
                            and tx_id not in any recurring cluster

discretionary_daily_avg = discretionary_total_180d / 180（此值为负数，表示可自由支配支出）。

步骤 4 — 分摊可自由支配支出

最简单的方法：将 discretionary_daily_avg 从该账户预测期内的每一天扣除。

如果星期几的模式很重要，可以采用更好的方法：计算各星期几的平均值（周一与周五的支出不同），并按星期几应用。除非 transactions 至少包含 90 天的数据，且各星期几的方差存在明显差异，否则默认采用简单方法。

步骤 5 — 应用覆盖项

对 category_overrides 中的每条记录，将明确的 {date, account_id, amount_cents, reason} 添加到当天的收支中。

步骤 6 — 向前滚算
balance[t] = balance[t-1] + Σ flows on day t

跟踪每个账户的余额变化。

步骤 7 — 标记低于安全下限的情况

对每个账户，找出 balance[t] < safety_floor_cents 的日期。确定：

  • trough_balance_cents — 预测期内的最低余额。
  • trough_date — 最低余额出现的日期。
  • first_breach_date — 首次低于安全下限的日期。
  • breach_days — 低于安全下限的天数。
步骤 8 — 置信区间

可自由支配支出的分摊存在方差。计算可自由支配支出的 30 天滚动标准差，并将预测结果表示为一个区间：balance ± 1.5σ × √days_from_today。在余额最低的日期显示 lower_balance_cents 和 upper_balance_cents，让用户看到范围，而不是看似精确的单点估算。

可自由支配支出建模

默认：按 180 天计算简单日均值，涵盖所有不属于定期支出、转账／投资或收入的支出。

细化方式（仅在数据支持时应用）：

  • 星期几。 周六和周日的支出通常较高——应用按星期几划分的系数。
  • 月初与月末。 可自由支配支出往往会在发薪日前后激增。如果定期收入在每月 1 日和 15 日到账，可考虑在发薪日后小幅上调。
  • 季节性。 11 月至 12 月的节日消费确实存在。如果预测期跨越这些月份，可采用 +20% 的乘数并记录说明。

在输出的 methodology 字段中记录所有细化方式，让用户清楚了解具体假设。

输出约定

{
  "horizon": { "start": "2026-04-25", "end": "2026-06-24", "days": 60 },
  "accounts": [
    {
      "account_id": "acc_chk_001",
      "starting_balance_cents": 1247500,
      "ending_balance_cents": 932100,
      "trough_balance_cents": 124300,
      "trough_date": "2026-05-30",
      "trough_band_cents": [82100, 166500],
      "first_breach_date": null,
      "breach_days": 0,
      "safety_floor_cents": 100000
    }
  ],
  "daily": [
    { "date": "2026-04-25", "balances": { "acc_chk_001": 1247500 }, "flows": [] },
    { "date": "2026-05-01", "balances": { "acc_chk_001": 1093200 },
      "flows": [
        { "account_id": "acc_chk_001", "amount_cents": -273500, "label": "Mortgage P&I", "type": "recurring" },
        { "account_id": "acc_chk_001", "amount_cents": -78000,  "label": "Mortgage escrow", "type": "recurring" }
      ]
    }
  ],
  "alerts": [],
  "methodology": "Daily discretionary derived from 180-day rolling average across 23 non-recurring categories; 1.5σ confidence band; weekend-adjusted paychecks; no seasonal multiplier in this horizon."
}

检测到资金缺口时：

{
  "alerts": [
    {
      "severity": "high",
      "type": "projected_below_floor",
      "account_id": "acc_chk_001",
      "first_breach_date": "2026-05-15",
      "trough_balance_cents": -42000,
      "trough_date": "2026-05-30",
      "drivers": [
        { "date": "2026-05-15", "amount_cents": -350000, "label": "Property tax (annual)" }
      ],
      "suggested_actions": [
        "Move $50,000 from savings before 2026-05-14",
        "Defer discretionary spend by $20,000 across the next 3 weeks"
      ]
    }
  ]
}

护栏

  • 绝不预测非现金账户。 券商账户／401k／HSA 余额不是现金流，而是持有资产。跳过这些账户。
  • 提前偿还抵押贷款是显式的，而非隐式的。 用户的标准抵押贷款还款属于定期支出；额外偿还本金则属于 category_override。不要预测额外的本金还款。
  • 可自由支配支出的平均值是尾部估算，而非预测。 这个区间旨在提醒用户这只是估算；低谷的下限才是规划依据，而非中间值。
  • 不要重复计算。 根据定义，定期支出条目会从可自由支配支出的计算中排除（与定期支出簇相关联的交易不属于可自由支配支出集合）。
  • 频繁刷新。 随着新交易不断入账，60 天预测会在几天内过时。每次有新数据导入后，Agent 层都应重新运行。

评论

支持 Markdown