bighf-builder-skills-v1
BigQuant 高频因子仓库开发指南。在用户需要创建、迁移、审查高频因子 Builder、Schema、Mixin、测试用例，或查询高频数据时使用此 skill。当用户提到高频因子、高频数据、tick 数据、分钟数据、L1/L2 行情、快照数据、委托队列、成交明细、逐笔数据、因子计算、因子构建、因子审查、因子验证、IC 检验、ICIR、Builder 迁移、HF Builder、HF 数据源等关键词时，即使没有明确要求，也应主动使用此 skill 来确保代码符合 bighfwarehouse 项目规范。
来源：SKILL.md
# BigHFWarehouse 高频因子开发指南
BigQuant 高频因子仓库，基于高频原始数据（tick/分钟级）**构建日频因子**并存储。因子输出通常是日频的，原始输入数据才是高频的。基于 `hfwarehouse/builder/` 架构。
## 频率约定（强制）
**所有因子必须按日度交易日严格计算，每个交易日输出一条记录。**
研报或论文中为减少计算量，有时仅计算每月最后一个交易日的数据。本项目不采用此裁剪策略：
- 必须对每个交易日独立完整地计算因子值，不得跳过任何交易日
- 计算逻辑可以使用回溯窗口（如过去 20/60 个交易日），但输出粒度必须是**逐日**的
- 禁止使用月末值向前填充（forward fill）替代日度计算
> 原因：仓库下游消费方统一按日频对齐，缺失交易日会导致数据对齐异常。
## 项目约定
- Python >= 3.11
- 核心依赖: polars, numpy, pyarrow, pydantic, dai
- DataFrame **必须**使用 polars (`dai.query(sql).pl()`)，禁止使用 pandas
- 依赖管理: `uv sync`
- Lint/格式化: `prek run -d <目标目录>`
- 审核阶段：新建因子一律落 `hfwarehouse/builder/staging/`，**审核通过后**才搬到 `output/` 并注册每日增量任务。agent 不得自行判定审核通过。两个阶段都可以写入 DAI（调试期也需要落库做因子分析检验），详见 `references/builder.md`「阶段目录：staging 与 output」
## dai 数据查询
高频数据量极大，查询有三条铁律：
1. **禁止全表扫描** — 永远不使用 `full_db_scan=True`
2. **必须用日期时间过滤** — 高频表过滤值必须包含时间部分（如 `'2024-01-02 00:00:00.000'`），仅用日期（`'2024-01-02'`）无法覆盖当天全部高频数据；日频表也可统一使用带时间部分的字符串，与高频表保持一致
3. **按需查询** — 只查需要的表、需要的列、需要的时间范围，不多查，不扩大范围
```python
import dai
# 正确: 过滤值包含时间部分，只选需要的列
date = "2024-01-02"
sql = f"""
SELECT date, instrument, open, close, volume
FROM my_hf_datasource
WHERE date >= '{date} 00:00:00.000'
AND date <= '{date} 23:59:59.999'
"""
df = dai.query(sql).pl()
# 错误: 过滤值仅写日期，无法覆盖当天全部高频数据
# df = dai.query("SELECT date, instrument FROM my_hf_datasource WHERE date = '2024-01-02'").pl()
# 禁止: 全表扫描 (高频数据量太大)
# df = dai.query(sql, full_db_scan=True).pl()
```
## 参考文档与触发规则
| 场景 | 操作 |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 构建新 Builder | 查 `references/sources/{datasource_id}.md` 了解原始表字段；读 `references/builder.md` 按步骤实现；若有**明确的**因子出处（用户提供或 PDF 中可直接读到），将其附加到 schema 对应因子字段的 `description` 末尾（格式：`。来源：{作者}. {发表日期}. {标题}. {机构}`，**发表日期尽可能精确到日**以锁定系列研报中的具体一篇），不得猜测或推断 |
| 用户提供 PDF 研报 | 阅读 `references/research-report.md`；读 PDF 时**顺手把发布日期抓下来**（首页署名行 / 页眉页脚 / 文件名，精确到日），它是 `## 文献来源` 与 schema 来源信息的必填项，漏了要重新翻 PDF；**动手前先做「第 0 步：查重」**——扫 `staging/` 与 `output/` 目录初筛，再逐个打开命中表的 `{datasource_id}.md` 比对 `## 文献来源` 小节，确认这篇研报的因子是否已建过，只构建未建部分 |
| 编写或修改 `{datasource_id}.md` 因子构建文档 | 阅读 `references/research-report.md`「markdown 文件格式」；文档必须含 `## 文献来源`（来源明确时）、`## 表结构`（表名 + 主键 + 逐字段类型与含义）、`## 依赖数据`（逐张上游表 + 频率 + 用到的字段 + 用途）三个顶部小节，研报复现还须含 `## 复现核对`，末尾须有 `## 示例数据` 小节（含 `{{sample_data}}` 占位符） |
| 需要说明本表依赖哪些前置数据表 | 阅读 `references/research-report.md`「`## 依赖数据` 小节」；依据 `builder.py` 中 `_build()` 的 SQL，把 `FROM` / `JOIN` 到的每张表逐行写进 `## 依赖数据` 小节，一张不漏，字段逐个列全，不得凭因子含义猜表 |
| 研报复现完成 / 跑完 IC 检验 | 按 `references/research-report.md`「`## 复现核对` 小节」把本项目结果与研报原文数值逐因子对照写进 `{datasource_id}.md`，供人工判断复现质量；对不上如实写差异，不得调参数去凑研报 |
| 生成或修改 Builder 代码后 | 阅读 `references/code-review.md` 逐项自检 → 阅读 `references/build-validation.md` 按三步完成构建验证 |
| 用户要求审查代码 | 阅读 `references/code-review.md` 逐项检查 |
| 迁移 Builder | 读源文件 → 按项目约定适配后写入目标目录 → 阅读 `references/code-review.md` 自检；阅读 `references/build-validation.md` 按三步完成构建验证 |
| 需要编写测试 | 阅读 `references/testing.md` |
| 编写 DAI SQL 因子计算逻辑 | **必须先查** `references/dai_functions.md`，从中选取 c_/m_/m_ta_ 函数；**严禁凭记忆写函数名**，所有函数名必须在文档中能找到；能用 SQL 表达的因子逻辑优先在 SQL 中实现，仅当 SQL 难以表达时才用 Python 补充 |
| 查询数据源字段 | 查 `references/sources/{datasource_id}.md` |
| 用户要求提交增量 / 因子审核通过 | 阅读 `references/builder.md`「阶段目录：staging 与 output」，按流转动作把目录从 `staging/` 搬到 `output/` 并改 notebook 导入路径 |
| 用户要求入库 / 写入因子数据做分析 | 直接运行 `{datasource_id}.ipynb`，`staging/` 与 `output/` 都允许入库；无需搬目录 |
| 回填历史数据 / 写 notebook 历史 cell | 历史区间**必须按自然年分批**：每年 `_build` 后立即 `dai_write`，禁止单次 `_build(start, end)` 跨多年；见 `references/builder.md`「Notebook 入口」 |
| 用户要求更新文档 / 改完 `{datasource_id}.md` 要同步到平台 | 运行 `{datasource_id}.ipynb` 第三段的 `update_docs()`，详见 `references/builder.md`「数据源文档更新」；不必重跑因子 |
| 创建 / 修改 notebook | notebook 第四段是 `AlphaMiner` 因子分析与单因子回测模板，新建因子时**必须照抄写入且整段保持 `# ` 注释**、默认不运行；模板与占位改法见 `references/builder.md`「Notebook 入口」Cell 7/8 |
| 用户要求做因子分析 / 单因子回测 / 更深入的因子检验 | 取消 notebook 第四段的注释，按当前因子改 `alpha_name`、`alpha_sql`、`factor_direction` 与日期区间后运行；前提是因子已入库 |
`cn_stock_prefactors` 是聚合日频 view，包含股票名称、股本、OHLC 等绝大多数日频字段，能用时优先使用，避免查多张原始表。