---
title: WebSocket 网关
created: 2026-04-13
updated: 2026-05-07
type: entity
tags: [gateway, websocket, api]
sources: [packages/backend/src/modules/netaclaw/gateway/, packages/frontend/src/modules/agent/store/chat.ts, packages/frontend/src/modules/agent/types/protocol.ts]
---

# WebSocket 网关

基于 Socket.IO 的实时通信层，包含两个命名空间：`/netaclaw`（Agent 对话）和 `/crew`（Crew 编排监控）。当前 `/netaclaw` 已经不仅承载 token 流，还承载 Session Tree 节点增量、leaf 切换、assistant 流式占位、工具执行状态、澄清、压缩、Todo、会话级子 Agent 批次等事件。

## 关键文件

| 文件 | 职责 |
|------|------|
| `gateway/server.ts` | Agent 对话 WebSocket，`@WSController('/netaclaw')` |
| `gateway/crew_server.ts` | Crew 编排 WebSocket，`@WSController('/crew')` |
| `gateway/session.ts` | 会话与 Session Tree 管理服务（创建、snapshot、leaf 切换、节点写回） |
| `gateway/protocol.ts` | 通信协议定义 |

## Agent 对话协议（`/netaclaw`）

### 客户端 → 服务端

| 类型 | 数据 | 说明 |
|------|------|------|
| `chat` | `{ sessionId, content, agentName?, agentId?, leafEntryId? }` | 发送聊天消息，可指定从哪个 leaf/节点继续 |
| `ping` | `{}` | 心跳 |
| `set_thinking_level` | `{ sessionId, level }` | 切换思考等级 |
| `clarify_response` | `{ sessionId, requestId, answer }` | 回答澄清问题 |
| `compact` | `{ sessionId, instructions? }` | 手动触发上下文压缩 |

### 服务端 → 客户端

| 事件类型 | 说明 |
|---------|------|
| `token` | LLM 文本增量 |
| `thinking` | 完整思考内容 |
| `thinking_delta` | 思考增量 |
| `thinking_done` | 思考结束 |
| `tool_call` | 兼容型工具调用事件 |
| `tool_result` | 兼容型工具结果事件 |
| `tool_call_started` | 工具开始执行，附带 runtime route / blocked reason / policySources |
| `tool_result_streamed` | 工具结果流式投影 |
| `tool_call_completed` | 工具最终完成态 |
| `process_event` / 工具过程事件载荷 | 长耗时工具和 Skill 的阶段进度，详见 [[runtime-process-events]] |
| `skill_start` / `skill_end` | Skill 生命周期 |
| `progress` | 过程进度 |
| `todo_update` | Todo 列表变更 |
| `token_update` | token 与上下文占用更新 |
| `clarify_request` | 发起澄清问题 |
| `compaction_start` | 压缩开始 |
| `compaction_done` | 压缩完成 |
| `compaction_error` | 压缩失败 |
| `subagent_run_started` | 子 Agent 批次开始 |
| `subagent_event` | 单个子 Agent 状态/结果事件 |
| `subagent_run_completed` | 子 Agent 批次结束 |
| `session_entry_added` | Session Tree 新增节点 |
| `session_entry_updated` | Session Tree 节点更新 |
| `session_leaf_changed` | 当前 leaf 切换 |
| `assistant_stream_start` / `assistant_stream_delta` / `assistant_stream_end` | 助手消息占位与流式回填 |
| `done` | 一轮推理结束 |
| `error` | 异常 |
| `pong` | 心跳响应 |

## 会话加载与 Session Tree 边界

当前对话恢复的主入口已经不是旧的线性消息视图，而是 Session Tree：

- `getSessionTreeSnapshot()` 返回完整 snapshot，并在返回前统一执行 `projectSubagentSnapshot()`。
- `switchSessionTreeLeaf()` 负责切换当前叶子并返回新的 snapshot。
- `appendSubagentResultEntry()`、`finalizeAssistantEntry()` 等写回逻辑会统一补上 `projectSubagentEntry()`，确保前端拿到的是已经投影过的节点。

旧的 `netaclaw_message` 历史加载仍存在，主要服务兼容逻辑与压缩流程；但前端 Agent Chat 主路径已经围绕 snapshot + 节点事件工作，而不是围绕 `compacted/full` 消息列表工作。

## 前端对接

| 前端文件 | 职责 |
|---------|------|
| `agent/hooks/websocket.ts` | Agent 对话 Socket.IO 客户端 |
| `agent/hooks/crew-monitor.ts` | Crew 编排 Socket.IO 客户端 |
| `agent/store/chat.ts` | Pinia Store 维持 WS 连接和事件分发 |
| `agent/views/chat.vue` | 对话页面 UI |

## 新增事件流

### Clarify 流

`clarify_request → 用户输入 → clarify_response`

详见 [[clarify-tool]]。

### 压缩流

`compact / auto-threshold → compaction_start → compaction_done|compaction_error`

详见 [[context-compaction]]。

### 子 Agent 流

`delegate_* → subagent_run_started → subagent_event* → subagent_run_completed`

详见 [[subagent-session]]。

### 过程事件流

`tool_call_started → process_event* → tool_result_streamed/tool_call_completed`

详见 [[runtime-process-events]]。这条链路让 [[vehicle-damage-skill]] 等长耗时 compute-entry Skill 可以持续把抽帧、检测、定位、复核等阶段推给前端，而不是只在结束时返回结果。

### Session Tree 流

`chat(leafEntryId?) → session_entry_added / assistant_stream_* / session_entry_updated / session_leaf_changed`

这条链路负责：

- 新建 user / assistant / subagent 节点。
- 在流式阶段保持 assistant 占位节点与文本增量同步。
- 在切换叶子或从旧节点继续发送时，让前端及时重建 active path。
- 让子 Agent 结果、tool metadata、projection diagnostics 通过节点更新自然回到历史视图。

## Crew 编排协议（`/crew` 命名空间）

| 事件 | 方向 | 说明 |
|------|------|------|
| `crew:trigger` | 客户端→服务端 | 触发集群运行 |
| `crew:control` | 客户端→服务端 | 控制运行（stop/resume/pause/retry） |
| `crew:run:status` | 服务端→客户端 | 运行状态变化 |
| `crew:task:status` | 服务端→客户端 | 任务状态变化 |
| `crew:log` | 服务端→客户端 | 日志消息 |
| `crew:escalation` | 服务端→客户端 | 升级事件 |

## 相关页面

- [[netaclaw-module]] — 所属模块
- [[agent-runtime]] — 消息处理后调用运行时
- [[crew-orchestration]] — Crew 编排系统
- [[thinking-system]] — 思考事件协议
- [[todo-system]] — todo_update 事件
- [[clarify-tool]] — 澄清交互事件
- [[context-compaction]] — 压缩事件与历史视图
- [[subagent-session]] — 子 Agent 批次事件
- [[runtime-process-events]] — 工具和 Skill 过程事件
- [[session-tree-runtime]] — snapshot、leaf 和节点更新模型
- [[react-loop]] — 执行流程概念