Version: 0.9.32.dev.260419
后端： 1. 会话历史接口切换为统一时间线读取，并兼容 extra.resume 恢复协议 - api/agent.go：新增 resume->confirm_action 映射（approve/reject/cancel），恢复请求缺 conversation_id 时拦截；GetConversationHistory 改为 GetConversationTimeline - routers/routers.go：路由从 GET /conversation-history 切换为 GET /conversation-timeline - model/agent.go：删除 GetConversationHistoryItem 旧 DTO 2. 新增会话时间线持久化链路（MySQL + Redis） - 新增 model/agent_timeline.go：定义 timeline kind、AgentTimelineEvent、持久化/返回结构 - 新增 dao/agent_timeline.go：写入事件、按 seq 查询、查询 max seq - inits/mysql.go：AutoMigrate 增加 AgentTimelineEvent - dao/cache.go：新增 timeline list/seq key，支持 incr/set seq、append/list、全量回填与删除 - 新增 service/agentsvc/agent_timeline.go：时间线读写编排（Redis 优先、DB 回源、seq 分配与冲突重试、extra 事件映射） 3. 聊天主链路改为写入 timeline，旧 history 服务下线 - service/agentsvc/agent.go：普通聊天用户/助手消息改为 appendConversationTimelineEvent - service/agentsvc/agent_newagent.go：透传 resume_interaction_id；注入 emitter extra hook 持久化卡片事件；正文写入 timeline - 删除 service/agentsvc/agent_history.go：下线 conversation-history 旧缓存编排 4. newAgent 恢复与确认防串单增强 - newAgent/model/graph_run_state.go：AgentGraphRequest 新增 ResumeInteractionID - newAgent/node/agent_nodes.go：透传 ResumeInteractionID - newAgent/node/chat.go：增加 stale_resume 校验；accept/reject 兼容 approve/cancel；非法动作返回 invalid_confirm_action - newAgent/stream/emitter.go：新增 extraEventHook / SetExtraEventHook，在 extra-only 与 confirm 事件触发 5. 日程暂存后同步刷新预览缓存，避免读到拖拽前旧数据 - service/agentsvc/agent_schedule_state.go：Save 后重建并覆盖 preview 缓存，保留 trace/candidate 等字段 6. 缓存失效策略调整到 timeline 口径 - middleware/cache_deleter.go：移除 conversation-history 失效逻辑；ChatHistory/AgentChat/AgentTimelineEvent 加入忽略集合 前端： 7. 新增时间线接口与类型定义 - frontend/src/api/schedule_agent.ts：新增 TimelineEvent/TimelineToolPayload/TimelineConfirmPayload 与 getConversationTimeline 8. AssistantPanel 全面对接 timeline 重建消息与卡片 - frontend/src/components/dashboard/AssistantPanel.vue：移除旧 history merge/normalize，新增 rebuildStateFromTimeline；支持 execution mode（always_execute）；支持 resume-only 发送；修复 confirm 弹层手动关闭后重复弹出；会话标题显示放宽；流式中隐藏 action bar 9. 精排弹窗健壮性与交互动效优化 - frontend/src/components/assistant/ScheduleFineTuneModal.vue：previewData 支持 nullable，新增 visible 控制与 watch 初始化，补齐空值保护并调整弹窗动画 仓库： 10. 新增前端时间线接入说明文档 - docs/frontend/newagent_timeline_对接说明.md：接口、kind、payload、刷新重建与迁移建议
This commit is contained in:
Losita
137
docs/frontend/newagent_timeline_对接说明.md
Normal file
137
docs/frontend/newagent_timeline_对接说明.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# 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` 是按顺序返回的数组，每项结构如下：
|
||||
|
||||
```json
|
||||
{
|
||||
"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`：
|
||||
|
||||
```json
|
||||
{
|
||||
"stage": "execute",
|
||||
"block_id": "execute.status",
|
||||
"display_mode": "card",
|
||||
"tool": {
|
||||
"name": "move",
|
||||
"status": "start|done|blocked|failed",
|
||||
"summary": "xxx",
|
||||
"arguments_preview": "xxx"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`confirm_request`：
|
||||
|
||||
```json
|
||||
{
|
||||
"stage": "confirm",
|
||||
"block_id": "confirm.status",
|
||||
"display_mode": "card",
|
||||
"confirm": {
|
||||
"interaction_id": "xxx",
|
||||
"title": "操作确认",
|
||||
"summary": "xxx"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`schedule_completed`：
|
||||
|
||||
```json
|
||||
{
|
||||
"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`）为准。
|
||||
|
||||
Reference in New Issue
Block a user