EigenLedger 报告里的 17 项指标分别是什么？
表格顺序与源码中的 data 字典完全一致，指标名就是你运行时看到的英文标签。
| 指标（报告中的标签） | 计算口径 | 适用场景 | 注意点 |
|---|---|---|---|
| Annual return | 按日频复合年化（CAGR） | 横向比较不同组合的收益水平 | 区间短于三年时年化极不稳定 |
| Cumulative return | 区间累计收益 | 回答「这一段时间赚了多少」 | 必须与起止日期同时给出 |
| Annual volatility | 日收益标准差 × 年化因子 | 衡量组合抖动幅度 | 与优化器的 max_vol 是两套口径 |
| Winning day ratio | 上涨日数 ÷ 总天数 | 直观感受胜率 | 高胜率可与负收益并存 |
| Sharpe ratio | 超额收益 ÷ 波动，rf 默认 0 | 风险调整后绩效对比 | rf=0 会系统性抬高数值 |
| Calmar ratio | 年化收益 ÷ 最大回撤 | 关注「赚的钱够不够抵回撤」 | 回撤极小时该值会异常大 |
| Information ratio | 超额收益 ÷ 跟踪误差（对基准） | 评估相对基准的稳定性 | 强依赖基准选择，基准错了它就没意义 |
| Stability | 收益序列回归拟合的 R² | 看收益曲线是否「平滑向上」 | 对极端值敏感，不能单独作为结论 |
| Max Drawdown | 历史最大回撤幅度 | 衡量最坏持有体验 | 只给幅度，不给修复时间 |
| Sortino ratio | 超额收益 ÷ 下行波动 | 更关注亏损波动的场景 | 与夏普口径不同，不能直接比大小 |
| Skew | 收益分布偏度 | 识别收益是否偏向单侧 | 样本少时噪声大 |
| Kurtosis | 收益分布峰度 | 识别肥尾与极端行情暴露 | 常与偏度一起读，不要单独判断 |
| Tail Ratio | 右尾分位 ÷ 左尾分位 | 粗略衡量盈亏不对称性 | 受尾部个别样本影响明显 |
| Common sense ratio | 尾部比率与盈亏比的组合口径 | 综合看尾部风险收益比 | 不是通用指标，跨平台比较前先对齐定义 |
| Daily value at risk | 默认 sigma=1, confidence=0.95 | 估日常极端亏损量级 | 报告里必须注明置信度与参数 |
| Alpha | 对基准回归的截距项 | 判断收益是否来自选股能力 | 基准不同结论可能相反 |
| Beta | 对基准回归的斜率项 | 衡量组合对市场的敏感度 | Beta≈1 说明组合基本跟随市场 |
报告不含交易次数、胜率（按交易计）、盈亏比、换手率、持仓集中度、分年度收益明细表。要做策略层面的评估，这些指标得另外补。
EigenLedger 一次分析会画出哪几张图？
同一份数据，report 参数不同，出图清单也不同——这点源码里写得很清楚。
| 图表 | 默认模式（report=False） | PDF 模式（report=True） | 看图时要注意什么 |
|---|---|---|---|
| 组合权重饼图 | 显示 | 显示并保存 allocation.png | 权重为 0 的标的会被直接从组合里剔除 |
| 收益柱状图 | 显示（标题 Returns） | 保存 ret.png | 红涨绿跌与国际惯例相反，按源码配色为蓝/灰 |
| 累计收益 vs 基准 | 显示 | 保存 retbench.png | 基准口径由 benchmark 参数决定 |
| 分年度收益 | 显示 | 保存 y_returns.png | 首年与末年常为不完整年份，勿直接比较 |
| 月度收益热力图 | 显示 | 保存 heatmap.png | 该图对 QuantStats 版本敏感，历史上多次报参数错误 |
| 回撤曲线 | 显示 | 保存 drawdown.png | 看形状比看终值更有信息量 |
| 回撤区间 | 显示 | 保存 d_periods.png | 能回答「回撤修复了多久」 |
| 滚动 Beta | 显示 | 保存 rbeta.png | 需要足够长的窗口，短区间噪声大 |
| 滚动波动率 / 滚动夏普 | 源码中被注释，不显示 | 滚动夏普会保存为 rsharpe.png | PDF 分支引用的 rvol.png 实际不会生成，见下节 |
ret.png、heatmap.png 等）。在项目根目录批量跑多份报告时，后一次会静默覆盖前一次；务必每次切换独立目录或提前备份。EigenLedger 的 PDF 报告能不能直接交付？
report=True 会调用 fpdf 拼一份 PDF，但源码里有几处硬编码会让它在中文环境下翻车。
| 限制 | 源码依据 | 后果 | 可行的绕法 |
|---|---|---|---|
字体写死为 arial | pdf.set_font("arial", "B", 14) | fpdf 内置字体不含 arial，也未注册中文字体，中文标的与说明会乱码或直接报字体未定义 | 先出 PNG 再自行排版，或改用支持中文的 PDF 工具 |
强制引用 rvol.png | PDF 分支 pdf.image("rvol.png", ...)，而生成该图的调用被注释 | 工作目录里没有这个文件时会抛图片读取错误，PDF 生成中断 | 先手工放置一个同名图片，或放弃 PDF 分支 |
| 封面 logo 走远程链接 | pdf.image("https://user-images.githubusercontent.com/...png", ...) | 离线环境无法生成封面 | 提前下载该图片或跳过封面 |
| 产出散落在工作目录 | 多张 PNG 以固定文件名写盘 | 仓库被图片文件污染，且便于覆盖 | 在独立临时目录中运行 |
| 图表文件名固定 | ret.png / heatmap.png 等为硬编码文件名 | 多次运行会静默覆盖上一次的图 | 每次运行切换独立目录并留存副本 |
| 指标值是字符串 | result 的字段统一转成带单位的字符串 | 直接参与后续计算会报错或得到错误结果 | 先清洗成数值再进入下游流程 |
如果仍要生成 PDF，建议的执行顺序：
- 切到空目录再运行，
filename显式指定成带日期的文件名，避免覆盖历史报告。 - 确认
rvol.png存在（可先手工补一张），否则这一步必然失败。 - 确认能访问 GitHub 图片 CDN，否则封面会失败。
- 生成后逐页检查中文是否可读，有乱码就改走「PNG + 自行排版」路线。
EigenLedger 返回值里有哪些字段可以直接取用？
PortfolioAnalysisResult 是一个空类，全部字段在运行中动态挂载——所以只有跑过才知道有什么。
| 字段 | 内容 | 适用场景 | 注意点 |
|---|---|---|---|
df | 报告指标的原始字典 | 想把指标写成表格或写进数据库 | 不是 DataFrame，需要自己转 |
CAGR / CUM / VOL | 年化、累计、波动 | 拼接自定义摘要 | 均为带单位的字符串 |
SR / CR / IR / SOR | 夏普、Calmar、信息比率、Sortino | 做多组合打分对比 | 字符串类型，参与计算前要转 float |
MD / VAR / TA / CSR | 回撤、VaR、尾部比率、常识比率 | 风险报告 | VaR 带百分号字符串 |
AL / BTA | Alpha 与 Beta | 收益归因的第一步 | 基准变化会同时改变这两个值 |
returns / creturns | 日收益序列与累计净值序列 | 自己再画图或做二次统计 | 索引为交易日期，可直接接 pandas |
benchmark | 基准收益序列 | 画相对强弱 | 来源可能是 yfinance 或本地数据 |
orderbook | 再平衡下的各期权重表；无再平衡时退化为资产-权重表 | 查「每一期到底配了什么」 | 两种形态来源不同，处理前先判断形状 |
SK / KU / win_ratio / STABILITY | 偏度、峰度、上涨日占比、稳定性 | 分布特征与体验描述 | 字符串，且部分数值被包成列表字符串 |
SR、BTA），且不是稳定的公开 API——项目处于低频维护状态，升级后字段可能变化，依赖它们时要自己加断言保护。拿到 EigenLedger 报告后按什么顺序读？
17 个数字一起看会失焦。按下面的顺序读，能最快发现「这份报告值不值得信」。
先看区间与标的
区间是否覆盖了完整的牛熊？标的里有没有上市时间明显晚于起点的票？这两点决定后面所有数字的成色。
再看累计收益与最大回撤这一对
累计收益配最大回撤，才构成完整体验描述。只看收益等于只看硬币的一面。
然后拆 Alpha 与 Beta
Beta 接近 1 时，高收益大概率来自市场本身；Alpha 才是选股或配置带来的部分，并且要检查它在不同区间是否稳定。
接着看分布类指标
偏度、峰度、尾部比率告诉你「收益是不是靠几次极端行情堆出来的」，这类组合的可持续性通常更差。
最后看基准相关信息比率
信息比率衡量相对基准的稳定性，基准选错时它没有意义；确认基准与组合同市场、同币种后再读。
报告类工作，EigenLedger 与本机技能怎么分工？
EigenLedger 强在「固定格式 + 可重跑」，本机技能强在「不写代码就能问」。
| 报告需求 | EigenLedger 路线 | 本机技能路线 | 建议 |
|---|---|---|---|
| 固定 17 项指标的批量报告 | 一次调用得到完整指标表 | 指标集合由各技能自行组织 | 要格式统一选前者 |
| 单只票的体检 | 曲线救国，需自建单标的组合 | a-share-metrics-card 直接输出体检卡 | 单标的场景选后者 |
| 图要更好看 | 图表样式写在源码里，改样式要改代码 | chart-image 可生成多种出版级图 | 交付图选后者，回测图选前者 |
| PDF 归档 | 有 PDF 分支但有字体与缺图限制 | 无内置 PDF 模板 | 两边都建议先出图再排版 |
| 指标解释 | 需要自己读源码与文档 | 可要求技能解释指标含义 | 教学场景选后者 |
| 结果可复现 | 脚本 + 版本号即可复现 | 依赖对话上下文，复现性较弱 | 正式研究选前者 |
披露：本机技能目录已核验（29 个技能），但 EigenLedger 与 EasyClaw 无已证实集成，上表为能力对照，不表示可以互相调用或结果一致。
关于报告内容的常见问题
为什么报告里没有交易次数和胜率？
因为这套分析的对象是「收益序列」而不是「交易记录」。源码从复权价格和权重直接算组合收益，没有成交事件的概念，因此无法统计交易次数、按笔胜率、盈亏比等指标。要这些数据得在策略层自行记录，以官方实现为准。
月度热力图为什么容易报错？
该图由 QuantStats 提供，历史上多次因 QuantStats 参数签名变化而报参数错误（社区 issue 中有明确记录）。项目把 QuantStats 锁定在 0.0.62，正是为了规避这类问题，因此升级依赖前务必先跑一遍出图流程。
report=True 生成的 PDF 为什么可能是空白的？
常见原因是执行目录里没有 rvol.png——PDF 分支会引用这张图，但生成它的调用在源码中被注释掉了。此外封面 logo 走远程链接、字体写死 arial，都会在离线或中文环境下失败。建议先出 PNG 再排版，以官方实现为准。
结果对象能直接转成 DataFrame 吗？
可以，但需要自己写：result.df 是字典结构（含指标名与数值两列），先 pd.DataFrame(result.df) 再设索引即可。注意多数指标值是带单位的字符串，参与计算前要先清洗，以官方实现为准。
零权重的标的会怎样？
源码会在分析时把权重为 0 的标的从组合列表中删除，也就是这一刻起引擎对象被修改了。若你在同一次会话里复用同一个 Engine 再分析一次，看到的组合已经不是最初那个。想复用请用 copy.deepcopy。
报告的图能直接放进对外材料吗？
技术上讲可以，但要注意图的默认样式是源码写死的（尺寸 30×8 等），且不标注数据来源与区间。正式对外材料建议自己据此重绘，并注明区间、数据源与假设，避免被误读为收益承诺。
和券商 App 里的收益曲线为什么对不上？
常见原因：券商按持仓市值与现金流计算，而这里按复权价格与固定权重计算；券商计入手续费、税费与实际分红，这里不计；券商的区间是自然日历，这里默认到运行当天。对齐这三项后再比较，以双方各自的口径说明为准。