rd-agent-factor-mining

⚙️ 本技能遵循公共运行环境契约（最高优先级，先于本文其余内容执行）： 详见 _shared/env-contract.md，执行前先读它。

RD-Agent 因子挖掘（端到端流水线）

调用 RD-Agent（Alpha Agent）自动挖掘 A 股 alpha 因子，覆盖完整链路： preflight → evolve（LLM 演化）→ 轮询 → 批量回测 → 排名 → explain → export → 报告。

0. 环境前置（必须，一分钟先过）

做任何挖掘前，先跑容器内三项健康检查。任一 FAIL 都要先修再挖。

cd ~/projects/quantmind && python3 scripts/alpha_agent/factor_pipeline.py --check-env
# 期望 3 项全 PASS: conda_shim / litellm_patch / deepseek_key

检查项	作用	失败处理
hardware	最低 8 核 / 32GB。RD-Agent 演化会把 CPU/内存打满，低于此规格直接 412 失败，避免整机卡死	换机器或关其他重负载；测试可设 ALPHA_AGENT_SKIP_HW_LOCK=1（生产勿开）
conda_shim	RD-Agent LocalEnv 硬编码 rdagent4qlib conda 环境，容器无 conda，靠 shim 映射到容器 python	确认 docker/conda-shim 挂载 /usr/local/bin/conda:ro 且文件有 +x
litellm_patch	litellm 1.97 + pydantic 2.13 冲突（Message is not fully defined）	确认 docker/litellm_sitecustomize.py 挂载为 site-packages/sitecustomize.py:ro
deepseek_key	因子挖掘走 DeepSeek 通道（llm_env.py 优先级最高）	更新 ~/projects/quantmind/.env 的 DEEPSEEK_API_KEY，改后必须 docker compose up -d quantmind recreate

preflight 机制全在管道脚本内置；手动检修环境见文末「常见问题」。

1. 一键管线（推荐入口）

cd ~/projects/quantmind

# 最小示例：一个方向，演化+批量回测+排名（默认报告 /tmp/rd_agent_factor_report.md）
python3 scripts/alpha_agent/factor_pipeline.py --direction "连板高度递减与涨停回封率"

# 全流程：演化 + 回测 + top5 解读 + 最高 |IC| 导出
python3 scripts/alpha_agent/factor_pipeline.py \
  --direction "筹码集中度上行伴随低位换手放大" \
  --universe csi300 --loops 3 \
  --explain-top 5 --export --min-ic 0.03 \
  --out /tmp/factor_report.md

# 只看环境
python3 scripts/alpha_agent/factor_pipeline.py --check-env

参数：

参数	默认	说明
--direction	必填	挖掘方向/假设，中文优先（见方向建议库）
--universe	csi300	csi300/csi500/csi1000/sse50/gem/star/csi800/all_a
--loops	3	演化轮数，实际以任务详情为准（可能出现归一值）
--check-env	off	只跑环境健康检查
--no-backtest	off	演化完成即停，不批量回测
--backtest-start	2025-01-01	回测起始日（到当天）
--backtest-universe	=universe	回测股票池
--explain-top N	0	对
--export / --min-ic	off / 0.0	对
--out	/tmp/rd_agent_factor_report.md	报告路径
--show-log	off	轮询时打印任务日志

管线阶段（脚本自动执行）：

1. preflight 三项健康检查
2. evolve 启动演化 → 拿 task_id
3. 轮询 tasks/{id} 直到 completed（打印 phase/loop/error）
4. 收集本次 task_id 的因子（metadata.task_id 过滤）
5. 逐个 factor/{id}/backtest 触发 → 轮询全部 completed
6. 按 |IC| 排序打印排行榜
7. 对 --explain-top 因子 explain（LLM 解读，写入报告）
8. --export 最高分因子
9. 生成 Markdown 报告到 --out

一个方向跑完约 30–90 分钟（数据管线 + LLM 演化 + 逐因子回测）。

1.5 因子工厂（QuantDB 富字段 × 算子 × 窗口 → 成千上万表达式因子）

R&D-Agent 是「LLM 提假设 → 逐因子回测」；因子工厂是「系统性批量衍生」：拿 QuantDB 的几百个数值字段 （l1_factors / features_daily）做算子 × 窗口 × 二元组合，全量算 IC/ICIR、相关性去重，产出可训练 parquet。 适合「数据面已知、想从海量式子里筛好货」。两者互补，可都跑。

# 容器内执行（重依赖 duckdb/pandas，QwenPaw 本地 venv 跑不了）
docker exec -w /app quantmind python /app/backend/scripts/factor_factory.py \
  --start-date 2025-09-01 --end-date 2026-08-31 --top-n 200
# 冒烟（小样本，先验证环境）
docker exec -w /app quantmind python /app/backend/scripts/factor_factory.py --smoke

• 产物：data/quantcustom/6_ml_datasets/l1_factors/dt=YYYYMMDD/data.parquet（列：symbol(后缀式) + date + OHLCV + 因子 float32）、MANIFEST.csv、PROPOSALS.json。
• 关键参数：--windows 5,10,20,60、--ops tsrank,tsstd,roc,zscore,delta,decay,slope、--cs-ops csrank,cszscore、--binary-ops csdiff,csratio,tscorr、--top-n 200、--pool-factor 3.0、--corr-threshold 0.85、--jobs 0（自动并行）、--compression zstd、--out。
• 只读展示：GET /api/v1/alpha-agent/factory-factors（读 MANIFEST，前端因子库加「工厂」徽标，仅展示不回测/训练操作）。
• 训练侧读取：QuantDBFactorReader(mode="CUSTOM")（QM_QUANTCUSTOM_DATA_DIR）。
• 落盘/目录口径见 [[quantdb-data-structure]] 的 quantcustom 小节。

2. 手动分步（需要精细控制时用 API）

认证

BASE=http://127.0.0.1:8000
TOKEN=$(curl -s -X POST $BASE/api/v1/auth/login -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123","tenant_id":"default"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('access_token',''))")
AUTH="Authorization: Bearer $TOKEN"

池子 / 类别 / 数据健康

curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/universes"        # 支持的股票池
curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/markets"          # 支持的市场
curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/factor-categories" # 挖掘类别参考
curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/data-summary"      # 数据覆盖（日期/股票数）

启动演化

curl -s -X POST "$BASE/api/v1/alpha-agent/evolve" -H "$AUTH" \
  --data-urlencode "market=a_share" \
  --data-urlencode "universe=csi300" \
  --data-urlencode "loop_n=3" \
  --data-urlencode "direction=低换手率高动量" \
  -w "\nHTTP %{http_code}\n"
# 返回 task_id（后续所有步骤用）

轮询 / 取消

curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/tasks/{task_id}"      # 状态 progress/phase/loop/error
curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/tasks/{task_id}/log"  # 实时日志（含失败原因）
curl -s -X POST -H "$AUTH" "$BASE/api/v1/alpha-agent/tasks/{task_id}/cancel"
# 状态机: pending → running → backtesting → completed | failed

因子回测（注意是 query 参数，不是 form）

curl -s -X POST -H "$AUTH" "$BASE/api/v1/alpha-agent/factors/{factor_id}/backtest?start_date=2025-01-01&end_date=2026-08-21&universe=csi300&data_source=qlib_bin"
# factors 列表里 ic_value/sharpe_ratio/rank_ic 回测完成后回填；status 变 completed

解读 / 导出 / 统计

curl -s -X POST -H "$AUTH" "$BASE/api/v1/alpha-agent/factors/{factor_id}/explain"   # LLM 解读因子逻辑
curl -s -X POST -H "$AUTH" "$BASE/api/v1/alpha-agent/factors/{factor_id}/export"    # 加入生产特征库
curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/factors"                               # 全部因子（含本次 task 的）
curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/stats"                                 # avg_ic/best_sharpe 等

3. 方向建议库（direction 直接用）

优先挖 78 核心因子集之外的空白区（筹码/微观结构/连板情绪/隔夜/资金流持续性）：

1. 连板情绪承继   连板高度递增与涨停回封率，捕捉题材情绪承接力由弱转强的启动票
2. 筹码分布       筹码集中度上行伴随低位换手放大，获利盘充分消化的突破信号
3. 隔夜/日内背离  隔夜收益与日内收益背离，捕捉大单隔夜布局意图
4. 资金流持续性   主力大单净流入的天数持续性与金额强度共振
5. 下行波动偏度   低下行风险与负偏度修正，挖掘低波动异象的非对称变体
6. 量价微观结构   开盘跳空幅度与量能共振，叠加尾盘动量延续
7. 动量质量       趋势斜率 R2 与收益动量叠加，过滤高噪音动量
8. 波动聚簇修正   波动率自相关的反转信号（高低波动切换）
9. 流动性衰减     换手率衰减速度与跌幅对比
10. 行业相对强度   个股相对行业指数 20 日超额与行业轮动方向一致

每批建议跑 1–3 个方向（串行排队），避免队列过载。

4. 验收标准（工具完成后自查）

• preflight 三项 PASS
• 演化任务 completed（非 failed）
• 有因子入库且完成批量回测（ic_value 非空）
• 排行榜上 |IC| 高、ICIR 明显 > 0 的因子受关注
• 高分因子完成 explain，解读与 direction 假设一致（非噪声）
• 确认有效的因子已 export（日志有导出记录）
• 报告落盘（默认 /tmp/rd_agent_factor_report.md）

5. 常见问题与踩坑

现象	根因	处理
timeout: failed to run command 'python' + conda: not found	容器无 conda，RD-Agent 需 rdagent4qlib env	conda shim 挂载 /usr/local/bin/conda；宿主机文件记得 chmod +x
Message is not fully defined / ChatCompletionReasoningSummaryTextBlock is not defined	litellm 1.97 + pydantic 2.13 冲突	docker/litellm_sitecustomize.py 挂载为 sitecustomize
Authentication Fails ... api key is invalid	DEEPSEEK_API_KEY 失效	换 key 到 .env，docker compose up -d quantmind recreate 才生效
因子 status=pending 且 ic_value=null	还没跑回测	触发 backtest（pipeline /--no-backtest 时更是如此）
任务秒 failed	先看 tasks/{id}/log 尾部具体错误	常见上面两类，按表修
engine upstream unavailable(503)	回测并发把 engine 挤忙	稍等重试；少并行任务
传 universe=all_a 详情显示 csi300	后端对部分池归一	以任务详情 universe 为准

6. 参考文件

• 一键管线：scripts/alpha_agent/factor_pipeline.py
• 环境修复：docker/conda-shim、docker/litellm_sitecustomize.py（compose 挂载固化）
• RD-Agent Runner 入口：scripts/alpha_agent/run_rd_agent.py
• 因子工厂：backend/scripts/factor_factory.py（+ backend/scripts/alpha_library_factors.py 复用算子/写盘）