diff --git a/docs/design/architecture-v3.0.md b/docs/design/architecture-v3.0.md index 88b8adc..f2285f0 100644 --- a/docs/design/architecture-v3.0.md +++ b/docs/design/architecture-v3.0.md @@ -1066,45 +1066,80 @@ SSEEventType: ## §19. 设计矛盾记录(原则 6) -### 19.1 状态机矛盾 🔀 +> ⚠️ 以下为庞统初判 + 用户复查后的修正版本。司马懿需重点验证:这些矛盾是否真实存在?是否是我们漏看了某个最新的设计专项? -| 状态 | v2.8 设计 | v3.1 代码 | 影响 | -|------|----------|----------|------| -| `pending` | → {claimed, cancelled} | → {claimed, paused, blocked, cancelled} | 代码允许直接暂停/阻塞 pending 任务 | -| `paused` | → {working, cancelled} | → {working, claimed, review, escalated, waiting_human, cancelled} | 代码支持恢复到暂停前的任意状态 | -| `done` | → set() (终态) | → {cancelled} | 代码允许取消已完成任务 | -| `cancelled` | → set() (终态) | → {pending} | 代码允许重新启动已取消任务 | -| `TERMINAL_STATUSES` | 设计定义了终态 | 代码中为空集 `frozenset()` | v3.1 取消了终态概念,全靠 VALID_TRANSITIONS 校验 | +### 19.1 状态机:v2.8 设计 vs v3.1 代码 🔀 -**评估**: 代码的 v3.1 版本更灵活实用(支持暂停恢复、取消后重启),但与 v2.8 设计文档不一致。**建议更新设计文档对齐代码**。 +**v2.8-state-enhancement 设计**(§1.2 完整状态转换表): -### 19.2 Mail 退役矛盾 🔀 +``` +pending: [claimed, cancelled] +paused: [working, cancelled] +done: [] ← 终态 +cancelled: [] ← 终态 +``` -**v2.6 设计**: "Mail 完全退役。黑板的两个操作替代了 Mail 的所有功能。" +**v3.1 代码**(db.py VALID_TRANSITIONS): -**实际**: Mail 作为 `_mail` 虚拟项目完整保留,有独立的 API 路由、前端 Tab、专用 spawn prompt。 +``` +pending: [claimed, paused, blocked, cancelled] ← 多了 paused、blocked +paused: [working, claimed, review, escalated, waiting_human, cancelled] ← 恢复到 resumed_from 状态 +done: [cancelled] ← done 可取消 +cancelled: [pending] ← cancelled 可重启 +TERMINAL_STATUSES = frozenset() ← 空集,无终态 +``` -**评估**: Mail 保留是正确的工程决策。**建议 PRD 更新**:Mail 降级为辅助通道(非主力),但保留。 +**关键差异**: -### 19.3 广播认领 vs Delegate 庞统 🔀 +| 状态 | v2.8 设计 | v3.1 代码 | 差异原因 | +|------|----------|----------|---------| +| pending | → {claimed, cancelled} | → {claimed, paused, blocked, cancelled} | 代码允许直接暂停/阻塞 pending 任务 | +| paused 恢复 | → {working, cancelled} | → 任意 paused 前状态 | 代码通过 `resumed_from` 字段恢复到暂停前的状态 | +| done | 终态 | → {cancelled} | 代码允许取消已完成任务 | +| cancelled | 终态 | → {pending} | 代码允许重新启动已取消任务 | +| TERMINAL_STATUSES | 有终态 | 空集 | v3.1 取消了终态概念 | -**v3.0-router-refactor 设计**: 去掉独立 LLM,改为"广播认领 + 确定性交接"。广播所有空闲 Agent → 自主 claim。 +**评估**: 代码更灵活实用(paused 恢复、cancelled 重启是实际需求)。**建议更新 v2.8-state-enhancement.md 对齐代码**。v2.8 设计文档可能需要补充一个 v3.1 修订记录。 -**实际**: Router 的模糊场景直接 delegate 庞统(`mode="delegate"`),无广播机制。 +**司马重点验证**: 是否有 v2.8 之后的某个专题设计文档更新了状态转换矩阵,而我们没看到? -**评估**: delegate 庞统更简单可靠。广播认领的复杂度(多 Agent spawn 竞争、claim 超时管理)当前不必要。**建议保留广播认领设计作为 v3.1+ 目标**。 +### 19.2 广播认领 vs Delegate 庞统 🔀(待进一步探讨) -### 19.4 续杯设计矛盾 🔀 +**v3.0-router-refactor 设计**: 双路径调度 +- 确定性路径:已知下一步谁做 → 直接 spawn +- 广播认领路径:不确定 → spawn 所有空闲 Agent → 自主 claim +- 无人认领 → claim_timeout → 庞统兜底 -**spawner-monitor-design**: 续杯只有 A2/A3 (Gateway timeout) 触发。 +**实际代码**: +- ✅ 确定性路径已实现(Router → Dispatcher → Spawner) +- ❌ 广播认领路径未实现(`_broadcast_claim()` 不存在) +- 临时替代:模糊场景直接 delegate 庞统 -**实际 spawner 代码**: 续杯逻辑在 `_handle_exit` 中,但具体的 `_do_retry` 实现可能存在差异(需确认所有场景是否按设计处理)。 +**评估**: 这是 v3.0 的核心设计目标,不是"已废弃"。当前 delegate 庞统是临时方案。**待进一步探讨实施时机和方案**。 -### 19.5 LLMDriver 残留 👻 +**司马重点验证**: 是否有其他设计文档补充了广播认领的实施细节? -**v3.0 设计**: 删除 LLMDriver 类。 +### 19.3 `_generate_title()` 绕过 Gateway 👻 BUG -**实际 router.py**: LLMDriver 已删除 ✅。但 `blackboard_routes._generate_title()` 仍然直接调 zhipu API(不走 Gateway),属于同类问题。 +**v3.0 设计**: 删除 LLMDriver 类,所有 LLM 调用走 Gateway。 + +**实际 router.py**: LLMDriver 已删除 ✅ + +**但 `blackboard_routes._generate_title()`(line 138-175)**: +- 直接用 `OpenAI` client 调 zhipu API +- 不走 Gateway,绕过了统一路由、计费、fallback +- 读取 `~/.openclaw/openclaw.json` 的 zhipu 凭据 +- 默认模型 `glm-4-flash`,fallback 为截取 description 前 30 字 + +**评估**: 这是一个 bug,应该改走 Gateway API 或者干脆让前端传 title(当前前端已支持传 title,LLM 生成只是 fallback)。 + +### 19.4 续杯设计 ✅(已验证一致) + +**spawner-monitor-design v2.0**: 续杯只有 A2/A3(Gateway timeout)触发。 + +**实际 spawner 代码**: `_handle_exit` 中 `cls["should_retry"]` 为 True 时才走 `_do_retry`,注释明确 "只有 A2/A3(gateway_timeout)触发续杯,其他都不 retry"。 + +**结论**: 代码和设计一致,不存在矛盾。删除此矛盾项。 ---