smartmate/docs/frontend/newagent_timeline_对接说明.md

NewAgent 时间线对接说明（前端）

1. 变更目标

后端已将 正文消息 与 卡片事件（工具调用/确认/排程完成） 统一落到会话时间线，刷新页面后可完整恢复，不再依赖“页面不刷新且持续订阅 SSE”才能看到卡片。

本次是开发环境直切，旧接口已退役：

• 退役：GET /api/v1/agent/conversation-history
• 新增：GET /api/v1/agent/conversation-timeline

2. 新接口

2.1 请求

GET /api/v1/agent/conversation-timeline?conversation_id={conversation_id}

鉴权与其他 agent 接口一致：JWT。

2.2 响应结构

data 是按顺序返回的数组，每项结构如下：

{
  "id": 123,
  "seq": 1,
  "kind": "assistant_text",
  "role": "assistant",
  "content": "你好，我来帮你处理。",
  "payload": {
    "reasoning_content": "..."
  },
  "tokens_consumed": 0,
  "created_at": "2026-04-19T12:00:00+08:00"
}

字段说明：

• seq：同一会话内严格递增顺序号，前端渲染顺序以它为准。
• kind：事件类型（见下文映射表）。
• role/content：正文消息使用。
• payload：卡片渲染所需结构化信息。

3. kind 映射（前端渲染）

• user_text：用户正文气泡。
• assistant_text：助手正文气泡。
• tool_call：工具开始卡片。
• tool_result：工具结果卡片。
• confirm_request：确认卡片。
• schedule_completed：排程完成卡片（展示完成态，详情仍走原有排程查询接口）。

3.1 卡片 payload 结构

tool_call / tool_result：

{
  "stage": "execute",
  "block_id": "execute.status",
  "display_mode": "card",
  "tool": {
    "name": "move",
    "status": "start|done|blocked|failed",
    "summary": "xxx",
    "arguments_preview": "xxx"
  }
}

confirm_request：

{
  "stage": "confirm",
  "block_id": "confirm.status",
  "display_mode": "card",
  "confirm": {
    "interaction_id": "xxx",
    "title": "操作确认",
    "summary": "xxx"
  }
}

schedule_completed：

{
  "stage": "deliver",
  "block_id": "deliver.status",
  "display_mode": "card"
}

4. 前端建议改造

4.1 会话初始化/刷新

进入会话页或刷新后，调用一次：

• GET /api/v1/agent/conversation-timeline

然后：

1. 直接按返回数组顺序渲染；
2. 不需要再拼接旧 conversation-history；
3. 旧接口调用逻辑可直接删除。

4.2 进行中会话（SSE）

进行中仍可继续消费 SSE（实时体验不变）。

建议策略：

1. 首屏先用 conversation-timeline 重建历史；
2. 新一轮聊天过程中继续把 SSE 增量渲染到当前 UI；
3. 页面刷新时再次拉 conversation-timeline，即可恢复完整状态。

5. 顺序保证

后端在写入时间线时为每个事件分配 seq，并将正文与卡片写入同一链路：

• 用户正文（user_text）
• 助手正文（assistant_text）
• 工具开始/结果（tool_call/tool_result）
• 确认卡片（confirm_request）
• 排程完成卡片（schedule_completed）

因此前端只要遵循 seq 顺序渲染，就不会出现“正文和卡片乱序”问题。

6. Token 说明

时间线中的 tokens_consumed 仅作为展示冗余字段，真实 token 账本统计仍以后端原有口径（chat_histories / agent_chats）为准。