From 44a75af38a8deafe214e4e62fe7cf4fb26fd9a3d Mon Sep 17 00:00:00 2001
From: cfdaily <cfdaily@gitee.com>
Date: Thu, 21 May 2026 10:57:41 +0800
Subject: [PATCH] auto-sync: 2026-05-21 10:57:41

---
 docs/design/v3.0-router-refactor.md | 174 ++++++++++++++++++++++++++++
 1 file changed, 174 insertions(+)
 create mode 100644 docs/design/v3.0-router-refactor.md

diff --git a/docs/design/v3.0-router-refactor.md b/docs/design/v3.0-router-refactor.md
new file mode 100644
index 0000000..17f3866
--- /dev/null
+++ b/docs/design/v3.0-router-refactor.md
@@ -0,0 +1,174 @@
+# v3.0 Router 重构方案：去掉独立 LLM，改用 Gateway spawn Agent
+
+**日期**: 2026-05-21
+**状态**: 方案待确认
+**影响文件**: `router.py`, `dispatcher.py`, `main.py`, `config/default.yaml`
+
+---
+
+## 问题
+
+当前 Router（`LLMDriver`）用独立的 `OpenAI()` 客户端直接调 zhipu API 做路由决策。
+这违反设计文档 `architecture-v2.6.md` 的核心原则：
+
+> **系统只有两种 LLM 调用方式，都通过 Gateway**：
+> 1. **L3 run agent** — `openclaw agent --agent <id>`，spawn 完整 Agent
+> 2. **L2 spawn sub** — `openclaw agent --agent <id> --session-id <uuid>`，轻量一次性
+
+独立 `OpenAI()` 不属于任何一层，是设计之外的野路子。
+
+### 具体问题
+1. **凭据管理**：需要单独维护 api_base/api_key，和 Gateway 配置重复
+2. **不走 Gateway**：无法利用 Gateway 的模型路由、fallback、计费
+3. **设计不一致**：设计文档三层模型（L1/L2/L3），Router 不在其中
+4. **可靠性差**：凭据为空时静默 fallback，不报错
+
+---
+
+## 方案：Router 改为"能力匹配 + spawn 庞统兜底"
+
+### 核心思路
+
+Router 有两种路由方式：
+- **确定性路由**（能力匹配、retry、handoff）→ 保留，纯 L1 逻辑，不调 LLM
+- **模糊路由**（首次分配、不确定场景）→ **不再调独立 LLM，改为 spawn 庞统让庞统决定**
+
+### 路由决策流程（改后）
+
+```
+任务进入 Router.route()
+  │
+  ├─ 快速路径1: 本地 action → daemon
+  ├─ 快速路径2: retry → 原执行者
+  ├─ Mode B: Agent handoff (next_capability) → 能力匹配
+  ├─ 快速路径3: 生命周期流转 → 能力匹配
+  ├─ 快速路径4: 有 assignee → 直接分
+  │
+  └─ 模糊场景（以上都不匹配）
+      │
+      → 返回 RouteDecision(agent_id="pangtong-fujunshi", mode="delegate")
+        庞统被 spawn 后，读取黑板任务信息，自己决定分配给谁
+        庞统通过 API 回写 assignee → ticker 下一轮 spawn 实际执行者
+```
+
+### 改动清单
+
+#### 1. 删除 `LLMDriver` 类（router.py）
+
+整个 `LLMDriver` 类删除，约 120 行。Router 的 `route()` 方法末尾：
+
+```python
+# 当前（Mode A: 独立 LLM 调用）
+if self.llm_driver:
+    decision = self.llm_driver.route(...)
+    ...
+
+# 改后（委托庞统）
+return RouteDecision(
+    agent_id=self.FALLBACK_AGENT,  # "pangtong-fujunshi"
+    reason="Uncertain routing, delegate to coordinator",
+    mode="delegate",
+    confidence=0.0,
+)
+```
+
+#### 2. `AgentRouter.__init__` 去掉 `llm_driver` 参数
+
+```python
+def __init__(self, agent_profiles, counter=None):  # 删 llm_driver
+```
+
+#### 3. Dispatcher 增加 `delegate` 模式处理
+
+当 `mode="delegate"` 时，spawn 庞统并传入"请分配此任务"的 prompt：
+
+```python
+# dispatcher.py decide() 中
+if decision.mode == "delegate":
+    return {
+        "level": DispatchLevel.FULL_AGENT,
+        "agent_id": "pangtong-fujunshi",
+        "reason": decision.reason,
+        "mode": "delegate",  # 标记，用于构建不同 prompt
+    }
+```
+
+`_build_spawn_message` 中为 `delegate` 模式生成专门的 prompt：
+
+```python
+if mode == "delegate":
+    return f"""你是任务协调员。请分析以下任务，决定最合适的执行者。
+
+## 任务信息
+- ID: {task.id}
+- 标题: {task.title}
+- 描述: {task.description}
+- 类型: {task.task_type}
+
+## 操作
+1. 分析任务需求
+2. 选择最合适的 Agent（从你已知的团队中）
+3. 通过 API 回写分配结果：
+   curl -X POST {api}/tasks/{task.id}/status -d '{{"status":"claimed","assignee":"<agent_id>"}}'
+4. 如果你自己能做，直接认领执行
+"""
+```
+
+#### 4. main.py 去掉 LLMDriver 初始化
+
+```python
+# 删掉 routing_config / llm_driver 的整个初始化块（~10行）
+# Router 构造不再传 llm_driver
+router = AgentRouter(
+    agent_profiles=agent_profiles,
+    counter=counter,
+)
+```
+
+#### 5. config/default.yaml 去掉 routing 节
+
+```yaml
+# 删掉整个 routing: 节（model/api_base/api_key/timeout/...）
+# 确定性路由的能力匹配不依赖配置
+# 模糊路由由庞统决策，不需要配置
+```
+
+---
+
+### 改动前后对比
+
+| 场景 | 改前 | 改后 |
+|------|------|------|
+| retry | 原执行者（确定性）| 不变 |
+| Agent handoff | 能力匹配（确定性）| 不变 |
+| 生命周期 review | 能力匹配（确定性）| 不变 |
+| 有 assignee | 直接分（确定性）| 不变 |
+| **首次分配/模糊** | **独立 LLM 调用** | **spawn 庞统决策** |
+
+### 影响
+
+- **删代码**：~130 行（LLMDriver + routing config）
+- **改代码**：~30 行（Router.route 末尾 + Dispatcher._build_spawn_message）
+- **config**：删 routing 节
+- **行为变化**：模糊场景从"1-2秒 LLM 返回"变成"spawn 庞统 → 庞统思考 → 回写"，多 30-60 秒但更准确
+- **优点**：不再需要维护独立 LLM 凭据，所有 AI 调用统一走 Gateway
+
+### 风险
+
+1. **庞统成为单点**：所有模糊路由都走庞统，如果庞统繁忙会被跳过（counter 限制）
+   - 缓解：庞统 max_concurrent=3，且 delegate 模式是轻量决策不是重活
+2. **速度变慢**：独立 LLM 1-2s vs spawn 庞统 30-60s
+   - 评估：首次分配本来就不用急，准确比快重要
+3. **确定性路由覆盖不到的场景**：如果能力匹配足够好，大部分场景不需要庞统
+   - 评估：对。实际运行中大部分任务要么有 assignee 要么有 task_type 可匹配
+
+---
+
+## 实施步骤
+
+1. 删 LLMDriver + router.py 清理
+2. main.py 去掉 llm_driver 初始化
+3. Dispatcher 增加 delegate 模式 prompt
+4. config/default.yaml 删 routing 节
+5. 发司马懿评审
+6. 评审通过后部署