重要说明：CherryQuant 是专门设计用于大学课程教学的项目，目标是帮助学生学习现代 Python 开发、软件架构设计、AI 集成和量化交易概念。
本项目不是生产级交易系统，不应用于真实交易。
通过学习本项目，学生将掌握：
- 🤖 大语言模型（LLM）集成与应用
- 📝 提示工程（Prompt Engineering）最佳实践
- 🔄 异步 AI API 调用与错误处理
- 💰 成本优化与速率限制策略
- ✅ 类型提示（Type Hints）与 Mypy 静态检查
- 🔀 异步编程（async/await）模式
- 📦 现代包管理（pyproject.toml + uv）
- 🧪 测试驱动开发（TDD）与代码覆盖率
- 🏛️ 六边形架构（Hexagonal Architecture）
- 💉 依赖注入（Dependency Injection）
- 🔌 适配器模式（Adapter Pattern）
- 🎯 设计模式实战应用
- 📊 中国期货市场基础知识
- 🔍 技术分析与策略设计
- ⚖️ 风险管理系统
- 📈 回测与性能评估
第 1-2 周 │ 📚 基础准备
├─ 环境搭建与 Python 3.12+ 基础
├─ 运行第一个示例
└─ 理解项目结构
第 3-4 周 │ 🏗️ 系统架构
├─ 六边形架构原理
├─ 数据管道设计
└─ 适配器模式实践
第 5-6 周 │ 🤖 AI 集成
├─ OpenAI API 使用
├─ 提示工程技巧
└─ AI 决策引擎实现
第 7-8 周 │ 💉 高级模式
├─ 依赖注入实战
├─ 测试策略
└─ 代码质量提升
第 9-10 周│ 🚀 综合实践
├─ 毕业项目设计
├─ 性能优化
└─ 部署与运维
详细学习路径: 请参阅 LEARNING_PATH.md
在开始之前，请确保你具备：
- ✅ Python 编程基础（中级水平，熟悉函数、类）
- ✅ 命令行基础（能够使用终端/命令提示符）
- ✅ Git 基础（clone, commit, push）
- 🔶 异步编程了解（推荐但非必需，课程中会讲解）
git clone https://github.com/your-username/CherryQuant.git
cd CherryQuant# 自动安装依赖和配置环境（学生版，无需 API 密钥）
bash scripts/teaching/student_setup.sh这个脚本会：
- ✅ 检查 Python 3.12+
- ✅ 安装 uv 包管理器
- ✅ 安装所有依赖
- ✅ 生成模拟数据（无需外部 API）
- ✅ 创建学生版配置文件
# 运行 Hello World 示例
uv run python examples/01_basics/hello_cherryquant.py你应该看到：
🍒 欢迎来到 CherryQuant 教学项目！
✅ 系统配置正常
✅ 模拟数据已加载
📚 准备开始学习之旅...
恭喜！ 你已经成功配置了学习环境。
CherryQuant 提供了丰富的脚本来简化常见任务。所有脚本都位于 scripts/ 目录下，按功能分类。
推荐使用 - 功能完整，支持多种模式
# 模拟交易模式（推荐学习）
uv run python run_cherryquant.py simulation
# 回测模式
uv run python run_cherryquant.py backtest
# 实盘模式（需要真实账户，不推荐学生）
uv run python run_cherryquant.py live新手友好 - 交互式选择运行模式
bash start.sh自动执行：
- ✅ 环境检查（uv, Python 3.12）
- ✅ 依赖安装
- ✅ 配置验证
- ✅ 交互式模式选择
# 学生环境一键配置
bash scripts/teaching/student_setup.sh
# 环境验证（Lab 01需要）
uv run python scripts/teaching/verify_environment.py# 初始化历史数据
uv run python scripts/data/init_historical_data.py
# 指定品种和日期范围
uv run python scripts/data/init_historical_data.py --symbols rb2501,hc2501 --start 20240101# 修复.env文件中的重复配置
uv run python scripts/utils/fix_env_config.py
# 数据库迁移（PostgreSQL → MongoDB）
uv run python scripts/utils/migrate_postgres_to_mongodb.py# 完整多代理系统
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
- 每个脚本的详细用途
- 参数说明和使用示例
- 按用户角色推荐的脚本
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
测试代码 (tests/):
- 完整的测试套件，覆盖单元、集成、端到端测试
- 学习测试驱动开发（TDD）的最佳实践
示例代码 (examples/):
- 配合课程的可运行示例
- 从简单到复杂，循序渐进
脚本工具 (scripts/):
- 日常开发和教学需要的各类脚本
- 详见 scripts/README.md
- Python 3.12 新特性概览
- 异步编程基础（async/await）
- 开发环境配置
- 实验: Lab 01 - 环境搭建与首次运行
- 六边形架构（Hexagonal Architecture）原理
- 为什么选择这种架构？
- CherryQuant 架构解析
- 实验: Lab 02 - 追踪数据流
- 课程材料: docs/course/01_System_Architecture.md
- 多数据源适配器模式
- 异步数据获取与缓存
- 错误处理与降级策略
- 实验: Lab 03 - 实现你的数据源
- 课程材料: docs/course/02_Data_Pipeline.md
- OpenAI API 集成
- 提示工程（Prompt Engineering）
- AI 决策的可靠性设计
- 实验: Lab 04 - 编写你的第一个 AI 交易代理
- 课程材料: docs/course/03_AI_Decision_Engine.md
- VNPy 框架集成
- 订单管理系统
- 风险控制实现
- 实验: Lab 05 - 自定义风险管理器
- 课程材料: docs/course/04_Trading_Execution.md
- 为什么需要依赖注入？
- 组合根（Composition Root）模式
- 提高代码可测试性
- 实验: Lab 06 - 重构为 DI 模式
- 课程材料: docs/course/05_Dependency_Injection.md
- 架构决策: ADR-0002: 采用依赖注入
- 单元测试与集成测试
- Mock 和 Stub 技术
- 测试覆盖率分析
- 实验: Lab 07 - 为 AI 引擎编写测试
- 课程材料: docs/course/06_Testing_Strategies.md
- PEP 8 风格指南
- Type Hints 最佳实践
- Linting 与格式化工具（Ruff, Black, Mypy）
- 实验: Lab 08 - 代码质量提升
- 课程材料: docs/course/07_Python_Best_Practices.md
- Structlog 使用
- 日志最佳实践
- 系统监控基础
- 课程材料: LOGGING_GUIDE.md
- 设计你自己的交易策略
- 完整系统实现
- 性能优化
- 课程材料: docs/course/09_Capstone_Project.md
所有实验都位于 docs/labs/ 目录，每个实验包含：
- 📋 README.md - 实验目标、步骤、交付物
- 💻 starter code - 起始代码模板
- ✅ test cases - 自动化测试
- 💡 hints.md - 提示（卡住时查看）
- 阅读实验说明:
docs/labs/labXX/README.md - 编写代码: 在
examples/labs/labXX/中完成 - 运行测试:
uv run pytest docs/labs/labXX/test_*.py - 提交作业: 参照实验说明的交付要求
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
- 🎬 系统架构讲解
- 🎬 代码演示与实践
- 🎬 实验指导视频
我们鼓励学生为项目做贡献！
- 报告问题: 发现 bug 或文档错误？提交 Issue
- 改进文档: 文档有不清楚的地方？提交 Pull Request
- 分享示例: 创建了有趣的交易策略？与大家分享
- 扩展功能: 实现了新功能？欢迎贡献
参见：CONTRIBUTING_STUDENT.md 获取详细指南
-
查看文档: 99% 的问题在文档中都有答案
-
实验提示: 每个实验都有
hints.md文件 -
提问: 在 GitHub Discussions 提问
-
联系教师: 通过课程平台联系
⚠️ 警告: 本项目是教学工具，不是投资建议。
- ❌ 不要用于真实交易
- ❌ 不保证盈利
- ❌ 不提供投资咨询
- ✅ 仅用于学习目的
期货交易存在高风险，可能导致本金全部损失。在考虑真实交易前，请：
- 充分了解风险
- 咨询专业人士
- 从模拟账户开始
部分高级功能需要外部 API（OpenAI, Tushare）：
- 🆓 基础学习: 使用模拟数据，无需 API 密钥
- 💰 高级功能: 需要 API 密钥（自费，教学目的）
⚠️ 成本注意: API 调用会产生费用，请谨慎使用
本项目采用 MIT 许可证 - 详见 LICENSE 文件
学生使用: 可以自由使用本项目代码用于学习、作业和个人项目
本教学项目基于真实的量化交易技术栈构建，感谢以下开源项目：
👉 查看完整文档索引 - 所有文档的导航中心
教学资源:
操作指南:
技术参考:
项目报告:
- 💡 提问: GitHub Discussions
- 🐛 Bug 报告: GitHub Issues
- 📧 邮件: teaching@cherryquant.com