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

AI-IDE 写策略技能

AI-IDE 用 AI 生成 Qlib 量化策略代码，并在 Docker 容器中隔离执行（策略运行 / 回测）。核心入口是 /api/v1/ai-ide/execute/*。

认证

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"
CT="Content-Type: application/json"

0. AI 服务（LLM）配置与自定义请求头

AI-IDE / QuantAgent / QuantBot 的 LLM 通道统一走「个人中心 → AI 服务」配置（持久化在 user_profiles）：

# 读取当前配置（api_key 已脱敏）
curl -s -H "$AUTH" "$BASE/api/v1/ai-ide/config/llm"

# 保存配置（自定义网关/模型：可带自定义请求头）
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/ai-ide/config/llm" -d '{
  "provider": "custom",
  "model": "your-model",
  "base_url": "https://your-gateway.example.com",
  "qwen_api_key": "sk-...",
  "extra_headers": "{\"x-opencode-session\": \"<session-id>\"}"
}'

# 测试连通（字段同上）
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/ai-ide/config/llm/test" -d '{ ... }'

• extra_headers：自定义请求头（JSON 字符串），存 user_profiles.llm_extra_headers，会注入到全部 LLM 调用 （AI-IDE/QuantAgent、QuantBot、策略 Lab、ai_strategy 等）。None=不改动，空串=清除，有值=覆盖。
• base_url：只填到域名即可，客户端会自动补 /v1/chat/completions（例：https://api.deepseek.com → https://api.deepseek.com/v1/chat/completions）。
• 注意：RD-Agent 子进程用的是自建网关，不会自动带上这里的 extra_headers（litellm 不读该变量），需要本地反向代理或单独 patch。

1. 运行策略 / 回测（核心）

AI-IDE 通过 Docker 容器执行策略代码。策略分三种模式自动识别：

1. 可执行脚本（有 if __name__ == '__main__' 或顶层可执行代码）
2. main() / run() 函数
3. 模块型策略（STRATEGY_CONFIG / get_strategy_config()）→ 回测中心兼容模式

1.1 启动执行（本地文件或临时代码）

# 从存储加载策略文件执行（云端策略）
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/ai-ide/execute/start" \
  -d '{
    "file_id": "strategy_id_xxx",
    "model_id": "mdl_cn_ensemble_xxx",        # 可选：指定回测模型（默认模型）
    "strategy_id": "strategy_xxx",
    "run_id": "run_xxx",
    "qlib_provider_uri": "db/qlib_data",      # 多市场 Qlib 数据路径
    "qlib_region": "cn",                      # cn / us / hk / crypto / futures
    "benchmark": "SH000300"
  }'

# 直接传代码执行（未保存代码）
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/ai-ide/execute/run-tmp" \
  -d '{
    "content": "print(1+1)",
    "filename": "tmp_strategy.py",
    "model_id": "mdl_cn_ensemble_xxx"
  }'
# 返回: {job_id, status: "started", runner_image}

1.2 流式查看日志 / 结果

# SSE 流式日志（[SYSTEM]/[RESULT]/[ERROR]/[PROCESS_FINISHED]）
curl -s -N -H "$AUTH" "$BASE/api/v1/ai-ide/execute/logs/{job_id}"

日志关键标记：

• [SYSTEM] 使用回测中心同一回测引擎执行 — 模块型策略进入回测
• [RESULT] annual_return: ... / sharpe_ratio: ... — 回测结果
• [ERROR] ... — 执行错误
• [PROCESS_FINISHED] — 执行结束

1.3 停止执行

curl -s -X POST -H "$AUTH" "$BASE/api/v1/ai-ide/execute/stop/{job_id}"

1.4 语法检查

curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/ai-ide/execute/check-syntax" \
  -d '{"code": "class Strategy: ..."}'

2. 回测默认模型

AI-IDE 回测使用默认模型（GET /api/v1/models/default，缺失时先经管理后台/训练链路配置），回测前自动检查模型 pred 就绪：

• 单模型：读模型目录 pred.pkl / pred.parquet；缺失时提示"请先对该模型执行推理生成预测"
• 融合模型（ensemble_config.json）：自动用子模型 pred 融合生成 pred.pkl（截面排名百分位加权）
• 向量化极速回测：纯 TopK 策略（topk=n_drop、无加权/无止损/无自定义类）自动走向量化引擎（秒级），复杂策略保真走 step 模式

3. 策略代码规范

模块型策略（回测中心兼容模式）需定义：

• STRATEGY_CONFIG：dict，含 class + kwargs（signal/topk/n_drop/rebalance_days 等）
• 或 get_strategy_config()：返回上述 dict
• 支持 POOL_FILE 顶部变量指定股票池文件

策略类参考（以代码为准：extended_strategies.py + recording_strategy.py；module_path 必须显写， 仅下表前 7 个类缺省时可由 builder 自动补全 strategy_builder.py:16-24）：

禁止引用 RedisVolatilityWeightedStrategy / RedisFullAlphaStrategy：代码中不存在， 生成会导致 ImportError。最小可用结构见后端模板 backend/services/engine/routers/ai_ide/skill_templates/qlib_model_strategy_config.md:16-35 （get_strategy_config() + signal: "<PRED>" + topk/n_drop/rebalance_days/only_tradable 必备， 因子过滤必须用 f_ 前缀参数）。

4. 股票代码口径（分层，禁止混用）

• Strategy Lab SDK（universe、buy/sell、ctx.history/feature）：前缀式 SH600036
• Qlib 模块型策略 / 直接读 QuantDB parquet / /stock-terminal / D.features：后缀式 600036.SH （跨格式查 parquet 会静默查空；Qlib 内部大小写由回测层自动兼容，生成代码时不用手写小写）
• 前端展示 / PG / Redis：前缀式（SH600036；Redis 快照键为小写 market:snapshot:sh600036）
• 生成策略代码时按目标执行层选用格式；不确定时用 StockCodeUtil.to_suffix/to_prefix （backend/shared/stock_utils.py）显式转换，禁止手写切片。

5. 策略云端落库

# 保存策略（字段以 StrategyCreateRequest 为准：name 必填，调参放 parameters，勿用 params/strategy_type/market）
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/strategies" \
  -d '{
    "name": "AI生成-低估值策略",
    "description": "PE<15 且 ROE>10",
    "code": "STRATEGY_CONFIG = {...}",
    "parameters": {"topk": 50, "n_drop": 5, "rebalance_days": 3},
    "tags": ["AI生成"]
  }'

# 策略列表 / 模板
curl -s -H "$AUTH" "$BASE/api/v1/strategies"
curl -s -H "$AUTH" "$BASE/api/v1/strategies/templates"

6. 实战流程（推荐）

当用户要求"写个策略 / 运行策略"时：

1. 理解需求：确认选股条件（市值/PE/ROE/动量/行业等）和市场
2. 生成策略代码：构造 STRATEGY_CONFIG（模块型）或可执行脚本
3. 保存落库：/strategies POST 保存到云端
4. 执行：/ai-ide/execute/start（带 model_id + qlib_provider_uri）
5. 看结果：/ai-ide/execute/logs/{job_id} SSE 流式，等 [PROCESS_FINISHED]
6. 回测深挖：用 [[backtest-center]] 技能对策略跑完整回测
7. 调优迭代：根据回测结果调参数，重新生成

7. 相关技能

• [[backtest-center]] — 完整回测中心（对比/优化/深度分析）
• [[smart-strategy-stock-picking]] — 条件选股生成股票池
• [[quantmind-operations]] — 模型训练/推理/数据更新

8. 常见问题