docs: 收敛 Web 工作台状态入口原则

2026-06-16 10:16:11 +00:00
parent 219292a9cb
commit 0bcf0dd725
1 changed files with 1 additions and 1 deletions
@@ -119,7 +119,7 @@ Web工作台应让用户在主任务区直接选择或创建会话、阅读用

 Web工作台必须使用显式 Agent session：无 session 时先让用户创建或选择 session，session failed、stale 或 canceled 时保留失败状态并要求用户显式切换或新建。刷新页面、重新打开工作台或短连接 result 轮询只能恢复已选 session、thread 和 trace 状态；除非用户登出或主动清空对话，不得自动生成新 conversation、替换 session 或用历史 prompt 拼接出续跑表象。

-会话列表、当前消息头、composer 主按钮和运行态动效必须共享同一会话状态派生路径。派生顺序应以服务端 conversation/message/trace 事实和当前本地 in-flight turn 为权威；workspace selected conversation、snapshot、stub 或浏览器临时缓存只能补充缺失字段，不得覆盖已有 conversation status、消息终态、首条用户请求摘要或运行中状态。运行中的 turn 必须同时反映在主任务区和对应 session tab；已进入终态的 turn 不得继续以 `Code Agent 处理中`、running 动效或旧 snapshot 文案呈现。
+会话列表、当前消息头、composer 主按钮和运行态动效必须先确定唯一权威 API，再由 Web 展示该 API 的结果；不得让 workspace selected conversation、snapshot、stub、localStorage、message 派生状态、trace 快照或浏览器临时缓存与权威 API 并列竞争、互相覆盖或按失败路径 fallback 成另一套数据源。已经定下来的权威 API 绑定如下：session rail 会话集合的唯一入口是 `/v1/agent/conversations`，当前 selected conversation 若需要出现在列表中，必须由该列表 API 自身返回；session 运行状态的唯一入口是按 `sessionId` 绑定的 session 状态 API；Code Agent turn/trace 阅读状态的唯一入口是按 `traceId` 绑定的 trace/result snapshot API。Web 在权威 API 失败时只能保留上一份成功结果或显示未加载/错误态，不得从 workspace selected snapshot、stub 或本地缓存拼出单条 session tab、running 状态或 final response。运行中的 turn 必须同时反映在主任务区和对应 session tab；已进入终态的 turn 不得继续以 `Code Agent 处理中`、running 动效或旧 snapshot 文案呈现。

 Agent 请求应采用短连接 submit 加 result/trace 轮询。`POST /v1/agent/chat` 或等价入口返回执行标识后，工作台通过 result 和 trace path 获取终态与可读过程，不持有一次长 HTTP 请求等待整个模型 turn。后端 result 已完成时，消息卡片必须替换为真实 final response；仍在 pending 或 trace 缺失时应显示明确状态，而不是把“result ready for polling”类中间文本当作最终回复。