EviCal

EviCal（Evidence-Calibrated Risk Allocation）是一套可审计的多因子风险预算框架。Agent 定义市场状态与因子状态，Ridge 用开发期数据学习“状态 → 未来 RankIC → 风险预算”；训练/验证门控、权重约束和含费回测由确定性代码执行。

正式实验覆盖 28、48、79 三档因子池，对比因子等权、单一动量、单一拥挤度和 EviCal。所有方法共享股票池、周频调仓、前 20% 等权多头及同一成本模型。

目录

evical/                  核心 Python 包
├─ agents/              Agent 调用与反馈迭代
├─ states/              固定状态和 Agent 状态规范
├─ policies/            Ridge 预算映射与权重约束
├─ backtest/            统一含费回测
├─ evaluation/          指标、门控和显著性检验
├─ experiments/         状态设计、风险预算与 replay 编排
└─ reporting/           报告数据和日度净值曲线
configs/                实验配置与策略要求
scripts/evical.py       统一实验入口
tests/                  测试
artifacts/evical/       数据缓存与实验产物
reports/evical/         报告网页源码

安装依赖

1. 环境要求

• Python 3.11 或更高版本。
• uv，用于按照仓库内的 uv.lock 创建 Python 虚拟环境并安装锁定依赖。
• Node.js 22.13 或更高版本，仅在开发或重新构建网页报告时需要；只运行 Python 实验无需安装 Node.js。

先克隆仓库并进入项目目录：

git clone <repository-url>
Set-Location CogAlpha_Prompt

若尚未安装 uv，可以在已有 Python 环境中安装：

python -m pip install --upgrade uv

2. Python 依赖

推荐严格使用仓库中的锁文件安装，包括测试依赖：

uv sync --frozen --extra dev

该命令会在项目内创建 .venv，无需手工激活；后续命令统一通过 uv run 执行。安装完成后运行测试：

uv run python --version
uv run pytest

3. 环境变量

复制环境变量模板：

Copy-Item .env.example .env

Linux/macOS 使用：

cp .env.example .env

按需在 .env 中填写 OPENAI_API_KEY、OPENAI_API_BASE、MODEL 和 TUSHARE_TOKEN。只有调用 Agent 或重新下载沪深300基准数据时才需要相应密钥；确定性 replay 不调用 LLM。.env 可能包含密钥，已被 Git 忽略，请勿提交或打包分发。

4. 本地数据

大体积数据和实验产物位于 artifacts/，该目录默认不纳入 Git。接收项目后，将股票面板放到：

artifacts/panel_1d.parquet

并在 configs/evical.yaml 中使用相对路径，避免依赖发送方电脑上的绝对路径：

panel_path: artifacts/panel_1d.parquet

项目会从完整面板中筛选 in_hs300 == 1 的动态沪深300成分股。若需要离线复现，还应一并保留 artifacts/evical/data/csi300_daily.parquet 和所需运行目录；否则程序会在配置了 TUSHARE_TOKEN 时重新获取基准数据。

5. 网页报告依赖（可选）

网页依赖由 package-lock.json 锁定，进入报告目录后安装：

Set-Location reports/evical
npm ci
npm run build

node_modules/ 是可重建目录，不应提交或放入项目交付包。返回项目根目录可执行：

Set-Location ../..

实验

Test/OOD 不得作为状态或参数选择依据。

# 1. 构建可复用因子、基础状态与先验
uv run python scripts/evical.py prepare `
  --config configs/evical.yaml `
  --run-id evical_prepare

# 2. Agent 迭代状态规范
uv run python scripts/evical.py design-states `
  --config configs/evical.yaml `
  --run-id evical_states `
  --prepared-source artifacts/evical/runs/evical_prepare/prepared `
  --state-attempts 3

# 3. 校准并冻结主风险预算策略
uv run python scripts/evical.py run `
  --config configs/evical.yaml `
  --run-id evical_main `
  --prepared-source artifacts/evical/runs/evical_prepare/prepared `
  --state-run artifacts/evical/runs/evical_states

# 4. 显著性检验与确定性重放
uv run python scripts/evical.py significance `
  --run-dir artifacts/evical/runs/evical_main

uv run python scripts/evical.py replay `
  --config configs/evical.yaml `
  --run-dir artifacts/evical/runs/evical_main

design-states 生成 Agent 状态规范，run 评估并冻结主风险预算策略，replay 在不调用 LLM 的情况下复核结果。若需让 Agent 参考上一轮失败原因，可向 design-states 追加 --prior-run <run-dir>。

报告

uv run python scripts/evical.py report `
  --run-dir artifacts/evical/runs/evical_main `
  --site-dir reports/evical

Set-Location reports/evical
npm ci
npm run build
npm run dev -- --port 3100

保持预览服务运行，在项目根目录执行：

node reports/export_evical_report.mjs

最终报告：reports/EviCal_研究报告.html。

产物

每次实验写入 artifacts/evical/runs/<run-id>/：

• manifest.json：配置、门控和汇总指标。
• policies/<pool>/：状态规范、校准参数、模型和候选记录。
• results/<pool>/<method>/<split>/：日度净值、因子权重、股票权重和成交。
• significance.json：显著性检验。
• replay_report.json：重放结果。