用途
该技能用于计算和比较投资回报指标，帮助用户评估投资表现、分析现金流时点对回报的影响，并区分基金经理的投资能力与投资者自身的现金流决策。
主要能力
- 简单（持有期）回报：R = (V_end - V_begin + D) / V_begin，其中 D 为期间收到的分红或利息。若期末价值已反映再投资分红，则不再重复加 D。
- 算术平均与几何平均：算术平均用于前瞻性输入（如均值-方差优化），几何平均用于衡量已实现的多期复合增长。两者差距近似为 σ²/2（波动拖累）。
- 对数回报：r = ln(V_end / V_begin)，具有时间可加性，适合统计建模和多期聚合。对数回报在时间上可加，但在资产间不可加。
- CAGR（复合年增长率）：CAGR = (V_end / V_begin)^(1/n) - 1，n 以年为单位，适用于无中间现金流的两个估值点之间的年化几何增长率。
- 时间加权回报（TWR）：通过链接各外部现金流之间的子期回报，剔除现金流时点影响，衡量基金经理的投资能力，是 GIPS 标准。精确 TWR 需要每个现金流日的组合估值。
- 修正 Dietz 回报：当无法获取每个现金流日的估值时，按日加权各外部现金流来近似期间回报。它是资金加权近似，链接修正 Dietz 子期回报可近似 TWR。当现金流相对组合价值较大或市场波动剧烈时，精度下降，建议在大额现金流日重新估值。
- 资金加权回报（MWR / IRR）：使所有投资者现金流（投入、撤出和终值）的净现值等于零的内部收益率。MWR 反映投资者实际体验，对现金流时点和金额敏感，通常用牛顿-拉夫森法或二分法数值求解。
- 年化：R_annual = (1 + R_period)^(periods_per_year) - 1。例如，2% 的季度回报年化为 (1.02)^4 - 1 = 8.24%。
- 子期链接：(1 + R_total) = ∏(1 + R_i)，是 TWR 和 CAGR 背后的基础恒等式。
使用方式
技能附带 scripts/return_calculations.py，提供 Returns 类，包含上述所有公式的静态方法（持有期回报、TWR、MWR/IRR 牛顿法、CAGR、年化、链接、算术/几何平均、对数回报转换等）。
运行方式：
uv run scripts/return_calculations.py（PEP 723 内联元数据自动解析 numpy）- 或安装 numpy 后运行
python3 scripts/return_calculations.py
裸调用或 --verify 会打印所有函数的演示，并断言上述示例值（示例1 CAGR = 10%，示例2 TWR = +8.0% 累计 / 3.92% 年化，MWR = -0.6682%），任何不匹配都会以非零状态退出。
--help 列出可用函数和导入用法。
编程使用时，导入而非运行：from return_calculations import Returns。
适用场景
- 评估基金经理业绩（使用 TWR）
- 分析投资者实际回报体验（使用 MWR）
- 计算无中间现金流的投资年化增长率（使用 CAGR）
- 比较不同投资策略的复合增长
- 需要时间可加性的统计建模（使用对数回报）
限制
- 精确 TWR 需要每个现金流日的组合估值。
- 修正 Dietz 在现金流相对组合价值较大（如单笔超过约 10%）或市场波动剧烈时精度下降，建议在大额现金流日重新估值。
- 年化回报对短于一年的期间意义有限，会放大噪声。
- 算术平均用于多期复合增长会高估终值。
- 若期末价值已包含再投资分红，不应在持有期回报公式中重复加 D。
- MWR 将基金经理能力与投资者择时决策混在一起，评估经理时应使用 TWR。
常见陷阱
- 混淆算术平均与几何平均：算术平均总是大于或等于几何平均（AM-GM 不等式）。
- 用算术平均预测多期复合增长会高估终值。
- 对极短期间年化：如 2% 周回报年化为 (1.02)^52 - 1 = 180%，会放大噪声且具有误导性。
- 在应使用 TWR 时忽略现金流时点。
- 重复计算分红。
- 在期间内大额现金流时盲目信任修正 Dietz。
交叉引用
- time-value-of-money（核心插件）：NPV、IRR 和折现概念与 MWR 计算重叠；负责项目/贷款 IRR。
- statistics-fundamentals（核心插件）：算术与几何平均、回报分布分析。