一个面向研究复现、时间一致性审计和执行可行性评估的 A 股多因子选股工程。项目覆盖标准数据接入、Point-in-Time（PIT）因子构建、样本外因子验证、组合约束、事件驱动回测、绩效归因、稳健性检验，以及可审计的 LLM 事件标签流程。
本项目是量化研究与工程验证框架。仓库中的样例结果基于合成数据，不代表真实可获得收益，不构成投资建议或交易依据。
| 研究环节 | 已实现能力 | 主要审计产物 |
|---|---|---|
| 数据工程 | 12 张标准表、CSV/Parquet 导入、字段映射、日期规范化、主键与跨表质量检查 | data_manifest.json、数据质量报告 |
| 时间一致性 | 信号日、执行日、目标收益结束日分离；财务公告日与可用日追踪；历史股票池过滤 | factor_panel_timing.csv、PIT 测试 |
| 因子研究 | 量价、风险、估值、质量、成长、资金流和事件因子；去极值、标准化与中性化 | IC、HAC t、FDR、非重叠分组、覆盖率、衰减和相关性 |
| 样本外验证 | 滚动训练/验证/测试窗口，历史方向锁定、因子筛选和 IC 权重 | 方向、权重、窗口 IC、样本外 IC 和异常标记 |
| 组合与回测 | TopN、单票与行业上限、最小持仓数、下一交易日开盘执行、订单/成交/持仓审计 | orders.csv、fills.csv、positions.csv、execution_compliance.csv |
| 交易约束 | 停牌、涨跌停、ST/板块规则、手数、换手、最小成交额和成交额参与率 | 未成交原因及未成交金额分析 |
| 稳健性检验 | 零/标准/高成本，延迟 1/2/3 日，成交额参与率 1%/5%/10% | robustness_scenarios.csv、情景图表 |
| 专业时间序列 | 平稳性/自相关/ARCH/结构突变诊断，过滤式 HMM 状态、Kalman 动态 IC、GJR-GARCH、DCC 小型因子协方差与预测基准比较 | time_series_diagnostics.csv、regime_probabilities.csv、dynamic_factor_weights.csv、model_selection_audit.csv |
| 绩效与归因 | 收益、波动、Sharpe、Sortino、Calmar、回撤、相对基准指标和多维贡献分析 | 主动行业暴露、个股/行业/市值/回撤/成本归因 |
| LLM 事件研究 | 默认离线标签器、Prompt/模型版本、JSONL 缓存、原文留痕和人工抽查门槛 | LLM 标签审计 CSV 与 Markdown 报告 |
R1 文本工程已经扩展为 fail-closed 的 PIT/去重/实体复核、Embedding adapter、统一 TextRepresentationArtifact、固定线性 evaluator 和协议门禁。操作流程与尚需人工决定的科研边界见 R1 工程实施与人工闸门。
可部署时序模型统一通过 PointInTimeForecaster.fit/update/forecast 调用。接口拒绝晚于 as_of_date 的训练观测和不晚于训练截止日的预测目标，并统一返回训练截止日、预测目标日、模型版本、观测数和有效性门槛状态。
数据拉取或本地导入
↓
标准化与数据版本登记
↓
质量阻断与 PIT 检查
↓
因子构建、处理与覆盖率审计
↓
滚动训练 / 验证 / 样本外评分
↓
受约束组合构建与事件驱动回测
↓
绩效、风险、成本与容量归因
↓
可复现的 run 目录、图表和研究报告
- Python 3.10 或更高版本。
- Windows PowerShell、macOS 或 Linux shell。
- 真实数据导入建议安装
pyarrow；AkShare 拉取需要安装akshare。
推荐使用项目自带的 Conda 环境定义（固定 Python 3.12，并使用 conda-forge）：
conda env create -f environment.yml
conda activate ashare-factor-research
python -m pip install -e ".[data,research,test]"环境定义更新后可执行：
conda env update -n ashare-factor-research -f environment.yml
python -m pip install -e ".[data,research,test]"若不使用 Conda，也可用标准虚拟环境安装：
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[data,research,test]"pyproject.toml 声明项目的最低依赖契约；environment.yml 是当前受支持的 Python 3.12 严格运行环境，可使用更窄的兼容范围；requirements.txt 仅作为通用 pip 安装清单。三者如需调整，应在同一变更中说明差异并运行完整质量门禁。当前没有经过验证的 lock file，生成新锁文件前应先在独立环境中完成一致性检查。
如不进行 editable install，可在源码目录运行前设置：
$env:PYTHONPATH="src"python -m ashare_factor_research.main validate-config
python -m ashare_factor_research.main run-research `
--protocol config/research_protocol.yaml `
--run-id sample-smoke查看版本、运行环境和配置路径：
python -m ashare_factor_research.main version真实模式不会把合成样例通过视为数据有效性证明。进入研究 pipeline 前，数据目录必须包含 data_manifest.json，并通过阻断级质量检查。
python -m ashare_factor_research.main fetch-data `
--start-date 2015-01-01 `
--symbols-file data/import/reviewed_symbols.csv `
--tables trade_calendar,stock_basic,daily_bar,benchmark_index `
--output-dir data/raw `
--batch-id akshare-2015-v1 `
--format csv历史估值、财务、指数成分、行业、ST、停复牌、涨跌停和事件数据应由可靠的本地数据源补齐，再统一导入。默认协议要求行情历史最晚从 2015-01-01 开始，以支持 2018 年后的 24+6 个月训练/验证及长窗口预热：
python -m ashare_factor_research.main import-data `
--mode real `
--source-registry config/data_source_registry.yaml `
--source-dir data/import/incoming `
--output-dir data/standard/real-v1 `
--format parquet可通过 --mapping <yaml> 提供分表字段映射。真实导入要求每张表的来源、许可、PIT 语义、历史起点、单位和审查证据均已登记；默认来源登记保持 pending_user_review，因此不会误解锁真实研究。manifest v2 会绑定来源登记 SHA-256、源文件 SHA-256、字段类型、行数和日期范围。
python -m ashare_factor_research.main quality-check `
--mode real `
--data-dir data/standard/real-v1 `
--output-dir outputs/quality/real-v1 `
--fail-on-blocking
python -m ashare_factor_research.main verify-data `
--mode real `
--data-dir data/standard/real-v1python -m ashare_factor_research.main run-research `
--protocol config/research_protocol.real.yaml `
--run-id real-baseline-YYYYMMDD `
--robustness真实模式会先生成 data_gate_summary.json、PIT/修订/幸存者/覆盖率/基准对齐五类 CSV；缺表、未批准来源、未来修订、当前成分回填、覆盖率低于 95%、基准错位或 manifest/hash 异常都会在模型运行前阻断。AkShare 日行情中的占位复权因子只允许进入原始暂存区，不能直接通过正式门禁。
| 配置文件 | 职责 |
|---|---|
config/project_config.yaml |
市场、基准、研究区间、股票池、信号/执行时点、walk-forward 和 LLM 审计规则 |
config/factor_config.yaml |
启用因子、处理参数、覆盖率阈值和中性化设置 |
config/backtest_config.yaml |
TopN、权重与行业约束、交易成本、执行限制和稳健性情景 |
config/research_protocol.real.yaml |
2015/2018/2024 时间切分、候选模型、统计检验和最终留出期冻结 |
config/data_source_registry.yaml |
分表数据来源、许可、PIT、单位和审查证据；默认待用户审查 |
config/experiment_registry.csv |
预注册模型与唯一 experiment_id |
CLI 参数可覆盖关键组合参数，但每次标准运行都会保存三份完整配置快照，便于复现和审计。
每次运行写入独立目录 outputs/runs/<run_id>/：
outputs/runs/<run_id>/
├── project_config_snapshot.yaml
├── factor_config_snapshot.yaml
├── backtest_config_snapshot.yaml
├── data_manifest.json
├── research_protocol_snapshot.json
├── run_metadata.json
├── evidence_manifest.json
├── run_summary.md
├── data_quality_report.md
├── metrics.csv
├── orders.csv
├── fills.csv
├── positions.csv
└── figures/
├── walk_forward_*.csv
├── factor_inference.csv
├── group_test_nonoverlap.csv
├── monthly_factor_ic.csv
├── monthly_factor_returns.csv
├── time_series_diagnostics.csv
├── regime_probabilities.csv
├── dynamic_factor_weights.csv
├── volatility_forecasts.csv
├── dynamic_covariance.csv
├── forecast_comparison.csv
├── model_selection_audit.csv
├── strategy_oos_comparison.csv
├── time_series_report.md
├── execution_compliance.csv
├── factor_panel_timing.csv
├── robustness_scenarios.csv
├── unfilled_order_analysis.csv
├── active_industry_exposure.csv
├── drawdown_contribution.csv
└── 其他因子、绩效与归因图表
run_metadata.json 记录 run_id、包版本、Git 基础提交、源码树哈希、配置哈希、数据版本、股票池、因子列表、成本和执行假设。
- 因子在信号日收盘后生成，不允许使用当日收盘信号在同一收盘价成交。
- 默认在下一交易日开盘尝试执行；稳健性模块可额外延迟 1 至 3 个交易日。
- 财务数据仅在
usable_date到达后可见，并保留报告期、公告日和可用日来源字段。 - 历史指数成分、行业、ST、停牌、涨跌停和退市状态必须按当时可见信息处理。
- 训练和验证标签必须在对应窗口边界前完整实现，避免未来收益跨窗泄漏。
- 状态模型只输出截至信号日的 filtered probability，不使用含未来观测的 smoothed probability；动态权重只接收
availability_date < test_date的 IC 标签。 - 真实模式不能形成动态或规则式 OOS score 时直接失败；只有合成样例允许
score_source=synthetic_fallback。 - 基准收益必须与策略日期严格对齐，不进行隐式前向填充。
- Q5-Q1 等多空结果是因子诊断，不等同于 A 股市场中的可交易做空收益。
- 回测成本、滑点和冲击参数属于研究假设，不能替代真实成交验证。
阶段 2–3 提供两个独立入口。月度样本固定为月末收盘信号、下一交易日开盘执行、相邻月末结束标签；真实模式还要求完整 PIT 表、全局人工签署、非空专项审计及历史成员字段覆盖率不少于 95%。
$env:PYTHONPATH="src"
python -m ashare_factor_research.main build-monthly-sample --mode sample --data-dir data/sample --output-dir outputs/monthly/sample
python -m ashare_factor_research.main run-time-series-baselines --monthly-ic outputs/monthly/sample/monthly_factor_ic.csv --monthly-returns outputs/monthly/sample/monthly_factor_returns.csv --state-variables outputs/monthly/sample/monthly_state_variables.csv --output-dir outputs/baselines/samplerun-time-series-baselines 默认只评估 2018–2023；2024-01-01 起的最终留出期不会进入训练、模型选择或晋级结论。Kalman、HMM 和 GARCH/DCC 仍属于后续阶段候选，不由本命令给出晋级结论。
统一质量门禁包含源码编译、单元测试、CLI smoke 和 Notebook smoke：
python -m ashare_factor_research.main quality默认 smoke 产物写入临时目录，不改写受版本控制的静态图表；只有显式传入 --update-artifacts 才更新展示产物。
也可以分别执行：
python -m compileall src tests
python -m unittest discover -s tests
python scripts/smoke_notebooks.py
python -m ashare_factor_research.main build-reportconfig/ 研究、因子和回测配置
data/sample/ 可提交的合成样例数据
docs/ 数据字典、实施矩阵和补充说明
notebooks/ 按研究流程排列的 7 个 Notebook
reports/ Markdown/PDF 报告和可复核样例产物
scripts/ 样例生成、质量检查和报告脚本
src/ashare_factor_research/ 核心 Python 包
tests/ 单元测试与端到端 smoke test
A-LLM- 是唯一主线交付目录；工作区其他 A-LLM-* 目录仅用于历史追溯，不应加入 PYTHONPATH。详见 历史目录说明。
核心合成样例图表：
- 合成样例只能验证工程链路，不能证明因子在真实市场中有效。
- AkShare 仅用于经过保守映射的端点；历史 PIT 数据仍需独立核验来源、修订口径和覆盖完整性。
- 当前执行模型无法完整模拟集合竞价、排队成交、盘口深度、复牌首日和极端市场冲击。
- 多次查看样本外结果并据此反复调参，仍会造成隐性样本外污染。
- LLM 模块仅用于事件结构化和辅助解释；未通过人工抽查门槛的标签不会进入组合信号。
所有结果仅用于量化研究、数据工程和系统开发，不构成任何投资建议。