investment-return-calculator

name	investment-return-calculator
description	当用户需要从券商对账单中计算年化复合收益率时调用

投资年化收益率计算

背景与核心理念

大多数券商软件不会直接提供“投资年化复合收益率”。但从长期看，年化复合收益率通常是衡量投资能力最重要的指标：它能避免被短期暴涨、单笔大赚、偶然清仓收益误导，真正回答“这笔投资资金以复利方式增长得怎么样”。

本技能的核心口径：只计算真正投入证券/基金等投资标的的资金收益。银证转账、闲置现金、账户现金余额不代表投资行为，不能作为本金或终值纳入投资收益率。

收益率应基于投资现金流：

• 买入/申购是投入，记为负现金流。
• 卖出/赎回/清仓/分红是回收，记为正现金流。
• 仍持有的仓位，用估值日市值作为一笔正现金流。
• 最后用这些现金流计算 XIRR，也就是年化复合收益率。

如何使用

用户需要提供券商对账单、交易流水、CSV、PDF、Excel 或粘贴文本。国内券商通常可以导出对账单，也可能每月自动发送；本技能主要处理这类“券商对账单解析 + 收益率计算”的场景。

如果用户使用互联网券商并能提供 API 数据，例如持仓、成交、分红、资金流水，优先用 API 或结构化数据；计算逻辑相同，但解析会更简单。

先用 scripts/parse_statement.py 把文件内容解析出来，再交给 Agent 分析。这个脚本只负责解析 PDF/CSV/TSV，不负责判断投资收益率。

python scripts/parse_statement.py statement.pdf -o parsed.json
python scripts/parse_statement.py trades.csv -o parsed.json

• PDF 会输出每页 text 和 layout_text，便于处理列错位的券商流水。
• CSV/TSV 会输出表头和逐行字典。
• 解析结果只是原始材料，后续仍要由 Agent 判断哪些行是买入、卖出、分红、持仓、银证转账等。

需要的数据

从对账单里提取这些数据即可：

• 标的：证券代码、证券名称、市场、币种。
• 买入：日期、数量、价格、成交金额、费用、实际净成本。
• 卖出/清仓：日期、数量、价格、实际净收入。
• 分红/派息：日期、金额、币种。
• 当前仍持有：持仓数量、估值日期。
• 汇率：当交易币种、报价币种和报告币种不一致时需要。

通常不需要这些数据：

• 银行转证券、证券转银行、入金、出金。
• 可用资金、资金余额、账户现金余额。
• 闲置现金、未投入投资标的的现金。
• 与证券交易无关的账户级资金流水。

已卖出和已清仓的标的必须计算进去，因为它们是投资历史的一部分；分红也必须计算进去，即使后来已经清仓。

现价获取

对账单通常没有当前股价。仍持有的标的需要补齐价格：

• 优先搜索获取最新价格或指定估值日收盘价。
• 如果搜索不方便，再尝试 yfinance 等本地脚本/行情库。
• 如果估值日不是交易日，使用最近一个前序交易日收盘价。
• 港股、美股等多币种资产，需要搜索或确认对应日期汇率。
• 涉及港币、美元等外币时，在结果顶部说明本次使用的汇率，例如“HKD/CNY = 0.91”，并说明汇率会影响人民币口径收益。

已经卖出或清仓的仓位不需要搜索现价，直接使用对账单里的实际卖出净收入。

计算方式

构建现金流后计算：

投入成本 = 所有买入/申购等负现金流的绝对值合计
回收与终值 = 卖出收入 + 清仓收入 + 赎回收入 + 分红 + 当前持仓市值
绝对盈亏 = 回收与终值 - 投入成本
非年化收益率 = 绝对盈亏 / 投入成本
年化复合收益率 = 对逐日现金流计算 XIRR

可以使用 scripts/calc_investment_return.py 计算 XIRR。输入示例：

{
  "valuation_date": "2026-05-29",
  "cash_flows": [
    {"date": "2026-04-22", "amount": -141012.69, "label": "买入 600519"},
    {"date": "2026-05-20", "amount": 150000.00, "label": "卖出 600519"},
    {"date": "2026-05-29", "amount": 376.23, "label": "现金分红 09992"}
  ]
}

正数是投资回收，负数是投资投入。传入脚本前，先排除银证转账、闲置现金和账户现金余额。

输出结果

按这个格式输出，数字替换为真实计算结果：

总年化复合收益率：+10.0%

| 指标 | 数值 |
|---|---:|
| 累计投入 | 约 21.0 万元（¥210,000） |
| 已回收现金 | 约 6.3 万元（¥63,000） |
| 持仓市值 | 约 16.5 万元（¥165,000） |
| 回收和持仓 | 约 22.8 万元（¥228,000） |
| 总盈亏 | +约 1.8 万元（+¥18,000） |
| 年化复合收益率 XIRR | +10.0% |

*已回收现金：包括卖出、赎回、分红

*基于 2026-05-29 港币汇率 HKD/CNY = 0.91 计算。

| 标的 | 投入 | 已回现金 | 持仓市值 | 总盈亏 | 持有时间 | 年化 |
|---|---:|---:|---:|---:|---:|---:|
| 示例A | 约 10.0 万元（¥100,000） | 约 2.0 万元（¥20,000） | 约 9.5 万元（¥95,000） | +约 1.5 万元（+¥15,000） | 8 个月 短期* | +18.0% |
| 示例B | 约 8.0 万元（¥80,000） | 约 1.0 万元（¥10,000） | 约 7.0 万元（¥70,000） | ¥0 | 1 年 2 个月 | 0.0% |
| 示例C（已清仓） | 约 3.0 万元（¥30,000） | 约 3.3 万元（¥33,000） | ¥0 | +约 3,000 元（+¥3,000） | 1 年 3 个月 | +7.8% |
| 合计 | 约 21.0 万元（¥210,000） | 约 6.3 万元（¥63,000） | 约 16.5 万元（¥165,000） | +约 1.8 万元（+¥18,000） |  | +10.0% |

口径：只计算投入证券/基金的资金；不含银证转账、闲置现金、账户现金余额。同一标的按证券代码/名称合并，不按港股通、沪港通、深港通等交易通道拆分。

价格与汇率来源：示例A、示例B使用 2026-05-29 收盘价；HKD/CNY 使用 2026-05-29 汇率。如不涉及外币，删除汇率行。

*短期：持有期不足 1 年。短期涨跌会显著放大年化复合收益率，应同时看非年化收益率和实际盈亏。

输出时注意：

• 顶部总览表和标的表合计行必须对得上。
• “已回收现金”包括卖出/清仓收入、赎回收入、现金分红/派息等已经回到现金里的投资收益，不包括银证转账和闲置现金。
• “当前总价值”= 已回收现金 + 持仓市值。
• 金额优先用“约 X 万元（¥具体数值）”；小于 1 万元时用“约 X 元（¥具体数值）”。
• 不要把“港股通组合费”“托管费”等费用单独列成一个标的；能归属到标的就并入对应标的，不能归属就放进口径说明或总费用备注。
• 标的表必须有“持有时间”，短于 1 年标记“短期*”。
• 保留“非年化收益率”和“年化复合收益率 XIRR”，避免用户只看被短期放大的年化数字。