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

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

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

1. **零信任读写分离 (Zero-Trust Read/Write Split)**：暴露在公网的服务仅提供纯静态渲染与只读 API，所有写操作强制通过 Admin API 配合 Bearer Token 鉴权。
2. **拒绝向量化中转 (No RAG/Embedding for State)**：摒弃使用 Embedding 模型作为任务状态缓存的方案。任务的本质是拓扑结构 (Topological Structure)，采用算法层面的**图遍历修剪 (Graph Traversal Pruning)** 实现上下文压缩，保留精确的前置/后置逻辑引用。
3. **白盒化执行 (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)$ 复杂度修剪算法：
1. **保留寻址坐标**: 完整输出从根节点到焦点节点的祖先路径。
2. **暴露局部视野**: 完整输出焦点节点的直接子节点。
3. **模糊兄弟分支**: 兄弟节点仅保留 `[状态] 标题`。
4. **折叠远端历史**: 已完成的无关树分支整合成一行统计摘要。

**输出形式**: 精简版 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)

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

---