tools/todo.md

# 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 展示策略、图表和回测。
- [ ] 端到端测试。