UI 协议会话对象与读取规则¶
这些接口读取和维护持久化记录,不提交模型推理或智能体任务。名称中的 UI 指这组接口的协议和 SDK 方法族,不表示已经验证当前控制台的可见入口。
调用前准备¶
将
BASE_URL设为目标环境的完整产品 API 前缀,准备该环境的个人访问令牌MOI_KEY。通过
X-Workspace-ID选择工作区。这组路径没有工作区段,仍需要同环境的工作区身份和有效角色。从当前用户的记录读取正整数
SESSION_ID或MESSAGE_ID。它们与智能体会话字符串 ID、A2A 任务 ID 分开。写操作前确认原记录;结果未知时先回读,避免重复创建或重复切换评价。
普通产品身份入口会拒绝附加的任务运行期授权头。SDK 的 conversations(workspace_id) 也须指定工作区,不能因 URL 没有工作区段就忽略该参数。
会话对象¶
详情与创建、更新的 data,以及列表的 data.sessions[] 使用此对象。
字段 |
类型 |
说明 |
|---|---|---|
|
integer |
服务端生成的会话 ID。 |
|
string |
会话标题。 |
|
string |
应用来源,开放字符串。UI 创建与列表的空来源默认 moi。 |
|
string |
会话所属用户 ID。 |
|
string |
配置文本,不是直接嵌入的 JSON 对象。 |
|
array(对象数组) |
标签展示数组;当前会话存储读取结果为空数组,不能据此判定是否置顶。 |
|
string |
标签来源。 |
|
string |
标签名称。 |
|
integer |
标签创建时间,Unix 秒。 |
|
integer |
标签更新时间,Unix 秒。 |
|
integer |
会话创建时间,Unix 秒。 |
|
integer |
会话更新时间,Unix 秒。 |
创建和更新的 tags 输入虽然能绑定到请求类型,但没有写入标签关系。UI 更新的 source 也不生效。创建、列表的 source 默认值与工作区 LLM 入口不同,不能把两个入口的省略行为合并。
消息对象¶
消息列表的 data[]、消息详情及点赞/点踩返回的 data 使用以下对象。
字段 |
类型 |
说明 |
|---|---|---|
|
integer |
消息 ID。 |
|
string |
消息所属用户 ID。 |
|
integer 或 null |
关联会话 ID;历史记录没有会话关联时为 null。 |
|
string |
保存消息时的应用来源。 |
|
string |
输出角色为 user、system 或 assistant;内部 agent_tool 在此协议映射为 user。 |
|
string |
原始内容文本。 |
|
string |
保存的消息内容。 |
|
string |
保存的模型名称。 |
|
string |
保存的消息状态,不等于模型任务状态。 |
|
string |
原响应文本。 |
|
string |
修改后的响应文本。 |
|
string |
保存的配置文本。 |
|
array(对象数组) |
可取得的消息标签;可选标签投影失败时也可能为空数组。 |
|
string |
标签来源。 |
|
string |
标签名;产品评价使用 system/liked、system/disliked。 |
|
integer |
标签创建时间,Unix 秒。 |
|
integer |
标签更新时间,Unix 秒。 |
|
integer |
消息创建时间,Unix 秒。 |
|
integer |
消息更新时间,Unix 秒。 |
消息列表使用字符串角色筛选。只有 user、system 和 assistant 被用作筛选,其他字符串当前按不筛选处理。source/model 虽能绑定,但不参与此列表筛选。
普通页、置顶子集与消息游标¶
普通与未置顶会话列表返回请求的原始 page/page_size。省略时响应可能是 0,实际查询却采用默认 1/20。普通列表的 page_size 超过 100 时实际按 20;未置顶列表有独立的兼容行为,不按该上限归一。使用明确的合法页码与页大小,不能直接把响应原值当作实际查询值。
置顶读取先取普通会话指定页,再筛这一页的 system/pinned。响应只有 sessions,没有 total 或页码。完整读取应先根据普通列表确定页范围,再读取每页置顶项;不能在某一页为空时提前停止。关联标签查询失败还可能返回空置顶结果,不能把空结果直接当成已确认没有置顶会话。
消息列表返回直接数组,按 ID 升序。下一页 after 取上页末条 ID,直到空数组;没有 total。与工作区消息列表的 data.messages/total 对象分开处理。
成功、错误与结果确认¶
所有十四个 UI 协议动作的成功 HTTP 状态均为 200,外层 code 和 msg 均为字符串 OK。创建不是 201,删除不是 204;返回对象的具体类型以各动作页为准。
{"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 以及成功删除会话,都不能替代目标存在性、模型完成或其他资源清理的独立证据。