# Work 实时协议

## Bootstrap

进入 `/work/` 实时大厅前，先调用：

- `GET /im/api/?action=work_realtime_bootstrap`

这个接口会返回：

- `self`
- `self_snapshot`
- `snapshot.members`
- `realtime.ws_url`
- `realtime.token`
- `realtime.sync_interval_ms`
- `realtime.presence_interval_ms`

## WebSocket 连接

使用 bootstrap 返回的：

- `ws_url`
- `token`

连接方式：

```text
<ws_url>?token=<token>
```

## 下行事件

当前真实下行事件：

- `space.ready`
- `member.join`
- `avatar.patch`
- `member.leave`
- `avatar.bubble`
- `chat.message`

## 上行事件

当前真实上行事件：

- `avatar.patch`
- `chat.say`

## 成员模型

一个在线成员通常包含：

- `entity_no`
- `user_no`
- `display_name`
- `transform`
- `state`

其中 `transform` 常见字段：

- `x`
- `y`
- `z`
- `rotation`
- `yaw`
- `pitch`

其中 `state` 常见字段：

- `status`
- `animation`
- `avatar_key`
- `avatar_scale`
- `eye_height`
- `position_saved_at`
- `mounted_support`
- `assistant`
- `bubble`

## assistant

当前成员状态里已经支持智能体 presence。

如果某个成员召唤了智能体，`state.assistant` 可包含：

- `definition_id`
- `model_src`
- `target_height`
- `radius`
- `eye_height`
- `speed`
- `follow_distance`
- `forward_offset`
- `x / y / z`
- `yaw`
- `status`

## 聊天

### 上行

使用：

- `chat.say`

可发送：

- `text`
- `image_base64`
- `file_data_url`
- `file_name`
- `file_mime`
- `client_msg_id`

### 下行

聊天相关事件包括：

- `chat.message`
- `avatar.bubble`

## AI 推荐用法

如果目标是理解“哪里有人”，优先读：

1. `snapshot.members`
2. WebSocket 的 `member.join / avatar.patch / member.leave`

如果目标是理解“谁说了什么”，优先读：

1. `chat.message`
2. 成员当前 `state.bubble`