deeptrade-quant 0.14.0

LLM-driven A-share (Shanghai/Shenzhen main board) stock screening CLI

DeepTrade

本地运行的 A 股（沪深主板）选股 CLI 框架：tushare 行情 + OpenAI 兼容 LLM（DeepSeek / Qwen / Kimi …）+ DuckDB 单机仓库 + 纯透传式插件 CLI。框架不携带任何业务策略，所有策略按需从官方注册表安装。

📖 在线文档：deeptrade.tiey.ai — 用户手册 + 开发者手册 + 官方插件目录

✨ 主要特性

• 轻量本地化：单文件 DuckDB + uv，一条命令跑完，无需服务进程或容器。
• 框架与插件物理解耦：deeptrade-quant wheel 只含框架（init / config / plugin / data），所有策略走 deeptrade plugin install <短名> 从注册表安装。
• 纯透传式插件 CLI：未知首词一律按 deeptrade <plugin_id> <argv...> 透传给插件，插件自管 --help、子命令、参数、持久化。
• 数据隔离（Plan A）：每个插件在自己的 migrations 里声明并拥有自己的表（含 tushare 派生数据），框架不持有任何业务表。tushare_sync_state / tushare_calls / llm_calls 都按 plugin_id 维度隔离。
• 多 LLM Provider 共存：llm.providers 字典化配置，多个 OpenAI 兼容服务并存；插件通过 LLMManager.get_client(name=...) 按名取用，单次 run 内可调多家。
• LLM 强约束：JSON 模式 + Pydantic 双层校验；永远不传 tools / function calls。
• 跨插件 LLM 复现性（v0.12+）：框架自带 LLM 响应重放缓存 + 稳定 fingerprint 工具 + run 元数据 API，同输入 / 同 profile / 同 schema 的重复运行直接命中缓存，不调 provider；插件传入 stage / schema_version / input_fingerprint 即可启用。

🚀 5 分钟上手

安装框架

# 推荐：pipx 隔离环境（命令名仍是 deeptrade）
pipx install deeptrade-quant
# 或
uv tool install deeptrade-quant

注：PyPI 项目名是 deeptrade-quant，CLI 命令是 deeptrade，Python 包名是 deeptrade（import deeptrade）。三者不同是 Python 生态常态（同 pip install scikit-learn → import sklearn）。

# 开发模式（克隆本仓库，editable install）
uv sync --all-extras
uv run pre-commit install
# 兜底（无 uv）
python -m venv .venv && source .venv/bin/activate  # Windows: .\.venv\Scripts\activate
pip install -e ".[dev]"

初始化与配置

deeptrade init                            # 建库 + 应用 core migrations（交互式可选配 tushare / LLM）
deeptrade config set-tushare              # 交互式输入 tushare token
deeptrade config set-llm                  # 交互式增/改/删 LLM provider（deepseek / qwen / kimi …）
deeptrade config list-llm                 # 列出已配置且可用的 provider
deeptrade config test-llm                 # 对所有 provider 做连通性自检（也可加 <name> 单测）
deeptrade config show                     # 表格展示当前配置（密钥脱敏）

# 可选：报告上传（v0.11+，全局开关默认关闭）
deeptrade config set report.upload.enabled true
deeptrade config set report.upload.token   <bearer-token>   # 可选；空串走匿名
# report.upload.url / report.upload.timeout 也可在此调；默认指向官网

报告上传（v0.11+）：框架提供 ReportUploader 公共服务，插件通过 ctx.make_report_uploader().upload(path, plugin_name=..., trade_date=...) 把执行报告 JSON 推到统一端点。配置键 report.upload.{enabled,url,timeout} 走 app_config，report.upload.token 走 secret_store；每次调用（含 skipped）都在 report_uploads 表留一行审计，token / Authorization 永不落库。上传失败永远只 WARN，不阻断 run。

LLM 复现性 & 缓存（v0.12+）：相同 (plugin_id, stage, provider, model, system+user prompt, profile, schema_version, input_fingerprint) 下，重复执行直接命中已验证响应，不再向 provider 发起调用。

• 配置键 llm.replay.{enabled,write,ttl_days} 全部走 app_config，默认 enabled=true / write=true / ttl_days=null（不过期）。
• 环境变量全局开关：DEEPTRADE_FRESH_LLM=1 跳过读缓存仅写、DEEPTRADE_NO_LLM_REPLAY=1 双向禁用、DEEPTRADE_REPLAY_ONLY=1 仅读不写（缺失 raise LLMReplayMiss，常用于离线复盘 / CI）。冲突时按 REPLAY_ONLY > NO_LLM_REPLAY > FRESH_LLM 优先级解析。
• 插件接入只需要在 complete_json 调用点传 replay=policy_from_env(policy_from_app_config(cfg))、stage="..."、schema_version="..."、input_fingerprint=hash_json(...) 四个新参数（参数缺失则不启用缓存，行为与 v0.12 前完全一致）。
• 跨插件 run 元数据：ctx.set_run_key_date / set_run_input_fingerprint / add_run_artifact / get_run_metadata / list_run_artifacts 写入框架 run_metadata / run_artifacts，为后续 deeptrade run compare 提供横向数据。
• 稳定多 provider 并发：deeptrade.core.parallel.run_parallel_ordered(providers, worker_fn) 返回结果按输入顺序，on_complete 回调按完成顺序触发；适合 debate 模式下让 dashboard 实时刷新但报告 / peer 输入仍然 canonical。

安装官方插件并运行

官方插件维护在 DeepTradePluginOfficial，框架按短名查注册表 → 拉 GitHub release tarball 自动安装。

# 浏览注册表
deeptrade plugin search                   # 全量列出
deeptrade plugin search anomaly           # 关键词过滤

# 按短名安装（注册表 → 该插件最新 release tag）
deeptrade plugin install limit-up-board
deeptrade plugin install volume-anomaly

deeptrade plugin list                     # 查看已安装

# 运行打板策略（CLI 由插件自管，--help 由插件渲染）
deeptrade limit-up-board --help
deeptrade limit-up-board run              # 默认日终模式
deeptrade limit-up-board run --allow-intraday --force-sync

# 运行成交量异动策略
deeptrade volume-anomaly screen           # 异动筛选 → upsert va_watchlist
deeptrade volume-anomaly analyze          # LLM 主升浪启动预测
deeptrade volume-anomaly evaluate         # T+N 自动回测闭环
deeptrade volume-anomaly stats            # 收益统计聚合

插件 Python 依赖（v0.4.0+）：deeptrade_plugin.yaml::dependencies 中以 PEP 508 形式声明的依赖，会在 plugin install / plugin upgrade 期间被框架自动装入当前 Python 解释器（探测顺序 uv pip install → python -m pip install，已满足条件的 spec 跳过）。

• --no-deps：跳过依赖安装步骤（适合离线环境，需自行 pip install 准备运行环境）
• --reinstall-deps：对全部声明的 spec 强制重跑 installer（带 --upgrade）
• 失败时框架会在错误信息中归因到"框架核心依赖"或具体已装插件，便于排查 spec 冲突
• 超时阈值（默认 300s）可用 DEEPTRADE_DEP_INSTALL_TIMEOUT 覆盖

第三方 / 本地开发插件：deeptrade plugin install <SOURCE> 三种来源统一处理，判定顺序为 本地目录存在 → git URL → 注册表短名：

• deeptrade plugin install ./path/to/my-plugin — 本地目录
• deeptrade plugin install https://github.com/owner/repo — 完整 git 仓库（仓库根需含 deeptrade_plugin.yaml）
• deeptrade plugin install my-plugin --ref v1.2.0 — 指定 tag/branch/sha

报告产出在 ~/.deeptrade/reports/<run_id>/。

📦 命令矩阵

框架命令（封闭集合）

命令	用途
deeptrade --version / -V	显示版本
deeptrade --help / -h	框架命令清单（不枚举插件子命令）
deeptrade init [--no-prompts]	建库 + 应用 core migrations
deeptrade db init / db upgrade	显式建库 / 应用待执行迁移
deeptrade db llm-cache {list, purge, inspect} (v0.13+)	LLM replay cache 横向运维：list 按 plugin/stage 过滤；purge --yes --plugin/--stage/--before 至少一个过滤器；inspect <cache_key 前缀>
deeptrade config {show, set, set-tushare, set-llm, list-llm, test-llm}	全局配置
deeptrade plugin search [keyword] [--no-cache]	浏览官方注册表
deeptrade plugin install <SOURCE> [--ref <REF>] [--no-deps] [--reinstall-deps] [-y]	注册表短名 / GitHub URL / 本地路径；依赖按 PEP 508 自动解析装入框架解释器
deeptrade plugin list / info <id>	列表 / 详情（未安装时回退注册表条目）
deeptrade plugin enable <id> / disable <id>	启 / 停
deeptrade plugin uninstall <id> [--purge]	卸载（--purge 才 DROP 表；依赖不反向卸载）
deeptrade plugin upgrade <SOURCE> [--ref <REF>] [--no-deps] [--reinstall-deps]	升级（SemVer 比较，禁止降级；只跑增量 migrations + 依赖）
deeptrade run {compare, show} (v0.13+)	跨插件 run 维度查询：show <run_id> 一个 run 的元数据/LLM 调用/artifacts；compare <a> <b> 4 段 diff（basic / 指纹 / LLM 调用 / artifact sha256）；都支持 --plugin <id> 与 --format json
deeptrade data sync-concepts [--type N,I,R] [--quiet] (v0.14+)	全量同步同花顺行业 / 概念 / 地域板块 + 成份股到框架库；插件通过 ctx.make_concept_repository().boards_by_stock(ts_code) 查询股票所属概念。
deeptrade data sync ...	（通用 data sync 已转交插件自管；调用会打印迁移提示）

保留字（不可作为 plugin_id）：init / config / plugin / data / run / db。其中 db 长度未达 plugin_id 正则下限（^[a-z][a-z0-9-]{2,31}$，至少 3 字符），已被隐式拒绝；其余五个由 RESERVED_PLUGIN_IDS 在安装时显式拦截。

插件命令（按 plugin_id 透传，插件自管）

命令	来源（注册表短名）
deeptrade limit-up-board {run, sync, history, report, settings}	limit-up-board（strategy）
deeptrade volume-anomaly {screen, analyze, evaluate, stats, prune, history, report}	volume-anomaly（strategy）
deeptrade <你的-plugin-id> ...	你自己写的任何插件

任意插件子命令的 --help 都由插件自身渲染——框架不感知动词语义。各插件的最新子命令、参数与运行手册见 DeepTradePluginOfficial。

🧱 架构

┌──────────────────────── deeptrade CLI (custom click.Group) ────────────────────────┐
│                                                                                    │
│  framework commands (closed):                                                      │
│      init │ config │ plugin │ data │ db                                            │
│                                                                                    │
│  plugin pass-through (open):                                                       │
│      <plugin_id>  ──argv──→  Plugin.dispatch(argv) → int  (plugin owns the rest)   │
└──────────────────────────────────┬─────────────────────────────────────────────────┘
                                   │
                                   │
                  ┌────────────────┴────────────────┐
                  ▼                                 ▼
        ┌──────────────────┐              ┌────────────────────┐
        │ Core services    │              │  Plugins (strategy)│
        │ DuckDB · Config  │              │  • metadata        │
        │ Tushare · LLM    │              │  • validate_static │
        └──────────────────┘              │  • dispatch(argv)  │
                                          └────────────────────┘

每个插件通过自己的 migrations 声明并拥有 <prefix>_* 业务表；tushare_sync_state / tushare_calls / llm_calls 按 plugin_id 维度隔离，__framework__ 为框架自身保留 sentinel。

🛠️ Troubleshooting / 环境变量

框架行为通过环境变量调节；以下几个在排错与隔离测试时最常用：

变量	默认	行为
DEEPTRADE_DEBUG	unset	置 1 / true / yes / on 时，插件 dispatch 报错改为输出完整 traceback（含 __cause__ 链）；否则只打一行 ✘ {ExcType}: {msg}
DEEPTRADE_SKIP_AUTO_MIGRATE	unset	逃生通道：置 1 时跳过 Database() 构造时的自动 apply_core_migrations。仅用于"一次失败迁移把所有 CLI 命令都堵住"的恢复场景，正常流程不要用
DEEPTRADE_DEP_INSTALL_TIMEOUT	300	单次 uv pip install / python -m pip install 子进程的秒级超时上限
DEEPTRADE_HOME	~/.deeptrade	本地工件根目录覆盖（DuckDB 文件、插件安装目录、注册表缓存、reports 都在这下）
DEEPTRADE_DB_PATH	<DEEPTRADE_HOME>/deeptrade.duckdb	单独覆盖 DuckDB 文件路径（不影响其他工件）
DEEPTRADE_FRESH_LLM	unset	置 1 / true / yes / on 时，本次进程内所有走 policy_from_env() 的 LLM 调用跳过读缓存、成功后仍写缓存
DEEPTRADE_NO_LLM_REPLAY	unset	同上，但完全禁用缓存读写（既不读、也不写）；优先级高于 FRESH_LLM
DEEPTRADE_REPLAY_ONLY	unset	同上，仅允许缓存命中；缺失即 raise LLMReplayMiss，不发起真实调用。优先级最高，用于离线复盘 / CI

凡 Database() 构造时（即任何 deeptrade <…> 命令首次落地）都会跑一次 apply_core_migrations，所以 0.4.2+ 的用户升级后无需再手动 deeptrade db upgrade。

📖 参考

• CHANGELOG.md — 版本变更与历次 breaking change 记录
• DeepTradePluginOfficial — 官方插件源码、注册表、各插件运行手册
• 历史快照 archive/with-builtin-plugins-v0.1.0-preview — 含 builtin 子树的最后一版状态（v0.2.0 之前）

⚖️ 免责声明

本工具仅用于策略研究、数据整理与候选标的分析，不构成投资建议，不进行自动交易。所有 LLM 输出基于提交的结构化数据，不引用任何外部信息源；用户应自行核验候选标的的最新状态后再做决策。