## 当前版本（v0.4.x）
自 **v0.4.0** 起，NTQ 引入 Python 原生文件存储（DuckDB），不再强制依赖第三方数据库服务——有 Python 即可运行。若您仍想使用 MySQL 或 PostgreSQL，向导与设置中均可配置。
最近更新摘要：
**v0.4.4**
- 策略投资组合使用**复权价格**（连续价格）作为信号、**实际价格**作为成交价的双轨回测，提升组合回测准确性。
- 投资组合回测新增「多机会时选择哪个机会投资」的接口，干预性更强。
- UI 新增**高级功能**入口：特征标签、数据契约和数据源。
- 各模块标准化重构：统一 API 文档、使用说明、架构说明等。
- 更多更新请参见 [CHANGELOG.md](CHANGELOG.md)。
## NTQ 是什么？
New Tea Quant是一款对个人开发者友好、轻量级、高性能量化策略回测与研究框架。
它不仅能帮你验证交易策略，还能在接入最新数据源后，作为市场**信号扫描器**，实时捕捉符合策略的交易机会并发出通知。（注：NTQ 专注投研与信号生成，不直接接入实盘交易）。
**如果您在量化研究中遇到过以下痛点，NTQ 将是您的绝佳选择：**
**🚀 个人PC运行效率低下**
- **痛点**：海量数据回测容易导致个人电脑内存溢出或进程卡死，被迫花钱上云。
- **NTQ 方案**：专门对个人 PC 深度优化过。内置动态资源调度引擎，自动根据 CPU 核心数与内存余量分配计算资源，实现运行稳定性与高速回测的相对平衡。
**📦 部署复杂，安装麻烦**
- **痛点**：配置环境折磨人，需要安装数据库、消息队列等一堆繁琐的第三方组件。
- **NTQ 方案**：零第三方外部服务依赖。只要你的电脑装有 Python（≥3.9），克隆代码即可一键运行，把时间留给策略，而不是配环境。
**🧭 研究结论缺少认知分层，需要复杂的分析**
- **痛点**：一体式回测只给一个净值曲线，不知道问题出在「信号太滥」「买点太差」「仓位太重」还是「根本执行不了」；改一个参数就要整段重跑，越调越懵。
- **NTQ 方案**：把研究拆成可独立验证的阶段——寻找机会的能力 → 捕获价格波动的能力 → 有没有把资金正确投入高价值资产的能力 → 策略执行者能不能适应策略交易方式的能力（即将推出的决策者模式）→ 以及多策略组合层（已规划）。先看清每一层好不好，再决定要不要往下走——避免被一条好看的净值曲线掩盖了底层信号或执行环节的真实问题。
**🔍 交易轨迹难以回溯**
- **痛点**：回测跑通了，但想逐股排查某笔交易的细节却无从下手，宛如黑盒。
- **NTQ 方案**：分层回测的每一步均落盘保留（含版本快照）；配合 Web 策略实验室，可逐股查看买卖轨迹。结构化产物也便于后续分析与机器学习特征工程。
**📊 横截面回测复杂且笨重**
- **痛点**：想做「每月/每年在全 A 里选 Top N、低价股组合」这类横截面策略，本地框架往往要手写大量循环，全市场一跑就占满内存，只能缩小样本或上云。
- **NTQ 方案**：原生支持横截面研究模式（如换仓日同步比较全市场标的）。大样本下框架自动分片加载与并行计算，在个人 PC 上也能完成全市场枚举；仓库内附低价股等横截面演示策略，可直接对照学习。
**🛡️ 实盘收益远低于回测**
- **痛点**：回测收益率极高，实盘却亏损。往往是因为忽略了未来函数、幸存者偏差、涨跌停限制或复杂的交易规则。
- **NTQ 方案**：内置贴近真实市场的回测引擎。框架在底层默认处理了几类最容易让回测失真的问题：
- **幸存者偏差**：使用 PIT（point-in-time）股票池来防范
- **交易规则限制**：自动遵守买入手数规则、涨跌停无法成交、T+1 等
- **未来函数**：数据按日期严格切割，防止「上帝视角」式回测
让您只需专注挖掘 Alpha，剩下的交给框架。
**♻️ 每个策略需要重复计算因子**
- **痛点**：多个策略复用同一个指标（如复杂动量因子）时，重复计算导致效率低下，且容易写错。
- **NTQ 方案**：提供强大的“特征标签”功能。支持特征预处理与全局缓存，一次计算，多策略复用。不仅提升了回测速度，更保证了因子逻辑的一致性与安全性。
### 您还能得到这些“工程化的小心思”
- **核心与用户数据的分离**：框架的核心功能`core` 与用户产生的数据 `userspace` 分离，升级框架时策略与配置可保留。
- **大量的配置驱动**：使用settings配置方式完成常做的事情；复杂逻辑再写 Python。
- **方便的使用接口**：自带UI和命令行cli，可以通过UI或者快捷命令完成大部分操作，且遵从「同一策略同一产物」。
- **可复现的研究记录**：版本快照与指纹、`results/` 结构化输出，便于对比「这次和上次差在哪」。
## NTQ真挚地邀请早期体验志愿者（v0.x）
NTQ 仍在快速迭代：**安装向导、文档和 Web UI 都会变**。我一个人很难覆盖所有操作系统、Python 环境和研究习惯——**非常需要一批愿意在本机试用的朋友，一起把框架磨到更好用**。
您**不必会写代码**。按上文完成安装、跑通一个 demo，然后把真实感受告诉我就很有价值。
### 我们特别希望您反馈什么
- **安装与上手**：哪一步卡住、哪句 README 看不懂、期望更省事的流程
- **策略实验室 / 制定策略**：界面是否顺手、三步回测是否符合您的研究习惯
- **回测结果**：报告是否看得懂、单股溯源是否够用、哪里和预期不一致
- **性能与稳定**：个人 PC 上是否 OOM、卡顿、异常报错（请尽量附系统与复现步骤）
- **文档与示例**：缺哪类 demo 策略、官网/仓库哪块需要补
### 如何参与（任选其一）
| 方式 | 适合 |
|------|------|
| [GitHub Issues](https://github.com/garnet1985/new-tea-quant/issues) | Bug、功能建议（推荐，便于跟踪） |
| [Gitee Issues](https://gitee.com/garnet/new-tea-quant/issues) | Bug、功能建议（推荐，便于跟踪） |
| [官网留言](https://new-tea.cn/zh-hans/contact) | 无需注册也可填表单 |
| GitHub / Gitee 私信 | 简短交流、不方便公开的细节 |
提 Issue 时如能附上：**系统（Win / macOS / Linux）、Python 版本、做到第几步、截图或报错摘要**，会大大加快排查。
### 请注意
NTQ 本身免费开源，但部分能力依赖您自备资源：
- **数据**：框架提供接入与存储能力，**不含**数据源的付费账号或 token；需在第三方平台注册/购买后自行配置。
- **通知与外部自动化**：短信、邮件、推送等**不在框架内**；扫描结果可通过 Adapter 等扩展点交给您自己的程序处理。
### 另外
需要**轻微的 Python/配置能力**（或使用 AI 辅助）。运行环境为 **Python 3.9+**；默认使用内置 **DuckDB** 文件库，也可在向导中改用 **MySQL / PostgreSQL**。更完整的教程与概念说明见官网 **[new-tea.cn](https://new-tea.cn)**（中文）。
本项目采用 **Apache 2.0** 许可，可自由学习、改造与扩展。
## 快速安装 + 运行一个策略
目标：**5 分钟内跑起框架 + 跑通一个演示策略**。
### 前提条件
- 本机需要有 **Python 3.9 或以上**版本。如果您不知道怎么安装，请参考这篇文档：[安装 Python](https://new-tea.cn/zh-hans/install-python)。
- **注意：如果您是开发者**：需要安装 Node.js（主要给 UI 用）；数据库建议使用 MySQL 或 PostgreSQL。（DuckDB 单写模式调试较麻烦）
### 第 1 步：获取代码
任选其一：
- **Git clone**（推荐）：
```bash
git clone https://github.com/garnet1985/new-tea-quant.git
cd new-tea-quant
```
- **下载 ZIP**：在 GitHub 仓库页选择 **Code → Download ZIP**，解压后进入 **`new-tea-quant`** 根目录（与 `launcher.py` 同级）。
### 第 2 步：在仓库根目录启动安装向导
在**项目根目录**（能看到 `launcher.py`）打开终端，执行其一：
```bash
python launcher.py
```
Windows PowerShell 可能是：
```bash
python .\launcher.py
```
若系统上 `python` 指向旧版本，可改用：
```bash
python3 launcher.py
```
脚本会：切到仓库根目录、确保虚拟环境、然后**启动 BFF + 前端并打开浏览器**，进入图形化 **Setup 安装向导**（由 BFF setup API 驱动步骤）。
### 第 3 步：在浏览器中按向导完成初始化
按页面提示依次完成即可，基本上都是按照默认方式安装。
演示数据的导入会在安装时自动完成（如果您已经有数据，会自动跳过数据安装）
安装成功后点「前往制定策略」进入策略页面。
至此，您就已经完成了NTQ的安装。
**如果您是开发者**，建议使用mysql或pgsql，数据库可以不用新建，程序会自动帮助您新建（如果和已有数据库重名会提示）。
### 第 4 步：运行一个 demo
NTQ 自带以下演示资产：
- **数据**：约 **2023-01 ~ 2025-12**、**300 只**股票的三年演示数据，请勿商用。
- **策略**：自带默认 demo 策略，仅供演示，请勿用于实盘。
#### 进入策略页面
在 UI 点击「制定策略」，或打开路径 `/strategy-design/`，进入策略目录：
在列表中选择感兴趣的策略，点击标题或「进入调试」进入详情页：
策略页面大致由四块组成：
- **策略信息**：顶部全宽区域，展示名称、说明、版本等，以及发布等全局操作。
- **策略配置**：左侧面板，随回测步骤变化。改参数会生成新版本，便于对比调试。
**注意**：策略**逻辑**不能在 UI 里改，只能在 `userspace/strategies/` 对应目录改代码；UI 仅能调试代码里暴露的参数。（后续可能会配套 AI 辅助。）
- **执行面板**：当前步骤的执行入口。回测分三步：
- **枚举**：在历史数据中找出策略机会；
- **价格回测**：按 1 股、不计成本，看策略对价格波动的捕获；
- **投资组合**：带起始资金、仓位与风控等，更接近真实交易环境。
- **策略报告**：各步骤执行后自动生成；三步各有对应报告。
#### 第一步：机会枚举
结合截图走一遍。枚举跑完后，报告通常分成两部分（后续步骤也类似）：**单股报告**与**全局报告**。
在表格中点击一只股票，可进入单股 K 线：图上会有 K 线、所用指标，并用标记标出策略抓住的机会（如下图蓝点）：
退出单股视图后，在列表下方可看该步骤的整体报告，例如枚举的全局分析（机会在哪些股票上分布、平均持续时长等），用来改进「机会产出」能力：
#### 第二步：价格回测
价格回测衡量单股价格波动的捕获能力。下图为单股买卖点示意——不强调盈亏，而是直观看入手 / 出手位置，方便调试进出场：
全局报告里会有买卖价分布、收益等信息；解读时请结合你在配置里设定的目标：
#### 第三步：投资组合模拟
投资组合模拟更接近真实交易：可设置仓位、初始资金等，在历史行情上模拟投资，检验策略是否可能真实获利。
（当前结果暂不支持点击单股下钻，后续会支持。）
#### 策略选股：在真实市场中找机会
策略调试完成后，可用 **策略选股** 扫描当前市场机会。从主导航进入「策略选股」即可。
**注意：** 调试好的策略必须先在策略内页标题下方点击 **「发布策略」**，才会真正用于扫描。否则参数只存在于工作台缓存，不会写回策略代码，扫描也不会用到你刚调好的版本。
要扫描「真实」市场机会，通常还需要：
- **足够新的数据**（现阶段 NTQ 不内置行情源，需自行接入数据源）
- **已发布、完整可用的策略**
进入「策略选股」后，可选用 **严格模式**（数据不够新则不执行），选中策略并点击「开始扫描」。结束后页面会列出策略筛出的当前机会：
若只想看演示：选择 **「扫描演示」** 模式再扫。应用会假定「今天」是你本地数据最晚交易日的下一天，再按该假想时点跑扫描。
以上是一个简单的策略运行与选股示例；NTQ 还有更多功能等待您继续探索。
## 支持一下项目
如果您觉得NTQ还不错、您愿意持续关注它的演进，欢迎在 [GitHub](https://github.com/garnet1985/new-tea-quant) 或 [Gitee](https://gitee.com/garnet/new-tea-quant) 上为仓库点亮一颗 **Star**——这对个人开源项目而言，是非常实在的支持。
这是我第一次认真做开源，您的认可与反馈，是我继续打磨框架的最大动力。谢谢您！
### 数据说明
1. 如果您想**获取更多（约 3 年，全 A 股市场）演示数据包**：用于更完整的策略验证/回测，请在 **[new-tea.cn](https://new-tea.cn)** 注册后下载，移走 `initialization/data/` 里原有 zip 后只放入 **1 个** zip，再执行 `python cli.py id`（强制全量重导加 `-f`）。可另配库名以并存 demo 与全量数据（见 `userspace/system/config/database/`）。
2. **自有数据源**：也可自行接入（例如 Tushare），详见 [userspace/extensions/data_source/README.md](userspace/extensions/data_source/README.md)。
3. 演示数据与 demo 策略仅供学习研究，请勿用于实盘或商用。
### 一些声明
当前版本仍是非正式 **v0.x**：现阶段不能保证任何 API 的稳定性；进入 1.0 后 API 将基本稳定。（正式版之前，所有 API 最多为 beta。）详见 [CHANGELOG.md](CHANGELOG.md)。
## 常用命令（`cli.py`）
分层回测与扫描（完整列表：`python cli.py -h`）：
```bash
python cli.py se --strategy rsi_v1 # 机会枚举
python cli.py sp --strategy rsi_v1 # 价格层
python cli.py so --strategy rsi_v1 # 资金层
python cli.py c --strategy rsi_v1 # 全市场扫描
python cli.py t --scenario demo/market_cap_tier # 特征标签
```
建议显式指定 `--strategy`；需要强制重算时加 `-f`。
---
## Fun time：AI 如何评价 NTQ？
> 以下为第三方 AI 在阅读 NTQ 一些核心文件与文档后的评价，仅供娱乐，附**完整回复截图**。**非商业广告**，不代表任何 AI 官方立场；AI 可能过度乐观，请结合本仓库自行判断。
> 也欢迎用您自己的 AI 评价本工程；请务必先让 AI 阅读核心代码后再评价，否则容易出现严重脱离实际的幻觉。