OPTION STRATEGY BACKTESTING · PYTHON
Optopsy：期权链级回测与统计的 Python 库
把「45 DTE 的 SPX 铁鹰，50% 止盈 + 2 倍止损，与持有到期比谁更好」这类问题，从手工表格变成几秒钟的分组统计与权益曲线。它作用在期权链上，而不是股票日线上。
- 40 个策略工厂：官方文档写「38 个」，源码
__all__实际导出 40 个。 - 逐腿 Delta 选股：每个腿独立用
TargetRange(target, min, max)定行权价。 - 85 个入场信号：RSI、MACD、布林带、ATR、IV Rank 等，跑在股票数据上。
- 一条前置红线：你的 Python 版本决定了 pip 会装到哪一套代码。
Optopsy 项目来源
goldspanlabs/optopsy · Python · AGPL-3.0
约 1.48k Star / 228 Fork（采集 2026-09-23，数字会随社区变化）
查看源码 ↗
WHAT IT SOLVES
Optopsy 它解决什么问题：期权研究的三个真实卡点
期权研究卡住的通常不是想法，而是「把想法变成一批可比较的交易」这件事。Optopsy 的定位正好落在这一步。
| 卡点 | 手工做法 | Optopsy 的做法 | 适用场景 | 注意点 |
|---|---|---|---|---|
| 行权价怎么定 | 凭感觉挑固定价位，换个标的就不成立 | 每腿按 Delta 目标选，配合可接受区间 | 要跨标的、跨年份比较同一套规则 | 数据里必须有 delta 列，否则任何策略都跑不起来 |
| 到期日怎么定 | 每笔单独记，无法按 DTE 分桶 | max_entry_dte / exit_dte 统一约束，再按区间分组 | 想知道哪一段 DTE 表现更稳 | 默认 exit_dte=0（持有到期），日历/对角默认是 7 |
| 成交价不现实 | 用中间价或收盘价，回测偏乐观 | 四档滑点模型（mid / spread / liquidity / per_leg） | 想评估策略对滑点的敏感度 | liquidity 模式需要数据里有 volume 或 open_interest |
| 结果只有均值 | 得到一串数字，说不清风险 | 分组统计 + simulate() 权益曲线 + 12 个风险指标 | 要做策略筛选和汇报 | 指标口径（年化因子、空数据返回值）以源码为准 |
| 策略太多 | 自己写每个组合的腿配对逻辑 | 40 个内置策略工厂，直接调用 | 快速横向比较多类策略 | Covered/Collar 类传真实股票数据更准，否则用合成深度实值 call 代替 |
| 早晚要退出 | 只有到期结算一种口径 | stop_loss / take_profit / max_hold_days 三件套 | 想做止盈止损的敏感性测试 | 三个参数有符号约束：止损必须负数、止盈必须正数 |
依据：官方 README、docs/parameters.md、docs/getting-started.md 与仓库源码（采集 2026-09-23）。这是研究工具，不做下单、不做推荐。
HOW IT WORKS
Optopsy 怎么工作：四步从期权链到结论
整条链路只有四步，理解这四步就能判断自己手上的数据能不能用。
csv_data() 按整数列索引映射成标准列simulate() 输出权益曲线依据官方文档与 optopsy/ 源码绘制的结构示意图；非官方流程图。
输入是期权链，不是日线
每条记录是「某个标的、某个报价日、某个到期日、某个行权价的一张期权」，最少 8 列。缺 delta 会让所有策略直接无效，这是新手最容易踩的常见坑之一。
产出是 DataFrame
默认返回按 DTE 与 Delta 区间分组的描述统计（count / mean / std / min / 25% / 50% / 75% / max）；raw=True 时返回逐笔明细，方便你接自己的分析流程。
三档安装，按需选
核心库只有 pandas / numpy 等基础依赖；[data] 加数据下载 CLI；[ui] 再加一个 Chainlit 对话界面。不需要什么就装什么，避免拉一堆用不上的包。
MODULES AT A GLANCE
Optopsy 三层结构速览：核心库、数据 CLI、对话界面各给什么
Optopsy 的 pyproject.toml 把能力拆成三层，装哪一层决定了你能做哪一段工作。
| 层 | 安装命令 | 提供什么 | 真实入口 | 前置条件 | 适用场景 | 注意点 |
|---|---|---|---|---|---|---|
| 核心库 | pip install optopsy | 策略、信号、模拟、风险指标 | import optopsy as op | Python 3.12–3.13；自备期权链数据 | 已有一份期权链 CSV/DataFrame，想直接回测 | 这一层不依赖任何外部数据源 |
| 数据层 | pip install optopsy[data] | 下载与缓存历史行情/期权链，Parquet 缓存 | optopsy-data CLI | 额外装 pyarrow / requests / yfinance；下载需 EODHD_API_KEY | 不想自己找数据，希望一条命令抓到 SPY 期权链 | 内置源是 EODHD，属于第三方付费服务；缓存默认落在 ~/.optopsy/cache/ |
| 界面层 | pip install optopsy[ui] | Chainlit 对话界面 + 工具集，含数据层 | optopsy-chat | 额外装 Chainlit / LiteLLM 等；需 LLM 的 API Key | 想用自然语言提需求、让模型调工具跑回测 | 默认模型是 Anthropic 的 Claude Haiku；对话记录与结果默认存本地 |
依据 pyproject.toml 的 [project.optional-dependencies]、[project.scripts] 与官方 data / chat-ui 文档整理。
README 只写了前两层，第三层（对话界面）只在官方 Chat UI 文档里描述——这是官方资料的一处不对称。
SETUP AND ROUTE
Optopsy 安装与路线：先确认你会装到哪一套代码
这是本站最想让你先看的一条。Optopsy 在 PyPI 上的最新版是 2.3.0，它的 requires-python 是 >=3.12,<3.14。如果你的 Python 不在这两个版本里，pip 会静默地给你另一套同名包（2.2.0），而那套包的 API 与官方文档描述的完全不是一回事——没有信号、没有模拟器、没有逐腿 Delta。
| 你的 Python | pip 实际装到的版本 | 你拿到的是什么 | 官方文档的写法还成立吗 |
|---|---|---|---|
| 3.8 – 3.11 | optopsy 2.2.0 | 另一套老代码：仅 7 个模块、30 个策略函数、包内版本号写着 2.0.3 | 不成立：simulate()、TargetRange、信号函数都不存在 |
| 3.12 – 3.13 | optopsy 2.3.0 | 官方文档描述的那一套：76 个模块、40 个策略、85 个信号、模拟器与风险指标 | 成立 |
| 3.14 及以上 | 回到 optopsy 2.2.0 | 又变回那套老代码（2.3.0 的上界把 3.14 排除在外） | 不成立 |
本机实测：对每个版本执行 pip download optopsy --only-binary=:all: --python-version <v>，7 档全部返回可下载包；另比对两个 wheel 的实际文件清单与 __init__.py 内容（采集 2026-09-23）。
为什么要单独提醒
这类「装上了但 API 不对」的问题，报错通常出现在你调用 op.simulate() 或 op.rsi_below() 的那一刻，而不是安装那一刻。新手容易先怀疑自己的代码，实际是包不对。
怎么确认自己装对了
装完先跑一行 import optopsy; print(len(optopsy.__all__))：现代版是 160，legacy 版远小于此。注意不能只看 optopsy.__version__，因为 2.3.0 包里写的仍是 2.2.0。
LOCAL SKILL ROUTE
Optopsy 免部署路线：EasyClaw 本机技能能覆盖哪些任务
如果你并不想先配 Python 环境，只想先拿到行情、算几个指标、出一张图，本机的 EasyClaw 技能目录里已经有能用的工具。这里如实说明它们各自覆盖到哪一步，以及它们不做什么。
| 本机技能 | 它负责什么 | 在期权研究链路里的位置 | 前置条件 | 注意点 |
|---|---|---|---|---|
| akshare-finance | 股票 / 期货 / 期权 / 基金等金融数据 | 取数据（含期权类数据） | 无需 API Key | 数据口径来自 AKShare，与 EODHD 不是同一套字段 |
| tushare-finance | 220+ 个 Tushare Pro 数据接口 | 取 A 股行情与财务数据 | 需要 TUSHARE_TOKEN | 接口权限与积分挂钩 |
| quant-analyst | 策略建模与回测方法论、风险指标、组合优化 | 提供「怎么评估」的方法与检查清单 | 无 | 是方法论文本，不替代可执行的期权链回测引擎 |
| stock-technical-mastery | MACD / RSI / 布林带 / 均线 + K 线形态 | 指标计算与形态识别 | 无 | 覆盖 A 股，不含港股/美股/期货 |
| chart-image | 从数据生成 PNG 图表（折线/柱状/K 线/热力图等） | 把结果画出来 | 首次需 npm install | 只负责出图，不负责算指标 |
| yahoo-finance-github | 美股实时报价、历史 K 线、新闻 | 美股侧的数据补充 | 无需 Key | 明确不支持 A 股与港股 |
| stock-monitor-skill-0-1-0 | 7 类预警规则（成本盈亏/均线/RSI/量能/跳空/止盈） | 持仓后的持续盯盘 | 需配置监控清单 | 不自动下单，不生成投资建议 |
依据本机 .easyclaw/skills/ 目录下各技能 SKILL.md 逐项核验（采集 2026-09-23）。这些技能能在目录里查到，不等于已安装、已授权或已在本机跑通。
边界必须说清楚：上述技能链路可以覆盖「取数据 → 算指标 → 出图 → 筛选与监控」。它们不提供期权链级的策略回测引擎——没有 40 个策略工厂、没有逐腿 Delta 选股、没有 simulate() 权益曲线、没有早退规则与滑点模型。两者是任务分工不同，不是互相替代。
Optopsy 自身不在 EasyClaw 技能目录中，与 EasyClaw 无已证实集成。
下面两张是本机技能路线的实际对话截图，用来说明「不配环境、一句话提问」这条路上手能拿到什么。它们展示的是技能路线自己的任务，与 Optopsy 的回测流程无关。
逐项任务分工、前置条件与不适合场景的完整对照，见顶部导航的「对比」页。
WHO FITS
什么情况下 Optopsy 合适，什么情况下别用
适合
你手上已经有一份期权链历史数据（自己买的、券商导出的、或者愿意接 EODHD），想按 Delta 规则成批回测某个具体策略，并且需要按 DTE 与 Delta 区间分组的结果分布。你会写一点 pandas，不介意自己管环境。
不适合
你要的是全市场自动选股、实时信号推送、或者实盘下单——这些不在它的职责范围内。你只想要一份现成的 A 股期权链数据源，官方也没有提供（内置源是面向美股的 EODHD）。你需要严格的开源许可宽松度时，也要先读 AGPL 条款。
| 你想做的事 | Optopsy 是否对口 | 更该看什么 |
|---|---|---|
| 按 Delta 规则批量回测某个期权策略 | 对口 | 策略手册 → 逐腿 Delta → 期权链契约 |
| 比较不同 DTE 区间、不同止损止盈的表现 | 对口 | 模拟与绩效（simulate() + 早退参数） |
| 把技术指标作为入场条件过滤期权交易 | 对口 | 入场信号（信号跑在股票数据上） |
| 拿到现成的 A 股期权链历史数据 | 不对口 | 官方数据源清单里没有 A 股；考虑自备 CSV 走 csv_data() |
| 自动选股 / 定时盯盘 / 消息推送 | 不对口 | 这属于另一类工具的任务；本机技能路线里有盯盘类技能 |
| 期权定价与希腊字母求解 | 不对口（这个库不做定价） | 它消费数据里的 Greeks，不自己算定价；需要定价请用专门的定价库 |
| 直接连券商实盘下单 | 不对口 | 本项目只做回测与统计 |
《你想做的事》一列依据官方文档与源码能力边界整理；「不对口」的判断同样是结论，不要绕过。
开源许可：GitHub API 标注为 AGPL-3.0，pyproject.toml 写 AGPL-3.0-or-later，而 PyPI 元数据的 license 字段为空。做网络服务前请先读官方 LICENSE 原文，本文不提供法律意见。
LIMITATIONS
Optopsy 限制与披露：本站验证到哪一步，没验证什么
把边界写清楚比多写一段赞美有用。下面是本站的验证状态，请按这个粒度理解全站内容。
| 项目 | 本站验证到哪一步 | 你应该怎么理解 | 注意点 |
|---|---|---|---|
| 仓库事实（版本 / Star / 许可 / 文件结构） | 已核验：读官方 README 原文、PyPI 元数据、GitHub API、克隆源码逐文件核对 | 可以直接引用 | Star / Fork 等数字会变化，已标采集日期 |
| pip 在不同 Python 上装到什么 | 本机实测：对 3.8–3.14 七档执行 pip 解析并比对 wheel 内容 | 可以直接引用，且这是本站最独特的证据 | 结果取决于 PyPI 当时的版本，版本更新后需复跑 |
| 2.3.0 的实际运行行为 | 未实测：本机没有 Python 3.12+，无法安装现代版 | 相关结论均为源码级核验，代码示例标注为官方文档示例 | 不要把本站示例当成「本站跑出来的结果」 |
| 回测收益 / 胜率 / 绩效数字 | 不作任何断言 | 本站不提供收益结论 | 官方免责声明明确：结果基于历史数据与简化假设，不代表未来 |
| 与 EasyClaw 的集成状态 | unverified：Optopsy 不在本机技能目录中 | 本机技能路线是「另一条可选路线」，不是集成证据 | 全站均按此口径披露 |
| 姊妹项目 optopsy-mcp | 未核验：仅见 README 自述 | 引用时已标注为官方自述 | 该仓库源码与可用性本站未验证 |
本站是第三方撰写的中文研究笔记，不是 Optopsy 官方文档；一切以实现与官方文档为准。
FAQ
Optopsy 常见问题（回答都带证据边界）
Optopsy 是什么？一句话能不能说清？
一句话：它是作用在期权链数据上的 Python 回测与统计库——用逐腿 Delta 规则选出具体合约、按 40 个内置策略组合腿、算出分组统计或权益曲线。它不是交易系统，也不是选股工具。以官方 README 与源码为准。
Optopsy 免费吗？
软件本身开源免费，许可为 AGPL-3.0（GitHub API 标注；pyproject.toml 写 AGPL-3.0-or-later，PyPI 元数据的 license 字段为空）。但数据可能不免费：内置数据源是 EODHD，需要它家的 API Key；你也可以完全不用内置源，自己提供 CSV。AGPL 对网络服务有额外条款，商用前请读官方 LICENSE 原文，本文不构成法律意见。
为什么我 pip 装完发现 API 跟文档不一样？
大概率是版本解析问题：requires-python 是 >=3.12,<3.14，只有 3.12 和 3.13 会装到官方文档描述的那一套（2.3.0）。3.8–3.11 以及 3.14 及以上会装到 PyPI 上的另一套 2.2.0，那套包只有 7 个模块、30 个策略函数，没有 simulate() 与信号系统。这是本站实测的 pip 行为，详见安装与版本页。
我需要准备什么样的数据？
一份期权链数据，至少包含 underlying_symbol / option_type / expiration / quote_date / strike / bid / ask / delta 这 8 列，delta 是硬性要求。用 csv_data() 加载时要注意它按整数列索引（从 0 开始）映射列，而不是按列名。字段细节见期权链契约页；以官方 getting-started 文档为准。
它支持 A 股期权吗？
官方没有提供 A 股期权数据源，内置源面向美股（EODHD）。但引擎本身不限定市场——只要你的数据满足上述字段契约，就可以用 csv_data() 喂进去。也就是说：能力上可能可行，数据上要你自己解决。这是本站基于官方数据源清单得出的结论，不是官方声明。
能不能用它做实盘交易或自动下单？
不能。它是回测与统计库，项目本身不含下单通道。官方免责声明也写明：结果基于历史数据与简化假设，未考虑全部现实因素（流动性约束、执行滑点、指派风险等）。本站同样不建议把回测结果当作交易依据，也不提供投资建议。
文档写 38 个策略，为什么你说 40 个？
因为官方四处（README、文档首页、策略页、包 docstring）写的是「38 Built-in Strategies」，但源码 optopsy/__init__.py 的 __all__ 实际导出 40 个策略函数，而且官方策略页自己的分类表就是 10 类 × 4 个 = 40 条——它和开头的数字自相矛盾。本站以源码实测为准，并把差异写在策略手册页。