OpenClaw 任务看板 V2：系统架构与开发规范

版本: 2.0 (包含 V2.1 诊断特性与 V2.2 上下文压缩算法) 核心定位: 面向公网的高安全只读看板 + 大模型思维链 (CoT) 可视化引擎 + 基于图遍历的动态上下文管理器。

1. 架构设计哲学 (Design Philosophy)

零信任读写分离 (Zero-Trust Read/Write Split)：暴露在公网的服务仅提供纯静态渲染与只读 API，所有写操作强制通过 Admin API 配合 Bearer Token 鉴权。
拒绝向量化中转 (No RAG/Embedding for State)：摒弃使用 Embedding 模型作为任务状态缓存的方案。任务的本质是拓扑结构 (Topological Structure)，采用算法层面的图遍历修剪 (Graph Traversal Pruning) 实现上下文压缩，保留精确的前置/后置逻辑引用。
白盒化执行 (White-box Execution)：将本地 Ollama 模型的截断原因、Token 消耗、推理步骤，通过结构化解析实时映射到可视化节点，终结黑盒调试。

2. 系统目录结构与模块划分

系统严格按职责分为四层微服务架构：

text openclaw-task-board/ ├── backend/ # 后端服务 (Node.js 原生，无重型框架) │ ├── server.js # HTTP 与 API 入口 │ ├── auth.js # Admin Token 鉴权中间件 │ ├── sse.js # Server-Sent Events (SSE) 推送引擎 │ └── data/ │ ├── repository.js # 任务树 CRUD 与持久化 (tasks.json) │ └── tree-pruner.js # 焦点树修剪算法 (上下文压缩引擎) ├── frontend/ # 公网静态只读前端 │ ├── index.html # 包含画布与诊断侧边栏 │ ├── js/ │ │ ├── app.js # 状态机与 SSE 监听 │ │ ├── layout-engine.js # Thought-Chain DAG 布局计算 │ │ └── renderer.js # SVG 渲染、节点交互与动画 (滤镜) │ └── css/styles.css # 低饱和粉色主题与发光动画 ├── sync-hook/ # OpenClaw 插件层 │ ├── handler.js # 生命周期事件监听 │ ├── cot-parser.js # XML 标签解析 (<plan>, <think>, <action>) │ └── tools/ │ └── get_task_details.js # 给大模型注册的主动召回工具 └── docs/ # 架构与 API 契约

3. 核心数据契约 (Data Schema)

3.1 增强型节点模型 (Node Schema V2)

在系统间流转的最小数据单元，扩展了语义类型与大模型诊断信息。

`json { "id": "task-1708781234-abc", "conversationId": "sess-xyz789", "parentId": "task-1708781000-root", "nodeType": "thought", // 枚举: prompt | sub-goal | thought | action | observation | conclusion "name": "评估系统状态并决定下一步", "status": "in-progress", // 枚举: pending | in-progress | completed | bug "content": "具体的思考内容或执行细节...", "timestamps": {

"created": "2026-02-24T08:00:00Z",
"started": "2026-02-24T08:00:01Z",
"completed": null

}, "llmDiagnostics": {

"rawInputLength": 4500, // 字符级长度记录
"tokenUsage": {
  "promptTokens": 1542,
  "completionTokens": 500,
  "totalTokens": 2042
},
"stopReason": "length", // stop | length | load
"latencyMs": 14500

} } `

4. 核心子系统规范

4.1 通信与安全总线 (Backend)

Public API: GET /api/public/conversations 与 GET /api/public/tasks/:conversationId。仅响应 JSON，无鉴权，但需配置 CORS 与限流。
Admin API: POST/PUT/DELETE /api/admin/tasks。用于 sync-hook 推送节点变更，Header 必须校验 Authorization: Bearer <TOKEN>。
SSE 流: GET /api/public/stream/:conversationId。建立单向长连接，当 Admin API 触发数据变更时，向对应会话的订阅者广播增量 JSON。

4.2 思维导图渲染引擎 (Frontend)

布局算法 (Layout Engine): 废弃传统静态树。基于水平主轴 (时间线) 与垂直发散 (任务拆解) 计算 SVG 坐标。支持多节点收敛到单一 conclusion 节点 (DAG 渲染)。
视觉语言:
- in-progress: 保留旋转虚线，叠加脉冲发光 (feGaussianBlur)。
- bug (如 stopReason === 'length'): 节点外发红光，并在 UI 提供 Debug 详情面板。

4.3 上下文管理与注入引擎 (State Injection)

严格控制传递给大模型的上下文长度，限制条件为： $N{total}=N{prompt}+N{predict}\le N{ctx}$

利用 tree-pruner.js 实现基于当前焦点节点的 $O(N)$ 复杂度修剪算法：

保留寻址坐标: 完整输出从根节点到焦点节点的祖先路径。
暴露局部视野: 完整输出焦点节点的直接子节点。
模糊兄弟分支: 兄弟节点仅保留 [状态] 标题。
折叠远端历史: 已完成的无关树分支整合成一行统计摘要。

输出形式: 精简版 Markdown 文本，由 sync-hook 在每次请求前动态拉取，并作为 System Prompt 注入。

4.4 大模型能力扩展 (Agent Tools)

为应对修剪算法可能导致的深层历史细节丢失，必须向 Ollama 注册 Function Calling：

Tool Name: get_task_details
Input: taskId
Execution: Hook 拦截该调用，请求 backend 获取该节点的完整 JSON（含 notes, bugDetails），作为 observation 节点返回给大模型。

5. 阶段性开发路线 (Implementation Roadmap)

Phase 1: 基础设施重构 (Backend & Data Layer)
- 初始化分离的目录结构。
- 实现只读 Public API、鉴权 Admin API 与 JSON 持久化。
- 实现跨端 SSE 推送服务。
Phase 2: 核心算法与大模型对接 (Context & Hooks)
- 编写 tree-pruner.js 实现焦点树修剪算法。
- 在 sync-hook 中实现 XML 标签解析 (<plan>, <think>, <action>)，并将数据映射到 Admin API。
- 注入 get_task_details 工具。
Phase 3: 可视化与交互 (Frontend SVG)
- 重写基于 DAG 的水平-垂直布局算法。
- 接入 SSE 流实现页面无刷新的节点状态闪烁与连线绘制。
- 开发包含 llmDiagnostics 数据的调试侧边栏。

v2.md 6.3 KB History Raw