From 4a9cf41ad31a94935f71c7327787d2e09e3d472b Mon Sep 17 00:00:00 2001
From: cfdaily <cfdaily@gitee.com>
Date: Sat, 30 May 2026 09:01:45 +0800
Subject: [PATCH] auto-sync: 2026-05-30 09:01:45

---
 docs/design/02-main-session-delegation.md | 40 +++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/design/02-main-session-delegation.md b/docs/design/02-main-session-delegation.md
index 7c58e83..ff75eac 100644
--- a/docs/design/02-main-session-delegation.md
+++ b/docs/design/02-main-session-delegation.md
@@ -480,6 +480,46 @@ openclaw agent 子进程退出
 - 验证 Agent 自主决策行为
 - 重跑 01-four-phase-loop 的 E2E 测试
 
+### Phase 3：迁移方案
+
+**迁移策略**：新旧路径并行，通过 feature flag 切换。
+
+```python
+# spawner.py
+USE_MAIN_SESSION = os.environ.get("MOZIPLUS_USE_MAIN_SESSION", "0") == "1"
+
+def spawn_full_agent(self, agent_id, ..., use_main_session=False):
+    if USE_MAIN_SESSION or use_main_session:
+        # 新路径：投递到 main session
+        return self._spawn_to_main_session(agent_id, ...)
+    else:
+        # 旧路径：UUID session（现有逻辑，保留）
+        return self._spawn_uuid_session(agent_id, ...)
+```
+
+**迁移步骤**：
+1. 代码部署（新旧路径并存，feature flag 默认关闭）
+2. 手动测试一个任务走新路径 → 验证 session 不爆炸、产出物正确
+3. 设置 `MOZIPLUS_USE_MAIN_SESSION=1` 开启全量迁移
+4. 监控 24h，检查：session 数量、任务完成率、幻觉误判率
+5. 确认稳定后删除旧路径代码
+
+**进行中任务处理**：
+- feature flag 切换前已创建但未完成的任务 → 继续走旧路径（`reuse_session_id=UUID`）
+- 切换后新创建的任务 → 走新路径（`use_main_session=True`）
+- `task_type=mail` 不受影响（Mail 路径已在 v1.0 使用 main session）
+
+**回滚方案**：
+- 设置 `MOZIPLUS_USE_MAIN_SESSION=0` → 立即切回旧路径
+- 新路径已产生的 session 保留不清理（不影响旧路径）
+- 回滚不会丢失数据（黑板数据独立于 session 路径）
+
+**回滚触发条件**：
+- session 数量未减少（新路径也有 session 爆炸）
+- 任务完成率下降超 30%
+- 幻觉误判（标 failed 但实际有产出）超过 10%
+- Agent main session 频繁超时（>5 次/小时`openclaw agent` 子进程超时）
+
 ---
 
 ## 十一、参考文件