Imported from wtx17/quant_data (
AGENTS.md). Install upstream withnpx skills add wtx17/quant_data. Copyright stays with the author.
quant_data Agent 指南
项目功能
quant_data 是量化研究数据访问库,统一读取本地 Parquet、ClickHouse 和 Tushare。
DataClient.get_panel()返回time × instrument的 Pandas 宽表。get_panel(universe=...)支持hs300、zz500、zz1000三个包内 历史成分面板。- ClickHouse 支持内置 Minghu 表和自定义表。
- Tushare 只读取带 manifest 的本地 Parquet 快照;PIT 和行业日历来自 ClickHouse stock_base.daily。
- Tushare
daily_basic支持普通日频宽表; - Tushare 财务披露数据支持交易日对齐的 point-in-time 面板。
- 行业成分支持有效区间展开。
- 每次查询都写入不含凭据的 JSON 审计记录。
默认数据集和字段见 DATASETS.md,由 initialize.py 统一注册。
运行环境
- Python:
>=3.11 - 环境:
conda activate qt。 - 非交互 shell:
source /opt/anaconda3/etc/profile.d/conda.sh
conda activate qt
conda 环境已经配置好以下环境变量:
- ClickHouse:
QUANT_DATA_CLICKHOUSE_*、MINGHU_CLICKHOUSE_*。 - 本地存档:
QUANT_DATA_TUSHARE_DATA_DIR(也可显式传 tushare_data_dir)。
测试环境
默认使用 qt Conda 环境,从仓库根目录执行。
安全的离线测试:
pytest -m "not clickhouse"
ruff check .
mypy .
python tools/generate_dataset_catalog.py --check
全量测试:
pytest
真实 ClickHouse 集成测试:
pytest -m clickhouse tests/test_clickhouse_integration.py
集成测试需要 MINGHU_CLICKHOUSE_HOST、MINGHU_CLICKHOUSE_USERNAME、
MINGHU_CLICKHOUSE_PASSWORD;端口、TLS 和测试日期可分别由
MINGHU_CLICKHOUSE_PORT、MINGHU_CLICKHOUSE_SECURE、
MINGHU_CLICKHOUSE_TEST_DATE 配置。
仅检查本次修改的 Python 文件格式:
ruff format --check path/to/changed.py
修改命名股票池或其解析逻辑时,至少运行:
pytest tests/test_universes.py tests/test_client.py tests/test_clickhouse.py
同时构建 wheel,并确认 quant_data/resources/universes/*.csv 已被打包。
修改约束
DATASETS.md由tools/generate_dataset_catalog.py生成,不要手工修改。tools/dataset_descriptions.toml是get_panel()输出说明:fields只包含可请求 的宽表值,每项必须有description和最终 Pandas Arrowoutput_dtype。面板 索引及证券列键不得列入;其他可请求的日期和身份字段仍须保留。来源 schema 和 读取配置留在后端 catalog,输出类型由catalog.py离线校验,不从 TOML 生成后端。get_panel()的universe只接受hs300、zz500、zz1000(忽略大小写和 首尾空白)的单个名称或非空名称列表;列表按输入顺序展开成分并集,名称和证券 保留首次出现顺序去重。必须同时提供闭区间start/end,并与instruments互斥。 查询方法必须拒绝裸字符串形式的instruments,单证券也应放入列表。- 股票池资源位于
resources/universes/,运行时不得依赖仓库外的源文件。<name>_panel.csv的第一列为change_date,后续列为全历史证券,行是从该日期 起生效的 0/1 状态;日期、代码、行宽和掩码严格校验,每行 1 的数量分别为 300/500/1000。 - 命名股票池必须在审计初始化后、数据集读取前展开。对
[start, end],选择start当日状态以及之后至end的所有调仓状态的证券并集;首行之前为空,末行 之后延续末状态。审计和面板参数需要保留规范化名称、panel 首末 change date、 选中数量、CSV SHA-256 以及完整展开列表;解析失败也必须写失败审计。 列表调用的 universe 元数据为 names、panels(各池原有元数据)、count(并集数量); 字符串调用保留原有结构。 - 展开后的股票池与手工传入完整
instruments列表使用相同的读取路径。不要隐式 改成全市场数据扫描;日历独立查询全市场去重日期。 - 修改 Tushare 字段时,同步更新:
backends/tushare_schemas.pytools/dataset_descriptions.tomltests/test_tushare_schemas.py- 重新生成
DATASETS.md
- 修改 ClickHouse 内置字段时,同步更新
backends/clickhouse_catalog.py和集成校验。 - 全部 Tushare 数据集必须使用本地存档。初始化要求
tushare_data_dir或对应环境变量;daily_basic无需日历,财务及行业通过 ClickHousestock_base.daily获取日历。 - 内部扫描仍使用 Arrow 长表;保留财务 PIT 的公告、修订及行业成分的有效区间。
- 自定义数据源不要求声明频率,也不检查分钟及以上粒度。
- 不要在审计、异常、日志或
repr中写入密码和 token。 - 不要在未确认兼容策略时放宽 Tushare Parquet manifest 和分区 schema 校验。
架构说明见 .agent/architecture.md,代码定位见 .agent/repo-map.md。
