# UI 协议会话对象与读取规则

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

这些接口读取和维护持久化记录，不提交模型推理或智能体任务。名称中的 UI 指这组接口的协议和 SDK 方法族，不表示已经验证当前控制台的可见入口。

<span id="prepare"></span>
## 调用前准备

1. 将 `BASE_URL` 设为目标环境的完整产品 API 前缀，准备该环境的个人访问令牌 `MOI_KEY`。
2. 通过 `X-Workspace-ID` 选择工作区。这组路径没有工作区段，仍需要同环境的工作区身份和有效角色。
3. 从当前用户的记录读取正整数 `SESSION_ID` 或 `MESSAGE_ID`。它们与智能体会话字符串 ID、A2A 任务 ID 分开。
4. 写操作前确认原记录；结果未知时先回读，避免重复创建或重复切换评价。

普通产品身份入口会拒绝附加的任务运行期授权头。SDK 的 `conversations(workspace_id)` 也须指定工作区，不能因 URL 没有工作区段就忽略该参数。

<span id="session-object"></span>
## 会话对象

详情与创建、更新的 `data`，以及列表的 `data.sessions[]` 使用此对象。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer | 服务端生成的会话 ID。 |
| `title` | string | 会话标题。 |
| `source` | string | 应用来源，开放字符串。UI 创建与列表的空来源默认 moi。 |
| `user_id` | string | 会话所属用户 ID。 |
| `config` | string | 配置文本，不是直接嵌入的 JSON 对象。 |
| `tags` | array（对象数组） | 标签展示数组；当前会话存储读取结果为空数组，不能据此判定是否置顶。 |
| `tags[].source` | string | 标签来源。 |
| `tags[].name` | string | 标签名称。 |
| `tags[].created_at` | integer | 标签创建时间，Unix 秒。 |
| `tags[].updated_at` | integer | 标签更新时间，Unix 秒。 |
| `created_at` | integer | 会话创建时间，Unix 秒。 |
| `updated_at` | integer | 会话更新时间，Unix 秒。 |

创建和更新的 `tags` 输入虽然能绑定到请求类型，但没有写入标签关系。UI 更新的 `source` 也不生效。创建、列表的 source 默认值与工作区 LLM 入口不同，不能把两个入口的省略行为合并。

<span id="message-object"></span>
## 消息对象

消息列表的 `data[]`、消息详情及点赞/点踩返回的 `data` 使用以下对象。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer | 消息 ID。 |
| `user_id` | string | 消息所属用户 ID。 |
| `session_id` | integer 或 null | 关联会话 ID；历史记录没有会话关联时为 null。 |
| `source` | string | 保存消息时的应用来源。 |
| `role` | string | 输出角色为 user、system 或 assistant；内部 agent_tool 在此协议映射为 user。 |
| `original_content` | string | 原始内容文本。 |
| `content` | string | 保存的消息内容。 |
| `model` | string | 保存的模型名称。 |
| `status` | string | 保存的消息状态，不等于模型任务状态。 |
| `response` | string | 原响应文本。 |
| `modified_response` | string | 修改后的响应文本。 |
| `config` | string | 保存的配置文本。 |
| `tags` | array（对象数组） | 可取得的消息标签；可选标签投影失败时也可能为空数组。 |
| `tags[].source` | string | 标签来源。 |
| `tags[].name` | string | 标签名；产品评价使用 system/liked、system/disliked。 |
| `tags[].created_at` | integer | 标签创建时间，Unix 秒。 |
| `tags[].updated_at` | integer | 标签更新时间，Unix 秒。 |
| `created_at` | integer | 消息创建时间，Unix 秒。 |
| `updated_at` | integer | 消息更新时间，Unix 秒。 |

消息列表使用字符串角色筛选。只有 user、system 和 assistant 被用作筛选，其他字符串当前按不筛选处理。source/model 虽能绑定，但不参与此列表筛选。

<span id="pagination"></span>
## 普通页、置顶子集与消息游标

普通与未置顶会话列表返回请求的原始 page/page_size。省略时响应可能是 0，实际查询却采用默认 1/20。普通列表的 page_size 超过 100 时实际按 20；未置顶列表有独立的兼容行为，不按该上限归一。使用明确的合法页码与页大小，不能直接把响应原值当作实际查询值。

置顶读取先取普通会话指定页，再筛这一页的 system/pinned。响应只有 sessions，没有 total 或页码。完整读取应先根据普通列表确定页范围，再读取每页置顶项；不能在某一页为空时提前停止。关联标签查询失败还可能返回空置顶结果，不能把空结果直接当成已确认没有置顶会话。

消息列表返回直接数组，按 ID 升序。下一页 after 取上页末条 ID，直到空数组；没有 total。与工作区消息列表的 data.messages/total 对象分开处理。

<span id="error-contract"></span>
## 成功、错误与结果确认

所有十四个 UI 协议动作的成功 HTTP 状态均为 200，外层 code 和 msg 均为字符串 OK。创建不是 201，删除不是 204；返回对象的具体类型以各动作页为准。

```json
{"code":"ErrParamInvalid","msg":"Bad Request","data":null}
```

| HTTP 状态码 | code | 当前映射 |
| --- | --- | --- |
| 400 | ErrWorkspaceRequired | 缺少工作区上下文。 |
| 400 | ErrParamInvalid | 路径 ID、请求解码或业务输入无效。 |
| 404 | ErrNotFound | 会话详情读取的 not-found。 |
| 500 | ErrServer | 通用服务错误，包括其他动作当前未单独映射的 not-found。 |

外层认证和工作区准入也可能在业务 handler 前拒绝。不能将会话详情的 404 映射套用于所有消息、更新、删除、置顶和评价动作；它们的当前通用错误分类不同。

点赞/点踩是切换动作，重复请求可能移除刚添加的评价。超时后先读取消息，不要自动重放。相反评价移除失败当前被忽略，可选标签读取失败也可能返回空数组；不能据此保证所有失败路径下始终互斥或已经清空评价。

会话/消息的实际归属仍按当前用户读取。空消息数组、最大消息 ID 为 0、空 tags 以及成功删除会话，都不能替代目标存在性、模型完成或其他资源清理的独立证据。
