金融数学工具箱 TYEclipse/dsh-finance

dsh-finance

DeepSeek Harness (dsh) 的金融数学工具箱：贷款月供与摊销、复利增长、名义/有效利率换算、现金流分析（NPV/IRR/回收期）、退休提款规划、储蓄目标规划、通胀购买力换算、多笔债务还款规划（雪崩法 vs 雪球法）、再融资对比（月供视角 vs 利息视角）。零运行时依赖、纯算术、完全确定性。

大模型心算金融公式极易出错——"30 万美元 4% 利率 30 年月供多少"、"这个项目的 IRR 是多少"、"我的积蓄按 4% 提款能撑 30 年吗"正是高频翻车问题。本插件把这些问题变成确定性的工具调用。

工具

| 工具 | 说明 |
| loan_payment | 等额本息月供（PMT）→ 月供、总还款、总利息。可选摊销表（上限 360 行）与每月固定提前还款（缩短期限、节省利息）。 |
| compound_growth | 一次性本金 + 每月定投的复利终值。支持日/月/季/半年/年/连续复利。可选逐年明细（上限 60 行）。 |
| rate_convert | 名义利率（APR）↔ 有效年利率（EAR）互转，含连续复利（EAR = e^r − 1）。 |
| cashflow_analysis | 任意现金流序列的 NPV（按折现率）、IRR（二分法）与简单/折现回收期。无符号变化或多重符号变化时如实报告，绝不编造数值。 |
| retirement_plan | 安全提款数学：给定每月提款额算耗尽时间（4% 法则一族），或给定年限算恰好耗尽余额的可持续月提款（PMT）。输出提款率、总提款额、利息收益；两者都给时判定能否撑满年限（lasts_horizon）。 |
| savings_goal | 储蓄目标规划：给定每月储蓄额算出还要多少个月达标（months_to_goal、期末余额、累计投入、利息收益）；给定期限（月数）算出每月必须存多少（required_monthly_contribution，向上取整到分，并给出该精确计划的期末余额）。两者都给时额外判定 on_track。储蓄额与收益率都为零、缺口永远填不满时如实报 unreachable，绝不给一个编造的月数。 |
| inflation_adjust | 购买力换算：今天这笔钱在 N 年后的名义成本、未来一笔名义金额折回今天的现值；给出名义收益率时，用精确费雪关系 (1+名义)/(1+通胀) − 1 算实际收益率，并同时给出名义与实际终值。支持通缩（负通胀）与小数年限（0.5 = 半年）。 |
| debt_payoff | 多笔债务 + 一个月度预算：先付清所有最低还款（合同义务），余额集中打一笔债，逐月模拟雪崩法（利率最高优先）与雪球法（余额最小优先）两种顺序，把"哪个更省利息"变成真实数字。输出还清月数、总还款、总利息、各债实际清零顺序（payoff_order）与策略优先级（priority_order），以及哪种顺序更省。预算只够最低还款且低于月息时如实报 debt_free: false，绝不编造月数。 |
| refinance_analysis | 继续还老贷款还是做再融资？把同一笔余额按新利率（可选新期限）与手续费重新算一遍，月供视角（新月供、手续费几个月回本）与利息视角（剩余年限的总利息）并列给出——只要期限变了，两个视角就会给出不同答案。返回 verdict（cheaper_every_way / payment_down_interest_up / payment_up_interest_down / not_better）与说明，而不是一个乐观数字；手续费默认为过户时现金支付，也可用 roll_costs_in 滚进新贷款余额；月供没有下降时不给回本月份。 |

为什么

- 专治 LLM 心算错误——复利、PMT、EAR 换算、IRR、提款数学是幻觉高发区，本插件给出精确且经过测试的答案。
- 零运行时依赖——纯 Math 运算，无网络、无文件系统、无动态执行，任何环境都安全。
- 外部锚点测试——头条数字全部对照公开资料验证（贷款月供表、教材 EAR 值、Excel IRR 官方示例）与独立闭式脚本生成，绝不自证往返。可持续提款与贷款月供同为 PMT 闭式，互相交叉校验。

安装

装进 web profile（dsh plugin 无默认 profile——必须带 --profile）
dsh plugin --profile web add github:TYEclipse/dsh-finance

验证层已挂载：

dsh --profile web --dump-config | grep '=='

用法示例

30 万美元 4% 利率 30 年月供多少？
→ loan_payment { principal: 300000, annual_rate_percent: 4, months: 360 }
→ monthly_payment 1432.25, total_interest 215610, total_paid 515610

1000 美元起投、每月加 100、10 年、5% 月复利，最后有多少？
→ compound_growth { principal: 1000, annual_rate_percent: 5, years: 10, compounding: "monthly", contribution_per_month: 100 }
→ future_value 17175.24（投入 13000，利息 4175.24）

"12% 名义利率、按月复利"实际年利率多少？
→ rate_convert { rate_percent: 12, input_kind: "nominal", compounding: "monthly" }
→ output_rate_percent 12.682503（有效 EAR）

这个项目值得投吗？（Excel IRR 官方示例，按 8% 折现） → cashflow_analysis { cash_flows: [-70000, 12000, 15000, 18000, 21000, 26000], discount_rate_percent: 8 } → npv 1390.96, irr_percent 8.663095, payback_periods 4.15

100 万积蓄按 4% 收益每月提 4000，能撑 30 年吗？
→ retirement_plan { principal: 1000000, annual_rate_percent: 4, monthly_withdrawal: 4000, years: 30 }
→ months_to_exhaust 538.42, withdrawal_rate_percent 4.8, lasts_horizon true
→（顺带：30 年可持续月提款额为 4774.15）

现有 1 万、每月存 500、按 5% 收益，多久攒到 5 万？
→ savings_goal { target_amount: 50000, current_savings: 10000, annual_rate_percent: 5, monthly_contribution: 500 }
→ months_to_goal 65, final_balance 50341.48（累计投入 42500，利息 7841.48）

20 年后要 10 万，现有 2 万按 6% 收益，每月得存多少？
→ savings_goal { target_amount: 100000, current_savings: 20000, annual_rate_percent: 6, months: 240 }
→ required_monthly_contribution 73.15, projected_balance 100002.38

今天的 1000 块，10 年后按 2.5% 通胀要花多少？若收益 6% 实际赚多少？
→ inflation_adjust { amount: 1000, annual_inflation_percent: 2.5, years: 10, nominal_rate_percent: 6 }
→ future_cost 1280.08, real_value 781.20, real_rate_percent 3.414634, nominal_future_value 1790.85, real_future_value 1399.01

信用卡 A 欠 5000（22%）、卡 B 欠 2000（12%），每月能还 600，先还哪张更省？
→ debt_payoff { debts: [{ name: "card A", balance: 5000, annual_rate_percent: 22, minimum_payment: 100 },
{ name: "card B", balance: 2000, annual_rate_percent: 12, minimum_payment: 50 }],
monthly_budget: 600 }
→ 雪崩法：13 个月还清，总还款 7739.37，总利息 739.37（卡 A 第 11 月清零、卡 B 第 13 月） → 雪球法：14 个月还清，利息 895.70 —— 雪崩法省 156.33 元、少 1 个月

语义

- 金额舍入：只在输出边界四舍五入到分；内部迭代保持全精度，末期还款自动调平余额。
- 提前还款：合同月供不变，期限缩短；输出 payoff_months、months_saved、interest_saved。
- 复利：loan_payment 按房贷惯例对 APR 月复利；compound_growth 先把任意频率换算成有效月利率再复利，定投精确合成；continuous 用 e^rt。
- 现金流：第 0 项为时点 0（通常是负的初始投入），第 t 项为期末现金流。IRR 仅在现金流恰好变号一次且存在根时给出，否则返回说明（无符号变化 / 可能不唯一）。回收期线性插值。
- 提款：月复利、月末提款。提款额 ≤ 利息收益（W ≤ P·r）时永不耗尽（never_exhausts: true）。可持续提款按分位舍入后的月供摊销，与银行口径一致。
- 储蓄目标：月复利、月末存入。months_to_goal 是余额首次达标的月份；required_monthly_contribution 为年金闭式解向上取整到分，projected_balance 用该精确到分的储蓄额重新模拟，两者口径自洽；储蓄额与收益率都为零导致缺口填不满时，报 unreachable（100 年上限）而非编造月数。
- 通胀：按年复利，指数保留小数年限（months 字段只是取整回声）。实际收益率用精确费雪关系，内部不舍入——real_future_value 不受展示用 real_rate_percent 舍入影响。通缩（负通胀）照常计算，不拒绝。
- 债务还款：各债按自身利率月复利；先付清全部最低还款（合同义务），剩余预算按策略优先级集中打一笔。payoff_order 是余额实际清零的顺序（与优先级顺序不是一回事），priority_order 才是策略排序。两种顺序始终都会模拟，comparison、best_strategy、interest_saved_by_best 都是有依据的数字——省下的利息由两个已报告总额相减得出，读者在界面上手算能对上。预算只够最低还款且低于月息时如实报 debt_free: false，不给编造月数。
- 再融资对比：两边都沿用 loan_payment 的合同月供口径。monthly_savings 与回本月份由已报告的月供相减得出，屏幕上的数字自洽。horizon.interest_saved 是 horizon_months（默认取两个期限中较短者）内的摊销视角，lifetime_interest_saved 取自报告的两个合同总额，因此当月供向上取整让贷款略早还清、末月留下零头时，两者会差几分钱。break_even_month 是累计月供节省首次覆盖过户现金的那个月，月供没有下降时字段缺席而不是给一个巨大数字。roll_costs_in: true 表示手续费滚进新余额（amount_financed = balance + closing_costs、upfront_cash = 0）。
- 零利率精确处理（无除零）：月供 = 本金 ÷ 期数；耗尽时间 = 本金 ÷ 提款额。
- 校验：每个工具校验输入，非法时返回 valid: false 与具体原因，绝不抛异常。

限制（设计如此）

- 不含手续费、税费、保险、托管——纯摊销数学。
- 摊销表上限 360 行、逐年明细上限 60 行（见 truncated 标记）。
- 不做货币换算——所有金额为同一货币单位。
- 低于 −100% 的利率视为无意义输入而拒绝，其余精确计算。
- 不支持不规则周期现金流（XIRR/XNPV）——周期均匀。
- IRR 按惯例取单值：现金流多次变号时标记而非给任意一个根。
- debt_payoff 上限 10 笔债务、100 年；预算分配是确定性的（先最低还款、再集中打一笔目标债），因此模拟的是雪崩/雪球这类顺序策略，不含任意还款顺序或"余额转移"玩法。
- refinance_analysis 只比较两笔固定利率贷款：不含点数/返现、不含 ARM 或前期优惠利率、不含提前还款罚金、不含抵税效应，也不做征信评分——它算的是你描述的这笔贷款，不是你最终能批下来的那笔。

许可证

MIT