Metadata-Version: 2.4
Name: deeptrade-quant
Version: 0.9.1
Summary: LLM-driven A-share (Shanghai/Shenzhen main board) stock screening CLI
Project-URL: Homepage, https://github.com/ty19880929/deeptrade
Project-URL: Repository, https://github.com/ty19880929/deeptrade
Project-URL: Issues, https://github.com/ty19880929/deeptrade/issues
Author: DeepTrade
License: MIT
License-File: LICENSE
Keywords: a-share,cli,deepseek,duckdb,llm,stock,tushare
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: duckdb>=1.0
Requires-Dist: keyring>=25.0
Requires-Dist: openai>=1.0
Requires-Dist: packaging>=23.0
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.7
Requires-Dist: tenacity>=8.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pandas>=2.2; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: tushare>=1.4; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: plugin-runtime
Requires-Dist: pandas>=2.2; extra == 'plugin-runtime'
Requires-Dist: tushare>=1.4; extra == 'plugin-runtime'
Description-Content-Type: text/markdown

# DeepTrade

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

> 📖 **在线文档**：[deeptrade.tiey.ai](https://deeptrade.tiey.ai) — 用户手册 + 开发者手册 + 官方插件目录

[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](#) [![python](https://img.shields.io/badge/python-3.11+-blue)](#) [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![version](https://img.shields.io/badge/version-0.4.2-blue)](CHANGELOG.md)

## ✨ 主要特性

- **轻量本地化**：单文件 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。

## 🚀 5 分钟上手

### 安装框架

```bash
# 推荐：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`）。

```bash
# 开发模式（克隆本仓库，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]"
```

### 初始化与配置

```bash
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                     # 表格展示当前配置（密钥脱敏）
```

### 安装官方插件并运行

官方插件维护在 [DeepTradePluginOfficial](https://github.com/ty19880929/DeepTradePluginOfficial)，框架按短名查注册表 → 拉 GitHub release tarball 自动安装。

```bash
# 浏览注册表
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 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 data sync ...` | （暂停用，下版本恢复；改用插件自带的 sync 子命令） |

保留字（不可作为 plugin_id）：`init / config / plugin / data / 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](https://github.com/ty19880929/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 文件路径（不影响其他工件） |

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

## 📖 参考

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

## ⚖️ 免责声明

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