# 多因子量化股票分析框架

**Repository Path**: kinnco/aquant-python

## Basic Information

- **Project Name**: 多因子量化股票分析框架
- **Description**: 多因子量化股票分析平台
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Multi-Factor Quant Platform

基于真实 A 股数据的多因子量化股票分析框架。

## 硬规则

- 不使用本地假数据
- 不使用假缓存
- 不使用 AI 自创行情、自创标签、自创样本
- 允许本地缓存，但缓存内容必须来自真实外部数据源
- 筛选、推荐、买入价、止盈止损、个股诊断必须使用当天真实实时数据
- 如果筛选或推荐依赖一段时间窗口，该窗口必须是“当天实时数据 + 向前连续真实历史数据”
- 回测、滚动验证、训练允许使用历史真实数据，但必须明确标注数据日期范围
- 当天无法取得实时数据时，明确提示“无法取得当天数据，请稍后再试”
- 当天部分股票无法取得实时数据时，明确提示“部分股票无法取得实时数据”

## 当前能力

- 真实行情与基础面数据获取
- 多因子计算
- 股票筛选
- 个股诊断与报告导出
- 观察池构建
- 持仓买卖信号
- 仓位计划
- 模型训练
- 回测引擎
- 滚动验证
- 批量运行
- 参数优化
- 大模型文本增强
- JSON / CSV / 终端中文输出

## 数据源

### 行情与基础面

- `AkShare`
- `Tushare`

### 实时行情

当前实时行情走多源探测：

- 新浪
- 腾讯

实时行情用于：

- 股票筛选主截面
- 推荐买入价
- 止盈止损
- 个股诊断最新行情部分

实时行情约束：

- 不再使用历史日线冒充实时行情
- 历史 `as_of` 不再叠加今天实时价到历史 K 线
- 若全部股票都拿不到当天实时数据，会直接报错
- 若部分股票拿不到实时数据，会提示“部分股票无法取得实时数据”
- 停牌股票会单独标记并跳过

### 文本与事件数据

- 政策文本
- 公司新闻
- 公司公告
- 企业事件

新闻源支持多源并行并做同新闻去重：

- 东方财富
- 腾讯新闻
- 头条搜索

## 因子体系

### 数值因子

- `momentum`
- `short_reversal`
- `low_volatility`
- `liquidity`
- `value`
- `quality`
- `growth`
- `size`

### 文本因子

- `text_sentiment_policy`
- `text_relevance_policy`
- `text_sentiment_company_news`
- `text_relevance_company_news`
- `text_sentiment_company_event`
- `text_relevance_company_event`
- `national_strategy`

### 图关系因子

- `graph_industry_peer`

## 模型

当前已接入：

- `lightgbm`
- `xgboost`

训练要求：

- 使用真实历史标签
- 不使用假标签兜底

## 交易与回测约束

回测和信号逻辑已考虑：

- 推荐买入价
- ATR 止盈
- ATR 止损
- 未来路径先触达判断
- 双边费用
- 滑点
- A 股 `T+1`

## 数据日期规则

### 1. 筛选、推荐、买入价、止盈止损、个股诊断

这些功能必须显示并区分以下字段：

- `latest_market_date`
  含义：本次推荐或分析使用的最新市场日期
- `screening_data_mode`
  含义：筛选口径
  当前对实时筛选入口应为 `realtime_plus_history`
- `screening_real_data_range`
  含义：本次筛选实际使用的真实股票数据日期范围
- `recommendation_price_date`
  含义：推荐买入价、止盈价、止损价对应的价格日期

### 2. 回测、训练、滚动验证

必须显示：

- `historical_backtest_cutoff_date`
  含义：本次回测或训练截面结束日期
- `backtest_real_data_range`
  含义：本次回测、训练、滚动验证实际使用的真实历史数据范围

### 3. 命令口径边界

以下命令属于实时筛选入口，必须使用当天真实实时数据：

- `run`
- `stock-report`
- `screening-test`
- `batch-run`
- `optimize-params`

这些命令现在不允许传入历史日期做筛选推荐。如果传入历史 `--as-of`，程序会直接报错。

以下命令允许使用历史真实数据：

- `walk-forward`
- `warm-cache`

### 4. 时间窗口规则

- 对筛选、推荐、止盈止损、个股诊断，若需要时间窗口，窗口必须是“当天实时数据 + 向前连续真实历史数据”
- 对回测、训练、滚动验证，窗口是历史真实数据范围
- 任何输出都必须让用户看见“价格日期”或“数据日期范围”

## 实时缓存机制

平台允许本地真实数据缓存，用来缓解外部接口波动。

### 实时缓存规则

- 实时缓存文件会记录数据日期
- 每次拉取实时行情前，先比对当天日期和缓存记录日期
- 如果查询日期大于缓存日期，会先清理旧实时缓存，再重拉当天实时行情
- 如果查询日期和缓存日期相同，且当天没有失败股票，则直接复用当天实时缓存
- 如果查询日期和缓存日期相同，但存在当天失败股票，则只补拉失败股票
- 停牌股票不计入“待补拉失败股票”

### 实时拉取统计

实时拉取完成后会输出：

- `total_symbols`
- `suspended_symbols`
- `failed_symbols`

如果存在失败股票，还会输出：

- `部分股票无法取得实时数据`

### 断点续拉

支持仅重试当天失败股票：

```bash
python -m multifactor_quant.cli run --retry-failed-realtime-only
```

## 个股诊断口径

个股诊断入口当前遵循：

1. 先拉取当天最新真实行情
2. 再单独标注历史回测截面日期
3. 明确区分推荐价格日期与历史训练/回测日期范围

## 大模型接入

当前支持：

- `openai`
- `deepseek`
- `kimi`
- `glm`
- `minimax`
- `forward`

### 转发模式

`forward` 适配 OpenAI 兼容转发接口，支持 `Responses API` 风格。

当前框架侧已兼容：

- 超时重试
- `429 / 5xx` 重试
- 单组文本失败不拖垮整批任务
- 不因 LLM 失败而伪造文本结果

### 推荐参数

- `--llm-apply-scope latest_only`
- `--llm-source-filter policy,company_event`
- `--llm-max-groups 4`

## 常用命令

### 主流程运行

说明：实时筛选入口，默认今天，不建议传历史 `--as-of`。

```bash
python -m multifactor_quant.cli run ^
  --data-provider akshare ^
  --train-start 2025-10-01 ^
  --symbols 600519.SH,000858.SZ
```

### 个股报告

说明：实时诊断入口，必须使用当天真实实时数据。

```bash
python -m multifactor_quant.cli stock-report ^
  --data-provider akshare ^
  --train-start 2025-10-01 ^
  --symbols 600519.SH,000858.SZ ^
  --symbol 600519.SH
```

### 滚动验证

说明：这是历史验证入口，可以使用历史真实数据。

```bash
python -m multifactor_quant.cli walk-forward ^
  --data-provider akshare ^
  --train-start 2025-10-01 ^
  --symbols 600519.SH,000858.SZ ^
  --min-train-periods 1 ^
  --as-of 2026-04-21
```

### 筛选测试

说明：实时筛选入口，必须使用当天真实实时数据。

```bash
python -m multifactor_quant.cli screening-test ^
  --data-provider akshare ^
  --train-start 2025-10-01 ^
  --symbols 600519.SH,000858.SZ ^
  --export-dir exports
```

### 批量重跑

说明：实时批量筛选入口，必须使用当天真实实时数据。

```bash
python -m multifactor_quant.cli batch-run ^
  --data-provider akshare ^
  --train-start 2025-10-01 ^
  --auto-universe-count 50 ^
  --universe-limit 300 ^
  --chunk-size 100 ^
  --resume
```

### 参数优化

说明：当前参数优化走实时筛选入口，必须使用当天真实实时数据，并输出当天筛选范围与历史回测范围。

```bash
python -m multifactor_quant.cli optimize-params ^
  --data-provider akshare ^
  --train-start 2025-10-01 ^
  --symbols 600519.SH,000858.SZ ^
  --target-count-grid 5,10,15 ^
  --atr-tp-grid 2.2,2.6,3.0 ^
  --atr-sl-grid 1.0,1.4,1.8 ^
  --export-dir exports
```

### 预热缓存

说明：这是数据准备入口，可以使用历史真实数据范围。

```bash
python -m multifactor_quant.cli warm-cache ^
  --data-provider akshare ^
  --symbols 600519.SH,000858.SZ ^
  --start-date 2025-10-01 ^
  --end-date 2026-04-21 ^
  --include-text
```

### 查看缓存

```bash
python -m multifactor_quant.cli cache-stats
python -m multifactor_quant.cli cache-list --namespace hist --limit 10
python -m multifactor_quant.cli cache-clear --namespace hist
```

## 关键 CLI 参数

### 通用

- `--data-provider akshare|tushare`
- `--symbols`
- `--symbols-file`
- `--train-start`
- `--as-of`
- `--lookback-days`
- `--target-horizon-days`
- `--rebalance-step-days`
- `--target-count`
- `--cache-mode normal|prefer_cache|cache_only|refresh`
- `--cache-ttl-hours`
- `--export-dir`

注意：

- 对 `run / stock-report / screening-test / batch-run / optimize-params`，`--as-of` 只能是今天
- 对 `walk-forward / warm-cache`，可以使用历史真实日期

### 实时行情

- `--retry-failed-realtime-only`

### LLM

- `--enable-llm-text`
- `--llm-provider openai|deepseek|kimi|glm|minimax|forward`
- `--llm-model`
- `--llm-api-key`
- `--llm-base-url`
- `--llm-timeout-sec`
- `--llm-max-docs`
- `--llm-source-filter`
- `--llm-max-groups`
- `--llm-apply-scope latest_only|all`

## 导出结果

### `run_summary.json`

至少包含：

- `analysis_date`
- `latest_market_date`
- `screening_data_mode`
- `screening_real_data_range`
- `recommendation_price_date`
- `historical_backtest_cutoff_date`
- `backtest_real_data_range`
- `screened`
- `signals`
- `allocation_plan`

### `stock-report` JSON

至少包含：

- `symbol`
- `name`
- `screening`
- `exposure`
- `factor_contributions`
- `signals`
- `screening_data_mode`
- `latest_market_date`
- `screening_real_data_range`
- `recommendation_price_date`
- `historical_backtest_cutoff_date`
- `backtest_real_data_range`
- `live_quote`

### `walk_forward.csv`

至少包含：

- `as_of`
- `latest_market_date`
- `screening_data_mode`
- `screening_real_data_start`
- `screening_real_data_end`
- `backtest_real_data_start`
- `backtest_real_data_end`
- `top_symbol`
- `top_name`

### `optimization_results.csv`

至少包含：

- `analysis_date`
- `latest_market_date`
- `screening_data_mode`
- `screening_real_data_start`
- `screening_real_data_end`
- `backtest_real_data_start`
- `backtest_real_data_end`
- `target_count`
- `atr_take_profit_mult`
- `atr_stop_loss_mult`
- `total_return`
- `top_symbol`
- `top_name`
- `status`

### `batch_screened.csv` / `batch_summary.json`

至少包含：

- `symbol`
- `name`
- `score`
- `latest_quote_date`
- `screening_data_mode`
- `screening_real_data_start`
- `screening_real_data_end`
- `historical_backtest_cutoff_date`
- `backtest_real_data_start`
- `backtest_real_data_end`

## 联调检查清单

- `run` 是否输出当天实时 `latest_market_date`
- `run` 是否输出 `screening_real_data_range`
- `stock-report` 是否导出名称与日期范围
- `screening-test` 是否显示 `price_date`
- `walk-forward` 是否输出每期真实数据范围
- `batch-run` 是否输出每只股票的筛选范围和回测范围
- `optimize-params` 是否真实跑网格而非仅解析参数
- 历史日期是否已被禁止用于实时筛选入口
- 历史验证入口是否仍能正常使用历史真实数据

## 当前验证状态

- CLI 主链路可执行，不再是直接抛 `RuntimeError` 的占位状态
- `optimize-params` 已执行真实参数网格
- 历史分析快照为空时，已补上真实历史快照回退
- 历史分析不再混入当天实时行情
- 实时筛选入口已禁止历史 `--as-of`
- 本地单元测试通过

## 已失效旧审计项说明

以下旧审计项在当前版本中已失效，不应再作为现状判断依据：

- “CLI 主执行链路当前未闭环”
  当前 `run / stock-report / screening-test / walk-forward / batch-run / warm-cache / cache-*` 均已接回真实执行分支，并有回归测试覆盖主链路分发。
- “optimize-params 仍是占位入口”
  当前 `optimize-params` 已进入真实参数网格执行流程，会逐组调用分析链路并输出排序结果；真实外部数据慢不等于该入口是占位实现。

如果后续再做代码审计，建议优先以当前代码、当前测试和最新实跑结果为准，而不是直接沿用历史 finding。

## 风险说明

- 实时行情依赖外部源稳定性，若当天源站异常，会按规则报错或提示部分失败
- 新闻源和公告源偶发波动时，文本因子覆盖率可能下降
- `Tushare` 需要真实 `TUSHARE_TOKEN`
- 不同源站对停牌、缺失字段、延迟更新的处理方式可能不同

## 后续扩展建议

- 增加更多实时行情源的可用性探测与自动切换
- 增加更细粒度的交易日历与停牌日历校验
- 为导出报告增加统一的“数据口径摘要”模块
- 为 LLM 分析补充更细的来源置信度字段

截至当前版本，核心框架已经形成可运行闭环。后续新增功能应继续遵守“真实数据优先、实时与历史口径分离、所有输出显示数据日期、不用假数据兜底”的原则。

## 同花顺真实网关参数模板

当前框架已支持两种执行模式：

- `broker_mode=paper`：本地模拟撮合，不触发真实券商下单。
- `broker_mode=real` 且 `broker_provider=tonghuashun`：走同花顺真实券商适配层发单。

需要特别说明：

- 框架不会硬编码猜测的同花顺真实下单路径。
- `broker_submit_order_path` 必须来自你实际拿到的官方交付文档、联调文档或专属网关配置。
- 如果还没有拿到真实交易网关参数，建议继续使用 `paper` 模式完成筛选、风控、信号和模拟交易联调。

### CLI 参数模板

```bash
python -m multifactor_quant.cli run ^
  --data-provider tonghuashun ^
  --train-start 2025-10-01 ^
  --symbols 600519.SH,000858.SZ ^
  --broker-mode real ^
  --broker-provider tonghuashun ^
  --broker-base-url https://你的真实交易网关域名 ^
  --broker-access-token 你的_access_token ^
  --broker-refresh-token 你的_refresh_token ^
  --broker-submit-order-path /你的真实下单路径 ^
  --broker-timeout-seconds 20
```

### 环境变量模板

```powershell
$env:THS_APP_KEY="你的同花顺数据AppKey"
$env:THS_ACCESS_TOKEN="你的同花顺数据AccessToken"
$env:THS_BASE_URL="https://quantapi.51ifind.com"

$env:THS_BROKER_BASE_URL="https://你的真实交易网关域名"
$env:THS_BROKER_ACCESS_TOKEN="你的真实交易AccessToken"
$env:THS_BROKER_REFRESH_TOKEN="你的真实交易RefreshToken"
$env:THS_BROKER_SUBMIT_ORDER_PATH="/你的真实下单路径"
```

### 关键参数说明

- `broker_mode`：执行模式，支持 `paper` 和 `real`。
- `broker_provider`：券商适配器提供方，当前真实交易适配支持 `tonghuashun`。
- `broker_base_url`：真实交易网关地址，不是行情接口地址。
- `broker_access_token`：真实交易接口访问令牌。
- `broker_refresh_token`：如接入方支持刷新流程，可用于换取新的访问令牌。
- `broker_submit_order_path`：真实下单接口路径，必须由正式联调资料提供。
- `broker_timeout_seconds`：交易接口超时秒数。

### 联调清单

1. 确认数据侧参数已可用，包括 `THS_APP_KEY`、`THS_ACCESS_TOKEN`、`THS_BASE_URL`。
2. 确认交易侧参数已可用，包括真实网关域名、访问令牌、刷新令牌、下单路径。
3. 确认账户侧约束已明确，包括可用资金、股东账号、市场权限、最小交易单位。
4. 确认交易规则口径一致，包括 A 股 `T+1`、涨跌停限制、整手规则、停牌处理规则。
5. 先用 `paper` 模式联调筛选、风控、执行拦截和订单映射，再切到 `real` 模式。
6. 真实联调建议先做最小金额测试单，再验证撤单、成交回报、持仓变动与资金变动是否一致。

### 当前真实券商适配边界

已完成：

- 网关地址拼接与请求封装
- 访问令牌注入
- 刷新令牌换新流程
- 下单结果映射到 `BrokerOrderResult`

尚未闭环：

- 撤单接口
- 委托查询
- 持仓查询
- 资金查询
- 订单状态轮询
- 部分成交与多次成交回报聚合

### 联调建议

- 第一步先跑 `paper`，确认筛选、推荐、风控和执行保护逻辑正常。
- 第二步切到 `real`，只做最小测试单，不直接大额实盘。
- 第三步分别验证买入、卖出、T+1 限制、涨跌停限制和停牌跳过逻辑。
- 第四步核对导出报告中的 `execution_guard_summary` 与 `simulated_trading_summary` 是否符合真实网关返回。

### 参考资料

- [同花顺 QuantAPI 部署说明](https://quantapi.51ifind.com/gwstatic/static/ds_web/quantapi-web/help-center/deploy.html)
- [同花顺 QuantAPI 示例文档](https://quantapi.51ifind.com/gwstatic/static/ds_web/quantapi-web/example.html)

## 生产配置模板

项目根目录提供 `multifactor.toml.example` 作为生产配置模板。

推荐使用方式：

1. 复制 `multifactor.toml.example` 为你自己的本地运行文件 `multifactor.toml`
2. 只在本地 `multifactor.toml` 中填写真实生产参数
3. 将示例模板保留在版本库中，本地 `multifactor.toml` 和 `*.bak_*` 备份文件一律不入库

这样可以把真实运行配置、转发地址、券商参数、邮件参数和后续敏感信息与版本库隔离开。

建议使用方式：

```bash
python -m multifactor_quant.cli run ^
  --config multifactor.toml ^
  --config-profile production ^
  --train-start 2025-10-01 ^
  --symbols 600519.SH,000858.SZ
```

当前分层规则：

- `[defaults]`：全局默认参数
- `[profiles.research]` / `[profiles.production]`：研究态与生产态覆盖参数
- `[provider.akshare]` / `[provider.tushare]` / `[provider.tonghuashun]`：数据源参数
- `[llm.*]`：不同大模型提供商参数
- `[broker.paper]` / `[broker.tonghuashun]`：撮合或真实券商参数

仓库当前的隔离规则：

- `multifactor.toml.example`：可入库的配置模板
- `multifactor.toml`：本地真实配置，已加入 `.gitignore`
- `*.bak_*`：本地修改前备份文件，已加入 `.gitignore`

生产配置里也可以直接固化通知过滤规则，例如：

```toml
[profiles.production]
notify_only_high_priority = false
notify_only_buy = false
notify_only_sell = false
```

含义如下：

- `notify_only_high_priority = true`：只发高优先级通知
- `notify_only_buy = true`：只发买入通知
- `notify_only_sell = true`：只发卖出通知

这 3 个参数可以组合使用，组合后按交集过滤。

## 券商联调 CLI

当前已补充以下券商联调命令：

```bash
python -m multifactor_quant.cli broker-account ^
  --config multifactor.toml ^
  --config-profile production ^
  --broker-mode real ^
  --broker-provider tonghuashun
```

```bash
python -m multifactor_quant.cli broker-positions ^
  --config multifactor.toml ^
  --config-profile production ^
  --broker-mode real ^
  --broker-provider tonghuashun
```

```bash
python -m multifactor_quant.cli broker-order-status ^
  --config multifactor.toml ^
  --config-profile production ^
  --broker-mode real ^
  --broker-provider tonghuashun ^
  --order-id 你的订单号
```

```bash
python -m multifactor_quant.cli broker-cancel ^
  --config multifactor.toml ^
  --config-profile production ^
  --broker-mode real ^
  --broker-provider tonghuashun ^
  --order-id 你的订单号
```

```bash
python -m multifactor_quant.cli broker-diagnostics ^
  --config multifactor.toml ^
  --config-profile production ^
  --broker-mode real ^
  --broker-provider tonghuashun ^
  --order-ids 订单号1,订单号2
```

```bash
python -m multifactor_quant.cli broker-order-status-batch ^
  --config multifactor.toml ^
  --config-profile production ^
  --broker-mode real ^
  --broker-provider tonghuashun ^
  --order-ids 订单号1,订单号2 ^
  --export-file exports/order_status_batch.json
```

```bash
python -m multifactor_quant.cli broker-cancel-batch ^
  --config multifactor.toml ^
  --config-profile production ^
  --broker-mode real ^
  --broker-provider tonghuashun ^
  --order-ids 订单号1,订单号2 ^
  --export-file exports/cancel_batch.json
```

```bash
python -m multifactor_quant.cli broker-report ^
  --config multifactor.toml ^
  --config-profile production ^
  --broker-mode real ^
  --broker-provider tonghuashun ^
  --order-ids 订单号1,订单号2 ^
  --export-file exports/broker_report.json ^
  --export-csv exports/broker_report.csv
```

说明：

- 这些命令不会依赖训练窗口参数，适合直接做券商接口联调。
- `paper` 模式下可用于检查接口结构是否接通。
- `real + tonghuashun` 模式下会读取真实券商路径参数。
- `broker-diagnostics` 会一次性输出账户快照、券商持仓，以及可选的多订单状态检查结果，适合批量联调和日常巡检。
- `broker-order-status-batch` 和 `broker-cancel-batch` 支持批量订单号输入，并可直接导出 JSON 联调结果。
- `broker-report` 会汇总账户快照、券商持仓和订单状态，支持同时导出 JSON 与 CSV。

## 日终对账摘要

当前 `run_summary.json`、`stock-report` 和运行摘要中已增加 `reconciliation_summary`，用于汇总：

- 本次筛选股票数量
- 本次信号数量
- 本次仓位计划数量
- 执行候选单数量
- 执行放行/拦截数量
- 模拟或真实下单提交/成交/拒绝数量
- 起始持仓数量与结束持仓数量
- 资金变化与组合市值
- 被拦截原因摘要
- 已成交股票摘要
- 可选券商账户快照与券商持仓快照

这部分用于盘后核对“策略建议”和“执行结果”是否一致，是后续扩展正式对账中心的基础。

当前导出文件增加：

- `reconciliation_summary.json`
- `reconciliation_summary.csv`
- `reconciliation_details.json`
- `reconciliation_details.csv`
- `dashboard.html`（通过命令生成）

其中：

- `JSON` 适合保留完整字段和后续二次处理
- `CSV` 适合快速盘后核对和汇总归档
- `reconciliation_details.*` 会按股票逐条输出：筛选结果、信号动作、仓位计划、执行放行/拦截、订单状态、成交金额、手续费等明细

## 静态控制台页面导出

可以基于已有导出文件生成一个最小静态页面：

```bash
python -m multifactor_quant.cli dashboard-export ^
  --export-dir exports ^
  --output exports/dashboard.html
```

该页面会集中展示：

- 分析日期与最新行情日期
- 放行订单、拦截订单、成交订单、组合市值
- Top 筛选股票
- 对账明细前若干行

## 实盘推荐中心

当前 `run`、`stock-report`、`batch-run` 在导出目录下会额外生成：

- `recommendation_center.json`
- `recommendation_center.csv`

内容包含：

- 推荐股票代码与名称
- 排名与评分
- 当天真实最新价格
- 推荐买入价
- 止盈价
- 止损价
- 买入距离百分比
- 盈亏比
- 预期未来收益率

这部分用于让实盘用户快速判断“是否接近买点、盈亏比是否值得、当前是否适合买入”。

## 止盈止损与卖出信号通知

当前会额外生成：

- `signal_notifications.json`
- `signal_notifications.csv`
- `signal_notifications.txt`

通知内容包括：

- `BUY` / `SELL` 动作
- 通知级别
- 置信度
- 推荐买入价
- 止盈价
- 止损价
- 当天真实最新价
- `T+1` 最早可卖日期
- 原因说明

其中 `signal_notifications.txt` 适合直接接企业微信、钉钉、邮件、短信等后续通知通道。

### 通知过滤规则

通知分发阶段现在支持以下过滤参数：

- `--notify-only-high-priority`
- `--notify-only-buy`
- `--notify-only-sell`

过滤规则在“真正发送前”生效，过滤后的结果才会参与：

- 实际 webhook / 邮件发送
- 通知冷却去重指纹计算
- `notification_dispatch_summary.json` 分发统计

可组合使用，组合后按交集过滤。例如：

```bash
python -m multifactor_quant.cli run ^
  --data-provider akshare ^
  --train-start 2025-10-01 ^
  --symbols 600519.SH,000858.SZ ^
  --notify-webhook-provider wecom ^
  --notify-webhook-url https://example.invalid/webhook ^
  --notify-only-high-priority ^
  --notify-only-sell
```

上例表示：只发送“高优先级卖出通知”。

如果过滤后通知数量为 0，则本次不会发送，并在分发摘要中标记：

- `skip_reason = filtered_empty`

终端汇总里也会显示本次通知过滤摘要，包括：

- 原始通知数量
- 过滤后通知数量
- 实际应用的过滤器列表

## 编码与乱码说明

为减少 Windows 下 `cli.py` 终端输出和 `README.md` 编辑保存时反复出现乱码，仓库已增加多层保护：

- CLI 启动时会在 Windows 下优先把 `stdout/stderr` 重设为 UTF-8 输出
- 根目录新增 `.editorconfig`，统一要求 `*.py`、`*.md`、`*.toml` 等文本文件按 UTF-8 保存
- 根目录新增 `.gitattributes`，统一文本文件换行和工作区编码
- 新增 `scripts/check_encoding.py`，可做仓库级编码巡检

需要说明的是：

- `cli.py` 里部分 `\\u4e2d\\u6587` 形式属于 Python 的 Unicode 转义，不是乱码
- 真正的乱码通常来自“文件被 ANSI / GBK / UTF-8 混合保存”或“终端代码页不是 UTF-8”
- 以后新增或修改中文文件时，尽量使用支持 `.editorconfig` 的编辑器并保持 UTF-8 保存

如果你在本机 PowerShell 手工运行时仍遇到终端乱码，建议同时确认当前终端为 UTF-8，例如：

```powershell
chcp 65001
$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
```

建议日常提交前执行一次：

```powershell
python scripts/check_encoding.py
```

如果你希望每次 `git commit` 前自动执行编码检查，可以启用仓库内置 hook：

```powershell
powershell -ExecutionPolicy Bypass -File scripts/install_git_hooks.ps1
```

或手工执行：

```powershell
git config core.hooksPath .githooks
```

启用后，`pre-commit` 会在每次提交前自动运行：

```powershell
python scripts/check_encoding.py
```

如果需要让 Git 重新按仓库规则接管文本文件，可执行一次：

```powershell
git add --renormalize .
```

说明：

- `.editorconfig` 负责约束编辑器保存格式
- `.gitattributes` 负责约束 Git 文本归一化行为
- `scripts/check_encoding.py` 负责尽早发现非 UTF-8 文件或疑似乱码文本

这样不能做到绝对 100% 杜绝乱码，但已经能把“以后再出现乱码”的概率显著压低。

## 因子权重测试

新增命令：

```bash
python -m multifactor_quant.cli factor-weight-test ^
  --config multifactor.toml ^
  --config-profile production ^
  --train-start 2025-10-01 ^
  --symbols 600519.SH,000858.SZ ^
  --weight-override-grid momentum=0.2,0.4;text_sentiment_policy=0.1,0.3 ^
  --export-dir exports
```

该命令会测试不同因子权重组合对：

- 推荐结果
- Top 股票
- 回测总收益
- 超额收益
- 命中率
- 类夏普指标

的影响，并导出：

- `factor_weight_test/factor_weight_test.csv`
- `factor_weight_test/factor_weight_test.json`

这部分适合持续优化“实盘推荐”和“盈利最大化”方向的因子配置。