INSTALL · VERSION BOUNDARY
Optopsy 安装：先确认你的 Python 会装到哪一套代码
Optopsy 的 requires-python 是 >=3.12,<3.14。只有 Python 3.12 和 3.13 会装到官方文档描述的那一套；其余版本 pip 会静默地给你另一套同名包，API 完全不是一回事。
- 一句话结论：想用文档里那套 API，就用 Python 3.12 或 3.13。
- 别只看版本号：2.3.0 的包内部仍写着
__version__ = "2.2.0"。 - 软件免费，数据不一定：内置数据源需要 EODHD 的 Key，但你可以完全不用它。
- 许可要看清：GitHub 标注 AGPL-3.0，而老包是 GPL-3.0，两者不是一回事。
len(optopsy.__all__)：现代版 160pyproject.toml、两个 wheel 的实际内容与本机 pip 解析实测绘制的示意图；非官方流程图。INSTALL ROUTES
Optopsy 三条官方安装路径：装哪一层决定你能做哪一段
三条路径都是官方的，区别只在于你要不要数据下载能力和对话界面。先选层，再动手。
| 路线 | 命令 | 装出来是什么 | 额外依赖 | 前置条件 | 适用场景 | 注意点 |
|---|---|---|---|---|---|---|
| ① 核心库 | pip install optopsy | 策略 / 信号 / 模拟 / 风险指标，纯计算 | pandas、numpy、tabulate、pandas-ta-classic、empyrical-reloaded、pytz、pydantic、rich | Python 3.12–3.13；自备期权链数据 | 已经有 CSV 或 DataFrame，只想回测 | 不需要任何账号或 Key |
| ② 数据层 | pip install optopsy[data] | 上一条 + optopsy-data 命令与 Parquet 缓存 | 额外 pyarrow、requests、python-dotenv、yfinance | 同上；下载数据需 EODHD_API_KEY | 不想自己找数据，想一条命令抓 SPY 期权链 | EODHD 是第三方付费服务；缓存默认 ~/.optopsy/cache/ |
| ③ 界面层 | pip install optopsy[ui] | 上两条 + Chainlit 对话界面与工具集 | 额外 chainlit、litellm、sqlalchemy、plotly、aiosqlite 等 | 同上；对话需 LLM 的 API Key | 想用自然语言提需求、让模型调工具跑回测 | 默认模型是 Anthropic 的 Claude Haiku；也可配 OpenAI 系 |
| ④ 源码安装 | git clone 后 pip install -e . | 与核心库相同，但代码可改 | 同核心库 | 需要 git 与 Python 3.12+ | 想读源码、改策略、参与调试 | 仓库是平铺布局（optopsy/ 直接在根目录），不是 src 布局 |
| ⑤ 仅测试用 | pip install optopsy[data] + 仓库 tests/ | 53 个测试文件可跑 | pytest、pytest-cov | 需要仓库源码 | 想确认某个行为在你这台机器上是否一致 | 官方 pytest 配置默认带 --cov=optopsy，首次跑会慢 |
依据 pyproject.toml 的 dependencies / optional-dependencies / project.scripts，以及官方 getting-started、data、chat-ui 三页文档整理。
两个命令行入口
optopsy-data 负责下载与缓存数据；optopsy-chat 启动对话界面。两者是两个独立的 console script，装哪层就得到哪一个。README 只写了数据入口，对话入口只在官方 Chat UI 文档里出现。
装之前先看 Python
执行 python -V 确认。低于 3.12 或高于 3.13 时，pip 不会报错，只会给你另一套包——这一点在下一节的差异表里逐项列出。
不装 [data] 也完全可用
核心库不依赖任何外部数据服务。你完全可以把券商导出的期权链整理成 CSV，用 csv_data() 喂进去。这是本站推荐的国内起步方式。
STEP BY STEP
Optopsy 安装步骤：五步装对，从确认 Python 到喂进首份数据
每一步都给可复制命令与判断标准。第 4 步是本站加的自检——官方文档没有这一步，但它能立刻告诉你装对没装对。
示例代码取自官方 getting-started 文档的写法；本站未在 3.12+ 环境实跑（本机无 Python 3.12+），属源码级核验。
python -V只有 3.12.x 与 3.13.x 会装到官方文档描述的那一套。若输出低于 3.12 或高于 3.13，先别继续，读下一节的两套包差异。
预期输出：Python 3.12.7 之类的输出；版本不符时后续步骤的 API 都对不上
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activateOptopsy 带 pydantic、pandas-ta-classic 等依赖，装进全局环境容易与既有项目冲突。虚拟环境是零成本隔离。
预期输出：命令提示符出现 (.venv) 前缀
[data]）
pip install optopsy
# 或需要数据下载 CLI 时
pip install "optopsy[data]"首次安装会拉取 pandas、numpy 等依赖。[data] 会额外拉 pyarrow（用于 Parquet 缓存）。
预期输出：Successfully installed optopsy-2.3.0 ...
python -c "import optopsy as op; print(len(op.__all__)); print(hasattr(op, 'simulate'), hasattr(op, 'TargetRange'))"这是本站实测出来最可靠的判据：现代版 __all__ 有 160 项，且 simulate 与 TargetRange 都存在。legacy 包两项均不存在。不要用 op.__version__ 判断——2.3.0 的包里写的是 2.2.0。
预期输出：现代版输出 160 True True；legacy 包会报 AttributeError 或输出更小的数字
import optopsy as op
data = op.csv_data(
"options.csv",
underlying_symbol=0, option_type=1, expiration=2,
quote_date=3, strike=4, bid=5, ask=6, delta=7,
)
print(data.columns.tolist())
print(op.long_calls(data).head())注意 csv_data() 接收的是整数列索引（从 0 开始），不是列名。列顺序对不上就会得到错误的映射结果，而不是报错。
预期输出：打印出标准化列名，以及按 dte_range / delta_range 分组的统计表
预期输出的形状：默认返回的是按 DTE 区间与 Delta 区间分组的描述统计，列包括 dte_range / delta_range / count / mean / std / min / 25% / 50% / 75% / max。如果你拿到的是逐笔明细，说明传了 raw=True。
WHAT PIP ACTUALLY GIVES YOU
Optopsy 两套同名包的差异对比：官方资料没有的一张表
下面是本项目把两个 wheel 下载下来、逐文件比对得到的结果。它解释了「为什么我装的 Optopsy 跟文档不一样」。
| 对比项 | optopsy 2.3.0（Python 3.12–3.13） | optopsy 2.2.0（其余版本） | 对你的影响 |
|---|---|---|---|
| 包内模块数 | 76 个 .py（wheel 共 90 个条目） | 7 个 .py（wheel 共 13 个条目） | 老包连目录结构都不同 |
| 目录结构 | 拆分为 strategies/、signals/、data/、ui/ 等子包 | 单一 strategies.py 文件 | 你的 import 路径在老包下全部失效 |
| 策略函数 | 40 个（含比例价差、鹰式、Collar、cash_secured_put） | 30 个（无比例价差、无鹰式、无 Collar） | 老包缺的 10 个策略根本无法调用 |
| 入场信号系统 | 有 signals/ 子包，85 个信号工厂函数 | 完全没有 | 老包不能用 RSI / MACD 等过滤入场 |
| 模拟与组合 | 有 simulate()、simulate_portfolio() | 完全没有 | 老包出不了权益曲线 |
| 风险指标 | 12 个指标函数 + compute_risk_metrics() | 完全没有 | 老包只有基础描述统计 |
| 逐腿 Delta 类型 | 有 TargetRange、Commission、Signal 等类型 | 无这些导出类型 | 老包的参数结构与文档不一致 |
| 数据 CLI 与界面 | 有 optopsy-data 与 optopsy-chat | 两个入口都不存在 | [data] / [ui] 装了也起不来 |
包内 __version__ | "2.2.0"（滞后于发行号） | "2.0.3"（也滞后） | 两套包都不能靠 __version__ 判断 |
| 许可元数据 | wheel 里是 AGPL-3.0-or-later | wheel 里是 GPL-3.0-or-later | 两者网络服务条款不同，别混用 |
本机实测：pip download optopsy --only-binary=:all: --python-version <v> 覆盖 3.8–3.14 共 7 档；两套 wheel 的完整文件清单、METADATA 与 __init__.py 全文已落盘留档（采集 2026-09-23）。
为什么会这样？PyPI 上同时存在两个发布序列：较早的 2.2.0 允许 >=3.8，较新的 2.3.0 收紧为 >=3.12,<3.14。pip 会在候选里挑选与你当前解释器兼容的最高版本，于是版本一低就落到老包上。这是包管理器的正常行为，但对使用者是个陷阱——官方 README 只写「Python 3.12-3.13」，没有说清其余版本的后果。
COST AND LICENCE
Optopsy 要花多少钱、许可怎么算：软件与数据是两件事
软件：开源免费
核心库、数据层、界面层都在同一个开源仓库里，没有付费版。许可为 AGPL-3.0（GitHub API 标注），pyproject.toml 写的是 AGPL-3.0-or-later，PyPI 元数据的 license 字段反而为空——三处不一致，以仓库 LICENSE 原文为准。
数据：可能收费
内置数据源是 EODHD，需要它家的 API Key，属于第三方付费服务。但你可以完全不使用内置源：把券商导出的期权链整理成 CSV，用 csv_data() 喂进去即可，这条路零额外成本。
| 你打算怎么用 | 要不要花钱 | 要花钱的地方 | 许可约束 | 适用场景 | 注意点 |
|---|---|---|---|---|---|
| 本地研究 / 学习 / 写文章 | 不需要 | 无；自备数据即可 | AGPL-3.0 允许使用与修改 | 个人研究、教学、内部探索 | 仍受 AGPL 约束，二次分发要保留许可 |
| 用内置 CLI 抓美股期权链 | 需要 | EODHD 的 API Key（第三方计费） | 同上 | 想省去找数据的功夫 | 本机无法验证具体价格与额度，以 EODHD 官方为准 |
| 直接用对话界面 | 需要 | EODHD Key（要取数时）+ LLM 的 API Key | 同上 | 想用自然语言跑回测 | 默认模型是 Anthropic 的 Claude Haiku，可换成其他 OpenAI 兼容模型 |
| 自建网站对外提供回测服务 | 要看条款 | 服务器成本 + 数据成本 | AGPL 对网络服务有额外条款，务必读原文 | 面向他人提供服务 | 这类场景不是「随便用」，请先读 LICENSE 原文并咨询专业人士 |
| 内部二次开发后对外分发 | 要看条款 | 视数据源而定 | AGPL 的传染性与署名要求需逐条确认 | 把代码集成进自己的产品 | 本文不提供法律意见；以官方 LICENSE 为准 |
| 只读源码找思路，不部署 | 不需要 | 无 | 阅读与借鉴通常风险最小 | 学习期权回测的实现方式 | 但如果复制代码进入你的项目，仍要遵守许可 |
许可信息取自 GitHub API 的 license 字段、pyproject.toml、两个 wheel 的 METADATA 与官方 LICENSE 文件；费用信息仅为「是否需要第三方 Key」的结构性说明，具体价格以对应服务商为准。
本站是第三方撰写的中文研究笔记，不构成法律意见；涉及商用与对外服务时请以官方 LICENSE 原文与专业意见为准。
DATA SOURCES AND NETWORK
Optopsy 数据从哪来：数据源来源清单与国内可行性
安装只是开头一步，真正卡住多数人的是数据。下面是官方文档列出的数据来源，以及本站对国内可用性的判断。
| 数据源 | 与 Optopsy 的关系 | 需要什么 | 国内可用性的现实情况 | 注意点 |
|---|---|---|---|---|
| EODHD（美股期权 API） | 内置：optopsy-data 直接对接 | EODHD_API_KEY | 属于境外服务，能否访问与计费方式需自行确认 | 本站未核验其价格与额度 |
| 券商导出（Schwab / IBKR / Tastytrade 等） | 非内置，但官方在文档里点名可行 | 你的券商账号与历史数据导出 | 有境外券商账户的用户可行 | 导出文件的列顺序需与 csv_data() 的索引参数对齐 |
| CBOE DataShop | 非内置，官方点名 | 按数据付费购买 | 需境外支付渠道 | 官方渠道数据，但成本通常较高 |
| HistoricalOptionData.com | 非内置，官方点名 | 购买；官方称有免费样例 | 需境外支付渠道 | 适合先小样验证流程 |
| Polygon.io | 非内置，官方点名 | API Key | 属于境外服务 | 官方文档只点名，未提供内置对接 |
| 中国 A 股期权数据 | 官方未提供 | — | 官方数据源清单里没有 A 股 | 引擎本身不限定市场，只要字段满足契约就能用；数据要自己解决 |
| 自建 CSV（任何来源） | 官方支持的基座 | 一份满足 8 列契约的表 | 最可行的路径：不依赖任何境外服务 | 列顺序与 delta 列是本步的关键 |
官方数据源清单来自文档的 Data Sources 一节；「国内可用性」一列是本站基于「是否依赖境外服务与支付渠道」的判断，不是官方声明。
关于 pip 镜像
安装本身走 PyPI，通常配合国内镜像即可顺利完成。真正的网络门槛在数据获取，不在装包。若你只是想先跑通流程，自建 CSV 是绕开网络问题的最短路径。
关于缓存
数据层会把下载结果存成 Parquet，默认位于 ~/.optopsy/cache/，按 options/ 与 stocks/ 分目录。重复下载只补缺口：官方说明内部空缺超过 5 个自然日会触发该区间重取，历史数据不做过期处理。
INSTALL TROUBLESHOOTING
Optopsy 安装阶段六类真实卡点与处置
按你看到的原文对号入座。前两类是本站实测出来的，官方文档没有覆盖。
| 你看到的现象 | 真实原因 | 怎么确认 | 怎么修 |
|---|---|---|---|
装上了，但 op.simulate 或 op.rsi_below 报 AttributeError | Python 不在 3.12–3.13，装到了 2.2.0 那套老包 | python -c "import optopsy as op; print(len(op.__all__))"，现代版是 160 | 换用 Python 3.12 或 3.13 建虚拟环境后重装 |
optopsy.__version__ 显示 2.2.0，但 pip 说装的是 2.3.0 | 2.3.0 的包内部版本号没有跟着更新，属于官方包自身的滞后 | 比对 pip show optopsy 的 Version 与 op.__version__ | 不用修；判断版本请用 len(op.__all__) 或 hasattr(op, 'simulate') |
pip install "optopsy[ui]" 很慢或依赖冲突 | 界面层会拉 Chainlit、LiteLLM、SQLAlchemy、plotly 等一大堆包 | 看 pip 输出里被解析的依赖数量 | 只做回测就装核心库；确实要界面时单独建虚拟环境 |
optopsy-data download SPY 报错或没有输出 | 没有配置 EODHD 的 Key，或网络不可达 | 确认环境变量 EODHD_API_KEY 是否设置 | 配置 Key 后重试；或放弃内置源，改用自建 CSV 走 csv_data() |
load_cached_options() 报缺 pyarrow | 只装了核心库，没有装 [data] | 看报错是否提到 pyarrow / parquet | pip install "optopsy[data]" |
导入就报 ModuleNotFoundError: optopsy | 装到了另一个解释器或另一个虚拟环境 | python -c "import sys; print(sys.executable)" 与 pip -V 是否指向同一环境 | 同一环境内重新安装；避免混用 python 与 python3 |
前两项来自本机 pip 解析与 wheel 内容实测；后四项依据官方文档的依赖说明与常见 Python 环境问题整理。
FAQ
Optopsy 安装常见问题
Optopsy 支持哪些 Python 版本？
pyproject.toml 与 PyPI 元数据都写 >=3.12,<3.14，也就是 3.12 与 3.13。低于 3.12 或 3.14 及以上，pip 会装到 PyPI 上的另一套 2.2.0。以官方仓库为准。
我用 Python 3.11，能不能凑合用？
能装上，但拿到的是另一套代码：只有 7 个模块、30 个策略函数，没有信号系统、没有 simulate()、没有逐腿 Delta 类型。官方文档里的 API 在那套包上基本都不可用。本站实测结论如此。
装的 Optopsy 要钱吗？
软件不要钱（AGPL-3.0 开源）。但内置数据源 EODHD 需要第三方 API Key，属于付费服务。你可以完全不用它——自备期权链 CSV 用 csv_data() 加载即可。
pip install optopsy 和 optopsy[data]、optopsy[ui] 有什么区别？
核心库只做策略、信号、模拟与指标计算；[data] 增加数据下载 CLI 与 Parquet 缓存；[ui] 再增加 Chainlit 对话界面。不需要的能力就别装，能显著减少依赖冲突。
怎么确认我装对了？
跑 python -c "import optopsy as op; print(len(op.__all__), hasattr(op,'simulate'), hasattr(op,'TargetRange'))"。现代版输出 160 True True。不要用 op.__version__——2.3.0 的包内部写的是 2.2.0。
AGPL-3.0 对我做网站有影响吗？
AGPL 针对网络服务有额外条款，与 MIT 这类宽松许可不同。如果你打算拿它对外提供服务，请先读官方 LICENSE 原文，并咨询专业人士。另外要注意早期 2.2.0 那套包是 GPL-3.0，与 2.3.0 的 AGPL 不是同一个许可。本文不提供法律意见。
装 Optopsy 和自己用 EasyClaw 技能，先做哪个？
如果你只是想先拿到行情、算几个指标、画张图，本机技能路线不需要配 Python 环境，门槛更低。如果你要做的是期权链级的策略回测（逐腿 Delta 选股、权益曲线、早退与滑点），那就得自己装 Optopsy——本机技能目录里没有对等的能力。两条路线的逐项分工见导航的「对比」页。