# 工作区 LLM 会话对象与调用规则

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

这些接口维护独立的会话、消息记录及其标签。它们不提交模型推理，也不创建智能体任务。

<span id="request-prerequisites"></span>
## 调用前准备

1. 使用目标环境的产品 API 身份凭据和有效工作区角色。
2. 将 `BASE_URL` 设为该环境的完整产品 API 前缀；工作区路径值与 `X-Workspace-ID` 一致。
3. 从同环境的会话列表取得正整数 `SESSION_ID`，再从消息列表取得 `MESSAGE_ID`。这些数值 ID 与智能体会话字符串 ID、A2A 任务 ID 分开。
4. 标签由非空 `source` 和 `name` 共同标识。将二者用于 URL 时分别编码，不能把含 `/`、空格或 `?` 的原值直接拼接到路径。

示例中的 `MOI_KEY` 是当前环境的个人访问令牌，`WORKSPACE_ID`、`SESSION_ID`、`MESSAGE_ID`、`TAG_SOURCE` 和 `TAG_NAME` 均须使用该环境的实际值。新建对象后，使用响应的 ID 继续调用。

会话和消息正文操作按当前用户查询；读取详情和会话列表不是整个工作区全部成员的记录清单。标签定义是工作区级集合。标签关系读取、添加和移除是不同入口，不能从空列表或 HTTP 204 推断目标对象存在或属于当前用户。

<span id="session-object"></span>
## 会话记录

工作区会话响应的 `data` 或 `data.sessions[]` 使用以下对象。时间为 Unix 秒整数。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer | 服务端生成的正整数会话 ID。 |
| `title` | string | 会话标题，可能为空。 |
| `source` | string | 应用来源，开放字符串。 |
| `user_id` | string | 会话所属的当前用户 ID。 |
| `config` | string | 配置文本。JSON 配置仍作为字符串返回。 |
| `created_at` | integer | 创建时间，Unix 秒；未记录时间时为 0。 |
| `updated_at` | integer | 更新时间，Unix 秒；未记录时间时为 0。 |

工作区会话对象没有内嵌 `tags`、`page` 或 `page_size`。标签通过独立关系接口读取。SDK 的共用对象可能具有这些属性，缺省属性不代表服务端返回了相应数据。

<span id="message-object"></span>
## 消息记录

消息详情的 `data` 和列表的 `data.messages[]` 使用以下对象。记录中的状态和模型名称属于存储数据，不表示一次模型调用实际发生。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer | 消息 ID。 |
| `user_id` | string | 消息所属用户 ID。 |
| `session_id` | integer | 消息关联会话 ID。 |
| `source` | string | 消息的应用来源。 |
| `role` | integer | 0=user、1=system、2=assistant、3=agent_tool。 |
| `original_content` | string | 原始内容文本。 |
| `content` | string | 保存的内容文本。 |
| `model` | string | 保存的模型名称。 |
| `status` | string | 保存的消息状态，默认 pending。 |
| `response` | string | 保存的原响应文本。 |
| `modified_response` | string | 保存的修改后响应文本。 |
| `config` | string | 配置文本。 |
| `created_at` | integer | 创建时间，Unix 秒。 |
| `updated_at` | integer | 更新时间，Unix 秒。 |

消息对象没有内嵌标签；单独读取消息标签关系。创建时允许角色 3，当前列表服务对 `role=3` 会省略角色筛选；不能据此认为返回结果只含工具消息。

消息翻页使用 `after`，不是 `offset`。消息按 ID 升序，下一页取上页末条消息 ID。返回的 `total` 先按角色和状态统计，不按 `after` 减少；不能以该值作为剩余条数。会话列表和工作区标签列表则使用 `page/page_size`，两套分页方式分别处理。

<span id="tag-object"></span>
## LLM 标签定义

标签在 `data` 或 `data.tags[]` 中返回。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `source` | string | 标签来源，与 name 共同标识定义。 |
| `name` | string | 标签名称。 |
| `created_at` | integer | 创建时间，Unix 秒。 |
| `updated_at` | integer | 更新时间，Unix 秒。 |

创建定义使用 `source/name`；添加关系使用 `tag_source/tag_name`。添加关系可同时创建缺失的标签定义。移除关系保留定义；删除定义则清除该 source/name 在工作区内的所有会话、消息关系。

`system/pinned`、`system/liked` 和 `system/disliked` 是产品使用的系统标签。一般业务标签使用自己的来源名称，避免混同产品置顶、点赞和点踩状态。

<span id="error-contract"></span>
## 错误格式与结果确认

工作区动作的业务错误使用数值 `code` 和 `message`：

```json
{"code":2,"message":"invalid request"}
```

| HTTP 状态码 | 业务 code | 条件 |
| --- | --- | --- |
| 400 | 2 | 工作区不一致、非正整数 ID、非法角色、无效标签或业务参数。 |
| 404 | 3 | 会话或消息读取动作找不到当前用户范围内的记录。 |
| 500 | 1 | 存储、转换或其他服务错误。 |

正文 JSON 解码复用另一层错误格式，可能返回 HTTP 400、字符串 `code=ErrParamInvalid` 和 `msg`。认证和准入还会返回各自错误；程序不能将所有失败固定解码成同一数值 code 类型。

条件更新标题不匹配可以返回 HTTP 200 和原值；这不是 409 冲突。重复删除一个已经不存在的会话可能为 404，而删除不存在的标签定义或标签关系可以为 204。标签关系读取返回空集合，也不能代替会话或消息详情的存在性检查。

保存消息和修改响应文本不调用模型；成功返回只说明对应存储动作的结果。会话/消息创建没有业务请求 ID 去重，追加文本也不是幂等操作。超时后先回读并确认，避免重复创建或重复追加。

删除会话后的消息、标签、文件清理要分别确认；会话删除的空响应不能作为其他资源已清理的证据。验证时登记实际生成的会话、消息及标签，保留尚不能确认清理的对象。
