# UI 与工作区 LLM 协议比较

两组入口由同一持久化 owner 管理，使用相同类型的数值记录 ID。它们不是可直接替换的 HTTP 别名，不能复制参数、成功状态或错误格式。

| 项目 | UI 协议 | 工作区 LLM 协议 |
| --- | --- | --- |
| 路径 | /sessions、/messages | /workspaces/{workspace_id}/llm/... |
| 工作区 | 请求头仍必需 | 路径与请求头保持一致 |
| 身份包装 | 普通产品身份，拒绝附加运行期授权头 | 支持运行期身份的产品入口，仍经过对应准入 |
| 成功 code | 字符串 OK，msg=OK | 数值 0 |
| 创建状态 | 200 | 201 |
| 删除会话 | 200，data.message=deleted | 204，无响应体 |
| 创建空 source | 默认 moi | 按空字符串保存 |
| 更新原标题条件 | 不读取 expected_title | 可选 expected_title，不匹配仍返回当前会话 |
| 会话对象 tags | 字段存在，当前存储读取返回空数组 | 对象不包含此字段 |
| 会话列表 | POST，请求体 page/page_size/source/keyword/tags | GET，查询 page/page_size/source/keyword/tag |
| 页码回传 | 普通/未置顶列表回传请求原值，不保证规范化 | 不回传页码/页大小 |
| 置顶列表 | 普通指定页的置顶子集 | 没有同名专用工作区入口 |
| 消息筛选 role | 字符串 user/system/assistant；其他字符串忽略 | 单个整数 0～3；3 进入 owner 后忽略筛选 |
| 消息列表数据 | data 直接是数组，无 total | data.messages 数组和 data.total |
| 消息角色输出 | user/system/assistant，agent_tool 映射为 user | 整数 0/1/2/3 |
| session_id | 可为 null | 工作区 DTO 使用整数 |
| 最近消息 | 不读取 completed_only，返回 session_id/message_id | 支持 completed_only，返回 message_id |
| 评价动作 | PUT like/dislike 是切换 | 工作区消息读取和文本维护接口不能代替评价切换 |
| 错误 | 字符串 code/msg/data:null，详情有单独 404 | 业务为数值 code/message，正文解码另有共用格式 |

SDK 用同一个 ConversationService 暴露两组方法。方法名中的 UI 与请求类型不是装饰：CreateUISession/ConversationUISessionRequest 和 CreateSession/ConversationWorkspaceSessionRequest 的默认值、输入及响应各按实际入口处理。

Python 将 UI 消息列表请求的 session_id/after 恢复为 JSON 数值；Go 和 CLI 也须使用数值。UI 消息 session_id=null 在 SDK 的 optional 字段中可表示为未设置，不能因此声称服务端返回了 0。CLI 的 protobuf JSON 还可能省略默认字段，HTTP 原始字段和客户端输出分开核对。

写入会话的 tags 字段没有创建标签关系，读取会话对象的空 tags 也不能判断是否置顶。维护 LLM source/name 标签、UI system/pinned 关系，以及通用资源标签的 ID/取值/资源关系，是不同合同。
