# OpenClaw 跑 Backtrader 标准流程

> 目标：用 **OpenClaw + Backtrader** 稳定地做指数策略研究，避免“任务做完了但没人知道”“结果散落一地”“Codex 和回测执行混在一起”的问题。

---

## 1. 角色分工

### A. Codex / 编码代理负责什么
只负责：
- 新增/修改 Backtrader 策略
- 改实验脚本
- 加参数扫描逻辑
- 改 summary / report 输出
- 重构 `backtrader-lab/` 内的代码

### B. OpenClaw exec/process 负责什么
只负责：
- 真正执行 Backtrader 回测
- 跑参数扫描
- 管后台 session
- 读取日志
- 确认是否完成
- 主动反馈结果

### C. 不要混用
原则：
- **Codex 写代码**
- **Backtrader 脚本自己跑**

不要把“让 Codex 干活”和“让 Codex 顺便当回测引擎”混成一件事。

---

## 2. 工作目录约束

所有 Backtrader 工作都限制在：

```bash
/home/erwin/.openclaw/workspace/cyb50-quant/backtrader-lab
```

规则：
- 不碰 `MEMORY.md / SOUL.md / AGENTS.md / USER.md`
- 不跑去 `index-rotation/` 乱改
- 量化实验只在 `backtrader-lab/` 收口

---

## 3. 推荐目录结构

```text
backtrader-lab/
├── chinext50.csv
├── chinext50_experiments.py
├── chinext50_experiment_summary.md
├── chinext50_dualthrust_optimization.md
├── results/
│   ├── latest.json
│   ├── latest.log
│   └── runs/
├── scripts/
│   ├── run_experiments.sh
│   ├── run_dualthrust_opt.sh
│   └── notify_summary.sh
└── OPENCLAW_BACKTRADER_WORKFLOW.md
```

最低要求：
- 回测脚本
- markdown summary
- json 结果文件
- log 文件

---

## 4. 标准执行方式

### 4.1 单次实验
直接执行 Backtrader 脚本：

```bash
cd /home/erwin/.openclaw/workspace/cyb50-quant/backtrader-lab
python3 chinext50_experiments.py
```

### 4.2 参数优化

```bash
cd /home/erwin/.openclaw/workspace/cyb50-quant/backtrader-lab
python3 chinext50_experiments.py --optimize-dualthrust
```

### 4.3 长任务后台运行
让 OpenClaw 用 `exec + process` 托管：

- `exec(background=true, pty=false/true 视需要)` 启动
- `process poll/log` 只做状态确认
- 不搞 sleep loop

---

## 5. 输出产物规范

每次回测至少产出 3 类东西：

### A. summary.md
给人看的结论：
- 跑了哪些策略
- 参数是什么
- 年化 / 夏普 / 最大回撤 / 胜率
- 推荐继续哪条

### B. results.json
给程序看的结构化结果：
- strategy name
- config
- metrics
- startedAt
- finishedAt
- data range
- command

### C. run.log
给排错用：
- stdout
- stderr
- traceback
- 执行时长

规则：
- **有 markdown，方便我直接汇报给用户**
- **有 json，方便后续自动比对/排序**
- **有 log，方便排错**

---

## 6. 反馈优先协议（最重要）

后台任务默认执行这套：

### 开始
必须反馈：
- 跑什么
- 在哪跑
- session 是什么
- 大概多久

### 中间
出现以下情况必须主动反馈：
- 第一批结果出来
- 发现明显候选最优
- 某个方向明显不行
- 卡住 / 报错

### 结束
必须主动反馈：
- 最优策略
- 关键指标
- 结果文件位置
- 下一步建议

### 禁止
- 不允许任务做完后沉默
- 不允许等用户追问才汇报

---

## 7. 通知机制：不要单点依赖 system event

因为 `openclaw system event` 可能出现 websocket `1006 abnormal closure`，所以不能只靠它。

### 三层通知方案

#### 第一层：快路径
任务结束时尝试：

```bash
openclaw system event --text "Done: backtrader experiment finished" --mode now
```

#### 第二层：状态落盘
每个任务写状态文件：

```text
backtrader-lab/.task-watch/<task-id>.json
```

至少包含：
- task id
- session id
- command
- status: running / done / failed
- summary path
- updatedAt
- announced: true/false

#### 第三层：watchdog 兜底
如果：
- 任务已完成
- 但 `announced=false`

则父侧必须：
- 读取 summary
- 主动发结果
- 把 announced 标记为 true

### 结论
- `system event` 是快路径
- **watchdog 才是兜底**

---

## 8. OpenClaw 里更适合的使用姿势

### 情况 A：新增策略
用 Codex：
- 写新策略类
- 改 `chinext50_experiments.py`
- 加参数扫描

### 情况 B：跑实验
不用 Codex 代跑，直接：
- `python3 chinext50_experiments.py`
- `python3 chinext50_experiments.py --optimize-dualthrust`

### 情况 C：定时任务
用 `cron isolated`：
- 晚上自动跑回测
- 跑完自动写 summary
- 再显式投递到 Feishu 当前聊天

投递必须显式指定：
- `channel=feishu`
- `to=ou_3923ae1d25c5056a9844718baf153e36`
- `accountId=main`

不要再用 `last`。

---

## 9. 推荐的脚本化方式

建议补两个脚本。

### 9.1 `scripts/run_experiments.sh`
职责：
- 运行基础实验
- stdout/stderr 写入 `results/latest.log`
- 结果写入 `chinext50_experiment_summary.md`
- 同时生成 `results/latest.json`

### 9.2 `scripts/run_dualthrust_opt.sh`
职责：
- 跑 DualThrust 参数搜索
- 写 `chinext50_dualthrust_optimization.md`
- 生成 json 结果
- 更新 task status

---

## 10. 推荐的节奏

### 日常研究
- 白天：问答式、小范围单次回测
- 晚上：批量参数扫描
- 周末：统一做 shortlist 排名

### 研究顺序
1. 先广撒网找候选
2. 再缩到 Top 2~3
3. 再做参数优化
4. 再做样本外验证
5. 最后才考虑实盘映射

---

## 11. 当前项目下的建议落地

基于当前 `backtrader-lab/`，建议后续这样走：

### 主线候选
- `DualThrustRegimeStrategy`
- `DonchianRegimeStrategy`
- `MomentumVolTargetStrategy`

### 当前 DualThrust 优化候选
#### 综合最强
- `range_period=20, k1=0.4, k2=0.4, regime=120`

#### 更稳版本
- `range_period=30, k1=0.3, k2=0.3, regime=120`

### 下一步
- 做样本内/样本外拆分
- 做手续费敏感性
- 做不同时间段稳定性验证

---

## 12. 一句话版本

**Codex 写 Backtrader，OpenClaw exec 跑 Backtrader，cron 负责定时，watchdog 负责不漏反馈。**