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 qtconda 环境已经配置好以下环境变量：
- 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。
