tools/todo.md

OptionAgent 构建 TODO

目标：构建一个能辅助期权交易研究的 agent。后续重点偏向波动率交易，而不是单纯方向性期权交易。它需要能查资料、查市场数据、分析 IV/RV/skew/term structure，生成波动率策略、回测策略，并根据回测结果迭代改进。所有输出必须带假设、风险、数据来源和限制说明，不直接承诺收益。

0. 当前已有能力

• 本地 RAG：QueryKnowledgeTool 已接入主 agent，可查询期权书籍知识库。
• PDF RAG 优化：支持 PyMuPDF 提取、公式块识别、章节 metadata、页码引用。
• Hybrid search：dense retrieval + BM25 + reranker。
• 本地 RAG eval：支持 local-options eval、BEIR/fiqa、Open RAGBench。
• 基础市场价格工具：query_market_asset 可查询股票、指数、ETF、crypto、forex 的当前价格。
• Web search/visit webpage 已接入主 agent，并通过工具初始化与网页解析 mock 测试。
• 期权链、IV、Greeks、期限结构、偏斜等基础数据模块已完成 MVP，并通过 mock 测试。
• 策略构建模块 MVP 已完成：支持 5 类波动率策略候选。
• 回测模块 MVP 已完成：支持 payoff 情景分析、RV signal 历史回测 proxy、历史期权 bid/ask quote CSV 真实腿级回测。
• QuantConnect/LEAN 期权回测模板已加入：可用于接入真实历史期权链、撮合、组合持仓和保证金模型。
• 策略改进/优化闭环 MVP 已完成：支持参数扫描和 best vs baseline 对比。

1. Research 模块：资料检索

1.1 本地知识库 RAG

• 查询本地书籍、PDF、Markdown 知识库。
• 返回 source、page、section、content_type、score、excerpt。
• 支持公式 chunk 和正文 chunk。
• 为期权策略类问题增加 query rewrite：
  • 中文问题转英文检索词。
  • 生成多个 query variants。
  • 对公式/章节/策略/风险问题采用不同检索策略。
• 增加 citation policy：
  • agent 最终回答必须引用 RAG 来源。
  • 没查到资料时明确说“不确定/资料不足”。

1.2 Web Search

• 将 DuckDuckGoSearchTool 和 VisitWebpageTool 接入 app.py 的 tools。
• 修复 VisitWebpageTool 中缺失的 re import。
• 给 web search 加使用边界：
  • 用于查最新市场事件、宏观事件、财报日期、公司公告、交易所规则。
  • 本地书籍知识优先用 RAG，实时信息优先用 web。
• Web 结果返回标题、URL 和摘要；发布时间后续按数据源能力增强。
• 对高风险市场信息做多源交叉验证。

2. Market Data 模块：市场数据与期权数据

2.1 标的行情

• 当前价格、日内 OHLC、成交量。
• 增加历史价格接口：
  • 日线、小时线、分钟线。
  • 支持 start/end/period/interval 参数。
  • 输出用于回测的标准 DataFrame/JSON。
• 增加 realized volatility 计算：
  • 10D/20D/30D/60D realized vol。
  • Parkinson/Garman-Klass 可选。

2.2 期权链

• 新增 query_option_chain(symbol, expiration) tool。
• 返回 calls/puts：
  • strike
  • bid/ask/mid/last
  • volume/open_interest
  • implied_volatility
  • in_the_money
  • expiration
  • days_to_expiration
• 支持列出全部 expiration dates。
• 对无流动性合约做标记：
  • bid/ask 缺失
  • spread 过宽
  • volume/OI 过低

2.3 Greeks 与波动率结构

• 新增 Greeks 计算模块：
  • delta/gamma/vega/theta/rho。
  • 支持 Black-Scholes-Merton。
  • 支持 dividend yield / risk-free rate 参数。
• 新增 IV surface / skew 分析 MVP：
  • ATM IV。
  • 近似 put-call skew。
  • ATM IV term structure slope。
  • IV percentile / rank 后续在 Milestone 2 完成。
• 新增 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 数据源抽象

• 建立 market_data/ 模块，避免所有行情逻辑堆在 app.py。
• 设计统一 schema：
  • UnderlyingQuote
  • OptionContract
  • OptionChain
  • VolSnapshot
• 第一阶段可用 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
• 支持波动率交易策略模板 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
• 每个策略输出：
  • 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 模块：波动率交易研究

• 构建 volatility dashboard MVP：
  • current IV vs historical IV range。
  • IV percentile / rank。
  • realized volatility windows。
  • IV-RV spread。
  • term structure chart。
  • skew chart。
• 识别波动率 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。
• 输出波动率观点 MVP：
  • long vol / short vol / neutral。
  • confidence。
  • key assumptions。
  • invalidation conditions。

4. Backtesting 模块：回测与情景分析

4.1 第一阶段：Payoff 与情景分析

• 新增 backtest/ 模块。
• 实现到期 payoff 情景表：
  • 不同标的价格下 PnL。
  • breakeven。
  • max loss/max profit。
• 实现情景分析 MVP：
  • underlying price shock。
  • IV up/down。
  • days passed / theta decay。
  • Greeks approximation。
• 增加波动率情景 MVP：
  • IV crush。
  • IV expansion。
  • realized move vs implied move。
  • gamma scalp breakeven move。
  • delta-hedging frequency sensitivity。
• 输出表格和 JSON，方便 agent 总结。

4.2 第二阶段：历史回测

• 获取历史 underlying price。
• 获取或近似历史 IV：
  • 优先真实历史 option chain。
  • 没有数据时用 realized vol 或当前 IV 做近似，并明确标注限制。
• 支持真实历史期权 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 等数据源。
• 设计 entry/exit rules MVP：
  • 入场条件。
  • 出场条件。
  • DTE 管理。
  • 固定 holding period。
  • 固定 entry frequency。
• 设计高级 entry/exit rules：
  • 止盈止损。
  • rolling 规则。
• 为波动率策略增加专门规则 MVP：
  • IV percentile 入场阈值。
  • IV-RV spread 入场阈值。
  • earnings 前后入场/退出。
  • DTE bucket。
  • delta hedge 频率。
  • gamma scalp rule。
• 计算指标 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 第三阶段：组合级回测

• 支持单策略多笔交易 MVP。
• 支持多策略/多标的组合交易。
• 支持现金、保证金、仓位占用。
• 支持交易成本、bid/ask slippage MVP。
• 支持 assignment / early exercise 风险近似。
• 生成交易日志 MVP。
• 生成风险归因。

5. Strategy Optimizer 模块：回测后改进

• 根据回测结果自动提出改进 MVP：
  • 调整 expiration。
  • 调整 strike/delta。
  • 调整止盈止损。
  • 限制入场市场环境。
  • 避开财报/宏观事件。
• 对波动率策略提出专门改进：
  • 调整 long/short vol 入场 IV percentile。
  • 调整 straddle/strangle delta。
  • 调整 delta hedge 频率。
  • 调整 DTE bucket。
  • 避开或利用 event vol。
  • 加入 tail hedge。
• 支持参数扫描 MVP：
  • DTE range。
  • delta target。
  • width。
  • profit target。
  • stop loss。
  • IV percentile threshold。
  • IV-RV spread threshold。
  • hedge frequency。
• 输出对比表：
  • baseline strategy
  • improved strategy
  • metrics delta
  • trade-off
• 防止过拟合：
  • train/test split。
  • walk-forward analysis。
  • out-of-sample period。

6. Agent Orchestrator 模块：完整工作流

• 定义标准工作流：

用户提出目标
  -> 解析意图和约束
  -> 查询 RAG/web 背景资料
  -> 查询标的行情和期权链
  -> 分析 IV/Greeks/流动性
  -> 生成多个策略候选
  -> 初步风险筛选
  -> 回测/情景分析
  -> 改进策略
  -> 输出最终报告

• 增加 agent prompt 约束：
  • 不承诺收益。
  • 不给无风险建议。
  • 必须说明假设和数据限制。
  • 必须输出最大亏损。
  • 必须说明流动性、滑点、IV、事件风险。
• 增加结构化输出格式：
  • 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 模块

• RAG retrieval eval。
• Market data tool 单元测试：已覆盖 RV、Greeks、历史价格 tool、期权链 tool、volatility snapshot mock。
• Strategy builder 单元测试：
  • payoff 计算正确。
  • max loss/max profit 正确。
  • breakeven 正确。
• Backtest engine 测试：
  • 单腿/多腿 payoff。
  • 交易成本。
  • rolling/exit rule。
• Agent end-to-end 测试：
  • 给定 symbol + outlook，能完整输出策略、风险和来源。

9. 推荐实现顺序

Milestone 1：Research + Market Data 可用

• 接入 web search 和 visit webpage 到主 agent。
• 修复 VisitWebpageTool。
• 新增 option chain 查询工具。
• 新增 Greeks/IV 基础计算。
• 新增 IV/RV/skew/term structure 基础分析。
• 将行情代码从 app.py 拆到独立模块。

Milestone 2：Volatility Dashboard MVP

• 计算 realized volatility windows。
• 计算 ATM IV、IV rank/percentile proxy。
• 计算 IV-RV spread。
• 计算 skew 和 term structure。
• 输出 volatility regime 判断。

Milestone 3：波动率策略生成 MVP

• 定义策略 leg schema。
• 实现 5 个优先策略模板：
  • long straddle
  • long strangle
  • short straddle
  • calendar spread
  • iron condor
• 实现 payoff/max loss/breakeven 计算。
• 根据 volatility regime 和 IV/RV 状态生成候选策略 MVP。

Milestone 4：回测 MVP

• 实现到期 payoff 和情景分析。
• 实现历史 underlying 回测 MVP。
• 实现 IV/RV 条件入场回测 MVP。
• 实现历史期权 quote CSV 的真实 long straddle 回测 MVP。
• 添加 QuantConnect/LEAN ATM long straddle 回测模板。
• 实现 straddle/strangle 的 delta hedge 情景分析 proxy。
• 输出核心指标和交易日志。

Milestone 5：优化闭环

• 参数扫描。
• 策略改进建议 MVP。
• 对比报告。
• 防过拟合验证。

Milestone 6：完整 Agent 工作流

• 统一 prompt 和输出格式。
• Gradio UI 展示策略、图表和回测。
• 端到端测试。