拿着 EigenLedger 报错原文怎么对号入座？
左列是你在终端里看到的文字（实测原文或 issue 原文），右列是处理方向。
| 报错原文（节选） | 所属层级 | 根因 | 处理方向 |
|---|---|---|---|
error: invalid command 'bdist_wheel' | 依赖 / 安装 | 构建 fpdf 源码包时缺少 wheel | 先 pip install wheel 再装 |
ModuleNotFoundError: No module named 'pytz' | 依赖 / 导入 | yfinance 0.1.96 需要 pytz，依赖清单未声明 | pip install pytz |
IndexError: single positional indexer is out-of-bounds | 数据 / 取数 | 行情返回空表，源码未做空表保护 | 先验证该代码能否取到数据 |
ValueError: attempt to get argmax of an empty sequence | 数据 / 取数 | 基准收益为空（较新版 pandas 上的表现） | 确认基准能联网取到 |
ValueError: Invalid frequency: A | 依赖 / 版本 | QuantStats 0.0.62 用了 pandas 已移除的频率别名 | 降低 pandas 版本，或改用无绘图路径 |
ValueError: at least one of the assets must have an expected return exceeding the risk-free rate | 数据 / 优化 | 优化器拿到的价格数据为空或全为常数 | 先解决取数，再谈优化 |
KeyError: 'Not an accepted rebalancing schedule' | 参数 | rebalance 字符串不在允许列表内 | 改用表内 14 个写法之一 |
KeyError: 'Date Range does not encompass rebalancing interval' | 参数 | 区间不足一个完整周期 | 拉长区间或缩短周期 |
KeyError: "the rebalance dates and start date doesn't match" | 参数 | 自定义日期表首列不等于 start_date | 让首列等于起点 |
AssertionError: Expected return method: ... not supported yet! | 参数 | expected_returns 传了白名单外的值 | 只填三个允许的方法名 |
AssertionError: Risk model: ... not supported yet! | 参数 | risk_model 传了白名单外的值 | 只填八个允许的方法名 |
ValueError: Weights and stocks lists must have the same length. | 参数 | 权重数量与标的数量不一致 | 逐项核对数量与顺序 |
最后三条是源码里显式写的校验信息，看到它们说明参数确实不合法，按提示改即可；而前面几条要么指向下游库、要么指向网络，属于「报错文字与根因不在同一层」的情况。
EigenLedger 装不上、import 不了怎么按顺序排除？
这一层的排查成本最低，也最容易被误判成「项目坏了」。
| 现象 | 排查顺序 | 判断依据 | 出处 / 备注 |
|---|---|---|---|
| pip 安装直接失败 | 看报错里出现的是哪个包名 | 报错包名就是缺构建工具的包 | 本站实测：fpdf 1.7.2 |
| 提示无法构建 wheel（PEP 517） | 确认是否需要编译依赖 | 社区历史记录中含 scs 构建失败 | issue #24 / #25 |
| import 时报缺模块 | 按报错里的模块名逐个补装 | 常见是传递依赖未声明 | 本站实测：pytz |
| Windows 安装报编译错误 | 确认 C++ 构建工具是否已装 | 官方 README 明确要求 | 官方 README |
| Mac M1 安装失败 | 换用 conda 或原生 ARM 解释器 | 社区报告过该平台问题 | issue #76 |
| Python 3.12 安装异常 | 降到 3.10 / 3.11 重试 | 社区报告版本探测组件失效 | issue #120 |
| 安装报错但信息很少 | 加 -v 重跑，或先单独装报错里的包 | 可定位到具体构建环节 | 通用做法 |
能导入 EigenLedger 但跑不出结果，问题在哪？
取不到数据时，报错不会说「网络问题」，而是抛出一个看起来像代码 bug 的异常。
| 现象 | 源码行为 | 怎么确认 | 处理方向 |
|---|---|---|---|
| 首只标的下不到数据 | 空价格表直接进入 assets.iloc[0] | 单独下载该代码并打印行数 | 换代码、换后缀或改用本地数据 |
| 提示某只标的初始状态不可用 | 首日价格为 NaN 即抛错 | 检查价格表首行是否有空值 | 把区间起点后移到数据齐全日 |
| 基准相关指标全是 NaN | 基准收益为空，回归无法进行 | 单独下载基准代码验证 | 换成可取的基准，或先解决可达性 |
| 提示数据源读取失败 | 历史版本曾依赖 pandas_datareader | 确认当前版本依赖链 | 升级用法，改用当前的数据获取方式 |
| 行情接口返回空数据 | 旧版 yfinance 与上游接口不匹配 | 与社区现象对照 | 注意：项目把 yfinance 钉在 <0.2，升级前需评估兼容性 |
| 饼图里出现未上市标的 | 缺失价格被填充为 1 后仍参与计算 | 核对标的上市日期与区间 | 调整区间或剔除该标的 |
本机实测结论：yf.download 返回 0 行时不抛异常，问题要到后续计算才暴露。因此「先单独下载一只标的、打印行数与首末日期」是这一步最有效的动作。相关社区记录见 issue #29、#131、#43。
EigenLedger 跑一半崩掉，为什么多半是依赖版本？
这个项目的依赖范围很窄，和「更新派」环境天然冲突。
| 报错 / 现象 | 冲突双方 | 为什么 | 处理方向 |
|---|---|---|---|
Invalid frequency: A | QuantStats 0.0.62 × pandas ≥2.2 | 旧的年度频率别名已被移除 | 降低 pandas 版本；或避免触发该绘图 |
monthly_heatmap() missing 1 required positional argument: 'benchmark' | QuantStats 版本 × 调用方式 | 函数签名变化导致参数不匹配 | 锁定 0.0.62 并避免混装其它版本 |
volatility() got an unexpected keyword argument 'trading_year_days' | QuantStats 新旧接口 | 参数在新版中被移除 | 按锁定版本对应的调用方式使用 |
TypeError: float() argument must be ... not 'DataFrame' | pandas 返回类型变化 | 单标的下载可能返回 DataFrame 而非 Series | 先在代码里统一类型再计算 |
| 字符串与时间戳比较报错 | 日期类型不统一 | 区间参数与数据索引类型不一致 | 统一成 YYYY-MM-DD 字符串 |
| 绘图后端报非法值 | matplotlib 环境变量 | 变量值带了多余空格 | 在代码里设置，不要手拼命令行字符串 |
| numpy 相关 ABI 报错 | numpy <2 约束 × 其它库要求 numpy≥2 | 二进制接口不兼容 | 为它单独建环境 |
参数写对了，EigenLedger 结果为什么仍不合预期？
这一层没有报错，只有「结果不对」，最难排查。
| 现象 | 可能原因 | 验证方式 | 处理方向 |
|---|---|---|---|
| 手填权重没生效 | 同时设了优化器，权重被覆盖 | 打印 pf.weights 看实际值 | 二者只留一个，或在报告里注明来源 |
| 单只标的组合报错 | 单标的走单独分支，行为与多标的不同 | 用两只标的复现对比 | 研究场景尽量避免单标的组合 |
| 指定 rebalance 后无法运行 | 周期名、区间长度或日期表起点不合规 | 对照三条例外信息逐项检查 | 见「再平衡机制」页的报错清单 |
| 优化器字符串写错但不报错 | 不在允许列表的值会被当作自定义优化器，构造期不校验 | 打印权重看是否等权 | 只使用四个大写关键字，或传真正的函数 |
| 再次分析同一对象结果不同 | 零权重标的会被就地删除，引擎对象被修改 | 打印 pf.portfolio 是否变短 | 复用前先深拷贝 |
| 结果每次都变 | 未写死 end_date，区间随当天生长 | 打印起止日期 | 显式固定两端日期 |
| 回测结束日期早于预期 | 启用了 risk_manager，序列被提前截断 | 对比设置前后的结束日期 | 分清「触发风控」与「数据缺失」 |
给 EigenLedger 维护者的最小复现应该包含什么？
项目处于低频维护状态，信息完整的 issue 更容易得到回应。
一条最小代码
只保留能复现问题的最少行数，去掉无关的自定义逻辑。
完整报错堆栈
包括最底层的异常类型与消息，不要只截最后一行。
环境版本
Python 版本 +
pip freeze中相关包的版本。数据与区间
标的代码、起止日期、是否使用本地数据。
使用的参数
optimizer、rebalance、benchmark、weights 的完整取值。
已尝试的做法
说明你排查过的步骤，避免重复建议。
| 排查需求 | EigenLedger 路线 | 本机技能路线 | 建议 |
|---|---|---|---|
| 本机依赖问题定位 | 需自己读堆栈与版本 | 可把报错贴进对话让技能协助判断 | 不确定方向时先问技能 |
| 数据是否可取 | 需自己写下载脚本验证 | 可由取数类技能直接验证 | 验证数据用技能更快 |
| 参数是否合规 | 可对照源码断言信息 | 可对照本站整理的白名单 | 两者结论一致 |
| 结果是否符合预期 | 需自己做区间与口径复核 | 可要求技能做交叉计算 | 重要结论建议双向核对 |
| 判断报错属于依赖还是参数 | 可对照本站四层排查表 | 可把报错贴进对话一起判断 | 两个方向的结论可以互相印证 |
| 复现同一故障给他人 | 需提供最小代码与环境版本 | 需提供对话上下文 | 报 issue 优先用脚本路线的最小复现 |
披露：本机技能目录已核验（29 个技能），EigenLedger 与 EasyClaw 无已证实集成；上表为排查场景的分工建议，不代表二者能互相调用。
关于报错排查的常见问题
报错里全是别的库的名字，怎么判断责任方？
按「谁抛出、谁缺依赖」判断：报错栈最底层的包是抛出方，但根因往往在上一层的调用参数或数据。经验做法是先把报错栈里涉及的包版本贴出来，再对照本站的版本冲突表；本项目把若干依赖钉在旧版本，冲突概率高于一般库，以官方实现为准。
所有问题都能靠降版本解决吗？
不能。降版本只对「依赖版本冲突」这一类有效；取数失败、数据首日为空、周期名写错这些问题降版本无效。先用「报错原文速查表」判断层级，再决定是否动版本，否则容易把环境改乱还找不到原因。
为什么取不到数据却不报「网络错误」？
因为数据层把「下载失败」与「下载成功但没有数据」都表现为空表，之后的计算才抛异常。本站实测中表现为 IndexError（新版 pandas）或 attempt to get argmax of an empty sequence（较旧 pandas）。因此看到这两类报错时，第一反应应该是「数据到手了吗」，而不是「算法错了吗」。
能靠升级 yfinance 修好取数吗？
不能直接升。发布包的约束是 yfinance <0.2，且新版 yfinance 默认不再返回名为 Adj Close 的列，源码里多处直接按该列名取值，升级会导致 KeyError 类问题。这对使用者意味着：在项目发新版之前，取数问题更现实的解法是换数据源并通过本地数据接入。
报错信息里出现「没有接受的再平衡调度」是什么意思？
这是源码里的固定提示，对应 Not an accepted rebalancing schedule，表示传入的周期字符串不在允许的 14 个写法内。它和「区间太短」「日期表起点不对」是三种不同的再平衡异常，三种的原始提示语都可以在本站再平衡页核对，以官方实现为准。
环境已经被改乱了怎么办？
删掉虚拟环境重建是最省时间的做法：这个项目的依赖组合（numpy<2、yfinance<0.2、ipython<8、quantstats 0.0.62）与常见新环境差异较大，逐个修依赖不如重建。重建时按本站安装页给出的顺序执行即可。
这些问题未来会修吗？
取决于项目是否继续发布新版本。当前 PyPI 最新版为 2024-10-28 发布的 2.1.6，仓库主分支在 2025-09 后仍有提交（含基准处理与 pandas 兼容改动），但两者源码已不一致，且 2026 年提交的社区 PR 未见合并。因此判断依据应以官方仓库的提交与发布记录为准，本文结论只代表 2026-09 的实测状态。