From 2d156f8da280ddae91472023747ada147f35e6d7 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Thu, 28 May 2026 10:00:07 +0800 Subject: [PATCH] auto-sync: 2026-05-28 10:00:07 --- docs/design/architecture-v3.0.md | 70 ++++++++++++-------------------- 1 file changed, 27 insertions(+), 43 deletions(-) diff --git a/docs/design/architecture-v3.0.md b/docs/design/architecture-v3.0.md index 1e4cc1e..aefa9aa 100644 --- a/docs/design/architecture-v3.0.md +++ b/docs/design/architecture-v3.0.md @@ -4,7 +4,7 @@ **基于**: PRD-v3.0 + architecture-v2.6 + v2.7~v3.0 增量设计 + 实际源码回溯 **作者**: 庞统（副军师） **日期**: 2026-05-28 -**状态**: 回溯定稿（v3 — 司马懿评审修正版） +**状态**: v3.0 正式版（T1 清理完成） --- @@ -552,7 +552,7 @@ Ticker.tick() } ``` -**Title 自动生成** 👻 BUG: `blackboard_routes._generate_title()` 直接用 OpenAI client 调 zhipu API 生成标题（不走 Gateway），绕过了 Gateway 统一路由 + 计费。与 v3.0 删除 LLMDriver 的目标矛盾。应改为走 Gateway API 或前端传 title（当前前端已支持）。 +**Title 自动生成** ⚠️ TODO: `blackboard_routes._generate_title()` 直接用 OpenAI client 调 zhipu API 生成标题（不走 Gateway），绕过了 Gateway 统一路由 + 计费。保留此函数，待未来替换为本地 LLM 调用。当前前端已支持传 title，LLM 生成只是 fallback。 ### 7.2 CLI 工具 ✅ @@ -1001,7 +1001,14 @@ SSEEventType: ## §17. 待实现项汇总（原则 2/3） -> ⚠️ 以下为庞统初判 + 用户复查后的修正版本。司马懿需重点验证：这些是否真的未实现？是否有遗漏的专题设计文档？ +> ⚠️ 以下为庞统初判 + 用户复查 + 司马懿评审后的修正版本（v3）。 +> +> **已清理的问题**（不在此列表中）： +> - ~~BUG-7 (planning 暂停失败)~~: v1 bug，v2 无 planning 状态，不存在 +> - ~~BUG-8 (cancel→resume 空图完成)~~: v1 bug，v2 用 Blackboard 模式，不走 DAG execute_graph +> - ~~P3 遗留 (404/4xx 响应码)~~: 已修复，当前代码已用 HTTPException +> - ~~续杯设计矛盾~~: 已验证代码与设计一致 +> - ~~广播认领矛盾~~: 已验证完整实现 ### 17.1 PRD 明确要求但未实现 @@ -1069,40 +1076,23 @@ SSEEventType: > ⚠️ 以下为庞统初判 + 用户复查后的修正版本。司马懿需重点验证：这些矛盾是否真实存在？是否是我们漏看了某个最新的设计专项？ -### 19.1 状态机：v2.8 设计 vs v3.1 代码 🔀 +### 19.1 状态机：v2.8 设计 vs v3.1 代码 ✅（已解决，以代码为准） -**v2.8-state-enhancement 设计**（§1.2 完整状态转换表）: +**决策**: 以代码实际实现为准，v2.8 设计文档已归档至 `archive-2.0/v2.8-state-enhancement.md`。 -``` -pending: [claimed, cancelled] -paused: [working, cancelled] -done: [] ← 终态 -cancelled: [] ← 终态 -``` +**代码实际状态机**（§5.2 已完整记录）: +- 11 个状态，VALID_TRANSITIONS 完整定义 +- `TERMINAL_STATUSES = frozenset()` — 无终态，全靠转换矩阵校验 +- `MANUAL_STATUSES = {cancelled, paused}` — 不参与聚合推导 +- paused 恢复通过 `resumed_from` 字段记录暂停前状态 +- done → cancelled、cancelled → pending 支持"反悔"操作 -**v3.1 代码**（db.py VALID_TRANSITIONS）: +**与 v2.8 设计的关键差异**（已归档，不再维护）: +- v2.8 定义了终态（done/cancelled），代码取消终态概念 +- v2.8 paused 只能恢复到 working，代码支持恢复到任意 paused 前状态 +- v2.8 pending 只能到 claimed/cancelled，代码多了 paused/blocked -``` -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() ← 空集，无终态 -``` - -**关键差异**: - -| 状态 | 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 取消了终态概念 | - -**评估**: 代码更灵活实用（paused 恢复、cancelled 重启是实际需求）。**建议更新 v2.8-state-enhancement.md 对齐代码**。v2.8 设计文档可能需要补充一个 v3.1 修订记录。 - -**司马重点验证**: 是否有 v2.8 之后的某个专题设计文档更新了状态转换矩阵，而我们没看到？ +这些差异都是工程实践中的合理扩展，代码更灵活实用。 ### 19.2 广播认领 vs Delegate 庞统 ✅（已解决，非矛盾） @@ -1120,19 +1110,13 @@ TERMINAL_STATUSES = frozenset() ← 空集，无终态 **纠正记录**: 庞统初版只检查了 router.py/spawner.py，遗漏了 ticker.py L540。司马懿评审纠正。 -### 19.3 `_generate_title()` 绕过 Gateway 👻 BUG +### 19.3 `_generate_title()` 绕过 Gateway ⚠️ TODO（保留，待替换本地 LLM） -**v3.0 设计**: 删除 LLMDriver 类，所有 LLM 调用走 Gateway。 +**现状**: `blackboard_routes._generate_title()`（line 138-175）直接用 OpenAI client 调 zhipu API，不走 Gateway。 -**实际 router.py**: LLMDriver 已删除 ✅ +**决策**: 保留此函数，不删除。未来替换为本地 LLM 调用。 -**但 `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）。 +**替换方向**: 本地 LLM（如 Ollama）或走 Gateway API。当前前端已支持传 title，LLM 只是 fallback，不影响正常使用。 ### 19.4 续杯设计 ✅（已验证一致）