refactor: 存储层迁移DuckDB + 模块重构
- 存储层重构: HDF5 → DuckDB（UPSERT模式、线程安全存储） - Sync类迁移: DataSync从sync.py迁移到api_daily.py（职责分离） - 模型模块重构: src/models → src/pipeline（更清晰的命名） - 新增因子模块: factors/momentum (MA、收益率排名)、factors/financial - 新增API接口: api_namechange、api_bak_basic - 新增训练入口: training模块（main.py、pipeline配置） - 工具函数统一: get_today_date等移至utils.py - 文档更新: AGENTS.md添加架构变更历史
This commit is contained in:
117
AGENTS.md
117
AGENTS.md
@@ -2,6 +2,15 @@
|
||||
|
||||
A股量化投资框架 - Python 项目，用于量化股票投资分析。
|
||||
|
||||
## 交流语言要求
|
||||
|
||||
**⚠️ 强制要求：所有沟通和思考过程必须使用中文。**
|
||||
|
||||
所有与 AI Agent 的交流必须使用中文
|
||||
代码中的注释和文档字符串使用中文
|
||||
禁止使用英文进行思考或沟通
|
||||
|
||||
|
||||
## 构建/检查/测试命令
|
||||
|
||||
**⚠️ 重要：本项目强制使用 uv 作为 Python 包管理器和运行工具。禁止直接使用 `python` 或 `pip` 命令。**
|
||||
@@ -67,25 +76,69 @@ uv run pytest tests/test_sync.py # ✅ 正确
|
||||
```
|
||||
ProStock/
|
||||
├── src/ # 源代码
|
||||
│ ├── data/ # 数据采集模块
|
||||
│ ├── config/ # 配置管理
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── client.py # Tushare API 客户端，带速率限制
|
||||
│ │ ├── config.py # 配置（pydantic-settings）
|
||||
│ │ ├── daily.py # 日线市场数据
|
||||
│ │ └── settings.py # pydantic-settings 配置
|
||||
│ │
|
||||
│ ├── data/ # 数据获取与存储
|
||||
│ │ ├── api_wrappers/ # Tushare API 封装
|
||||
│ │ │ ├── API_INTERFACE_SPEC.md # 接口规范文档
|
||||
│ │ │ ├── api.md # API 接口定义
|
||||
│ │ │ ├── api_daily.py # 日线数据接口
|
||||
│ │ │ ├── api_stock_basic.py # 股票基础信息接口
|
||||
│ │ │ ├── api_trade_cal.py # 交易日历接口
|
||||
│ │ │ └── __init__.py
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── client.py # Tushare API 客户端（带速率限制）
|
||||
│ │ ├── config.py # 数据模块配置
|
||||
│ │ ├── db_inspector.py # 数据库信息查看工具
|
||||
│ │ ├── db_manager.py # DuckDB 表管理和同步
|
||||
│ │ ├── rate_limiter.py # 令牌桶速率限制器
|
||||
│ │ ├── stock_basic.py # 股票基本信息
|
||||
│ │ ├── storage.py # HDF5 存储管理器
|
||||
│ │ └── sync.py # 数据同步
|
||||
│ ├── config/ # 全局配置
|
||||
│ │ ├── storage.py # 数据存储核心
|
||||
│ │ └── sync.py # 数据同步主逻辑
|
||||
│ │
|
||||
│ ├── factors/ # 因子计算框架
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── settings.py # 应用设置（pydantic-settings）
|
||||
│ └── __init__.py
|
||||
│ │ ├── base.py # 因子基类（截面/时序）
|
||||
│ │ ├── composite.py # 组合因子和标量运算
|
||||
│ │ ├── data_loader.py # 数据加载器
|
||||
│ │ ├── data_spec.py # 数据规格定义
|
||||
│ │ ├── engine.py # 因子执行引擎
|
||||
│ │ ├── momentum/ # 动量因子
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── ma.py # 移动平均线
|
||||
│ │ │ └── return_rank.py # 收益排名
|
||||
│ │ └── financial/ # 财务因子
|
||||
│ │ └── __init__.py
|
||||
│ │
|
||||
│ ├── pipeline/ # 模型训练管道
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── pipeline.py # 处理流水线
|
||||
│ │ ├── registry.py # 插件注册中心
|
||||
│ │ ├── core/ # 核心抽象
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── base.py # 基类定义
|
||||
│ │ │ └── splitter.py # 时间序列划分策略
|
||||
│ │ ├── models/ # 模型实现
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ └── models.py # LightGBM、CatBoost 等
|
||||
│ │ └── processors/ # 数据处理器
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── processors.py # 标准化、缩尾、中性化等
|
||||
│ │
|
||||
│ └── training/ # 训练入口
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py # 训练主程序
|
||||
│ ├── pipeline.py # 训练流程配置
|
||||
│ └── output/ # 训练输出
|
||||
│ └── top_stocks.tsv # 推荐股票结果
|
||||
│
|
||||
├── tests/ # 测试文件
|
||||
│ ├── test_sync.py
|
||||
│ └── test_daily.py
|
||||
├── config/ # 配置文件
|
||||
│ └── .env.local # 环境变量（不在 git 中）
|
||||
├── data/ # 数据存储（HDF5 文件）
|
||||
├── data/ # 数据存储（DuckDB）
|
||||
├── docs/ # 文档
|
||||
├── pyproject.toml # 项目配置
|
||||
└── README.md
|
||||
@@ -182,10 +235,10 @@ except Exception as e:
|
||||
- 对配置单例使用 `@lru_cache()`
|
||||
|
||||
### 数据存储
|
||||
- 通过 `pandas.HDFStore` 使用 **HDF5 格式** 进行持久化
|
||||
- 使用 **DuckDB** 嵌入式 OLAP 数据库进行持久化
|
||||
- 存储在 `data/` 目录中（通过 `DATA_PATH` 环境变量配置）
|
||||
- 对可追加数据集使用 `format="table"`
|
||||
- 追加时处理重复项：`drop_duplicates(subset=[...])`
|
||||
- 使用 UPSERT 模式（`INSERT OR REPLACE`）处理重复数据
|
||||
- 多线程场景使用 `ThreadSafeStorage.queue_save()` + `flush()` 模式
|
||||
|
||||
### 线程与并发
|
||||
- 对 I/O 密集型任务（API 调用）使用 `ThreadPoolExecutor`
|
||||
@@ -240,3 +293,39 @@ uv run python -c "from src.data.sync import sync_all; sync_all(force_full=True)"
|
||||
# 自定义线程数
|
||||
uv run python -c "from src.data.sync import sync_all; sync_all(max_workers=20)"
|
||||
```
|
||||
|
||||
## 架构变更历史
|
||||
|
||||
### v2.0 (2026-02-23) - 重要更新
|
||||
|
||||
#### 存储层重构
|
||||
**变更**: 从 HDF5 迁移到 DuckDB
|
||||
**原因**: DuckDB 提供更好的查询性能、SQL 下推能力、并发支持
|
||||
**影响**: 所有数据表现在使用 DuckDB 存储，旧 HDF5 文件可手动迁移
|
||||
|
||||
#### Sync 类迁移
|
||||
**变更**: `DataSync` 类从 `sync.py` 迁移到 `api_daily.py`
|
||||
**原因**: 实现代码职责分离，每个 API 文件包含自己的同步逻辑
|
||||
**影响**:
|
||||
- `sync.py` 保留为调度中心
|
||||
- `api_daily.py` 包含 `DailySync` 类和 `sync_daily` 函数
|
||||
|
||||
#### 新增模块
|
||||
**pipeline 模块**: 机器学习流水线组件（处理器、模型、划分策略）
|
||||
**training 模块**: 训练入口程序
|
||||
**factors/momentum**: 动量因子（MA、收益率排名）
|
||||
**factors/financial**: 财务因子框架
|
||||
**data/utils.py**: 日期工具函数集中管理
|
||||
|
||||
#### 新增 API 接口
|
||||
`api_namechange.py`: 股票曾用名接口（手动同步）
|
||||
`api_bak_basic.py`: 历史股票列表接口
|
||||
|
||||
#### 工具函数统一
|
||||
`get_today_date()`、`get_next_date()`、`DEFAULT_START_DATE` 等函数统一在 `src/data/utils.py` 中管理
|
||||
其他模块应从 `utils.py` 导入这些函数，避免重复定义
|
||||
|
||||
### v1.x (历史版本)
|
||||
|
||||
初始版本，使用 HDF5 存储
|
||||
数据同步逻辑集中在 `sync.py`
|
||||
|
||||
Reference in New Issue
Block a user