旧版分组回测按调仓时可见的分数确定持仓，不再先删除未来收益缺失的股票。 已形成组合的缺失收益或中途整期缺失会报错，不重新分配权重；尚未成熟的末端区间不计收益。 多空收益扣除多、空两条腿各自的换手费用；独立分组净收益列仍保留原含义。
高级因子风险已接入原始 PIT 历史、组合优化与目标检查；暴露流水线、加权行业约束回归、 多期风险估计及配置示例见高级因子风险接入。
研究可信度升级：接口、使用示例、验收及限制见 11–20 使用说明。
当前开发分支基于 0.4.2，修复研究时间泄漏、收益口径和执行成本接线，并新增真实公开数据到
日／周频模拟决策卡的入口。账户事实统一采用 standard/v2@2.0.0，不再输出另一份不同策略的 v1 账本。
该分支尚未发版，需联合安装修订后的 quant-data-kit、quant-lab；
使用方法、证据边界和旧配置迁移见 研究与决策工作流。
A 股多因子选股研究项目：从 AKShare 拉取行情，计算因子，做 IC 分析、分层回测与散户约束下的组合模拟。
研究用途：结果仅供学习研究，不构成投资建议。
运行python -m a_share_multifactor.preflight --config configs/run_four_factors.yaml --data-dir data --symbols-limit 50
会沿分层研究实际使用的加载路径，检查缓存行情、历史股票池、基本面可得时点、因子可计算性、全收益基准和执行规则输入，
输出asm.quantile-preflight/v1JSON。请将配置路径替换为自己的已有配置。
它不下载缺失数据、不发布快照、不计算综合得分或回测、不创建结果目录。
缺少必需输入、未来基本面导致因子完全缺失、历史成员缺价或基准口径错误均明确失败。
执行规则检查复用回放的费用与仓位限制、未复权价格、证券主表映射和规则有效期校验。
配置可通过 instrument_catalog 指定证券规则 CSV；相对路径按 YAML 所在目录解析，预检和正式执行使用同一路径。
未指定时使用仓库内规则表。预检记录规则文件哈希，但这些声明的规则不代表交易所完整历史规则认证。
所需文件、available_at时点规则、历史成员覆盖和H00300基准字段见缓存准备与字段约定。
--dry-run仍会计算完整回测，仅跳过结果写出，不能替代上述只读预检。
预检保留输入哈希和实际观察区间，但不锁定输入，不证明完整历史市场状态、独立PIT版本或投资适用性；
正式执行仍重新校验。数据加载API的read_only=True也禁止刷新和快照创建。
a_share_multifactor.paired_research.run_paired在独立输出目录冻结配方、输入清单哈希与
单维干预计划，再逐项运行真实模拟账本。非现金定义可以声明risk和risk_model：
省略风险模型表示继承配方，显式risk_model: null表示移除模型，空字典属于无效模型。
被动基准因此可以明确移除模型，同风险基准和单维干预继续保留原模型。
每次执行前保存execution-definition.json，其哈希进入尝试回执；失败仍保留且令归因不可用。
等权分配可以保留因子与历史行业约束，目标是距离等权最近的可行组合；预算、单标的上限、
换手及被移除持仓的卖出共同受限，跟踪误差仍由原风险门禁检查。费用干预的
cost_multiplier同时作用于佣金、最低佣金、税费与成交滑点，不能解读为仅佣金效应。
这些结果是模型内反事实；剩余项包含未解释因素与交互，不能宣称因果识别或替换冻结前向参数。
现金与趋势可以分别以cash_buffer和trend_filter维度预登记。前者仅改变现金缓冲，
不修改持仓数量、单只上限或风险模型；后者仅在etf_trend与rank之间切换，保留
原排序分数和调仓日期。现金缓冲下降后，其他仓位上限仍可能限制投入；应检查实际
分配和账本，不能将配置值变化直接换算成现金机会成本。多个情景须使用独立研究ID，
在运行前固定，并保留所有结果而非按收益选取。
Python · Pandas · Scikit-learn · quant-data-kit · AKShare · PyArrow · Matplotlib
| 类别 | 因子 | 说明 |
|---|---|---|
| 基本面 | pe_ratio, pb_ratio, market_cap, forecast_score |
估值 + 业绩预告得分 |
| 技术面 | momentum_20d, volatility_20d |
动量、波动 |
| 情感面 | northbound_chg_5d |
北向持股 5 日变化（T+1 披露滞后） |
| 宏观面 | industry_rs_20d |
行业 20 日相对 HS300 强弱 |
# 安装审计过的运行时、开发和editable构建依赖；Notebook工具单独安装`.[notebook]`
python -m pip install --no-deps --requirement requirements.lock
python -m pip check
python -m pip install --no-deps --no-build-isolation --editable .
python -m pip check
# 本地开发已通过上面的no-deps、no-build-isolation方式安装editable项目。
# 拉取含另类数据
python -m a_share_multifactor.fetch_data --fetch-alt --symbols-limit 10 --verbose
# 四类因子 IC + 回测
python -m a_share_multifactor.backtest --config configs/run_four_factors.yaml --verbose
# 输出: outputs/four_factors/ic_summary.csv, report.html离线 smoke test（无网络时）：
python scripts/seed_alt_smoke_data.py
python -m a_share_multifactor.backtest --config configs/run_four_factors.yaml --symbols-limit 5| 模块 | 说明 |
|---|---|
| 因子 | 市值、PE、PB、20 日动量、20 日波动率 |
| 合成 | 等权、IC 加权、滚动 IC、Ridge、OLS |
| 回测 | 分层回测、HS300 基准超额、换手成本 |
| 数据治理 | PIT可获得时间、历史股票池、不可变快照、质量摘要 |
| 验证 | expanding walk-forward、泄漏审计、FDR校正、折间稳定性 |
| 运行契约 | 标准returns/positions/orders/costs/exposures及哈希清单 |
| 散户模式 | 1 万元本金、100 股一手、最低佣金、印花税 |
| 调仓频率 | 日 / 周 / 月；最少持有天数；可选提前止盈 |
| 工具 | 多模型对比、81 组参数网格、指定日期买入清单 |
a-share-multifactor/
├── configs/ # YAML 配置
├── src/a_share_multifactor/ # 核心库
├── scripts/ # 辅助脚本
├── notebooks/ # Jupyter 研究笔记
├── tests/ # 单元测试
├── data/ # Parquet 缓存（gitignore，见 data/README.md）
└── outputs/ # 回测输出（gitignore）
- Python 3.10+
- 可访问 AKShare 数据源的网络环境
- 全量拉取 HS300 约 15–20 分钟（视网络与限流而定）
# 1. 克隆并安装
git clone https://github.com/PureSaber/a-share-multifactor.git
cd a-share-multifactor
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
# source .venv/bin/activate
pip install -e ".[dev]"
# 2. （可选）复制环境变量模板
copy .env.example .env # Windows
# cp .env.example .env # macOS / Linux
# 3. 拉取并缓存数据
python -m a_share_multifactor.fetch_data --config configs/default.yaml
# 或: asm-fetch --config configs/default.yaml
# 调试时可限制股票数量
python -m a_share_multifactor.fetch_data --symbols-limit 10 --verbose
# 4. 运行 IC 分析 + 分层回测
python -m a_share_multifactor.backtest --config configs/default.yaml --verbose
# 或: asm-backtest --config configs/default.yaml --verbose
# 5. 查看 outputs/latest/ 下的 CSV 与 report.html
# 6. 运行测试
pytest -q安装后可使用以下入口（等价于 python -m ...）：
| 命令 | 说明 |
|---|---|
asm-fetch |
拉取 AKShare 数据到 Parquet |
asm-backtest |
IC 分析 + 分层回测 |
asm-grid-search |
因子参数扫描 |
asm-compare |
多合成方法对比（含散户模式） |
asm-retail-grid |
散户 OLS 参数网格（81 组） |
| 文件 | 用途 |
|---|---|
configs/default.yaml |
默认研究配置（demo 区间） |
configs/run_2025_now.yaml |
2025 至今多模型对比 |
configs/run_retail_10k.yaml |
1 万散户、月度调仓 |
configs/run_retail_daily_10k.yaml |
1 万散户、日/周频调仓 |
configs/run_report.yaml |
生成 HTML 报告 |
回测前请将各配置中的 end_date 改为你需要的截止日期，然后重新 asm-fetch。
asm-fetch --config configs/run_retail_10k.yaml
asm-compare --config configs/run_retail_10k.yaml输出：outputs/long_only_10k_retail_2025_now/（资金曲线、交易流水、HTML 报告）
asm-fetch --config configs/run_retail_daily_10k.yaml
asm-retail-grid --config configs/run_retail_daily_10k.yaml输出：outputs/retail_param_grid/（CSV、热力图、Top 20 排名）
python scripts/compute_buy_list.py --trade-date 2026-07-17 \
--config configs/run_retail_daily_10k.yaml| 字段 | 说明 |
|---|---|
factor_directions |
因子方向（+1 / -1） |
holding_period |
rebalance 或固定天数 |
filters.use_historical_universe |
是否按历史 HS300 成分过滤 |
filters.pit_fundamentals |
时点基本面（merge_asof） |
synthesis.method |
equal_weight / ic_weight / rolling_ic_weight / ridge / ols |
costs.retail_mode |
散户模式（整手、最低佣金等） |
costs.trade_freq |
daily / weekly / monthly |
costs.min_holding_days |
最少持有交易日 |
fetch.max_workers |
并行拉取线程数（限流时可设为 1） |
validation.* |
OOS训练/测试/步长/embargo与FDR阈值 |
每次认证回测在outputs/<run_id>/standard/v2/写入不可变backtest-ledger契约，完整包含
returns、positions、portfolio_snapshots、exposures、orders、order_events、fills、costs、
cash_ledger和margin，并通过load_and_validate_standard_run回读验证；standard/根目录仍
双写历史v1以保持读取兼容。认证订单只能经过
Strategy.on_event -> DeterministicRunEngine -> 撮合/成交 -> RuleBookRiskGate -> ExactAccountLedger。
trading_costs.py和trade_ledger.py保留为legacy/research-only，不得用于认证产物。
fixture目录是版本化、显式、PIT的测试目录，其有效期是认证fixture窗口，不代表标的上市历史。
认证写出在任何文件落盘前检查Git工作树并对dirty状态fail closed；scored_panel使用与行列顺序无关的canonical SHA-256进入dataset snapshots和lineage，fixture catalog同样以sha256:标识，instrument master版本绑定catalog哈希前12位。
冻结的QExecv0.5.1对非期货费用只提供统一Fee及原始maker/taker分类；认证路径原样保留该分类，不在产物层拆分commission或stamp_duty。若需要显式费用分类，必须由项目负责人串行修订quant-execution并重新发布冻结tag。
本研究修复分支的pyproject.toml和requirements.lock固定到包含修复的不可变提交：
QDK 5b68af566ee1d47f62caa5449719912df6e17983、QLab 938927e5bcad641d46e3bd733e6323719d44aa50。
QFactors 固定 0ee0bcd66a94d887dbcc6196dfb85b154550c196，
QExec 固定 67164347c0a1fbb3e4f7a1b49ab9b172d02e86db，统一公司行动、试验登记与账户导入能力。
这是一组开发版本依赖，不使用浮动分支；旧发布标签不修改。默认安装和 CI 均包含此次修复，
不再依靠本地相邻仓库覆盖来通过测试。正式发布仍需完成对应仓库的发布流程。
锁文件由规范环境Windows+Python3.10和固定pip-tools==7.6.2重建，覆盖runtime、dev和editable-build依赖；Jupyter等仅用于交互研究的
Notebook工具不进入CI的dev闭包，需要时单独安装.[notebook]。并在Python3.10、3.11、3.12
中严格按锁安装验证。AKShare 1.18.88的Linux元数据会同时安装两个相互覆盖的MiniRacer实现；
本项目使用可审计的metadata-only派生wheel，包内全部运行代码、资源和
LICENSE与官方wheel逐字节一致，Windows和Linux统一只使用mini-racer==0.14.1。锁文件头与实际
重建命令统一为：
python tools/rebuild_lock.py迁移只新增不可变standard/v2产物，不改写历史v1；回滚使用Git revert同时恢复
pyproject.toml、requirements.lock、CI和本文档，再按旧锁重装。旧tag不移动、不覆盖。
# 代码检查与格式化
ruff check src tests scripts tools
ruff format src tests scripts tools
# 测试
pytest -q
# 提交前钩子（推荐）
pre-commit install
pre-commit run --all-filesCI（GitHub Actions）在Windows和Linux上分别运行Python3.10、3.11、3.12矩阵，先从固定官方wheel
双重重建并核验派生wheel哈希与payload；随后执行严格锁安装、双pip check、MiniRacer运行烟测、
Ruff、完整Pytest，并要求run_contract.py纯分支覆盖率不低于97%。Windows+Python3.10job还会
从零连续重建锁两次并与仓库版本比较；Linux只安装并验证这份规范锁，因为依赖元数据中的平台条件
（例如colorama）会让Linux上的重新解析得到不同但不具规范性的闭包。
- AKShare 限流：调低
fetch.max_workers或增大sleep_seconds - 数据目录为空：必须先运行
asm-fetch，详见 data/README.md - HS300 历史成分：基于 AKShare 成分调整记录，可能存在数据源误差
- PE/市值缺失：合并时 left join，IC 计算自动 dropna
- Windows 下 scipy/sklearn DLL 报错：尝试
pip install --force-reinstall scipy scikit-learn
- 因子投资核心概念（IC、IR、分层回测）
- 使用 Python 量化库进行 A 股因子研究的方法论
本地联合开发版本已增加真实公开数据到模拟决策卡的入口，详见
研究可信度与决策工作流。需要同时安装修订后的
quant-data-kit 与 quant-lab；冻结发布标签尚不包含这些变更。
asm-disclosures支持带原文件摘要、单位和修订链的基本面导入，默认按实际采集时点准入。研究工作台会复核来源材料与派生历史；输入和真实性边界见披露接入说明。
New research runs use next-open forward labels and disclose cross-sectional sample counts. See IC labels and execution timing for horizon, availability and historical close-to-close compatibility details.