dragon-quant 🐉

龙头战法量化筛选系统 — A 股涨停板龙头识别工具

基于通达信 TDX（首选）+ 同花顺、雪球、腾讯三大公开数据源，对涨停候选股进行多维量化评分，自动识别市场龙头；同时提供日志查询、SQLite 持久化、龙头回测与 Web UI 可视化能力。

当前主流程使用五维「识别真龙」评分体系：带动性 30% / 领涨性 25% / 抗跌性 15% / 流动性 20% / 资金承接 10%，采用门槛 + 加权两段式聚合（四大特征任一低于门槛即一票否决，资金承接不否决仅加权贡献）。设计哲学：龙头不是预判出来的，是「识别」出来的。完整规则见 评分规范。

目录

• 龙头回测成绩单（历史样本）
• 安装
• 快速开始
• CLI 命令大全
• Programmatic API
• 评分体系
• 数据源
• 目录结构
• 设计原则
• 持久化
• 免责声明
• License

龙头回测成绩单（历史样本）

入选后第一个非一字板日以最低价买入；最大收益按收益观察窗口统计，最大回撤按「买入日至最大收益出现日」窗口统计。

安装

pip install dragon-quant

# 或从源码
git clone https://github.com/gitBingxu/dragon-quant.git
cd dragon-quant && pip install -e .

要求 Python ≥3.9；tmdx（通达信 TDX）为默认依赖，Python ≥3.10 时随 pip install dragon-quant 自动安装；Python 3.9 因 tmdx 自身要求（≥3.10）被跳过，此时所有 CLI 命令（除 -h/--help/-v/--version）会在控制台提示升级 Python，scan 自动回退同花顺/雪球/腾讯。

快速开始

# 首次使用：配置雪球 Cookie（个股数据依赖；自动获取需 playwright，首次自动下载 chromium 内核约 150MB，走国内镜像）
dragon-quant data cookie-fetch

# 查看 Linux 风格帮助提示
dragon-quant -h
dragon-quant scan -h

# 五维「识别真龙」扫榜 — 找 top5 龙头
dragon-quant scan --top 5

# 账户级模拟交易回测（按真实账户逐日推进，可 --ui 打开 /account 面板）
dragon-quant review-account --ui-only

# 龙头回测 + Web UI
dragon-quant review --ui
# 查看龙头回测面板（默认读取 dragons_v2）
dragon-quant review --ui-only

# 实盘辅助交易（复用 review-account 策略，纯信号记账，不维护模拟账户）
dragon-quant buy                              # 盘中：候选池内触发买点的标的全部记入买入信号
dragon-quant sell                             # 盘中：对已买入未卖出的信号判定是否卖出
dragon-quant buy --date 20260907 --at 10:00   # 历史日期回放当日分时（必须指定 --at）

雪球 Cookie 也可手动设置：dragon-quant data cookie-set --cookie "xq_a_token=...; u=..."。Cookie 文件位于数据目录下的 cookies/xueqiu（macOS ~/Library/Application Support/dragon-quant/，Windows %APPDATA%\dragon-quant\，可用 DQ_DATA_DIR 覆盖）。自动获取（data cookie-fetch）首次运行会自动下载 chromium 内核（约 150MB，走国内镜像，仅一次），无需手动 playwright install。

CLI 命令大全

scan — 扫榜

dragon-quant scan [--top 25] [--candidates 5] [--workers 2] [--force] [--no-cache]

scan 走五维「识别真龙」体系。输出包含：板块排行（领涨/领跌明细）、候选股列表、评分表格、自然语言详细报告，并自动持久化到数据目录的 *_v2 表（macOS ~/Library/Application Support/dragon-quant/，Windows %APPDATA%\dragon-quant\，可用 DQ_DATA_DIR 覆盖）。scan_v2 仍可用于旧脚本兼容，但帮助文档不再展示。

blacklist — 板块黑名单

拉取领涨/领跌板块时按子串过滤（行业板块切换后默认种子为空，按需维护）。

dragon-quant blacklist list
dragon-quant blacklist add "次新股"
dragon-quant blacklist remove "次新股"

dragons — 导出龙头（JSON）

dragon-quant dragons                             # 最新有龙头数据的交易日，全部龙头
dragon-quant dragons --date 20260519             # 指定交易日
dragon-quant dragons --date 20260519 --true-only # 只输出真龙 (is_true_dragon=1)

固定读取 dragons_v2（扫描物化的入选龙头）并以 JSON 输出：外层含 trade_date / source / count，dragons 为龙头明细数组。--date 缺省时取最新有龙头数据的交易日（非「今天」）。无数据时输出 {"error": ...} 并以非零码退出，便于脚本判断。

review — 龙头回测

dragon-quant review                       # 自动筛 5~20 交易日内 pending 票全回测
dragon-quant review --date 20260519 --top 5
dragon-quant review --date 20260519
dragon-quant review --force --date 20260519
dragon-quant review --ui                  # 回测后启动 Web UI（默认展示 dragons_v2）
dragon-quant review --ui-only --port 8765 # 仅看结果（默认 dragons_v2）

review 默认读取/写回 dragons_v2；--source v1 仅用于查询和回测历史旧表。回测流程：从对应 dragons_* 表读 pending 龙头 → 找入选后第一个非一字板日（high != low）以最低价买入 → 算 max_return_5d / max_return_hold_days → 按买入日至峰值窗口算 max_drawdown_5d → 写回对应 DB 表。回测时对每只 pending 个股追加一段量价分析，结论写入独立的 vpa_analysis 表。

review-account — 账户级模拟交易

dragon-quant review-account --from 20260501 --to 20260601
dragon-quant review-account --from 20260501 --to 20260601 --capital 200000 --ui
dragon-quant review-account --ui-only

review-account 与 buy/sell 共用 review_account 策略与成交函数（evaluate_buy/evaluate_sell/fill_price/fee），统一候选、买卖规则与费用，因此后续只改 review_account + 回测即可同步调整 buy/sell。回测按开盘及完整 5 分钟 K 顺序重放，不能用当天最终数据决定早盘交易。候选为前 3 个真实交易日的全部真龙并集（共享层过滤否决/低于 50 分），按 code 去重保留综合分更高者，不再截断前 N 只；空池不向更早日期补票，回测首日会加载区间前的候选日期。

• 开盘 MA5 承接只用上日日 K 指标与量能；突破前高改为首根 5 分钟 K 完成后确认，需该根换手 ≥0.5% 带量（turn_strong_bar_turnover_min），日 K 兜底日不触发；分歧买龙等待完整 30 分钟承接窗口，不把瞬时触板当成保证成交。
• 多候选择优：买点得分越高越优先，同分看五维综合分，再按代码稳定排序（不再参考真龙 rank）。
• 信号与成交分离：历史信号在下一可交易事件撮合，实时信号等待更晚的有效报价；跳空不补填成本线或止损价，封死涨跌停不假定能买卖。
• T+1、当天卖出后不再买入；按事件顺序先卖后买，不用下午卖出结果阻止早上买入。止损、移动止盈、保本、高开窗口和尾盘规则共用一处实现；尾盘以 14:55 已知行情判断，15:00 只估值和更新峰值。
• 默认仍保留原仓位基线；--config params.json 可统一设置风险预算、单票仓位上限、MA5 距离/趋势过滤、ATR 移动止盈。最低佣金默认每笔 5 元，双边滑点 0.2%，佣金 0.03%，卖出印花税 0.05%。
• 数据分级成交：当日所有相关个股都有完整 5 分钟 K 时走严格盘中撮合；任一缺失则整日日K兜底（开盘价买入、当日 OHLC 判止损止盈，分歧买龙/高开窗口等分时规则自动跳过）。雪球 5 分钟历史约仅保留 14 天，故多月回测多为兜底模式，成交价为保守近似，结果标注 data_quality（strict_5min/mixed/daily_fallback）与 fallback_days。日K本身缺失或预热不足仍报错、不保存部分回测；停牌/除权口径缺口需先解决。

/account 继续支持生成/删除记录，POST /api/account/runs 可传 strategy_params JSON；快照附带完整 positions，旧记录仍可读取。完整规则见 STRATEGY.md。review_account.evaluation.compare_strategies 使用时间顺序训练/验证/独立测试和双倍滑点压力测试；数据不足时返回原因，不自动推广参数，不保证收益改善。

buy / sell — 实盘辅助交易

dragon-quant buy --date 20260907 --at 10:00   # 历史日期回放当日分时（必须指定 --at）
dragon-quant buy                              # 实时：回放截至当前已完成5分钟K
dragon-quant sell --date 20260908 --at 14:55  # 对已买入未卖出的信号判定卖出

buy/sell 底层与 review-account 完全复用同一 review_account 策略与成交函数，只做信号记账、不维护模拟账户/资金/数量/仓位：只要候选池标的触发买点就记一条买入（buy-all，不再择优取第一只）；sell 从信号表筛出「买入日之前且未平仓」的信号，回放当日行情判定卖出。策略调参只需改 review_account + 回测，buy/sell 自动跟随。

• SignalEngine 复刻 TradingEngine.step 的「决策 → 下一可执行事件成交」两段式与峰值跟踪，去掉资金/数量/仓位/次数限制；卖出用 notional Position（qty=100）保证 break_even_price 与回测精确一致。
• 历史回放必须显式指定 --date YYYYMMDD --at HH:MM，仅用历史数据；实时运行不指定 --at，回放截至当前已完成的5分钟K。
• 信号表 buy_sell_signals：同一未平仓 code 幂等去重，峰值跨日写回供移动止盈/保本判定。
• buy/sell 仍不接券商。数据齐全、参数和事件一致时，两条路径的买点/卖点/成交价与回测一致，不代表真实市场必然成交。

vpa — 量价分析

dragon-quant vpa --code 600519 [--source xueqiu] [--days 60] [--no-save]

独立于评分体系的量价健康度验证模块，基于「多空博弈 + 量能验证」，内置 4 个插件式因子：量额灵敏度 / 趋势量价验证 / 突破放量验证 / 量价背离。输出健康度（0-100）+ 偏多/中性/偏空信号 + 判断依据，定位「验证器」而非买卖指令。

data — 原子数据查询

dragon-quant data sector [--asc]                       # 行业板块涨/跌幅榜
dragon-quant data components --sector 881167           # 行业成分股（同花顺 6 位代码）
dragon-quant data kline --code 600172 [--days 20]      # 个股日 K
dragon-quant data minute --code 600172                 # 个股 1 分 K（分时）
dragon-quant data quote --code 600172                  # 实时行情
dragon-quant data batch-quote --codes 600172,000001    # 批量行情
dragon-quant data cookie-status                        # Cookie 状态

logs / storage — 日志与数据管理

dragon-quant logs tail [-n 20]
dragon-quant logs --source v2 query [--date 20260513] [--category scorer:drive] [--level error] [--code 600172]
dragon-quant logs --source v2 summary
dragon-quant logs clear --days 7

dragon-quant storage status      # 存储状态
dragon-quant storage size        # 磁盘占用
dragon-quant storage clear --all # 清理全部

Programmatic API

import dragon_quant

result = dragon_quant.scan(top_n=5, candidates_n=5, workers=2)

# 返回 dict：
# {
#   "timestamp": "...", "elapsed_s": 38.2,
#   "sectors": {"up": [...], "down": [...]},
#   "ranking": [
#     {"code": "...", "name": "...", "concepts": [...], "board_count": 3,
#      "composite_score": 73.5,
#      "is_true_dragon": true, "rank": 1, "reject_reason": null,
#      "dimensions": {"drive": {...}, "leadership": {...}, "anti_drop": {...},
#                     "liquidity": {...}, "absorption": {...}}}
#   ],
#   "report_text": "..."
# }

原子数据查询：

from dragon_quant.data import (
    get_sector_ranking, get_sector_components,
    get_kline, get_minute_kline, get_quote, batch_get_quotes,
    cookie_status, fetch_cookies,
)

sectors = get_sector_ranking(asc=False)        # 行业涨幅榜
stocks = get_sector_components("881167")       # 行业成分股
kline = get_kline("600172", days=30)
quote = get_quote("600172")

评分体系

五维「识别真龙」

聚合：四大特征任一低于门槛或执行异常即否决；资金承接不否决，无数据、无信号或异常均降级为 50 分。全部候选保留诊断综合分，但只有通过者按综合分降序、同分代码升序获得真龙排名（否决者 rank=null）。raw_output.ranking 和 scan_stocks_v2 保存全部明细；报告及 dragons_v2 只使用 Top N 真龙，不用否决票补位。无真龙仍保存扫描和原因，五日去重后保留原排名。

关键口径：稳定封板取最后一次开板后持续封至最后有效分钟的起点；带动与跟风按动作先后互斥判定，同步启动不判方向，相关性奖励只看首次触板前；抗跌性使用 SH000001 上证指数，反弹需基准和个股均实际回升，横盘不获反弹分；非涨停买一量不算封单，从未触板的完整分时稳定性为 0；资金承接以扫描日领跌 Top20 行业为对手盘，六根五分钟线不跨午休或隔夜，逐板块验证先跌后拉且间隔不超十分钟。阈值与降级分集中于 scorers/registry.py。

资金承接单事件按强度/广度/持续性 60%/20%/20% 评分，拉升满分参考为 3%、出逃规模（绝对均跌百分比×有效板块数）满分参考为 10。同交易时段的重叠窗口合并为独立事件，取消次数加分；事件分按三交易日半衰期向中性 50 衰减，再取衰减后最强的最多三个独立事件均值。报告展示原始窗口数、独立事件数、代表事件原始分和衰减结果；不调整维度总权重 10%，不新增否决条件。

成分股每行业最多约 50 只，属于采样而非全市场覆盖；腾讯行情按代码排序分批获取，不再截断总量为 200 只。领涨性使用日 K 派生的连板与五日涨幅，带动/抗跌/流动性看当日，承接回看十日。分钟和盘口只能提供采样证据，不能证明逐笔封单或实际资金流向。

历史数据不会自动重算或清理；盘后需要重新取数评分时执行 dragon-quant scan --force --no-cache，旧扫描记录仍代表当时规则。

数据源

封单数据首选 TDX 五档盘口，回退腾讯 gtimg 收盘盘口（盘后仍保留收盘瞬间状态）。

目录结构

dragon_quant/
├── cli.py                # CLI 门面（解析树 + main() + 共享 helper）
├── cli_commands.py       # 各子命令 _cmd_* 处理函数
├── orchestrator.py       # 编排器（Phase A→F，固定五维评分）
├── data.py               # 原子数据查询 API
├── rate_limit.py         # 并发限流器
├── providers/            # 数据源适配（tdx/ths/xueqiu/tencent/cookie）
├── scorers/           # 五维评分器 + registry + aggregator
├── vpa/                  # 量价分析（插件式因子）
├── cache/                # 内存+本地双缓存
├── logging/              # ScanLogger + ReportBuilder + query
├── storage/              # paths / db（SQLite 门面 + 领域模块）/ manager
├── utils/trading.py     # 交易日历工具
├── review.py             # 龙头回测
├── review_account/       # 账户级模拟交易回测（strategy/simulator/models/indicators/service）
├── live_trade/           # 实盘辅助交易 buy/sell（signal_engine/trader/service，复用 review_account 策略）
├── web_ui/               # 回测 Web UI（Vite+React+TS / stdlib HTTPServer）
└── models/types.py      # 数据模型

设计原则

1. Provider 抽象：所有数据源实现 StockProvider 接口，评分器只依赖接口，可无缝切换/新增数据源。
2. 评分器是 cache 消费者：统一签名 score(code, cache, **kwargs) -> ScoreResult，只读缓存不发请求；编排器 Phase A→D 预填，Phase E 打分。
3. 并发与限流：RateLimiter 按 provider 串行排队 + 随机延迟，不同 provider 并发。
4. 结构化日志：ScanLogger 全链路打点，支持按类别/级别/代码查询。
5. 历史兼容：主流程固定写 *_v2 表；旧 *_v1 表保留显式查询能力，不参与新扫描。

持久化

SQLite 表分为三类：

• 当前主流程：scans_v2 / scan_stocks_v2 / scan_logs_v2 / dragons_v2
• 历史旧表：scans_v1 / scan_stocks_v1 / scan_logs_v1 / dragons_v1（仅显式 --source v1 查询）
• 共享表：vpa_analysis / sector_blacklist
• 账户级 review 表：review_account_runs / review_account_snapshots / review_account_trades / review_account_positions / review_account_events
• 实盘辅助买卖信号表：buy_sell_signals（buy / sell 命令使用，未平仓 code 唯一）

运行时不创建旧无后缀 scans / scan_stocks / scan_logs / dragons 表；新扫描固定写 source="v2" 和 *_v2 表，以兼容已存在的 v2 历史数据。

dragons_v2 表关键字段：

• source：固定为 v2；旧 dragons_v1 仅用于历史记录。
• version：入库时的包版本号。
• review 字段：buy_date / buy_price / max_return_5d / max_drawdown_5d / max_return_hold_days / review_status，按 source 独立维护。

scan_stocks_v2 填充 dim_liquidity / is_true_dragon / reject_reason 等五维识别字段。

review_account_* 表用于账户级模拟交易：runs 保存 UI 记录名称、策略参数与汇总，snapshots 保存每日权益/现金/持仓快照，trades 保存交割单及买卖逻辑，positions 保存已平仓持仓的收益和退出原因，events 保存买入、卖出、持仓和空仓原因时间线。

buy_sell_signals 表用于实盘辅助交易（buy / sell）：记录买入（code/name/entry_date/entry_price/买入原因与信号）与卖出（exit_date/exit_price/卖出原因/持有天数），并保存最高浮盈/价（highest_return/highest_price）与半仓标记供跨日移动止盈/保本判定；未平仓 code 由部分唯一索引 idx_buy_sell_open 保证幂等去重。

免责声明

本工具仅供学习交流，不提供任何个股买卖建议，开发者不承担任何个股买卖亏损。评分、回测与实盘辅助交易的所有输出均为技术研究结果，不构成投资建议；据此操作产生的盈亏由使用者自行承担。

License

MIT