# CherryQuant
**Repository Path**: qdphenix/CherryQuant
## Basic Information
- **Project Name**: CherryQuant
- **Description**: https://github.com/nehcuh/CherryQuant
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-11-26
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 🍒 CherryQuant - AI量化交易教学项目
[](https://python.org)
[](LICENSE)
[](https://docs.astral.sh/uv/)
[]()
**面向大学生的 AI 编程、Python 最佳实践、软件架构与量化交易教学项目**
[学习路径](#-学习路径) • [快速开始](#-快速开始) • [课程大纲](#-课程大纲) • [实验练习](#-实验练习)
---
## 🎓 这是一个教学项目
> **重要说明**：CherryQuant 是专门设计用于大学课程教学的项目，目标是帮助学生学习现代 Python 开发、软件架构设计、AI 集成和量化交易概念。
>
> **本项目不是**生产级交易系统，不应用于真实交易。
### 📖 教学目标
通过学习本项目，学生将掌握：
#### 1. **AI 编程技能**
- 🤖 大语言模型（LLM）集成与应用
- 📝 提示工程（Prompt Engineering）最佳实践
- 🔄 异步 AI API 调用与错误处理
- 💰 成本优化与速率限制策略
#### 2. **Python 最佳实践**
- ✅ 类型提示（Type Hints）与 Mypy 静态检查
- 🔀 异步编程（async/await）模式
- 📦 现代包管理（pyproject.toml + uv）
- 🧪 测试驱动开发（TDD）与代码覆盖率
#### 3. **软件架构设计**
- 🏛️ 六边形架构（Hexagonal Architecture）
- 💉 依赖注入（Dependency Injection）
- 🔌 适配器模式（Adapter Pattern）
- 🎯 设计模式实战应用
#### 4. **量化交易概念**
- 📊 中国期货市场基础知识
- 🔍 技术分析与策略设计
- ⚖️ 风险管理系统
- 📈 回测与性能评估
---
## 🗺️ 学习路径
### 推荐学习顺序（10周课程）
```
第 1-2 周 │ 📚 基础准备
├─ 环境搭建与 Python 3.12+ 基础
├─ 运行第一个示例
└─ 理解项目结构
第 3-4 周 │ 🏗️ 系统架构
├─ 六边形架构原理
├─ 数据管道设计
└─ 适配器模式实践
第 5-6 周 │ 🤖 AI 集成
├─ OpenAI API 使用
├─ 提示工程技巧
└─ AI 决策引擎实现
第 7-8 周 │ 💉 高级模式
├─ 依赖注入实战
├─ 测试策略
└─ 代码质量提升
第 9-10 周│ 🚀 综合实践
├─ 毕业项目设计
├─ 性能优化
└─ 部署与运维
```
**详细学习路径**: 请参阅 [LEARNING_PATH.md](LEARNING_PATH.md)
---
## 🚀 快速开始
### 前置要求
在开始之前，请确保你具备：
- ✅ **Python 编程基础**（中级水平，熟悉函数、类）
- ✅ **命令行基础**（能够使用终端/命令提示符）
- ✅ **Git 基础**（clone, commit, push）
- 🔶 **异步编程了解**（推荐但非必需，课程中会讲解）
### 学生环境搭建（3 步开始）
#### 步骤 1: 克隆项目
```bash
git clone https://github.com/your-username/CherryQuant.git
cd CherryQuant
```
#### 步骤 2: 一键环境配置
```bash
# 自动安装依赖和配置环境（学生版，无需 API 密钥）
bash scripts/teaching/student_setup.sh
```
这个脚本会：
- ✅ 检查 Python 3.12+
- ✅ 安装 uv 包管理器
- ✅ 安装所有依赖
- ✅ 生成模拟数据（无需外部 API）
- ✅ 创建学生版配置文件
#### 步骤 3: 运行你的第一个示例
```bash
# 运行 Hello World 示例
uv run python examples/01_basics/hello_cherryquant.py
```
你应该看到：
```
🍒 欢迎来到 CherryQuant 教学项目！
✅ 系统配置正常
✅ 模拟数据已加载
📚 准备开始学习之旅...
```
**恭喜！** 你已经成功配置了学习环境。
---
## 📜 脚本和工具
CherryQuant 提供了丰富的脚本来简化常见任务。所有脚本都位于 `scripts/` 目录下，按功能分类。
### 🚀 主运行脚本（根目录）
#### `run_cherryquant.py` - 主运行脚本
**推荐使用** - 功能完整，支持多种模式
```bash
# 模拟交易模式（推荐学习）
uv run python run_cherryquant.py simulation
# 回测模式
uv run python run_cherryquant.py backtest
# 实盘模式（需要真实账户，不推荐学生）
uv run python run_cherryquant.py live
```
#### `start.sh` - 一键启动脚本
**新手友好** - 交互式选择运行模式
```bash
bash start.sh
```
自动执行：
- ✅ 环境检查（uv, Python 3.12）
- ✅ 依赖安装
- ✅ 配置验证
- ✅ 交互式模式选择
### 🎓 教学辅助脚本
```bash
# 学生环境一键配置
bash scripts/teaching/student_setup.sh
# 环境验证（Lab 01需要）
uv run python scripts/teaching/verify_environment.py
```
### 💾 数据处理脚本
```bash
# 初始化历史数据
uv run python scripts/data/init_historical_data.py
# 指定品种和日期范围
uv run python scripts/data/init_historical_data.py --symbols rb2501,hc2501 --start 20240101
```
### 🔧 工具脚本
```bash
# 修复.env文件中的重复配置
uv run python scripts/utils/fix_env_config.py
# 数据库迁移（PostgreSQL → MongoDB）
uv run python scripts/utils/migrate_postgres_to_mongodb.py
```
### 🚀 高级运行脚本
```bash
# 完整多代理系统
uv run python scripts/runners/run_cherryquant_complete.py
# AI选股系统
uv run python scripts/runners/run_cherryquant_ai_selection.py
# 多Agent协作系统
uv run python scripts/runners/run_cherryquant_multi_agent.py
```
### 📖 详细文档
👉 **完整脚本说明**: [scripts/README.md](scripts/README.md)
- 每个脚本的详细用途
- 参数说明和使用示例
- 按用户角色推荐的脚本
---
## 📁 项目结构
CherryQuant 采用清晰的目录组织，便于学习和维护：
```
CherryQuant/
├── 📜 运行入口（根目录）
│ ├── run_cherryquant.py # 主运行脚本（支持 simulation/backtest/live 模式）
│ └── start.sh # 交互式启动脚本（新手友好）
│
├── 📖 核心文档（根目录）
│ ├── README.md # 项目总览（本文件）
│ ├── LEARNING_PATH.md # 10周学习路径
│ └── THIRD_PARTY_NOTICES.md # 第三方许可证
│
├── 🎯 核心目录
│ ├── src/ # 源代码（六边形架构）
│ │ └── cherryquant/
│ │ ├── adapters/ # 适配器层（数据、交易）
│ │ ├── ai/ # AI决策引擎
│ │ ├── services/ # 业务逻辑服务
│ │ ├── bootstrap/ # 应用启动和DI配置
│ │ ├── utils/ # 工具函数
│ │ └── web/ # Web API接口
│ │
│ ├── docs/ # 📚 完整文档中心
│ │ ├── course/ # 课程模块（Module 0-7）
│ │ ├── labs/ # 实验指导（Lab 01-08）
│ │ ├── guides/ # 操作指南
│ │ ├── reference/ # 技术参考
│ │ ├── adr/ # 架构决策记录
│ │ └── reports/ # 项目报告
│ │
│ ├── tests/ # 🧪 测试代码
│ │ ├── unit/ # 单元测试
│ │ ├── integration/ # 集成测试
│ │ └── e2e/ # 端到端测试
│ │
│ ├── scripts/ # 📜 工具脚本
│ │ ├── runners/ # 系统运行脚本
│ │ ├── data/ # 数据处理脚本
│ │ ├── utils/ # 工具脚本
│ │ ├── tests/ # 手动测试脚本
│ │ └── teaching/ # 教学辅助脚本
│ │
│ ├── examples/ # 💡 示例代码（按章节）
│ │ ├── 01_basics/ # 基础示例
│ │ ├── 02_architecture/ # 架构示例
│ │ ├── 03_data_pipeline/ # 数据管道示例
│ │ └── 04_ai_integration/ # AI集成示例
│ │
│ ├── config/ # ⚙️ 配置文件
│ │ ├── settings/ # 系统设置
│ │ ├── alert_config.py # 警报配置
│ │ └── sector_mapping.json # 板块映射
│ │
│ └── docker/ # 🐳 Docker配置
│ ├── docker-compose.yml # 基础服务（MongoDB, Redis）
│ └── docker-compose.test.yml
│
├── 🔧 运行时目录（.gitignore忽略）
│ ├── logs/ # 运行日志
│ ├── data/cache/ # 数据缓存
│ └── htmlcov/ # 测试覆盖率报告
│
└── 📦 配置文件
├── pyproject.toml # Python项目配置（依赖、工具）
├── uv.lock # 依赖锁文件
├── .env.example # 环境变量模板
├── .gitignore # Git忽略规则
└── pytest.ini # 测试配置
```
### 目录说明
**核心源代码** (`src/cherryquant/`):
- 采用六边形架构，核心业务逻辑与外部依赖解耦
- 所有业务代码都在这里，是学习的重点
**文档系统** (`docs/`):
- 完整的教学材料，从课程到实验
- 按主题分类，便于查找和学习
- 详见 [docs/README.md](docs/README.md)
**测试代码** (`tests/`):
- 完整的测试套件，覆盖单元、集成、端到端测试
- 学习测试驱动开发（TDD）的最佳实践
**示例代码** (`examples/`):
- 配合课程的可运行示例
- 从简单到复杂，循序渐进
**脚本工具** (`scripts/`):
- 日常开发和教学需要的各类脚本
- 详见 [scripts/README.md](scripts/README.md)
---
## 📚 课程大纲
### Module 0: 前置知识与环境搭建
- Python 3.12 新特性概览
- 异步编程基础（async/await）
- 开发环境配置
- **实验**: [Lab 01 - 环境搭建与首次运行](docs/labs/lab01_setup/)
### Module 1: 系统架构设计
- 六边形架构（Hexagonal Architecture）原理
- 为什么选择这种架构？
- CherryQuant 架构解析
- **实验**: [Lab 02 - 追踪数据流](docs/labs/lab02_data_flow/)
- **课程材料**: [docs/course/01_System_Architecture.md](docs/course/01_System_Architecture.md)
### Module 2: 数据管道设计
- 多数据源适配器模式
- 异步数据获取与缓存
- 错误处理与降级策略
- **实验**: [Lab 03 - 实现你的数据源](docs/labs/lab03_data_source/)
- **课程材料**: [docs/course/02_Data_Pipeline.md](docs/course/02_Data_Pipeline.md)
### Module 3: AI 决策引擎
- OpenAI API 集成
- 提示工程（Prompt Engineering）
- AI 决策的可靠性设计
- **实验**: [Lab 04 - 编写你的第一个 AI 交易代理](docs/labs/lab04_ai_agent/)
- **课程材料**: [docs/course/03_AI_Decision_Engine.md](docs/course/03_AI_Decision_Engine.md)
### Module 4: 交易执行与风险管理
- VNPy 框架集成
- 订单管理系统
- 风险控制实现
- **实验**: [Lab 05 - 自定义风险管理器](docs/labs/lab05_risk_manager/)
- **课程材料**: [docs/course/04_Trading_Execution.md](docs/course/04_Trading_Execution.md)
### Module 5: 依赖注入实战 ⭐ 新增
- 为什么需要依赖注入？
- 组合根（Composition Root）模式
- 提高代码可测试性
- **实验**: [Lab 06 - 重构为 DI 模式](docs/labs/lab06_dependency_injection/)
- **课程材料**: [docs/course/05_Dependency_Injection.md](docs/course/05_Dependency_Injection.md)
- **架构决策**: [ADR-0002: 采用依赖注入](docs/adr/0002-dependency-injection.md)
### Module 6: 测试驱动开发 ⭐ 新增
- 单元测试与集成测试
- Mock 和 Stub 技术
- 测试覆盖率分析
- **实验**: [Lab 07 - 为 AI 引擎编写测试](docs/labs/lab07_testing/)
- **课程材料**: [docs/course/06_Testing_Strategies.md](docs/course/06_Testing_Strategies.md)
### Module 7: Python 代码规范 ⭐ 新增
- PEP 8 风格指南
- Type Hints 最佳实践
- Linting 与格式化工具（Ruff, Black, Mypy）
- **实验**: [Lab 08 - 代码质量提升](docs/labs/lab08_code_quality/)
- **课程材料**: [docs/course/07_Python_Best_Practices.md](docs/course/07_Python_Best_Practices.md)
### Module 8: 结构化日志与监控
- Structlog 使用
- 日志最佳实践
- 系统监控基础
- **课程材料**: [LOGGING_GUIDE.md](docs/LOGGING_GUIDE.md)
### Module 9: 毕业项目 🎓
- 设计你自己的交易策略
- 完整系统实现
- 性能优化
- **课程材料**: [docs/course/09_Capstone_Project.md](docs/course/09_Capstone_Project.md)
---
## 🧪 实验练习
所有实验都位于 `docs/labs/` 目录，每个实验包含：
- 📋 **README.md** - 实验目标、步骤、交付物
- 💻 **starter code** - 起始代码模板
- ✅ **test cases** - 自动化测试
- 💡 **hints.md** - 提示（卡住时查看）
### 如何完成实验
1. **阅读实验说明**: `docs/labs/labXX/README.md`
2. **编写代码**: 在 `examples/labs/labXX/` 中完成
3. **运行测试**: `uv run pytest docs/labs/labXX/test_*.py`
4. **提交作业**: 参照实验说明的交付要求
---
## 📂 项目结构（学习版）
```
CherryQuant/ # 项目根目录
├── docs/ # 📚 文档与课程
│ ├── course/ # 课程材料
│ │ ├── 00_Prerequisites.md
│ │ ├── 01_System_Architecture.md
│ │ ├── 02_Data_Pipeline.md
│ │ └── ...
│ ├── labs/ # 🧪 实验说明与测试
│ ├── adr/ # 📝 架构决策记录（学习设计思维）
│ └── reference/ # 📖 参考文档
│ └── advanced/ # 高级主题（可选）
│
├── examples/ # 💡 代码示例
│ ├── 01_basics/ # Module 1 示例
│ ├── 02_data/ # Module 2 示例
│ ├── 03_ai/ # Module 3 示例
│ └── complete_system/ # 完整系统演示
│
├── src/cherryquant/ # 📦 核心代码库（学习重点）
│ ├── bootstrap/ # 🚀 应用启动与依赖注入
│ ├── ai/ # 🤖 AI 决策引擎
│ ├── adapters/ # 🔌 数据与存储适配器
│ ├── services/ # ⚙️ 后台服务
│ └── logging_config.py # 📋 结构化日志配置
│
├── tests/ # ✅ 测试用例（学习测试编写）
├── config/ # ⚙️ 配置管理
├── scripts/teaching/ # 🛠️ 教学辅助脚本
│
├── LEARNING_PATH.md # 🗺️ 详细学习路径
├── README.md # 📖 本文件（学生指南）
└── pyproject.toml # 📦 Python 项目配置
```
### 学习建议
- 📁 **从 `examples/` 开始**: 循序渐进的代码示例
- 📚 **阅读 `docs/course/`**: 理论知识与概念
- 🧪 **完成 `docs/labs/`**: 动手实践，巩固知识
- 🔍 **研究 `src/cherryquant/`**: 深入理解实现细节
- 📝 **学习 `docs/adr/`**: 理解架构决策的思考过程
---
## 🎯 学习成果
完成本课程后，你将能够：
✅ **构建 AI 驱动的应用**
- 集成 OpenAI API
- 设计有效的提示词
- 处理 AI 响应的不确定性
✅ **编写高质量 Python 代码**
- 使用类型提示增强代码可维护性
- 遵循 PEP 8 和最佳实践
- 编写异步代码
✅ **设计可维护的软件架构**
- 应用六边形架构原则
- 实现依赖注入
- 使用设计模式解决常见问题
✅ **开发量化交易系统基础**
- 理解期货交易流程
- 实现数据管道
- 设计风险管理系统
---
## 🎥 额外学习资源
### 推荐阅读
- 📘 **Clean Architecture** by Robert C. Martin
- 📙 **Fluent Python** by Luciano Ramalho
- 📗 **Designing Data-Intensive Applications** by Martin Kleppmann
### 在线资源
- 🌐 [Python 官方文档](https://docs.python.org/3.12/)
- 🌐 [Real Python 教程](https://realpython.com/)
- 🌐 [Hexagonal Architecture 介绍](https://alistair.cockburn.us/hexagonal-architecture/)
- 🌐 [OpenAI API 文档](https://platform.openai.com/docs/)
### 视频教程（计划中）
- 🎬 系统架构讲解
- 🎬 代码演示与实践
- 🎬 实验指导视频
---
## 🤝 学生贡献
我们鼓励学生为项目做贡献！
### 如何贡献
1. **报告问题**: 发现 bug 或文档错误？[提交 Issue](https://github.com/your-username/CherryQuant/issues)
2. **改进文档**: 文档有不清楚的地方？提交 Pull Request
3. **分享示例**: 创建了有趣的交易策略？与大家分享
4. **扩展功能**: 实现了新功能？欢迎贡献
参见：[CONTRIBUTING_STUDENT.md](CONTRIBUTING_STUDENT.md) 获取详细指南
---
## 💬 获取帮助
### 遇到问题？
1. **查看文档**: 99% 的问题在文档中都有答案
- [学习路径](LEARNING_PATH.md)
- [常见问题](docs/FAQ.md)
- [故障排查](docs/reference/advanced/TROUBLESHOOTING.md)
2. **实验提示**: 每个实验都有 `hints.md` 文件
3. **提问**: 在 [GitHub Discussions](https://github.com/your-username/CherryQuant/discussions) 提问
4. **联系教师**: 通过课程平台联系
---
## ⚠️ 重要声明
### 关于交易
> ⚠️ **警告**: 本项目是教学工具，不是投资建议。
>
> - ❌ **不要用于真实交易**
> - ❌ **不保证盈利**
> - ❌ **不提供投资咨询**
> - ✅ **仅用于学习目的**
期货交易存在高风险，可能导致本金全部损失。在考虑真实交易前，请：
- 充分了解风险
- 咨询专业人士
- 从模拟账户开始
### 关于 API 使用
部分高级功能需要外部 API（OpenAI, Tushare）：
- 🆓 **基础学习**: 使用模拟数据，无需 API 密钥
- 💰 **高级功能**: 需要 API 密钥（自费，教学目的）
- ⚠️ **成本注意**: API 调用会产生费用，请谨慎使用
---
## 📄 许可证
本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
**学生使用**: 可以自由使用本项目代码用于学习、作业和个人项目
---
## 🙏 致谢
本教学项目基于真实的量化交易技术栈构建，感谢以下开源项目：
- [vnpy](https://www.vnpy.com/) - Python 量化交易框架
- [Tushare](https://tushare.pro/) - 金融数据 API
- [OpenAI](https://openai.com/) - GPT 大语言模型
- [FastAPI](https://fastapi.tiangolo.com/) - 现代 Web 框架
- [Pydantic](https://pydantic.dev/) - 数据验证库
---
## 📚 文档导航
### 完整文档中心
👉 **[查看完整文档索引](docs/README.md)** - 所有文档的导航中心
### 快速链接
**教学资源**:
- 📖 [课程模块](docs/course/) - 完整的教学材料
- 🧪 [实验指导](docs/labs/) - 动手实践
- 📖 [学习路径](LEARNING_PATH.md) - 10周学习计划
**操作指南**:
- 🚀 [快速开始](docs/guides/quick-start.md) - 5分钟上手
- 💾 [数据下载](docs/guides/data-download.md) - 获取历史数据
- 📝 [日志使用](docs/guides/logging.md) - 日志系统
**技术参考**:
- 🏗️ [系统架构](docs/reference/architecture.md) - 详细设计
- 📋 [架构决策](docs/adr/) - ADR 记录
- 🔌 [API 文档](docs/reference/api/) - 接口说明
**项目报告**:
- ✅ [项目验证](docs/reports/verification.md) - 功能验证
- 🧪 [测试报告](docs/reports/testing.md) - 测试结果
---
## 📬 联系我们
- 💡 **提问**: [GitHub Discussions](https://github.com/your-username/CherryQuant/discussions)
- 🐛 **Bug 报告**: [GitHub Issues](https://github.com/your-username/CherryQuant/issues)
- 📧 **邮件**: teaching@cherryquant.com
---
**准备好开始学习之旅了吗？**
[开始学习 →](LEARNING_PATH.md)
---
Made with ❤️ for Education | CherryQuant Teaching Project