# 📈 Season · 量化投研 CLI
**单控制流 · LLM 只做路由与解读的 A 股终端量化研究工作站**
`单控制流 Single Controller` `Jev 快判断 + DeepSeek 慢思考` `类别路由 + 口径元数据` `规则集显式断言` `Grounding 数字溯源` `Fail-closed` `观点台账`
**[✨ 核心功能](#-核心功能) [🏗️ 架构总览](#️-架构总览) [📁 目录结构](#-目录结构) [🚀 快速开始](#-快速开始) [📋 命令表](#-cli-命令表) [🗺️ 路线图](#️-路线图) [⚙️ 配置说明](#️-配置说明) [⚖️ 合规与免责](#️-合规与免责) [📄 完整文档](#-完整文档)**
> 📘 **执行基准（双 PRD 协作）：** 技术准则以 `Season量化投研CLI_Bot_PRD_v1.3.md`（v1.2_ver1 增补 RAG 章节，2026-09-21）为唯一执行基准；金融知识以 `Season金融知识指导规格_Finance_PRD_v1.0.md` 为知识元规格——技术 PRD 管 HOW，Finance PRD 管 WHAT。两份 PRD 均为**本地文档，不入仓库**。
---
> **💬 重要提示（Important）**
>
> 本项目以个人开源为主进行开发维护，数据源插件化，可任意接入第三方数据源。**仅供学习研究使用。**
>
> ⚠️ 本项目仅作为本地量化研究提供解决思路与方案，**不作为投资软件或者看盘软件**。明确不做：不荐股、不代客理财、不对客收费、LLM 不参与资金决策；所有输出标注「**AI 辅助研究，非投资建议，需人工复核**」。
---
## ✨ 核心功能
把 A 股量化研究员的日常工作流 —— **取数 → 因子/策略研究 → 回测 → 评价 → 报告 → 盘前/盘后监控** —— 完整搬进终端，全程可复现、可测试、可审计。
| 能力 | 说明 | 阶段 |
|------|------|:---:|
| 🖥️ **终端交互** | 自然语言 + 显式命令双模式（NL Router 转换），Textual 多屏看板 | P0→P2 |
| 📈 **行情与技术面** | 实时快照 / K 线 / MA·MACD·RSI·BOLL·KDJ / ASCII 图表与 PNG 导出 | P0 |
| 🔍 **条件选股** | 表达式筛选（如 `PE<15 & ROE>15%`），单控制流调度 | P0 |
| ⚙️ **事件回测** | RQAlpha 内核，T+1 / 涨跌停 / 停牌 / 复权 / 交易成本全内置 | P1 |
| 🧮 **因子研究** | 因子库 + IC / 分层回测 / 行业·市值中性化（Polars 向量化） | P1 |
| 📄 **研究报告** | 读回测 JSON 生成 md / HTML / Word，数字 100% grounding 溯源 | P1 |
| 🛰️ **定时监控** | APScheduler 盘前/盘后任务 + 告警 + 观点台账到期复盘 | P2 |
| 🛡️ **风控网关** | pre-execute 架构级硬编码拦截，最高优先级，可否决一切信号 | P2 |
**三大硬约束**：仅做 A 股 · 数据源全部国内网络稳定可达 · 不做多智能体自治架构（Single Controller + Tools）
**明确不做**：高频/T0/Level2 微观结构 alpha · 强化学习自主探索 · 跨资产（期货/期权/债券/外汇） · 自动实盘自优化 · 自然语言直接下单
## 🏗️ 架构总览
```
┌─────────────────────────────────────────────────────────┐
│ ① 展示层 Terminal UI │
│ Click 命令 + Textual TUI（看板/选股/回测/因子/监控/复盘） │
├─────────────────────────────────────────────────────────┤
│ ② 意图路由 NL Router（v1.2 双层：Jev 预分流 + DeepSeek） │
│ 置信≥0.92 直达工具；DeepSeek 全局降级备用；fail-closed │
├─────────────────────────────────────────────────────────┤
│ ③ 工具层 Tool Registry │
│ quote / kline / indicator / screen / backtest / factor │
│ / report / event / watch / risk / config │
├─────────────────────────────────────────────────────────┤
│ ④ 确定性计算内核（LLM 不碰数值） │
│ factors：NaN/warmup registry 合约 │
│ backtest：规则集显式断言 + 子进程隔离 + run ID 断线重连 │
├─────────────────────────────────────────────────────────┤
│ ⑤ 数据层 Data Abstraction（类别路由 + 口径元数据） │
│ 统一接口：get_daily / get_fundamental / get_event / │
│ get_quote / get_lhb，口径元数据随 DataFrame 强制流转 │
├─────────────────────────────────────────────────────────┤
│ 横切：Risk Gateway（pre-execute）· Report（grounding） │
│ Watch（盘前/盘后 + 观点台账） │
└─────────────────────────────────────────────────────────┘
```
**实现状态（P3 课程版五段交付，2026-10-10）**：段1 Web 网关（FastAPI +
SSE 流式 + per-user token + 日配额 + 请求队列串行，CloudBase 云托管已上线）
→ 段2 新手友好 IO（三档预设 mandate / 向导式澄清 / 双层报告 / 群粘贴）
→ 段3 多用户协作层（ledger operator/group/source + 按人按组聚合复盘）
→ 段4 对账闭环（CSV 交易日志导入五重校验 / 决策卡三方对账 / 周复盘 +
Server酱微信推送）→ 段5 验收回归 + 开源（本文档）。原 P2 状态：
**实现状态（P2 全部交付 + 合规自检全绿）**：P2 四段交付——风控网关
（pre-execute 架构级拦截，gated 工具分发前置）/ 多因子打分选股 /score
（质量35/估值35/动量30，业界惯例中值可配）/ 观点台账+Watch 定时任务
（APScheduler 盘前盘后 + Jev 告警过滤 + 终端/邮件双通道）/ 验收回归
（合规自检六项全绿，scripts/compliance_check.py）。测试 216/216；
覆盖 ledger 96%/gateway 85%/score 83%。盘中任务插槽留 P3（mootdx 依赖链
评估）。原 P1 状态：
**实现状态（P1 全部交付 + 验收回归通过）**：①~⑤ 层全部交付；②层双层路由已实装——Jev 预分流
（2026-09-29 实测：路由 5/5 全对、延迟 577~857ms）→ 置信 ≥0.92 直达 /
<0.92 或超时 1500ms 升 DeepSeek 复核 → 双败转手动命令模式，降级链全程审计；
事件分级 classify 模式已接入（失败降级「未分级」，红线 §8.4）；L2 准则卡
F0~F6 挂载解读层（D9 体积校验）；L3 受限 RAG 按 D8=FTS5 定稿实装（69 分片
七域索引、gram 交集判据、TC-K6 fail-closed，开关 [knowledge].enabled 默认关）。
**验收（P1 段 7）**：TC-R1~R9 / TC-K1~K7 共 16 条用例全绿（对照表
[docs/acceptance.md](docs/acceptance.md)）；测试 162/162；覆盖率 72%
（核心链路 85~99%）；端到端演示 `python scripts/demo_e2e.py`（自然语言 →
Jev 路由 → mandate 澄清 → 回测 → 报告，存档 [docs/demo-session.md](docs/demo-session.md)）。
### 数据源稳定性分层（多源能力路由）
| 层级 | 来源 | 用途 | 稳定性 | License |
|------|------|------|--------|---------|
| **主源** | Tushare Pro | 日线 / 财务 / 分红 / 龙虎榜 | 高（规范 API） | BSD-3 |
| **备源** | AKShare | 补数据、临时查询 | 中（爬虫聚合） | MIT |
| **免费直连** | mootdx（TCP）/ 腾讯 / 新浪 / 东财 | 行情快照、K 线、龙虎榜、解禁 | 中（统一限流入口） | MIT |
| **公告校验** | 巨潮资讯 | 财务 / 公告原始披露日 | 高（官方，POST+UA） | 官方网站 |
| **付费预留** | 同花顺 Financial-API / iFinD / Choice | 官方行情 / 竞价 / 涨停池 / PIT | 很高（官方） | 商业授权 |
> 换源不换口径：五类数据（行情/财务/事件/快照/龙虎榜）各自维护独立的主源→备源→直连降级链，任一类故障不影响其他类取数；复权口径混合的回测请求直接拒绝。
### v1.1 工程合约（竞品事故 → 回归用例）
| 合约 | 内容 | 防的事故 |
|------|------|----------|
| **规则集显式断言** | 回测启动时逐项断言 T+1/涨跌停/印花税/手数/复权，缺项拒绝运行 | A 股篮子被静默路由进 crypto 引擎，无 T+1 仍出「自洽」指标 |
| **口径元数据** | 每个 DataFrame 携带复权状态/来源/抓取时间，混合即警告或拒绝 | 未复权除息缺口被当成真实暴跌 |
| **分页完整性校验** | 历史 K 线反向分页 + 空页复核 | 免费接口单窗口 500 根 bar，正向翻页静默截断成「最近两年」 |
| **NaN/warmup registry** | 因子统一 NaN 传播 + warmup 掩码，不合规拒绝入池 | 462 个因子中 84 个缺数据时静默返回常数，污染 IC |
| **Grounding gate** | 报告每个数字可溯源到工具返回，核验失败截断 | LLM 编造数字补全报告 |
| **Fail-closed** | 所有校验路径失败即拒绝，区分「验证通过」与「未验证」 | 审计「全 PASS 但什么都没验证」 |
| **统一限流入口** | 串行 ≥1s + 随机抖动 + Keep-Alive + UA | 东财高频拉取触发封 IP（实测 >5/s、并发≥10、200 次/分封禁） |
## 📁 目录结构
```
season_quant/
├── src/season_quant/
│ ├── cli/ # ① Terminal UI：Click 命令面板 + Textual 多屏
│ │ │ # （九屏：看板/选股/自选/回测/因子/监控/信号/复盘/数据状态，PRD §2.5）
│ ├── router/ # ② NL Router：自然语言 → 结构化工具调用
│ │ │ # 双层路由：Jev 预分流（≥0.92 直达）→ DeepSeek 兜底
│ │ │ # Judge Provider 可插拔（jev / deepseek / mock）
│ ├── tools/ # ③ Tool Registry：注册/发现/参数校验（fail-closed）
│ │ │ # quote·kline·indicator·screen·backtest·factor·
│ │ │ # report·event·watch·risk·config
│ ├── engine/ # ④ 确定性计算内核（LLM 不碰数值）
│ │ ├── factors/ # 因子引擎：IC/分层/中性化 + NaN/warmup registry
│ │ └── backtest/ # 回测引擎：A股规则 + 规则集显式断言 + 子进程隔离
│ ├── data/ # ⑤ 数据抽象层：类别路由 + 口径元数据 + 统一限流 + 缓存
│ │ └── sources/ # tushare（主）/ akshare（备）/ mootdx / 直连源适配
│ ├── knowledge/ # 知识层（v1.3）：L1 硬编码校验器 + L2 准则卡 +
│ │ # L3 受限 RAG（SQLite FTS5，仅挂 System 2，K1~K4 合约）
│ ├── risk/ # 风控网关：pre-execute 硬编码拦截（最高优先级）
│ ├── report/ # 报告：md/HTML/Word + grounding 溯源（[data:]/[kn:] 双标记）
│ ├── watch/ # 盘前/盘后定时监控 + 观点台账（JSON 存档复盘）
│ └── utils/ # 交易日历探针、日志、配置加载
├── tests/ # 测试金字塔
│ ├── unit/ # 单元：工具/因子/风控规则/知识校验器
│ ├── integration/ # 集成：Router → Tool → Engine 链路
│ └── e2e/ # 端到端：终端自然语言 → 报告
├── config/
│ └── settings.example.toml # [data.routing/ratelimit/cache] [llm] [judge]
│ # [risk] [backtest] [watch] [knowledge]
├── docs/
│ ├── architecture.md # 分层架构详解 · 模块↔PRD 映射
│ ├── reuse-compliance.md # 复用决策表 · 合规红线落地
│ ├── tech-radar.md # 技术雷达（Jev 评估与实测）
│ ├── dual-prd-framework.html # 双 PRD 协作框架决策图
│ ├── knowledge-gap-analysis_2026-09-21.md # 金融知识缺口调研
│ ├── knowledge/ # 金融知识库（Finance PRD §2，进 git 版本化）
│ │ ├── README.md # 索引 + 知识条目登记表
│ │ ├── research-guidelines.md # 投研指南准则正文（F0~F6）
│ │ ├── indicator-dict.yaml # 指标口径字典（L1 消费）
│ │ ├── event-dict.yaml # 事件口径字典（预告 8 档/事件窗）
│ │ ├── counterexamples.md # 反例清单（TC-K 用例素材）
│ │ └── cases/ # L3 检索语料（因子史/宏观传导/事件手册）
│ └── assets/ # logo 等静态资源
├── scripts/
│ └── check_env.py # 环境自检（纯标准库）
└── data/ # 运行时目录，均不入库（.gitignore 排除）
├── cache/ # SQLite + Parquet 缓存
└── output/ # 报告/图表产物
```
## 🚀 快速开始
```bash
# 0) 环境要求：Windows + Python 3.11+（建议 3.12.7）
python scripts/check_env.py # 环境自检（纯标准库，探测依赖与配置）
# 1) 安装 P0 依赖
pip install tushare akshare mootdx rich apscheduler
pip install -e . # 安装 season 命令入口
# 2) 配置密钥
copy .env.example .env # 填 TUSHARE_TOKEN / LLM_API_KEY 等
copy config\settings.example.toml config\settings.toml
# 3) 运行（P0 已交付，2026-09-29）
season # 进入交互会话 / 命令面板
season ask "贵州茅台近一年最大回撤" # NL Router → 工具调用 → 解读
```
**示例会话（P1 已交付链路：mandate 澄清 → 回测 → 报告）**
```text
> season ask "回测 600519"
router: mock keyword rule -> backtest {'codes': '600519', ...} conf=0.95
执行失败（fail-closed）:
开始回测前需要确认约束（F0 Mandate，禁止默认补全，TC-K4）：
- holding_period：持有期（策略信号到持仓的预期持有长度）（推荐参考值：一年）
- benchmark：业绩基准（引擎当前按上证指数 sh000001 计算超额收益）（推荐参考值：上证指数）
- risk_budget：风险预算（可承受的最大回撤/波动约束）（推荐参考值：最大回撤不超过20%）
> season backtest 600519 --start 20260101 --end 20260925 \
--holding-period 一年 --benchmark 上证指数 --risk-budget "最大回撤不超过20%"
backtest (8.2s)
标的 600519｜区间 20260101 ~ 20260925
规则断言 T+1 ✓ 涨跌停 ✓ 印花税 ✓ 手数 ✓ 复权=前复权 ✓ 成交价=次日开盘 ✓
区间收益 | 最大回撤 | 夏普 | 基准超额（TC-K1 双口径，<1 年年化禁报）
F0 Mandate: holding_period=一年 | benchmark=上证指数 | risk_budget=最大回撤不超过20%
> season report # 取最新回测结果 → md + HTML（grounding 核验 PASS 才输出）
```
## 📋 CLI 命令表
所有命令支持自然语言等价输入（由 NL Router 转换），显式命令便于脚本化与测试。
| 命令 | 说明 | 阶段 |
|------|------|:---:|
| `/quote