# OpenClaw 任务看板：当前实现方法与技术要点（基线）

更新时间：2026-02-24

## 1. 当前实现目标与范围

当前版本已经实现一个可运行的“对话任务看板”基线，核心目标是：

1. 把 OpenClaw 对话自动同步为任务节点。
2. 以思维导图形式在画布展示父子层级关系。
3. 支持节点详情卡编辑（开始时间、计划、Bug 原因、备注等）。
4. 支持导出 JSON / SVG。
5. 用低饱和粉色主题展示状态，执行中节点带旋转虚线动画。

## 2. 代码结构与职责

| 路径 | 职责 |
| --- | --- |
| `task-board/server.js` | Node 原生 HTTP 服务，提供静态资源与任务 CRUD API，持久化到 `tasks.json` |
| `task-board/public/index.html` | 页面结构：顶部工具栏、侧边统计、SVG 画布、节点详情弹窗 |
| `task-board/public/app.js` | 前端状态管理、树布局计算、SVG 绘制、节点交互、导出逻辑 |
| `task-board/public/styles.css` | 低饱和粉色主题、状态色、连线样式、执行中虚线旋转动画、响应式布局 |
| `hooks/task-board-realtime/HOOK.md` | Hook 元数据，声明监听的 OpenClaw 事件 |
| `hooks/task-board-realtime/handler.js` | 对话到任务节点的实时同步逻辑（含去重、补偿扫描、会话收尾） |
| `task-board/.sync-state.json` | Hook 同步状态（会话映射、计数器、已处理消息索引） |
| `task-board/tasks.json` | 看板任务数据文件 |

## 3. 后端实现（任务服务）

服务：`task-board/server.js`

### 3.1 技术选型

1. Node.js 原生 `http` + `fs`，无额外框架。
2. 单文件 JSON 持久化，适合本地轻量部署与调试。

### 3.2 任务数据模型

字段（标准化后）：

1. `id`：`timestamp-random` 形式字符串。
2. `name`：节点名称，最长 120。
3. `parentId`：父节点 id，根节点为 `null`。
4. `status`：`pending | in-progress | completed | bug`。
5. `createdAt` / `updatedAt`：ISO 时间。
6. `startTime` / `endTime`：可选 ISO 时间。
7. `plannedApproach`：计划说明（最多 2000）。
8. `bugDetails`：Bug 终止说明（最多 2000）。
9. `notes`：补充信息（最多 3000）。

### 3.3 API

1. `GET /api/tasks`：返回任务列表。
2. `POST /api/tasks`：创建任务（校验父节点存在）。
3. `PUT /api/tasks/:id`：更新任务（校验状态、时间、父子环）。
4. `DELETE /api/tasks/:id`：级联删除该节点及全子树。

### 3.4 关键约束

1. 父子关系禁止成环（`detectCycle`）。
2. 状态自动补齐时间：
3. `in-progress` 无 `startTime` 时自动填充。
4. `completed/bug` 无 `endTime` 时自动填充。

## 4. 前端实现（画布 + 卡片）

入口：`task-board/public/app.js`

### 4.1 画布与布局

1. 使用 SVG 分层渲染：`linksLayer`（连线）+ `nodesLayer`（节点）。
2. 通过 `buildTreeLayout` 把数据组织成树：
3. 根节点按 `createdAt` 排序。
4. 子节点按 `createdAt` 排序。
5. `x` 由深度决定，`y` 通过 DFS 叶子递增并把父节点放在子树中线。
6. 连线使用三次贝塞尔曲线。

### 4.2 交互能力

1. 拖拽平移画布（pointer）。
2. 滚轮缩放（scale clamp）。
3. `fitView` 自动适配到当前节点包围盒。
4. 点击节点打开详情弹窗。
5. 弹窗可编辑状态、时间、计划、Bug、备注；可增删子节点。
6. 导出 JSON 与 SVG。

### 4.3 状态与视觉表达

1. 低饱和粉色主色系在 `styles.css` 的 `:root` 变量定义。
2. 状态色：
3. `pending` 灰粉、`in-progress` 粉、`completed` 绿、`bug` 红粉。
4. 执行中动画：
5. 节点外环 `progress-ring` 使用 `stroke-dasharray` + `stroke-dashoffset` 动画旋转虚线。

## 5. 实时同步实现（OpenClaw Hook）

入口：`hooks/task-board-realtime/handler.js`

### 5.1 监听事件

`HOOK.md` 当前声明：

1. `message:received`
2. `message:sent`
3. `agent:bootstrap`
4. `command:new`
5. `command:reset`
6. `command:stop`

### 5.2 同步策略

1. 对每个 `sessionKey` 维护一个根节点（Conversation）。
2. 每条用户消息写为子节点（Turn）。
3. `/new` 和 `/reset` 时把当前会话根节点置为 `completed`，下次消息再开新根。
4. 如果事件中无 `sessionId`，会从 `~/.openclaw/agents/<agent>/sessions/sessions.json` 反查。
5. transcript 读取策略：
6. 在 `sessionId.jsonl` 与 `sessionId-topic-*.jsonl` 中选择最近修改的文件。
7. 扫描尾部用户消息并批量补写未处理消息。

### 5.3 去重与状态文件

1. 去重键：`sessionKey::messageId`，无 messageId 时使用内容+时间 hash。
2. `task-board/.sync-state.json` 保存：
3. `sessions`：会话到根节点映射。
4. `counters`：会话根节点编号计数。
5. `messages`：已处理消息索引（防重复写入）。
6. 配置项：
7. `maxRememberedMessages` 控制消息去重索引上限。

### 5.4 时序补偿（避免“慢一拍”）

1. 事件触发时先进行一次即时 transcript 扫描。
2. 额外安排异步延迟补扫（当前为 1600ms、4800ms），不阻塞主流程。
3. 该机制用于处理 transcript 落盘晚于 hook 触发时刻的情况。

## 6. 当前实现与需求对照

### 6.1 已满足

1. 对话自动入板（主节点 + 子节点）。
2. 层级关系可视化。
3. 状态色区分明确。
4. 执行中旋转虚线动画。
5. 节点详情卡字段完整。
6. 导出 JSON / SVG。
7. 低饱和粉色整体风格。

### 6.2 当前缺口（你刚提出的两点）

1. 缺少“按对话筛选”的下拉标签或会话选择器。
2. 当前布局是“树状层级布局”，不是“思考链/思维链”导图语义布局。

## 7. 已知技术限制与结构问题

1. 数据层是平铺数组 + `parentId`，缺少对“对话维度”的一级索引接口。
2. 前端默认一次渲染全部节点，缺少“按会话聚焦/隔离”。
3. 节点语义目前只有根/子区分，缺少“推理步骤类型”（观察、假设、行动、验证、结论等）建模。
4. 布局算法是静态树排布，不包含链路方向强化、时间轴、分支合并等“思考链视觉语法”。
5. 同步依赖本地 JSON 文件，暂不支持多实例并发写入。

## 8. 后续重构建议（用于你准备的新结构）

1. 数据层先引入“会话视图模型”：
2. `conversationId -> nodes[]` 与全量任务存储分离。
3. API 增加 `GET /api/conversations` 与 `GET /api/tasks?conversationId=...`。
4. 前端增加“会话下拉 + 标签筛选 + 仅看当前会话”模式。
5. 把当前树布局抽象成 `layout engines`：
6. `tree`（兼容模式）+ `thought-chain`（新模式）可切换。
7. 给节点补充“思考链语义字段”（例如 `stepType`, `confidence`, `evidenceRef`）。
8. Hook 写入时可按语义模板自动填充（至少先区分 user-turn / agent-turn / tool-turn）。

---

如果后续要拆目录，建议以 `backend/`, `frontend/`, `sync-hook/`, `docs/` 四层分离，先保证 API 与布局引擎可独立迭代。