auto-sync: 2026-05-28 08:13:07

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"。
+
+**结论**: 代码和设计一致，不存在矛盾。删除此矛盾项。
 
 ---