quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/factor_test/config.py

@@ -0,0 +1,184 @@
+# coding: utf-8
+"""Pydantic 配置模型 / Configuration Models"""
+
+from pydantic import BaseModel, Field
+from typing import Optional
+
+
+class FactorSetting(BaseModel):
+    """因子配置"""
+    name: str = Field(..., description="因子名称")
+    factor_dir: str = Field(..., description="因子文件路径")
+    factor_key: str = Field(default='', description="H5 key (如因子在 H5 中)")
+    format: str = Field(default='h5', description="数据格式: h5/csv/npy/parquet")
+    hypothesis: str = Field(default='', description="研究假设 (供 LLM 一致性检查)")
+    description: str = Field(default='', description="因子描述 (供 LLM 一致性检查)")
+    expression: str = Field(default='', description="代码表达式 (供 LLM 一致性检查)")
+
+
+class TradableSetting(BaseModel):
+    """可交易性配置"""
+    no_st: bool = Field(default=True, description="剔除 ST")
+    no_suspended: bool = Field(default=True, description="剔除停牌")
+    no_up_down_limit: bool = Field(default=False, description="剔除涨跌停")
+    min_ipo_days: int = Field(default=360, description="剔除上市不足 N 日的新股")
+    trace: Optional[dict] = Field(default=None, description="追踪条件, e.g. {'suspend': (25, 1)}")
+
+
+class PreprocessSetting(BaseModel):
+    """预处理配置
+
+    T0-2/T0-3 (Phase 3.1):
+    - adj_date_beg/end 改 Optional[int]=None (H10 兼容, 启动校验抛错)
+    - 新增 3 隐式默认 Pydantic 字段 (mad_n=5.0, pct_low=0.025, pct_high=0.975, M5)
+    M12: 新增 i18n_name_map 自定义行业名称映射 (覆盖全局默认 INDUSTRY_MAPPING)
+    """
+    adj_date_beg: Optional[int] = Field(
+        default=None, description="起始日期 yyyymmdd (H10: None → 启动报错)"
+    )
+    adj_date_end: Optional[int] = Field(
+        default=None, description="截止日期 yyyymmdd (H10: None → 启动报错)"
+    )
+    adj_mode: list = Field(default=['M', 'end'], description="调仓模式: [mode, position]")
+    sample_index: str = Field(default='all', description="样本池: all/HS300/ZZ500/ZZ800/custom")
+    sample_index_customdir: Optional[tuple] = Field(
+        default=None, description="自定义样本池路径 (sample_index=custom 时必填)"
+    )
+    sample_industry: str = Field(default='all', description="行业筛选: all/中信行业名")
+    tradable: TradableSetting = Field(default_factory=TradableSetting)
+    missing: str = Field(default='', description="缺失值处理: ''/ind_avg")
+    extreme: str = Field(default='', description="去极值: ''/median/pct_shrink")
+    norm: str = Field(default='', description="标准化: ''/zscore/norm")
+    industry_neutral: bool = Field(default=False, description="行业中性化")
+    risk_neutral: bool = Field(default=False, description="风险因子中性化")
+    risk_factors: list = Field(default_factory=list, description="风险因子: [(file, key), ...]")
+    # T0-2: 隐式默认从节点 __init__ 提升到 Pydantic 字段
+    mad_n: float = Field(default=5.0, description="median winsorize 倍数 (M5)")
+    pct_low: float = Field(default=0.025, description="pct_shrink 下分位 (M5)")
+    pct_high: float = Field(default=0.975, description="pct_shrink 上分位 (M5)")
+    # M12: 自定义行业名称映射 (中文→英文, key=code 列名, value=行业名) → 覆盖全局 INDUSTRY_MAPPING
+    i18n_name_map: Optional[dict[str, str]] = Field(
+        default=None,
+        description="自定义行业名称映射 (key: 列名, value: 显示名) → 覆盖全局 INDUSTRY_MAPPING",
+    )
+
+
+class ICSetting(BaseModel):
+    """IC 分析配置"""
+    min_group_size: int = Field(default=5, description="计算 IC 最少需要的因子值数量")
+
+
+class GroupSetting(BaseModel):
+    """分组分析配置"""
+    groups: int = Field(default=5, description="分组数")
+    factor_direction: int = Field(default=1, description="因子方向: 1=越大越好, -1=越小越好")
+    floor_mode: str = Field(
+        default='group', description="数据不足时策略: group=跳过, last=沿用上期"
+    )
+    hedge: str = Field(default='equal', description="对冲基准: HS300/ZZ500/equal/custom")
+    hedge_path: Optional[str] = Field(default=None, description="自定义对冲基准路径")
+
+
+class LongShortSetting(BaseModel):
+    """多空组合配置"""
+    factor_direction: int = Field(default=1, description="因子方向: 1=越大越好, -1=越小越好")
+
+
+class ScoreSetting(BaseModel):
+    """市值行业分层打分配置
+
+    T0-2 (Phase 3.1): 新增 3 隐式默认 Pydantic 字段
+    (n_industries=29, n_size_groups=3, n_quantile_groups=5, H15).
+    """
+    enabled: bool = Field(default=True, description="是否运行")
+    n_industries: int = Field(default=29, description="行业数 (中信 29 / 申万 30, H15)")
+    n_size_groups: int = Field(default=3, description="市值分组数 (H15)")
+    n_quantile_groups: int = Field(default=5, description="因子分位数 (H15)")
+
+
+class RiskCorrelationSetting(BaseModel):
+    """风险因子相关性配置"""
+    factors: str = Field(default='all', description="风险因子: 'all' 或 [(file, key), ...]")
+
+
+class AnalysisSetting(BaseModel):
+    """分析配置"""
+    ic: ICSetting = Field(default_factory=ICSetting)
+    group: GroupSetting = Field(default_factory=GroupSetting)
+    longshort: LongShortSetting = Field(default_factory=LongShortSetting)
+    score: ScoreSetting = Field(default_factory=ScoreSetting)
+    risk_corr: RiskCorrelationSetting = Field(default_factory=RiskCorrelationSetting)
+
+
+class OutputSetting(BaseModel):
+    """输出配置"""
+    dir: str = Field(default='./output/', description="输出目录")
+    format: list = Field(default=['parquet', 'json'], description="输出格式")
+
+
+class FeedbackSetting(BaseModel):
+    """FactorFeedback 集成配置
+
+    enabled=False 时, 现有行为完全不变 (向后兼容)。
+    enabled=True 时, pipeline_runner 自动包装 5 个分析节点返回为 FactorFeedback,
+    聚合到 ctx['Feedback'], 并可选择持久化到 output_dir。
+    """
+    enabled: bool = Field(default=False, description="是否启用 FactorFeedback 自动包装")
+    output_dir: Optional[str] = Field(
+        default=None,
+        description="Parquet/JSON 持久化目录 (None=不持久化, 仅返回 ctx)",
+    )
+    judge_enabled: bool = Field(
+        default=False, description="是否启用 LLMJudge (hypothesis↔expression 一致性)"
+    )
+    judge_model: str = Field(default="mock", description="LLMJudge 模型名 (mock/deepseek-v3/...)")
+    judge_max_attempts: int = Field(default=3, description="LLMJudge 解析失败最大重试次数")
+
+
+class QualityGateConfig(BaseModel):
+    """QualityGate 集成配置 (Week 3)。
+
+    enabled=False: 不构造 QualityGateNode, 行为不变
+    enabled=True:  构造 QualityGateNode, 可在 run_evolution() 中拦截低质量因子
+    """
+    enabled: bool = Field(default=False, description="是否启用 QualityGateNode")
+    zoo_path: Optional[str] = Field(default=None, description="FactorZoo 路径 (None=内存)")
+
+
+class EvolutionConfig(BaseModel):
+    """演化主循环配置 (Week 4)。
+
+    enabled=False: 不演化, run_evolution() 抛错
+    enabled=True:  启用多轮演化循环
+    """
+    enabled: bool = Field(default=False, description="是否启用演化模式")
+    max_rounds: int = Field(default=3, description="演化总轮数 (不含 round 0 原始)")
+    parents_per_round: int = Field(default=1, description="每轮选几个 parent (crossover 时强制 2)")
+    parent_selection_strategy: str = Field(
+        default="top_percent_plus_random",
+        description="选择策略: best/random/weighted/weighted_inverse/top_percent_plus_random",
+    )
+    top_percent_threshold: float = Field(default=0.3, description="top_percent_plus_random 阈值")
+    metric: str = Field(default="sharpe", description="用于排序/加权的指标")
+    pool_dir: Optional[str] = Field(
+        default=None, description="TrajectoryPool 路径 (None=output.dir/trajectory)"
+    )
+    early_stop_patience: int = Field(default=0, description="连续 N 轮无改善则停 (0=不启用)")
+
+
+class SingleFactorTestConfig(BaseModel):
+    """单因子回测完整配置"""
+    factor: FactorSetting
+    preprocess: PreprocessSetting
+    analysis: AnalysisSetting = Field(default_factory=AnalysisSetting)
+    output: OutputSetting = Field(default_factory=OutputSetting)
+    feedback: FeedbackSetting = Field(default_factory=FeedbackSetting)
+    quality_gate: QualityGateConfig = Field(default_factory=QualityGateConfig)
+    evolution: EvolutionConfig = Field(default_factory=EvolutionConfig)
+    data_path: str = Field(default='./testdata/test_h5_new/', description="数据根目录")
+    load_keys: list = Field(
+        # M7: 默认含 tradability filter 必需键 (st/suspend/ud_limit/ipo_days)
+        default=['stklist', 'trade_dt', 'cp', 'id_citic1', 'mv_float',
+                 'st', 'suspend', 'ud_limit', 'ipo_days'],
+        description="需要加载的数据 key 列表"
+    )

QuantNodes/research/factor_test/config_builder.py

@@ -0,0 +1,276 @@
+# coding: utf-8
+"""SingleFactorTestConfig 流式构造器 / Config Builder (Phase 3.4)
+
+``SingleFactorTestConfig`` 是深度嵌套的 pydantic 模型 (factor / preprocess /
+analysis{ic,group,longshort,score,risk_corr} / output / feedback /
+quality_gate / evolution)。手工构造冗长易错 (e.g.
+``run_evolution_e2e._build_config`` 37 行嵌套)。
+
+``SingleFactorTestConfigBuilder`` 提供流式 API 扁平化常用字段:
+
+    cfg = (
+        SingleFactorTestConfigBuilder()
+        .factor("mom20", "mom20.h5", hypothesis="momentum")
+        .dates(20240101, 20241231)
+        .preprocess(extreme="median", norm="zscore")
+        .groups(5, direction=1)
+        .output("./out/", fmt=["json"])
+        .data_path("./data/")
+        .build()
+    )
+
+设计要点:
+  - 每个 setter 返回 ``self`` 支持链式
+  - 默认值全部委托各 ``*Setting`` 的 pydantic 默认 (单一真值源, 不重复)
+  - ``build()`` 时统一构造 pydantic 模型并触发校验 (缺必填如 factor 即报错)
+  - 不改 ``SingleFactorTestConfig`` / ``config.py``; 现有直接构造方式不变
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from QuantNodes.research.factor_test.config import (
+    AnalysisSetting,
+    EvolutionConfig,
+    FactorSetting,
+    FeedbackSetting,
+    GroupSetting,
+    ICSetting,
+    LongShortSetting,
+    OutputSetting,
+    PreprocessSetting,
+    QualityGateConfig,
+    RiskCorrelationSetting,
+    ScoreSetting,
+    SingleFactorTestConfig,
+    TradableSetting,
+)
+
+
+def _clean(kwargs: dict) -> dict:
+    """剔除值为 None 的项, 让 pydantic 默认值生效 (单一真值源)。"""
+    return {k: v for k, v in kwargs.items() if v is not None}
+
+
+class SingleFactorTestConfigBuilder:
+    """流式构造 ``SingleFactorTestConfig``。
+
+    所有 setter 仅记录非 None 字段; ``build()`` 时聚合为 pydantic 模型,
+    缺省字段沿用各 ``*Setting`` 的默认值。
+    """
+
+    def __init__(self) -> None:
+        self._factor: Optional[dict] = None
+        self._preprocess: dict = {}
+        self._tradable: Optional[dict] = None
+        self._ic: dict = {}
+        self._group: dict = {}
+        self._longshort: dict = {}
+        self._score: dict = {}
+        self._risk_corr: dict = {}
+        self._output: dict = {}
+        self._feedback: dict = {}
+        self._quality_gate: dict = {}
+        self._evolution: dict = {}
+        self._top: dict = {}
+
+    # ── factor ────────────────────────────────────────────────
+    def factor(
+        self,
+        name: str,
+        factor_dir: str,
+        *,
+        factor_key: Optional[str] = None,
+        fmt: Optional[str] = None,
+        hypothesis: Optional[str] = None,
+        description: Optional[str] = None,
+        expression: Optional[str] = None,
+    ) -> "SingleFactorTestConfigBuilder":
+        self._factor = _clean({
+            "name": name,
+            "factor_dir": factor_dir,
+            "factor_key": factor_key,
+            "format": fmt,
+            "hypothesis": hypothesis,
+            "description": description,
+            "expression": expression,
+        })
+        return self
+
+    # ── preprocess ────────────────────────────────────────────
+    def dates(self, beg: int, end: int) -> "SingleFactorTestConfigBuilder":
+        self._preprocess["adj_date_beg"] = beg
+        self._preprocess["adj_date_end"] = end
+        return self
+
+    def adj_mode(self, mode: list) -> "SingleFactorTestConfigBuilder":
+        self._preprocess["adj_mode"] = mode
+        return self
+
+    def sample(
+        self,
+        index: Optional[str] = None,
+        industry: Optional[str] = None,
+        *,
+        index_customdir: Optional[tuple] = None,
+    ) -> "SingleFactorTestConfigBuilder":
+        self._preprocess.update(_clean({
+            "sample_index": index,
+            "sample_industry": industry,
+            "sample_index_customdir": index_customdir,
+        }))
+        return self
+
+    def preprocess(
+        self,
+        *,
+        missing: Optional[str] = None,
+        extreme: Optional[str] = None,
+        norm: Optional[str] = None,
+        mad_n: Optional[float] = None,
+        pct_low: Optional[float] = None,
+        pct_high: Optional[float] = None,
+    ) -> "SingleFactorTestConfigBuilder":
+        self._preprocess.update(_clean({
+            "missing": missing,
+            "extreme": extreme,
+            "norm": norm,
+            "mad_n": mad_n,
+            "pct_low": pct_low,
+            "pct_high": pct_high,
+        }))
+        return self
+
+    def neutralize(
+        self,
+        *,
+        industry: Optional[bool] = None,
+        risk: Optional[bool] = None,
+        risk_factors: Optional[list] = None,
+    ) -> "SingleFactorTestConfigBuilder":
+        self._preprocess.update(_clean({
+            "industry_neutral": industry,
+            "risk_neutral": risk,
+            "risk_factors": risk_factors,
+        }))
+        return self
+
+    def tradable(self, **kwargs: Any) -> "SingleFactorTestConfigBuilder":
+        self._tradable = dict(kwargs)
+        return self
+
+    # ── analysis ──────────────────────────────────────────────
+    def ic(self, *, min_group_size: Optional[int] = None) -> "SingleFactorTestConfigBuilder":
+        self._ic.update(_clean({"min_group_size": min_group_size}))
+        return self
+
+    def groups(
+        self,
+        n: Optional[int] = None,
+        *,
+        direction: Optional[int] = None,
+        floor_mode: Optional[str] = None,
+        hedge: Optional[str] = None,
+        hedge_path: Optional[str] = None,
+    ) -> "SingleFactorTestConfigBuilder":
+        self._group.update(_clean({
+            "groups": n,
+            "factor_direction": direction,
+            "floor_mode": floor_mode,
+            "hedge": hedge,
+            "hedge_path": hedge_path,
+        }))
+        return self
+
+    def longshort(self, *, direction: Optional[int] = None) -> "SingleFactorTestConfigBuilder":
+        self._longshort.update(_clean({"factor_direction": direction}))
+        return self
+
+    def score(
+        self,
+        *,
+        enabled: Optional[bool] = None,
+        n_industries: Optional[int] = None,
+        n_size_groups: Optional[int] = None,
+        n_quantile_groups: Optional[int] = None,
+    ) -> "SingleFactorTestConfigBuilder":
+        self._score.update(_clean({
+            "enabled": enabled,
+            "n_industries": n_industries,
+            "n_size_groups": n_size_groups,
+            "n_quantile_groups": n_quantile_groups,
+        }))
+        return self
+
+    def risk_corr(self, factors: Any = None) -> "SingleFactorTestConfigBuilder":
+        if factors is not None:
+            self._risk_corr["factors"] = factors
+        return self
+
+    # ── output / feedback / quality_gate / evolution ─────────
+    def output(
+        self,
+        dir: Optional[str] = None,
+        *,
+        fmt: Optional[list] = None,
+    ) -> "SingleFactorTestConfigBuilder":
+        self._output.update(_clean({"dir": dir, "format": fmt}))
+        return self
+
+    def feedback(self, **kwargs: Any) -> "SingleFactorTestConfigBuilder":
+        self._feedback.update(kwargs)
+        return self
+
+    def quality_gate(self, **kwargs: Any) -> "SingleFactorTestConfigBuilder":
+        self._quality_gate.update(kwargs)
+        return self
+
+    def evolution(self, **kwargs: Any) -> "SingleFactorTestConfigBuilder":
+        self._evolution.update(kwargs)
+        return self
+
+    # ── top-level ─────────────────────────────────────────────
+    def data_path(self, path: str) -> "SingleFactorTestConfigBuilder":
+        self._top["data_path"] = path
+        return self
+
+    def load_keys(self, keys: list) -> "SingleFactorTestConfigBuilder":
+        self._top["load_keys"] = keys
+        return self
+
+    # ── build ─────────────────────────────────────────────────
+    def build(self) -> SingleFactorTestConfig:
+        """聚合并构造 SingleFactorTestConfig (触发 pydantic 校验)。
+
+        Raises:
+            ValueError: 未设置 factor (name/factor_dir 必填)。
+            pydantic.ValidationError: 字段校验失败。
+        """
+        if self._factor is None:
+            raise ValueError(
+                "factor is required: call .factor(name, factor_dir) before build()"
+            )
+
+        preprocess = dict(self._preprocess)
+        if self._tradable is not None:
+            preprocess["tradable"] = TradableSetting(**self._tradable)
+
+        analysis = AnalysisSetting(
+            ic=ICSetting(**self._ic),
+            group=GroupSetting(**self._group),
+            longshort=LongShortSetting(**self._longshort),
+            score=ScoreSetting(**self._score),
+            risk_corr=RiskCorrelationSetting(**self._risk_corr),
+        )
+
+        kwargs: dict = {
+            "factor": FactorSetting(**self._factor),
+            "preprocess": PreprocessSetting(**preprocess),
+            "analysis": analysis,
+            "output": OutputSetting(**self._output),
+            "feedback": FeedbackSetting(**self._feedback),
+            "quality_gate": QualityGateConfig(**self._quality_gate),
+            "evolution": EvolutionConfig(**self._evolution),
+        }
+        kwargs.update(self._top)
+        return SingleFactorTestConfig(**kwargs)

QuantNodes/research/factor_test/e2e/data_prep.py

@@ -0,0 +1,163 @@
+# coding: utf-8
+"""E2E 数据准备 — 生成 H5 格式合成数据, 模拟 iFinD 真实数据结构。
+
+输出目录结构 (符合 LoadDataNode 期望):
+    {output_dir}/
+    ├── stk_daily.h5     # 股票日数据
+    │   ├── cp           # 收盘价
+    │   ├── st           # ST 标记
+    │   ├── suspend      # 停牌
+    │   ├── ud_limit     # 涨跌停
+    │   ├── ipo_days     # 上市天数
+    │   ├── id_citic1    # 行业
+    │   └── mv_float     # 自由流通市值
+    ├── index_daily.h5   # 指数日数据
+    │   ├── index_cp     # 指数收盘价
+    │   └── ...
+    ├── stklist.h5
+    ├── trade_dt.h5
+    └── {factor_name}.h5  # 因子数据 (如 momentum_20d)
+
+用法:
+    python -m QuantNodes.research.factor_test.e2e.data_prep \\
+           --output-dir /tmp/e2e_data/ \\
+           --n-days 120 --n-stocks 30 \\
+           --factors momentum_20d,reversal_5d,volatility_60d
+"""
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from QuantNodes.core.path_utils import ensure_dir
+
+
+def _gen_factor_data(rng: np.random.RandomState, n_days: int, n_stocks: int,
+                     name: str) -> pd.DataFrame:
+    """生成特定形态的因子值 (与名称挂钩, 让不同因子有不同 IC)。"""
+    dates = _gen_dates(n_days)
+    stocks = _gen_stocks(n_stocks)
+    if "momentum" in name.lower():
+        # 因子值与未来收益正相关 (正 IC)
+        trend = np.linspace(0, 0.5, n_days).reshape(-1, 1)
+        base = rng.randn(n_days, n_stocks) + trend
+    elif "reversal" in name.lower():
+        # 因子值与未来收益负相关 (负 IC)
+        trend = -np.linspace(0, 0.5, n_days).reshape(-1, 1)
+        base = rng.randn(n_days, n_stocks) + trend
+    elif "volatility" in name.lower():
+        # 因子值与波动率相关 (弱 IC)
+        base = rng.randn(n_days, n_stocks) * 0.5
+    else:
+        # 默认: 随机因子 (无 IC)
+        base = rng.randn(n_days, n_stocks)
+    return pd.DataFrame(base, index=dates, columns=stocks)
+
+
+def _gen_dates(n_days: int) -> list[int]:
+    # H11: 不再硬编码 '2026-01-04', 默认从 1 年前开始 (滚动)
+    start_date = (datetime.now() - timedelta(days=365)).strftime('%Y-%m-%d')
+    return [int(d.strftime('%Y%m%d'))
+            for d in pd.bdate_range(start_date, periods=n_days)]
+
+
+def _gen_stocks(n_stocks: int) -> list[int]:
+    return list(range(100001, 100001 + n_stocks))
+
+
+def _gen_index_cp(rng: np.random.RandomState, n_days: int) -> pd.DataFrame:
+    """沪深 300 + 中证 500 指数收盘价。"""
+    dates = _gen_dates(n_days)
+    return pd.DataFrame({
+        '000300.SH': 3500 + np.cumsum(rng.randn(n_days) * 10),
+        '000905.SH': 6000 + np.cumsum(rng.randn(n_days) * 15),
+    }, index=dates)
+
+
+def _gen_stk_daily(rng: np.random.RandomState, n_days: int, n_stocks: int) -> dict:
+    """生成 stk_daily.h5 的所有 key。"""
+    dates = _gen_dates(n_days)
+    stocks = _gen_stocks(n_stocks)
+    # 收盘价: 几何布朗运动
+    price = 100 * np.exp(np.cumsum(rng.randn(n_days, n_stocks) * 0.02, axis=0))
+    # 行业 (申万一级 1-30)
+    industry = rng.randint(1, 31, (n_days, n_stocks))
+    # 自由流通市值
+    mv = rng.lognormal(10, 1, (n_days, n_stocks))
+    # ST / 停牌 / 涨跌停 — 稀疏
+    st = np.zeros((n_days, n_stocks), dtype=int)
+    st[:, :min(2, n_stocks)] = 1
+    suspend = np.zeros((n_days, n_stocks), dtype=int)
+    if n_stocks > 3:
+        suspend[5:8, 3] = 1
+    ud_limit = np.zeros((n_days, n_stocks), dtype=int)
+    if n_stocks > 5:
+        ud_limit[10:12, 5] = 1
+    # 上市天数 (>360 不剔除)
+    ipo_days = np.ones((n_days, n_stocks), dtype=int) * 500
+    ipo_days[0, 0] = 100  # 第一只新股, 会被 IPO < 360 剔除
+    return {
+        "cp": pd.DataFrame(price, index=dates, columns=stocks),
+        "st": pd.DataFrame(st, index=dates, columns=stocks),
+        "suspend": pd.DataFrame(suspend, index=dates, columns=stocks),
+        "ud_limit": pd.DataFrame(ud_limit, index=dates, columns=stocks),
+        "ipo_days": pd.DataFrame(ipo_days, index=dates, columns=stocks),
+        "id_citic1": pd.DataFrame(industry, index=dates, columns=stocks),
+        "mv_float": pd.DataFrame(mv, index=dates, columns=stocks),
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="E2E 数据准备")
+    parser.add_argument("--output-dir", required=True, help="输出目录")
+    parser.add_argument("--n-days", type=int, default=120, help="天数 (默认 120)")
+    parser.add_argument("--n-stocks", type=int, default=30, help="股票数 (默认 30)")
+    parser.add_argument("--factors", default="momentum_20d,reversal_5d,volatility_60d",
+                        help="逗号分隔的因子列表")
+    parser.add_argument("--seed", type=int, default=42, help="随机种子")
+    args = parser.parse_args()
+
+    out = Path(args.output_dir)
+    ensure_dir(out)
+    rng = np.random.RandomState(args.seed)
+    n_days, n_stocks = args.n_days, args.n_stocks
+    factors = [f.strip() for f in args.factors.split(",") if f.strip()]
+
+    print(f"生成数据: {n_days} 天 × {n_stocks} 股票, 因子={factors}")
+    print(f"输出目录: {out}")
+
+    # 1. stklist / trade_dt
+    dates = _gen_dates(n_days)
+    stocks = _gen_stocks(n_stocks)
+    pd.DataFrame(stocks, columns=[0]).to_hdf(out / "stklist.h5", key="data", mode="w")
+    pd.DataFrame(dates, columns=[0]).to_hdf(out / "trade_dt.h5", key="data", mode="w")
+    print(f"  ✓ stklist.h5, trade_dt.h5 ({len(stocks)} stocks × {len(dates)} dates)")
+
+    # 2. stk_daily.h5
+    stk_daily = _gen_stk_daily(rng, n_days, n_stocks)
+    with pd.HDFStore(out / "stk_daily.h5", mode="w") as store:
+        for key, df in stk_daily.items():
+            store.put(key, df, format="table")
+    print(f"  ✓ stk_daily.h5 ({len(stk_daily)} keys)")
+
+    # 3. index_daily.h5
+    index_cp = _gen_index_cp(rng, n_days)
+    with pd.HDFStore(out / "index_daily.h5", mode="w") as store:
+        store.put("index_cp", index_cp, format="table")
+    print(f"  ✓ index_daily.h5 (index_cp: {index_cp.shape})")
+
+    # 4. 因子 H5 (LoadDataNode 用 factor_dir 加载)
+    for fname in factors:
+        factor = _gen_factor_data(rng, n_days, n_stocks, fname)
+        factor.to_hdf(out / f"{fname}.h5", key="data", mode="w")
+        print(f"  ✓ {fname}.h5 (shape: {factor.shape})")
+
+    print("\n✓ 数据准备完成")
+    print(f"  data_path: {out}")
+
+
+if __name__ == "__main__":
+    main()