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

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

调用前准备

  1. 将 BASE_URL 设为目标环境的完整产品 API 前缀,准备该环境的个人访问令牌 MOI_KEY。

  2. 通过 X-Workspace-ID 选择工作区。这组路径没有工作区段,仍需要同环境的工作区身份和有效角色。

  3. 从当前用户的记录读取正整数 SESSION_ID 或 MESSAGE_ID。它们与智能体会话字符串 ID、A2A 任务 ID 分开。

  4. 写操作前确认原记录;结果未知时先回读,避免重复创建或重复切换评价。

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

会话对象

详情与创建、更新的 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 入口不同,不能把两个入口的省略行为合并。

消息对象

消息列表的 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 虽能绑定,但不参与此列表筛选。

普通页、置顶子集与消息游标

普通与未置顶会话列表返回请求的原始 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 以及成功删除会话,都不能替代目标存在性、模型完成或其他资源清理的独立证据。

最后更新于