# OptionAgent 构建 TODO 目标：构建一个能辅助期权交易研究的 agent。后续重点偏向波动率交易，而不是单纯方向性期权交易。它需要能查资料、查市场数据、分析 IV/RV/skew/term structure，生成波动率策略、回测策略，并根据回测结果迭代改进。所有输出必须带假设、风险、数据来源和限制说明，不直接承诺收益。 ## 0. 当前已有能力 - [x] 本地 RAG：`QueryKnowledgeTool` 已接入主 agent，可查询期权书籍知识库。 - [x] PDF RAG 优化：支持 PyMuPDF 提取、公式块识别、章节 metadata、页码引用。 - [x] Hybrid search：dense retrieval + BM25 + reranker。 - [x] 本地 RAG eval：支持 local-options eval、BEIR/fiqa、Open RAGBench。 - [x] 基础市场价格工具：`query_market_asset` 可查询股票、指数、ETF、crypto、forex 的当前价格。 - [x] Web search/visit webpage 已接入主 agent，并通过工具初始化与网页解析 mock 测试。 - [x] 期权链、IV、Greeks、期限结构、偏斜等基础数据模块已完成 MVP，并通过 mock 测试。 - [x] 策略构建模块 MVP 已完成：支持 5 类波动率策略候选。 - [x] 回测模块 MVP 已完成：支持 payoff 情景分析、RV signal 历史回测 proxy、历史期权 bid/ask quote CSV 真实腿级回测。 - [x] QuantConnect/LEAN 期权回测模板已加入：可用于接入真实历史期权链、撮合、组合持仓和保证金模型。 - [x] 策略改进/优化闭环 MVP 已完成：支持参数扫描和 best vs baseline 对比。 ## 1. Research 模块：资料检索 ### 1.1 本地知识库 RAG - [x] 查询本地书籍、PDF、Markdown 知识库。 - [x] 返回 source、page、section、content_type、score、excerpt。 - [x] 支持公式 chunk 和正文 chunk。 - [ ] 为期权策略类问题增加 query rewrite： - 中文问题转英文检索词。 - 生成多个 query variants。 - 对公式/章节/策略/风险问题采用不同检索策略。 - [ ] 增加 citation policy： - agent 最终回答必须引用 RAG 来源。 - 没查到资料时明确说“不确定/资料不足”。 ### 1.2 Web Search - [x] 将 `DuckDuckGoSearchTool` 和 `VisitWebpageTool` 接入 `app.py` 的 tools。 - [x] 修复 `VisitWebpageTool` 中缺失的 `re` import。 - [x] 给 web search 加使用边界： - 用于查最新市场事件、宏观事件、财报日期、公司公告、交易所规则。 - 本地书籍知识优先用 RAG，实时信息优先用 web。 - [x] Web 结果返回标题、URL 和摘要；发布时间后续按数据源能力增强。 - [ ] 对高风险市场信息做多源交叉验证。 ## 2. Market Data 模块：市场数据与期权数据 ### 2.1 标的行情 - [x] 当前价格、日内 OHLC、成交量。 - [x] 增加历史价格接口： - 日线、小时线、分钟线。 - 支持 start/end/period/interval 参数。 - 输出用于回测的标准 DataFrame/JSON。 - [x] 增加 realized volatility 计算： - 10D/20D/30D/60D realized vol。 - Parkinson/Garman-Klass 可选。 ### 2.2 期权链 - [x] 新增 `query_option_chain(symbol, expiration)` tool。 - [x] 返回 calls/puts： - strike - bid/ask/mid/last - volume/open_interest - implied_volatility - in_the_money - expiration - days_to_expiration - [x] 支持列出全部 expiration dates。 - [x] 对无流动性合约做标记： - bid/ask 缺失 - spread 过宽 - volume/OI 过低 ### 2.3 Greeks 与波动率结构 - [x] 新增 Greeks 计算模块： - delta/gamma/vega/theta/rho。 - 支持 Black-Scholes-Merton。 - 支持 dividend yield / risk-free rate 参数。 - [x] 新增 IV surface / skew 分析 MVP： - ATM IV。 - 近似 put-call skew。 - ATM IV term structure slope。 - IV percentile / rank 后续在 Milestone 2 完成。 - [x] 新增 volatility trading 专用指标 MVP： - realized volatility: 5D/10D/20D/30D/60D。 - implied vs realized spread。 - volatility risk premium: IV - RV。 - IV term structure slope。 - skew slope / put-call skew。 - vol-of-vol proxy 后续增强。 - event IV premium 后续增强。 - [ ] 对 yfinance IV 字段做 sanity check： - IV 为 0、缺失、异常值时标记。 - bid/ask/mid 不合理时不参与策略构建。 ### 2.4 数据源抽象 - [x] 建立 `market_data/` 模块，避免所有行情逻辑堆在 `app.py`。 - [x] 设计统一 schema： - `UnderlyingQuote` - `OptionContract` - `OptionChain` - `VolSnapshot` - [x] 第一阶段可用 yfinance，后续可接 Polygon/Tradier/IBKR。 ## 3. Strategy Builder 模块：策略构建 后续策略构建以波动率观点为核心，方向观点为辅助变量。 ### 3.1 用户意图解析 - [ ] 解析用户输入： - 标的 symbol。 - 波动率观点：long vol / short vol / vol mean reversion / event vol / skew trade。 - 方向观点：bullish/bearish/neutral/range-bound。 - 时间周期。 - 风险承受。 - 账户约束/最大亏损。 - 是否允许裸卖。 - [ ] 如果关键信息缺失，agent 需要追问，而不是直接生成交易。 ### 3.2 策略候选生成 - [ ] 支持基础策略模板： - long call / long put - covered call - cash-secured put - vertical spread - calendar spread - straddle / strangle - iron condor - collar - [x] 支持波动率交易策略模板 MVP： - long straddle / long strangle - short straddle / short strangle - delta-hedged straddle - calendar spread - diagonal spread - variance-style option basket approximation - skew trade: risk reversal / put spread vs call spread - term structure trade: near-term short vol + longer-term long vol - [x] 每个策略输出： - legs - expiration - strike - net debit/credit - max profit - max loss - breakeven - margin estimate - Greeks exposure - liquidity warnings ### 3.3 策略筛选规则 - [ ] 根据市场状态筛选策略： - 高 IV：偏向 credit spread / iron condor / covered call。 - 低 IV：偏向 long options / calendar / debit spread。 - 趋势观点强：vertical spread / directional options。 - 震荡观点：short premium / condor。 - [ ] 根据波动率状态筛选策略： - IV 明显高于 RV：考虑 short vol，但必须检查事件风险和尾部风险。 - IV 明显低于 RV：考虑 long vol，但必须检查 theta bleed。 - 近月 IV 异常高：考虑 calendar/diagonal 或 event vol 策略。 - skew 极端：考虑 risk reversal、put spread、skew mean reversion。 - term structure 陡峭：考虑跨期限 vol trade。 - [ ] 加入风险约束： - max loss 不超过用户预算。 - spread 不能过宽。 - OI/volume 低的合约排除。 - 禁止默认裸卖期权。 - [ ] 输出多个候选策略并排序，而不是只给一个。 ### 3.4 策略解释 - [ ] 每个策略必须解释： - 为什么适合当前市场。 - 主要盈利条件。 - 主要亏损场景。 - Greeks 风险。 - IV crush / event risk。 - Vega / gamma / theta trade-off。 - Long vol 或 short vol 的核心假设。 - 流动性和滑点风险。 - [ ] 必须引用 RAG/web/market data 来源。 ## 3.5 Volatility Research 模块：波动率交易研究 - [x] 构建 volatility dashboard MVP： - current IV vs historical IV range。 - IV percentile / rank。 - realized volatility windows。 - IV-RV spread。 - term structure chart。 - skew chart。 - [x] 识别波动率 regime MVP： - low vol regime。 - high vol regime。 - vol expansion。 - vol compression。 - event-driven vol。 - [ ] 事件模块： - earnings date。 - CPI/FOMC/NFP 等宏观事件。 - event implied move。 - post-event IV crush risk。 - [x] 输出波动率观点 MVP： - long vol / short vol / neutral。 - confidence。 - key assumptions。 - invalidation conditions。 ## 4. Backtesting 模块：回测与情景分析 ### 4.1 第一阶段：Payoff 与情景分析 - [x] 新增 `backtest/` 模块。 - [x] 实现到期 payoff 情景表： - 不同标的价格下 PnL。 - breakeven。 - max loss/max profit。 - [x] 实现情景分析 MVP： - underlying price shock。 - IV up/down。 - days passed / theta decay。 - Greeks approximation。 - [x] 增加波动率情景 MVP： - IV crush。 - IV expansion。 - realized move vs implied move。 - gamma scalp breakeven move。 - delta-hedging frequency sensitivity。 - [x] 输出表格和 JSON，方便 agent 总结。 ### 4.2 第二阶段：历史回测 - [x] 获取历史 underlying price。 - [ ] 获取或近似历史 IV： - 优先真实历史 option chain。 - 没有数据时用 realized vol 或当前 IV 做近似，并明确标注限制。 - [x] 支持真实历史期权 quote CSV 输入： - 必需字段：date、underlying_symbol、underlying_price、contract_symbol、option_type、expiration、strike、bid、ask。 - 可选字段：mid、delta、gamma、theta、vega、implied_volatility、volume、open_interest。 - 当前实现可做 ATM long straddle 的真实开仓/平仓腿级 PnL。 - 注意：yfinance 不能可靠提供历史 option chain，严肃回测需要 Polygon/ORATS/OptionMetrics/QuantConnect 等数据源。 - [x] 设计 entry/exit rules MVP： - 入场条件。 - 出场条件。 - DTE 管理。 - 固定 holding period。 - 固定 entry frequency。 - [ ] 设计高级 entry/exit rules： - 止盈止损。 - rolling 规则。 - [x] 为波动率策略增加专门规则 MVP： - IV percentile 入场阈值。 - IV-RV spread 入场阈值。 - earnings 前后入场/退出。 - DTE bucket。 - delta hedge 频率。 - gamma scalp rule。 - [x] 计算指标 MVP： - total PnL - max drawdown - win rate - avg win/loss - [ ] 计算高级指标： - total return - CAGR - Sharpe/Sortino - exposure time - tail loss - realized vs implied PnL attribution - theta PnL - vega PnL - gamma scalping PnL ### 4.3 第三阶段：组合级回测 - [x] 支持单策略多笔交易 MVP。 - [ ] 支持多策略/多标的组合交易。 - [ ] 支持现金、保证金、仓位占用。 - [x] 支持交易成本、bid/ask slippage MVP。 - [ ] 支持 assignment / early exercise 风险近似。 - [x] 生成交易日志 MVP。 - [ ] 生成风险归因。 ## 5. Strategy Optimizer 模块：回测后改进 - [x] 根据回测结果自动提出改进 MVP： - 调整 expiration。 - 调整 strike/delta。 - 调整止盈止损。 - 限制入场市场环境。 - 避开财报/宏观事件。 - [ ] 对波动率策略提出专门改进： - 调整 long/short vol 入场 IV percentile。 - 调整 straddle/strangle delta。 - 调整 delta hedge 频率。 - 调整 DTE bucket。 - 避开或利用 event vol。 - 加入 tail hedge。 - [x] 支持参数扫描 MVP： - DTE range。 - delta target。 - width。 - profit target。 - stop loss。 - IV percentile threshold。 - IV-RV spread threshold。 - hedge frequency。 - [x] 输出对比表： - baseline strategy - improved strategy - metrics delta - trade-off - [ ] 防止过拟合： - train/test split。 - walk-forward analysis。 - out-of-sample period。 ## 6. Agent Orchestrator 模块：完整工作流 - [ ] 定义标准工作流： ```text 用户提出目标 -> 解析意图和约束 -> 查询 RAG/web 背景资料 -> 查询标的行情和期权链 -> 分析 IV/Greeks/流动性 -> 生成多个策略候选 -> 初步风险筛选 -> 回测/情景分析 -> 改进策略 -> 输出最终报告 ``` - [x] 增加 agent prompt 约束： - 不承诺收益。 - 不给无风险建议。 - 必须说明假设和数据限制。 - 必须输出最大亏损。 - 必须说明流动性、滑点、IV、事件风险。 - [x] 增加结构化输出格式： - `market_context` - `strategy_candidates` - `selected_strategy` - `backtest_summary` - `risk_warnings` - `sources` ## 7. UI / Report 模块 - [ ] Gradio UI 支持输入： - symbol - outlook - time horizon - risk budget - strategy preference - [ ] 展示： - 策略 legs 表格。 - payoff 图。 - Greeks 表格。 - 回测指标。 - 引用来源。 - [ ] 支持导出 Markdown/HTML report。 ## 8. Evaluation 模块 - [x] RAG retrieval eval。 - [x] Market data tool 单元测试：已覆盖 RV、Greeks、历史价格 tool、期权链 tool、volatility snapshot mock。 - [x] Strategy builder 单元测试： - payoff 计算正确。 - max loss/max profit 正确。 - breakeven 正确。 - [x] Backtest engine 测试： - 单腿/多腿 payoff。 - 交易成本。 - rolling/exit rule。 - [ ] Agent end-to-end 测试： - 给定 symbol + outlook，能完整输出策略、风险和来源。 ## 9. 推荐实现顺序 ### Milestone 1：Research + Market Data 可用 - [x] 接入 web search 和 visit webpage 到主 agent。 - [x] 修复 `VisitWebpageTool`。 - [x] 新增 option chain 查询工具。 - [x] 新增 Greeks/IV 基础计算。 - [x] 新增 IV/RV/skew/term structure 基础分析。 - [x] 将行情代码从 `app.py` 拆到独立模块。 ### Milestone 2：Volatility Dashboard MVP - [x] 计算 realized volatility windows。 - [x] 计算 ATM IV、IV rank/percentile proxy。 - [x] 计算 IV-RV spread。 - [x] 计算 skew 和 term structure。 - [x] 输出 volatility regime 判断。 ### Milestone 3：波动率策略生成 MVP - [x] 定义策略 leg schema。 - [x] 实现 5 个优先策略模板： - long straddle - long strangle - short straddle - calendar spread - iron condor - [x] 实现 payoff/max loss/breakeven 计算。 - [x] 根据 volatility regime 和 IV/RV 状态生成候选策略 MVP。 ### Milestone 4：回测 MVP - [x] 实现到期 payoff 和情景分析。 - [x] 实现历史 underlying 回测 MVP。 - [x] 实现 IV/RV 条件入场回测 MVP。 - [x] 实现历史期权 quote CSV 的真实 long straddle 回测 MVP。 - [x] 添加 QuantConnect/LEAN ATM long straddle 回测模板。 - [x] 实现 straddle/strangle 的 delta hedge 情景分析 proxy。 - [x] 输出核心指标和交易日志。 ### Milestone 5：优化闭环 - [x] 参数扫描。 - [x] 策略改进建议 MVP。 - [x] 对比报告。 - [ ] 防过拟合验证。 ### Milestone 6：完整 Agent 工作流 - [x] 统一 prompt 和输出格式。 - [ ] Gradio UI 展示策略、图表和回测。 - [ ] 端到端测试。