EigenLedger 安装有哪几步实测失败？
环境：Windows + Python 3.11.9 + pip 26.2.1，全新虚拟环境，2026-09-23 实测。
| # | 执行的操作 | 实测结果 | 根因 |
|---|---|---|---|
| 1 | pip install EigenLedger | 失败：metadata-generation-failed，构建 fpdf 1.7.2 时报 error: invalid command 'bdist_wheel' | 该依赖只有源码包，新版 pip 的隔离构建环境不再预装 wheel |
| 2 | 先 pip install wheel 再重试 | 成功：装上 EigenLedger 2.1.6 及全部传递依赖 | 补上了构建工具 |
| 3 | import EigenLedger | 失败：ModuleNotFoundError: No module named 'pytz' | 传递依赖 yfinance 0.1.96 需要 pytz，但项目依赖清单里没有它 |
| 4 | pip install pytz 后再导入 | 成功：Engine、portfolio_analysis 均可导入 | 补齐隐式依赖 |
| 5 | 跑 README 的快速开始（联网取数） | 失败：IndexError: single positional indexer is out-of-bounds | 行情接口返回 0 行，源码在 wts/assets.iloc[0] 处没有空表保护 |
| 6 | 改用本地数据（data=）跑分析 | 部分成功：17 项指标算出来了，但随后在绘图阶段抛 ValueError: Invalid frequency: A | pip 解析出 pandas 3.0.6，而 QuantStats 0.0.62 仍在用已被移除的 "A" 频率别名 |
| 7 | 把 pandas 降到 2.1 后重跑 | 失败点前移：在取基准收益时抛 ValueError: attempt to get argmax of an empty sequence | 基准始终联网取数（即使已传 data=），本机取不到行情时必然失败 |
| 8 | optimizer="EF" 构造引擎 | 失败：ValueError: at least one of the assets must have an expected return exceeding the risk-free rate | 优化器在构造期就取数，取不到数据后交给 PyPortfolioOpt，报出的是下游错误 |
| 9 | rebalance="monthly" 构造引擎 | 成功：打印出 45 列再平衡权重表 | 无优化器时不需要行情，逐期沿用同一组权重 |
第 6 步的指标数值来自本站合成的价格序列（几何随机游走），只用于验证代码能否跑通，不代表任何真实标的的收益，也不构成任何投资参考。第 7 步说明：降 pandas 版本并不会让流程跑通，只是把失败点从绘图阶段前移到基准取数阶段——真正卡住的是「基准必须联网」这件事。
EigenLedger 按什么顺序装能一次装完？
顺序很重要：先给构建工具，再装库，最后处理运行时依赖。
建独立虚拟环境
python -m venv venv后激活。这个库把 numpy 钉在 <2、yfinance 钉在 <0.2，装进全局环境容易和别的项目打架。先装构建工具 wheel
pip install wheel。不装它，下一步会在编译 fpdf 时失败——这是本次实测的第一步报错。安装 EigenLedger
pip install EigenLedger。此时会连带装上 QuantStats 0.0.62、PyPortfolioOpt 1.6.0、yfinance 0.1.96 等。补齐 pytz
pip install pytz。缺它则import EigenLedger直接失败，而报错信息指向 yfinance，容易误判。确认能访问行情接口
发布版 2.1.6 的基准收益始终联网获取，即使你已传入本地数据表。取不到行情时，分析会在基准环节失败，报错信息与网络无关，容易误判。
先用本地数据验证组合链路
用一张本地价格表（
data=）验证「组合收益 → 指标表」这段逻辑是对的，再把基准问题单独解决。这样能把「代码问题」和「数据可达性问题」分开。
EigenLedger 一共钉住了哪些依赖版本？
下面的约束来自发布包元数据，是「同一环境里能不能和别的库共存」的判断依据。
| 依赖 | 发布包中的约束 | 本次实测解析结果 | 影响 |
|---|---|---|---|
| numpy | >=1.21.0,<2.0.0 | 1.26.4 | 与要求 numpy≥2 的新库无法共存 |
| pandas | 未声明 | 3.0.6 | 没有上界约束，会被解析到最新版，触发绘图报错 |
| quantstats | >=0.0.62,<0.0.63 | 0.0.62 | 只能装 0.0.62，该版本与新版 pandas 不兼容 |
| yfinance | >=0.1.0,<0.2.0 | 0.1.96 | 旧版取数接口与上游行情服务已不匹配 |
| pyportfolioopt | >=1.4.0,<2.0.0 | 1.6.0 | 优化器实现来源，报错信息常来自它 |
| fpdf | >=1.7.2,<2.0.0 | 1.7.2 | PDF 分支依赖；只有源码包，是安装失败的直接原因 |
| matplotlib | >=3.4.0,<4.0.0 | 3.11.2 | 绘图后端无显示环境时需手动切到 Agg |
| ipython | >=7.16.0,<8.0.0 | 7.34.0 | 被钉在 7.x，与已升级到 8.x 的环境冲突 |
| pytz | 未声明 | 需手工安装 | 本次实测中导致导入失败 |
注意「Python 版本」声明：发布元数据写的是 requires_python >=3.0，分类器却列出 3.4 到 3.13。这两个说法都没有实际鉴别力，请以你自己实测的 Python 版本为准（本站用 3.11.9）。
不同平台装 EigenLedger 会遇到什么问题？
社区 issue 里反映的问题分布很有规律。
| 平台 / 环境 | 典型问题 | 来源 | 处理方向 |
|---|---|---|---|
| Windows | 官方 README 要求先装 C++ 构建工具 | 官方 README | 装 Visual Studio Build Tools 后再 pip |
| macOS | 官方 README 要求装 Xcode 命令行工具 | 官方 README | 先 xcode-select --install |
| Mac M1（ARM） | 社区 issue 记录过安装失败 | issue #76 | 优先用 conda 或原生 ARM 版 Python 重建环境 |
| Python 3.12 | 社区 issue 记录过版本探测组件失效 | issue #120 | 改用 3.10 / 3.11 更稳 |
| Colab / Notebook | 官方推荐环境，出图与显示最顺畅 | 官方 README | 适合先跑通，再迁到本地 |
| 无显示的服务器 | 绘图会因缺少后端报错 | 源码依赖 matplotlib | 导入前设 MPLBACKEND=Agg，并注意变量值不要带多余空格 |
| 受限网络（无法访问境外行情） | 取数返回空表，随后抛 IndexError | 本站实测 | 改用本地数据，或换用可用的数据源 |
怎么确认 EigenLedger 真的能用了？
导入成功不等于能出报告，按这四步逐级验证。
| 验证级别 | 目的 | 通过标准 | 不过时的含义 |
|---|---|---|---|
| 1. 能导入 | 排除缺依赖 | import EigenLedger 无异常 | 缺 pytz 之类的隐式依赖 |
| 2. 能构造 | 排除参数与取数问题 | Engine(...) 返回对象且权重合理 | 若用了优化器，多半是取数失败 |
| 3. 能算指标 | 排除数据与库版本问题 | 打印出 17 行指标表 | 数据表结构或首日空值问题 |
| 4. 能出图 | 排除绘图依赖问题 | 图正常显示或落盘 | pandas 过新或绘图后端未设置 |
| 5. 能出 PDF | 排除字体与缺图问题 | report=True 生成文件且中文可读 | 字体未注册或 rvol.png 缺失 |
| 6. 能重跑 | 排除隐性状态 | 同参数两次运行结果一致 | 未写死 end_date，或数据源已变化 |
第 3 级通过、第 4 级失败是本次实测遇到的情况：portfolio_analysis() 会在算完指标后继续绘图，绘图抛错会中断整个函数，导致你拿不到返回值。这也是「指标都算出来了却白跑一场」的原因。
不想装 EigenLedger 的环境，还有哪些路？
把「装依赖」这件事的成本摊开看，选择会更清楚。
自己装 EigenLedger
- 需要在虚拟环境里装 5～8 个包，其中 2 个要手工补
- 依赖版本冲突会以底层报错形式出现，排查成本高
- 优点：结果可复现、可脚本化、可批量
- 缺点：环境会随依赖升级失效
用本机技能
- 无本地 Python 环境要求，取数与出图由技能完成
- 以自然语言提问，不需要理解参数体系
- 优点：上手快，适合一次性查询与快速判断
- 缺点：结论留痕与批量复现弱于脚本
| 判断维度 | Python 脚本路线 | 本机技能路线 | 建议 |
|---|---|---|---|
| 首次可用时间 | 本次实测需 4 步才导入成功 | 对话即用 | 急着要结论选技能路线 |
| 环境维护 | 需要自己维护虚拟环境与版本 | 由本机统一维护 | 不想维护选技能路线 |
| 批量与自动化 | 脚本化能力强 | 偏交互 | 批量场景选脚本 |
| 结果可复现 | 固定依赖版本即可复现 | 依赖对话上下文 | 正式研究选脚本 |
| 指标口径透明度 | 可直接读源码核对 | 取决于各技能实现 | 需要审计口径选脚本 |
披露：本机技能目录已核验（29 个技能），EigenLedger 与 EasyClaw 无已证实集成，上表只比较两条路线的工作方式，不代表二者数据或结论一致。
装完之后，先用哪几条命令自检？
把下面六条按顺序跑一遍，能把「环境问题」与「代码问题」分开。
| 顺序 | 命令 | 看什么 | 不符合预期时先查什么 |
|---|---|---|---|
| 1 | python -V | Python 版本 | 建议 3.10 / 3.11；3.12+ 有历史问题记录 |
| 2 | pip list | 关键包版本是否齐全 | 是否缺 pytz、wheel，pandas 是否过新 |
| 3 | python -c "import EigenLedger" | 能否导入、有无缺模块 | 报错里的模块名就是要补装的包 |
| 4 | 构造一个不设优化器的 Engine | 参数校验是否通过 | 权重长度、日期格式、白名单取值 |
| 5 | 打印 pf.weights | 权重是否符合预期（等权或手填） | 是否误传了优化器与 weights 同时存在 |
| 6 | 用本地数据跑一次 portfolio_analysis | 指标表能否打印出来 | 数据表首行是否有空值、列名是否匹配 |
| 7 | 记录 pip freeze 输出 | 环境快照是否留档 | 没有快照就谈不上复现 |
第 6 条是分水岭：能打印出 17 行指标表，说明取数、权重、指标三条链路都通了；卡在这一步通常是数据问题而不是库的问题，具体见「真实报错排查」页。
关于安装的常见问题
为什么 pip install 会直接失败？
本次实测的失败点是依赖 fpdf 1.7.2：它只提供源码包，而新版 pip 的隔离构建环境不再预装 wheel，于是报 invalid command 'bdist_wheel'。先执行 pip install wheel 再安装即可通过这一步。不同 pip 版本的报错文字可能不同，但根因相同，以你的实际输出为准。
装完了 import 还是报错怎么办？
本次实测报的是 ModuleNotFoundError: No module named 'pytz'。原因是 yfinance 0.1.96 需要 pytz，而项目的依赖清单没有声明它。执行 pip install pytz 即可。报错堆栈指向 yfinance 时不要去找 yfinance 的问题，先看「缺哪个包」。
一定要用 conda 吗？
不必须。官方 README 只要求 Windows 装 C++ 构建工具、macOS 装 Xcode 命令行工具。本站用标准 venv 完成了安装。若你的平台在编译科学计算包时反复失败，用 conda 取预编译包会更省事，以官方 README 为准。
能不能在同一个环境里和别的量化库共存？
风险较高。这个库把 numpy 钉在 <2、yfinance 钉在 <0.2、ipython 钉在 <8、quantstats 钉在 0.0.62，任何要求 numpy≥2 或新版 yfinance 的库都会与它冲突。建议为它单独建环境。
为什么指标算出来了却没有结果对象？
portfolio_analysis() 是「算指标 → 绘图 → 返回结果」一条线。绘图抛异常时函数直接中断，返回值拿不到。本次实测就是在绘图阶段因 pandas 频率别名问题中断的。想先拿指标，可在异常前自行捕获，或先把 pandas 版本降到兼容档，以官方实现为准。
无显示器的服务器上怎么跑？
需要在导入库之前把 matplotlib 后端切到 Agg。注意环境变量值不要带多余空格（MPLBACKEND=Agg 会直接报「不是合法后端」）——这是本站实测踩到的一个真实坑，建议在代码里设置而不是在命令行拼字符串。
这些依赖版本以后会自动变好吗？
取决于项目是否发新版。本项目的 PyPI 最新版是 2024-10-28 发布的 2.1.6，而仓库主分支在 2025-09 之后仍有提交，两者源码并不一致。也就是说：pip 装到的版本比 GitHub 主分支旧，安装体验不会自动改善，以官方仓库与发布记录为准。