cfdaily
519 lines
19 KiB
Markdown
519 lines
19 KiB
Markdown
# Agent 路由机制重设计方案
|
||
|
||
**版本**: v2.0
|
||
**作者**: 庞统（副军师）🐦
|
||
**日期**: 2026-05-17
|
||
**状态**: 待评审
|
||
**触发**: E2E 测试暴露 review 阶段派错 Agent（张飞被派去审查自己），根因是 Daemon 硬编码路由
|
||
**评审**: 司马懿
|
||
|
||
---
|
||
|
||
## 1. 问题诊断
|
||
|
||
### 1.1 Bug 根因
|
||
|
||
任务生命周期中 `assignee` 只在执行阶段被设置（张飞 claim → assignee="zhangfei-dev"）。到 review 阶段，`decide()` 走 Level 2：`task.assignee` 在注册列表中 → 又派给张飞。
|
||
|
||
### 1.2 更深层的问题
|
||
|
||
**Daemon 在做 AI 该做的决策。** v2.6 架构明确定义：
|
||
|
||
| 维度 | v2.6 设计目标 | 当前实现 |
|
||
|------|-------------|---------|
|
||
| 决策者 | Agent（在黑板上自主决策） | Daemon（if-else 硬编码） |
|
||
| Daemon 角色 | 投递员（执行黑板上的决策） | 调度器（决定谁干什么） |
|
||
| 编排方式 | AI agent 在黑板上自主领活 | 配置表驱动（非 AI 判断） |
|
||
|
||
T3-10 设计原文写着"配置表驱动非 AI 判断"——与 v2.6 核心原则矛盾。
|
||
|
||
---
|
||
|
||
## 2. 调研发现
|
||
|
||
### 2.1 学术前沿
|
||
|
||
| 来源 | 核心发现 | 对我们的价值 |
|
||
|------|---------|-------------|
|
||
| **bMAS** arXiv 2507.01701 | Control Unit（LLM 驱动）根据黑板当前内容动态选择 Agent | 路由本身可以是 LLM 调用，不是 if-else |
|
||
| **Self-Selection** arXiv 2510.01285 | 任务不显式分配，Agent 根据自己能力自主决定是否参与 | 最 AI Native 的模式，我们的演进目标 |
|
||
| **MasRouter** arXiv 2601.04861 | 根据任务复杂度动态选模型规模 + confidence 机制 | confidence 阈值 + 历史表现动态评分 |
|
||
| **AgentGate** arXiv 2604.06696 | 3B-7B 小模型做结构化路由决策 | 验证"路由可以是 AI"的可行性 |
|
||
|
||
### 2.2 生产实践
|
||
|
||
| 项目 | 模式 | 启发 |
|
||
|------|------|------|
|
||
| **Microsoft Conductor**（2026.05 开源） | YAML 确定性编排 | 确定性流程 + LLM 动态路由分层混合 |
|
||
| **Azure Agent Patterns** | 5 种模式：顺序/并发/群聊/**Handoff**/Magentic | **Handoff**：Agent 完成后自己决定交接给谁 |
|
||
| **AWS 动态分派** | 事件驱动 + 上下文感知路由 | 路由变成事件，不是轮询 |
|
||
| **Claude Code Agent Teams** | Lead coordinator + context 隔离 | Lead 做分解+分配+监控，subagent 只拿相关 context |
|
||
|
||
### 2.3 已有调研的线索
|
||
|
||
- architecture-v2.6.md：**"Agent 决策，Daemon 执行"**；Daemon 是投递员不是决策者
|
||
- shared-consciousness-research.md：Control Unit 是 LLM 驱动的，不是规则路由
|
||
- v2.6-research-01：Hermes 幻觉门控——不信任 Agent 完成声明
|
||
|
||
---
|
||
|
||
## 3. 设计原则
|
||
|
||
| # | 原则 | 说明 |
|
||
|---|------|------|
|
||
| P1 | 路由决策在 Agent 层，不在 Daemon 层 | "谁该做这个任务"由 Agent 自己或 LLM 决定，Daemon 只执行 |
|
||
| P2 | 当前 Agent 最清楚下一步需要谁 | 刚做完工作的人最清楚该交接给谁（Azure Handoff） |
|
||
| P3 | 路由可审计 | 每次路由决策记录到黑板，可回溯 |
|
||
|
||
---
|
||
|
||
## 4. 三种路由模式
|
||
|
||
### 4.1 模式总览
|
||
|
||
```
|
||
┌───────────────────────────────────────────────────────────┐
|
||
│ 路由决策入口 │
|
||
│ Dispatcher.decide(task) │
|
||
└────────┬──────────────┬──────────────────┬────────────────┘
|
||
│ │ │
|
||
┌────▼────┐ ┌────▼─────┐ ┌────────▼────────┐
|
||
│ Mode A │ │ Mode B │ │ Mode C │
|
||
│ LLM路由 │ │ Agent交接 │ │ Agent自主领活 │
|
||
│(中心化) │ │(去中心化) │ │ (去中心化) │
|
||
└────┬────┘ └────┬─────┘ └────────┬────────┘
|
||
│ │ │
|
||
LLM选Agent 执行者说需要谁 Agent自己来领
|
||
```
|
||
|
||
### 4.2 Mode A：LLM 路由（中心化）
|
||
|
||
**场景**：首次分配（pending → claimed）、异常升级（failed/blocked）、无明确 handoff 指令时。
|
||
|
||
**机制**：Daemon 调用一次轻量 LLM API，传入任务信息 + Agent 能力画像 + 负载状态，LLM 返回选择的 Agent + 理由 + 置信度。
|
||
|
||
**关键**：不是 spawn 一个 Agent session，是一次 ~300 token 的 API 调用（~1-2s，<¥0.01）。
|
||
|
||
```
|
||
输入: 任务描述 + 6个Agent画像 + 负载
|
||
输出: {"agent_id": "xxx", "reason": "...", "confidence": 0.9}
|
||
约束: ~200 token response, temperature=0.1
|
||
```
|
||
|
||
### 4.3 Mode B：Agent 声明式交接（去中心化）⭐ 最高频
|
||
|
||
**场景**：Agent 完成当前阶段后，明确声明下一步需要什么。
|
||
|
||
**机制**：Agent 在 POST /status 时附带 `next_capability` 字段：
|
||
|
||
```json
|
||
{
|
||
"status": "review",
|
||
"agent": "zhangfei-dev",
|
||
"next_capability": "review",
|
||
"handoff_note": "代码已实现，请审查质量和安全性"
|
||
}
|
||
```
|
||
|
||
Daemon 读 `next_capability`，查 Agent 能力画像找到匹配者（排除当前执行者），直接 spawn。
|
||
|
||
**这是最 AI Native 的模式**——刚做完工作的人最清楚下一步需要谁。不需要 LLM 调用，0ms 延迟。
|
||
|
||
### 4.4 Mode C：Agent 自主领活（去中心化）— 未来演进
|
||
|
||
**场景**：Daemon 广播任务需求，Agent 自己决定是否 claim。
|
||
|
||
**当前阶段不实现**，保留演进空间。数据结构（agent_profiles、capabilities）不变，只需把"Daemon 查表派发"改为"Daemon 广播 + Agent 自己 claim"。
|
||
|
||
### 4.5 模式选择逻辑
|
||
|
||
```python
|
||
def decide(self, task, action_type=""):
|
||
# 确定性快速路径（0ms，不调 LLM）
|
||
if self._is_deterministic(task, action_type):
|
||
return self._deterministic_route(task, action_type)
|
||
|
||
# Mode B: Agent 声明了 next_capability → 直接匹配
|
||
if task.next_capability:
|
||
return self._match_capability(task.next_capability,
|
||
exclude={task.assignee})
|
||
|
||
# Mode A: 无明确 handoff → LLM 路由
|
||
return self._llm_route(task, action_type)
|
||
```
|
||
|
||
**确定性快速路径**包括：
|
||
- 机械检查（L1_guardrail、format_check）→ Daemon 本地执行
|
||
- 已有 assignee 且非生命周期流转（如 crashed → retry 同一人）→ 直接用
|
||
|
||
---
|
||
|
||
## 5. 核心组件设计
|
||
|
||
### 5.1 Agent 能力画像（Agent Profile）
|
||
|
||
每个 Agent 在配置中声明自己的能力（**不是 Daemon 硬编码**）：
|
||
|
||
```yaml
|
||
# config/default.yaml → agents 段扩展
|
||
agents:
|
||
zhangfei-dev:
|
||
capabilities: [coding, implementation, scripting]
|
||
can_review: false
|
||
max_concurrent: 1
|
||
|
||
simayi-challenger:
|
||
capabilities: [review, quality_check, debate]
|
||
can_review: true
|
||
max_concurrent: 2
|
||
|
||
guanyu-dev:
|
||
capabilities: [risk, compliance, position_check]
|
||
can_review: true
|
||
max_concurrent: 1
|
||
|
||
zhaoyun-data:
|
||
capabilities: [data, acquisition, cleaning, verification]
|
||
can_review: false
|
||
max_concurrent: 1
|
||
|
||
jiangwei-infra:
|
||
capabilities: [deploy, infrastructure, docker, vnpy]
|
||
can_review: false
|
||
max_concurrent: 1
|
||
|
||
pangtong-fujunshi:
|
||
capabilities: [planning, coordination, escalation, strategy]
|
||
can_review: true
|
||
is_fallback: true
|
||
max_concurrent: 3
|
||
```
|
||
|
||
Daemon 启动时读取配置，写入黑板 `agent_profiles` 表。未来可演进为 Agent 自己注册。
|
||
|
||
### 5.2 LLM 路由器（LLMDriver）
|
||
|
||
```python
|
||
class LLMDriver:
|
||
"""bMAS Control Unit — 轻量 LLM 路由决策"""
|
||
|
||
def __init__(self, model: str, api_base: str, api_key: str):
|
||
self.model = model
|
||
self.client = OpenAI(base_url=api_base, api_key=api_key)
|
||
|
||
def route(self, task, agent_profiles, active_agents) -> RouteDecision:
|
||
prompt = self._build_prompt(task, agent_profiles, active_agents)
|
||
|
||
response = self.client.chat.completions.create(
|
||
model=self.model,
|
||
messages=[{"role": "user", "content": prompt}],
|
||
response_format={"type": "json_object"},
|
||
max_tokens=200,
|
||
temperature=0.1,
|
||
)
|
||
|
||
result = json.loads(response.choices[0].message.content)
|
||
return RouteDecision(
|
||
agent_id=result["agent_id"],
|
||
reason=result["reason"],
|
||
confidence=result.get("confidence", 0.5),
|
||
)
|
||
```
|
||
|
||
**Routing Prompt 模板**：
|
||
|
||
```
|
||
你是任务路由器。根据任务需求和 Agent 能力，选择最合适的 Agent。
|
||
|
||
## 当前任务
|
||
- ID: {task_id}
|
||
- 标题: {task_title}
|
||
- 状态: {task_status}
|
||
- 描述: {task_description}
|
||
- 上一步执行者: {previous_assignee}
|
||
|
||
## 可用 Agent
|
||
{每个Agent: ID, 能力列表, 当前负载}
|
||
|
||
## 约束
|
||
1. review/quality_check 不能选上一步执行者
|
||
2. 同等能力优先选负载最低的
|
||
3. 必须匹配任务所需能力
|
||
|
||
## 输出
|
||
{"agent_id": "...", "reason": "...", "confidence": 0.0-1.0}
|
||
```
|
||
|
||
### 5.3 Dispatcher 重写
|
||
|
||
```python
|
||
class Dispatcher:
|
||
def __init__(self, config, counter):
|
||
self.counter = counter
|
||
self.agent_profiles = config.get("agent_profiles", {})
|
||
self.llm = LLMDriver(
|
||
model=config.get("routing", {}).get("model", "zhipu/glm-5.1"),
|
||
api_base=config.get("routing", {}).get("api_base", ""),
|
||
api_key=config.get("routing", {}).get("api_key", ""),
|
||
)
|
||
self.LOCAL_ACTIONS = {"L1_guardrail", "format_check", "file_exists_check"}
|
||
|
||
def decide(self, task, action_type="") -> dict:
|
||
# ── 快速路径：确定性路由 ──
|
||
if action_type in self.LOCAL_ACTIONS:
|
||
return {"level": "local", "reason": "机械检查，Daemon本地执行"}
|
||
|
||
# retry 同一人
|
||
if action_type == "retry" and task.assignee:
|
||
return {"level": "full_agent", "agent_id": task.assignee,
|
||
"reason": "retry原执行者", "mode": "deterministic"}
|
||
|
||
# ── Mode B: Agent 声明式交接 ──
|
||
if task.next_capability:
|
||
agent = self._match_capability(task.next_capability,
|
||
exclude={task.assignee})
|
||
if agent:
|
||
return {"level": "full_agent", "agent_id": agent,
|
||
"reason": f"执行者handoff: 需要{task.next_capability}",
|
||
"mode": "agent_handoff"}
|
||
|
||
# ── Mode A: LLM 路由 ──
|
||
decision = self.llm.route(task, self.agent_profiles,
|
||
self.counter.active_agents)
|
||
|
||
# 合法性校验
|
||
if (decision.agent_id not in self.agent_profiles
|
||
or decision.confidence < 0.7):
|
||
return {"level": "full_agent", "agent_id": "pangtong-fujunshi",
|
||
"reason": f"LLM低置信度({decision.confidence}): {decision.reason}",
|
||
"mode": "fallback"}
|
||
|
||
return {"level": "full_agent", "agent_id": decision.agent_id,
|
||
"reason": decision.reason, "mode": "llm_route",
|
||
"confidence": decision.confidence}
|
||
|
||
def _match_capability(self, capability, exclude=None):
|
||
"""从能力画像中匹配 Agent"""
|
||
candidates = [
|
||
aid for aid, prof in self.agent_profiles.items()
|
||
if aid not in (exclude or set())
|
||
and capability in prof.get("capabilities", [])
|
||
]
|
||
if not candidates:
|
||
return None
|
||
if len(candidates) == 1:
|
||
return candidates[0]
|
||
return min(candidates, key=lambda a: self.counter.active_agents.get(a, 0))
|
||
```
|
||
|
||
### 5.4 assignee 语义变更
|
||
|
||
| 维度 | 当前 | 改为 |
|
||
|------|------|------|
|
||
| `assignee` 含义 | 任务负责人（贯穿全生命周期） | **当前阶段执行者**（随状态流转更新） |
|
||
| 新增 `previous_assignee` | 无 | 保存前一阶段执行者（用于排除和审计） |
|
||
|
||
```python
|
||
# 状态流转时更新
|
||
task.previous_assignee = task.assignee
|
||
task.assignee = new_agent_id
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 路由审计
|
||
|
||
每次路由决策写入黑板 `routing_decisions` 表。
|
||
|
||
### 6.1 表结构
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS routing_decisions (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
task_id TEXT NOT NULL,
|
||
from_status TEXT, -- 前一状态
|
||
to_status TEXT, -- 目标状态
|
||
mode TEXT NOT NULL, -- deterministic / agent_handoff / llm_route / fallback
|
||
selected_agent TEXT NOT NULL,
|
||
previous_agent TEXT, -- 前一阶段执行者
|
||
reason TEXT, -- 路由理由
|
||
confidence REAL, -- LLM 置信度（Mode A 才有）
|
||
model TEXT, -- 使用的 LLM 模型（Mode A 才有）
|
||
latency_ms INTEGER, -- 路由耗时
|
||
created_at TEXT DEFAULT (datetime('now')),
|
||
FOREIGN KEY (task_id) REFERENCES tasks(id)
|
||
);
|
||
|
||
CREATE INDEX idx_routing_task ON routing_decisions(task_id);
|
||
```
|
||
|
||
### 6.2 审计日志示例
|
||
|
||
```
|
||
task=test-e2e-001 | pending→claimed | mode=llm_route
|
||
→ zhangfei-dev (confidence=0.95, reason="编码任务匹配coding能力")
|
||
→ model=zhipu/glm-5.1, latency=1200ms
|
||
|
||
task=test-e2e-001 | working→review | mode=agent_handoff
|
||
→ simayi-challenger (reason="执行者handoff: 需要review")
|
||
→ latency=2ms
|
||
|
||
task=test-e2e-001 | review→done | mode=agent_handoff
|
||
→ pangtong-fujunshi (reason="审查通过，交接给协调者收尾")
|
||
→ latency=1ms
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 路由模型配置
|
||
|
||
### 7.1 后端配置
|
||
|
||
```yaml
|
||
# config/default.yaml 新增
|
||
routing:
|
||
model: "zhipu/glm-5.1" # 默认路由模型
|
||
api_base: "" # 空=用 OpenClaw Gateway
|
||
api_key: "" # 空=用 OpenClaw 默认
|
||
confidence_threshold: 0.7 # 低于此值 fallback
|
||
max_tokens: 200
|
||
temperature: 0.1
|
||
```
|
||
|
||
### 7.2 前端配置入口
|
||
|
||
在现有 `ModelConfig.tsx` 页面顶部新增"路由模型"配置区域：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 🎯 路由模型（Control Unit） │
|
||
│ ┌─────────────────────┐ ┌────┐ │
|
||
│ │ zhipu/glm-5.1 ▾ │ │应用│ │
|
||
│ └─────────────────────┘ └────┘ │
|
||
│ 任务路由使用的 LLM（推荐轻量快速模型） │
|
||
├─────────────────────────────────────────────┤
|
||
│ 🐦 庞统 pangtong-fujunshi │
|
||
│ 当前: zhipu/glm-5.1 │
|
||
│ ... │
|
||
```
|
||
|
||
- 模型下拉列表复用 OpenClaw 已注册的 `knownModels`（和 Agent 模型选的是同一个数据源）
|
||
- 通过后端 API `PATCH /api/config/routing-model` 保存
|
||
- 调用 `api.setModel` 同理，走 Gateway 模型配置
|
||
|
||
### 7.3 API
|
||
|
||
```python
|
||
# blackboard_routes.py 新增
|
||
@api_route("GET", "/api/config/routing")
|
||
def get_routing_config(request):
|
||
return {"model": config.routing.model,
|
||
"confidence_threshold": config.routing.confidence_threshold}
|
||
|
||
@api_route("PATCH", "/api/config/routing")
|
||
def set_routing_config(request):
|
||
new_model = request.json.get("model")
|
||
# 校验模型在 OpenClaw 已注册模型列表中
|
||
config.routing.model = new_model
|
||
config.save()
|
||
return {"ok": True}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 改动清单
|
||
|
||
### 8.1 数据模型
|
||
|
||
| 变更 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| 新增 `agent_profiles` 配置段 | 配置 | 每个 Agent 声明能力列表 |
|
||
| 新增 `routing` 配置段 | 配置 | 路由模型 + 参数 |
|
||
| tasks 新增 `next_capability` 字段 | DDL | Agent 声明下一步需要的能力 |
|
||
| tasks 新增 `previous_assignee` 字段 | DDL | 保存前一阶段执行者 |
|
||
| 新增 `routing_decisions` 表 | DDL | 路由审计日志 |
|
||
| `assignee` 语义变更 | 逻辑 | 从"任务负责人"改为"当前阶段执行者" |
|
||
|
||
### 8.2 代码
|
||
|
||
| 文件 | 变更 |
|
||
|------|------|
|
||
| `dispatcher.py` | 重写：新增 LLMDriver + Mode A/B/C 路由逻辑 |
|
||
| `config/default.yaml` | 新增 `agent_profiles` + `routing` 配置段 |
|
||
| `blackboard_routes.py` | status API 接受 `next_capability`；新增路由配置 API |
|
||
| `ticker.py` | 使用新 dispatcher；路由结果写 routing_decisions |
|
||
| `blackboard/db.py` | 新增 routing_decisions 表 DDL；tasks 表新增字段 |
|
||
| `ModelConfig.tsx` | 新增路由模型配置区域 |
|
||
|
||
### 8.3 不变
|
||
|
||
| 不变 | 原因 |
|
||
|------|------|
|
||
| 状态机（pending→claimed→working→review→done） | 状态流转语义正确 |
|
||
| Agent prompt 模板（S2） | Agent 仍按 4 步流程，只在 POST /status 时多传一个字段 |
|
||
| Spawner 逻辑 | spawn 机制不变 |
|
||
| 前端 Dashboard 核心布局 | 只在 ModelConfig 加一个区域 |
|
||
|
||
---
|
||
|
||
## 9. 和现有实践的对标
|
||
|
||
| 实践 | 本方案对应 |
|
||
|------|----------|
|
||
| bMAS Control Unit（LLM 驱动） | Mode A: LLMDriver 实现，轻量 API 调用 |
|
||
| Azure Handoff（Agent 交接） | Mode B: next_capability + handoff_note |
|
||
| 自主选择（arXiv 2510.01285） | Mode C: 未来演进，数据结构预留 |
|
||
| MasRouter（confidence） | confidence 阈值 + fallback 机制 |
|
||
| Microsoft Conductor（确定性 + 动态混合） | 快速路径（确定性）+ LLM 路由（动态）分层 |
|
||
| 幻觉门控（Hermes） | LLM 输出合法性校验 + confidence 阈值 |
|
||
| "Agent 决策，Daemon 执行"（v2.6 原则） | Mode B 是最直接的实现：Agent 自己决定交接给谁 |
|
||
|
||
---
|
||
|
||
## 10. 演进路线
|
||
|
||
```
|
||
Phase 1（本次实现）: Mode A + Mode B
|
||
- LLMDriver 路由（首次分配、异常场景）
|
||
- Agent 声明式交接（最高频场景）
|
||
- 路由审计表
|
||
- 前端路由模型配置
|
||
|
||
Phase 2（未来）: Mode C
|
||
- 同样的 agent_profiles 和 capabilities 数据结构
|
||
- Daemon 广播需求 → Agent 自己 claim
|
||
- 迁移成本极低（数据结构不变，只改消费方式）
|
||
|
||
Phase 3（更远）: 经验驱动的路由
|
||
- 路由审计数据反哺 LLM prompt（历史匹配成功率）
|
||
- Agent 可靠性评分（参考 MasRouter）
|
||
- 动态能力发现（Agent 完成新类型任务后自动更新画像）
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 司马懿评审要点
|
||
|
||
请重点关注：
|
||
|
||
1. **LLMDriver 的异常处理**：API 超时/失败时的 fallback 策略是否合理
|
||
2. **Mode B 的安全性**：Agent 声明 `next_capability` 时是否需要校验（防恶意指定）
|
||
3. **assignee 语义变更**的影响范围：是否有其他模块依赖"assignee = 任务负责人"
|
||
4. **routing_decisions 表设计**：字段是否充分，索引是否合理
|
||
5. **配置 API 的安全性**：修改路由模型是否需要鉴权
|
||
6. **性能影响**：Mode A 的 ~2s 延迟在 tick cycle 中是否可接受
|
||
|
||
---
|
||
|
||
## 12. 参考
|
||
|
||
- bMAS: arXiv 2507.01701 — Blackboard LLM Multi-Agent System
|
||
- Self-Selection: arXiv 2510.01285 — Agent 自主选择模式
|
||
- MasRouter: arXiv 2601.04861 — Confidence-Aware Routing
|
||
- AgentGate: arXiv 2604.06696 — 结构化路由引擎
|
||
- Microsoft Conductor: github.com/microsoft/conductor — 确定性编排
|
||
- Azure Agent Patterns: learn.microsoft.com — Handoff 模式
|
||
- v2.6 调研报告: docs/research/shared-consciousness-research.md
|
||
- v2.6 架构设计: docs/design/architecture-v2.6.md
|
||
- T3-10 调度判据: docs/design/topic3-challenge-review-proposal.md §5.4
|