chat-process-timeline-plan.md 59 KB

AI 聊天「思考过程 + 分步结论」设计方案

项 内容
文档状态 草案 v1.0(待评审,评审通过后按 §11 分阶段实施)
日期 2026-11-18
影响范围 后端 ai-server module/ai(org.dromara.ai 迁移后包 com.zsjz.ai.module.ai);前端 ai-electron/frontend workbench 聊天页
变更性质 增量式:新增事件/表/组件,不重写编排业务逻辑,不新增权限码,存量历史数据不回填
关联文档 docs/design/pale-reef-swan.md(权限融合)、docs/design/tool-call-detail-plan.md(工具明细)

决策记录(已与需求方确认)

# 决策 说明
D1 界面形态:统一折叠过程面板 助手气泡顶部「执行过程」容器;流式自动展开为步骤时间线,完成后自动折叠为一行摘要;每步含一行结论、可展开详情
D2 内容范围:模型思考 + 执行步骤 流式展示模型原始推理(reasoning),同时展示路由/工具/专家/确认等执行步骤;模型不吐思考时自动降级为纯执行步骤
D3 过程持久化 + 精确回放;存量历史会话不回填、不迁移 新对话步骤落库,刷新/切会话后精确还原;数据库中已有旧消息无步骤行,按现有卡片渲染,不写 backfill 脚本
D4 编排专家的输出必须展示 专家运行期间回答文本实时镜像进步骤详情;完成后步骤给结论行、可展开完整原文;原文随步骤持久化,回放可见

1. 背景与目标

1.1 现状痛点

当前聊天页(ai-electron/frontend/src/workbench/views/chat/index.vue,约 5400 行单体 SFC)对"AI 在干什么"的透出非常有限:

  1. 没有思考过程:模型原始推理(reasoning_content)完全没有透出。框架其实已经解析了它(见 §2.6),但桥接层直接忽略。
  2. 只有一行瞬态状态:phase 事件驱动的 phaseText 状态条(index.vue:252-255)在长等待时播报"数剑在干什么",但正文一开始流出就消失,用户无法回看本轮经历了哪些阶段。
  3. 没有"每步结论":工具卡只给入参/结果摘要原文,专家卡只在 done 后回填原文,路由只有一行判定文案;缺少"这一步做完了什么"的一句话结论。
  4. 历史顺序是近似:步骤顺序不持久化,历史重建时工具卡在前、正文在后、route/expert 插到首个 text 前(index.vue:1931-1966,1871-1928),与实时所见不一致。

1.2 目标

  • 对标大厂 AI 聊天体验,让用户实时看到本轮的完整执行过程(思考 → 路由 → 工具 → 专家 → 确认 → 整合),每一步都有一行结论,可展开看详情。
  • 过程持久化,刷新/切会话后精确回放(顺带修复历史顺序近似问题)。
  • 零侵入:不改既有编排语义、不动权限模型、旧前端/旧消息/无思考模型全部自动降级;总开关可一键回退到现状。

1.3 大厂体验对标拆解

产品 代表体验 本方案取舍
DeepSeek 可折叠「深度思考」块,推理文本流式渲染,结束显示"已深度思考(用时 X 秒)",默认折叠 采纳:thinking 步流式渲染 + 耗时摘要 + 自动折叠(D2)
ChatGPT o 系列 "Thought for X seconds" 一行摘要,展开看思考摘要;工具/检索步骤折叠为活动行 采纳:完成后折叠为一行摘要(D1);不采纳其 LLM 摘要(成本/时延),用确定性结论,LLM 摘要列为 P3 可选
Manus 任务步骤时间线,每步状态图标 + 标题 + 结果摘要,过程与最终回答分离 采纳:纵向步骤时间线 + 每步一行结论 + 过程/正文分离(D1/D4);不采纳右侧双栏(现有右侧已是工件面板,窄屏成本高)
Coze / Dify 工作流节点卡片,节点输入/输出可展开 采纳:步骤详情可展开(入参/出参/原文);不采纳节点画布(聊天场景线性时间线足够)

1.4 非目标(明确不做)

  • 不回填/迁移存量历史会话的过程数据(D3)。
  • 不重写编排逻辑(RouteDecisionTool / AiRouteOrchestrator / 专家直答接管语义保持不变)。
  • 不新增权限码(steps 端点复用 ai:chat:query)。
  • 不全局强制开启模型 thinking(避免 reasoning 吃光 maxTokens,module/llm/LlmService.java:345 已有教训)。
  • 不做 SSE Last-Event-ID 断点续传(维持现状)。

2. 现状分析(均已读源码/jar 核实)

后端基路径 B = ai-server/src/main/java/com/zsjz/ai/module/ai;前端基路径 F = ai-electron/frontend/src。

2.1 前端链路

  • 聊天页单体 SFC:F/workbench/views/chat/index.vue(name AiAgentChat)。消息列表模板 66–361,parts 循环 138–246,输入区 364–578,右侧工件面板 582–659。
  • UI 库 Ant Design Vue(非 Element Plus);图标 Icon(@/core/components/Icon,i-mdi:*);Markdown 渲染 F/workbench/components/AiMarkdown.vue(markdown-it + highlight.js)。
  • 消息模型(局部 ref,无 Pinia):
    • MessagePart(887–930):kind: 'text'|'tool'|'confirm'|'expert'|'route' + 各 kind 字段;
    • LocalMessage(933–961):id, role, content, parts[], streaming, status, createTime, errorMsg, durationMs, toolCallCount, totalTokens, attachments, sources, retryPayload, phaseText。
  • SSE 客户端:F/workbench/api/chatSse.ts — fetch + ReadableStream(GET,x-token 头;EventSource 无法带自定义头故不用),URL 36–43:/ai/chat/stream?sessionId&messageId、/ai/chat/resume、/ai/chat/session/{sid}/message/{mid}/regenerate(base = apiUrl + /js + /a)。帧为无名 SSE,按 payload.type 分发(119–127)→ 未注册的类型自动忽略。
  • 事件处理:handleStreamEvent(index.vue:2817-3016),逐事件映射见 §2.3。
  • 历史加载:handleSelectSession(2412–2478)并行 GET /messages + /toolCalls + /routeRuns(F/workbench/api/chat.ts:230-240),toLocalMessage(1931–1966)+ appendRouteParts(1871–1928)重建卡片,/pending 恢复确认卡。
  • 可复用资产:tool-card/expert-card 折叠模式(模板 140–207,样式 3985/4907)、msg-sources 折叠(258–300)、展开键数组 expandedToolKeys/expertExpertKeys/expandedSourceKeys(1482–1582)、a-timeline(F/workbench/views/audit/trace/index.vue:237 已用)、工具中文名 TOOL_LABELS/toolLabel(F/core/http/aiConstants.ts)、设计令牌 F/workbench/styles/workbench.less(--wb-*,见 §8.10)。

2.2 后端链路

  • 两步发送:POST /ai/chat/session/{sid}/message 先落库用户消息(B/controller/AiChatController.java:272),再 GET /stream?sessionId&messageId 开 SSE(Controller:413;resume:435;regenerate:476)。
  • 发射:AiSseSupport.send(B/core/agent/AiSseSupport.java:43-52)— 无名帧 + JSON 信封 LinkedHashMap,必含 type(envelope():31)。无 DTO 类。
  • 编排:AiChatFacade.streamChat(B/core/agent/AiChatFacade.java:301-503)经 AgentAssembler(:316)构建 AgentScope HarnessAgent,agent.prepareRun(...).stream().subscribe(dispatchEntryEvent)(438–445)→ AiStreamEventBridge.handle(130–182)把 io.agentscope.core.event.AgentEvent 桥接为 SSE。
  • 路由:入口智能体「数剑」经自定义工具 RouteDecisionTool(route_decision)调 AiRouteOrchestrator.execute;专家作为第二个 HarnessAgent 运行(runExpert,Orchestrator:535–719),拥有独立 AiStreamState(设 speakerExpertName,:561–568)。
  • 进度播报:AiPhaseSupport.emit(B/core/agent/AiPhaseSupport.java:80-98),7 阶段 routing/thinking/tool/expert/resuming/integrating/finalizing,带 speaker(entry/expert),按 phase|text 去重。
  • 收尾:AiTurnFinisher(B/core/agent/AiTurnFinisher.java)四路径 — finish(:229,正常落库+done)、finishPending(:346,HITL 暂停)、finishPendingResume(:385,恢复段收尾)、finishCancelled(:174,中止)。工具明细仅在收尾/暂停时由 buildToolLogs(:551/:568)从内存 AiStreamState.tools 落库,专家明细经 route.expertToolLogs 合并。

2.3 现有 SSE 事件全清单

type 载荷关键字段 后端来源 前端效果(index.vue)
start — Facade:70,430;ExpertResumeDriver:45 无操作(2824)
phase phase, text, speaker, expertName? AiPhaseSupport:80-98 msg.phaseText 状态条,首个 text_delta 清除(2826)
text_delta replyId, blockId, delta Bridge:344-350 追加 text part + content(2831)
tool_call_start replyId, toolCallId, toolName, source? Bridge:423-428 push tool part(running);跳过 ROUTE_PROTOCOL_TOOLS=['route_decision','submit_expert_result'](1862)(2844)
tool_call_delta toolCallId, delta Bridge:473-476 拼接 part.input JSON(2858)
tool_result toolCallId, toolName, state, output, durationMs, source? Bridge:562-569 终态+输出+耗时,触发工件刷新(2865)
references replyId, items[], toolCallId Bridge:570-577 合并 KB 来源(去重 docId+chunkIndex)(2959)
answer_reset {} Bridge:86;Orchestrator:87,735 清空 text parts(安全拦截/专家接管)(2952)
route_decision action(route/pinned/self), expertKey, expertAgentId, expertName Orchestrator:213-217 push route note(2903)
expert_start expertKey, expertAgentId, expertName, attemptNo, callKind Orchestrator:545-550 push expert 卡(running)(2917)
expert_result 同上 + status(success/invalid) Orchestrator:713-718 expert 卡终态(2930)
expert_invalid expertKey, error Orchestrator(校验失败分支) invalid + expertError(2937)
route_fallback reason Orchestrator:198 等 route note「已由数剑自行回答」(2945)
tool_confirm messageId, replyId, expiresInSec, toolCalls[{toolCallId,toolName,toolLabel,toolDesc,input,content}] Finisher:444-451 暂停流,push confirm 交互卡(2881)
done messageId, replyId, durationMs, toolCallCount, totalTokens?, references? Finisher:291-303 finalize + syncExpertConclusions()(1526)回填专家原文(2964)
aborted messageId, durationMs Finisher:211-214 status='3' 已中止(2984)
error message, reasonCode? Finisher:603-608;Facade:588-591 status='1' + errorMsg(2997)

2.4 专家直答与回填机制(D4 的关键背景)

  • 专家链路 forwardToolEvents=false(Bridge:140-143):专家内部工具卡不下发(避免噪声),但 phase 照播"专家「X」正在调用「Y」工具…"——只透出用了哪个工具,入参/结果不下发。
  • 专家正文直传为最终回答(direct-answer handoff,Facade:607-613):专家 text_delta 转发给用户,入口正文经 answer_reset 丢弃。
  • 专家完整原文存 ai_route_expert_call.rawOutput(8000 字上限)/parsedOutput;前端在 done 后经 GET /session/{sid}/routeRuns(Controller:256,AiRouteRunDetailVo.expertCalls[].rawOutput)回填到 expert 卡(syncExpertConclusions,index.vue:1526-1551)。
  • text_delta 载荷目前没有 speaker 字段,但桥接层持有 state.speakerExpertName,可零成本区分入口/专家(本方案据此做镜像,见 §5.4)。

2.5 持久化现状

表 内容 写入时机 缺口
ai_message content=最终纯文本;replyId/streaming/status(0/2 待确认/3 中止)/errorMsg/toolCallCount/tokens/durationMs/sources(JSON) 收尾/暂停 无步骤、无思考、无顺序
ai_tool_call_log sessionId/messageId/userId/agentId/toolCallId/toolName/toolInput(全量)/toolOutput(截断)/state/durationMs 仅收尾/暂停(buildToolLogs) 无步骤序号,与正文顺序无关
ai_trace 每轮一行,parentTraceId(专家子 trace)、model 快照、contextJson、transitionsJson({state,detail} 节点:tool_call/tool_error/resume/error,有上限) 流中追加 粗粒度审计节点,非展示时间线
ai_route_run action/decisionJson(reason/confidence)/taskContext/expertCallCount/status/degradeReason/durationMs 编排收尾 —
ai_route_expert_call attemptNo/callKind/contractJson/rawOutput(≤8000)/parsedOutput/validationError/status/tokens/durationMs 专家调用收尾 专家原文已有,但未进步骤时间线

删除回答仅删 ai_message 行(AiSessionServiceImpl.deleteAnswerMessages:447-465、deleteChatRound),明细靠 messageId 关联查询天然过滤;审计保留任务按 create_time 物理清理 6 张明细表(AiAuditRetentionMapper/Task)。

2.6 框架能力(已核实 jar)

  • pom agentscope.version=2.0.5(ai-server/pom.xml:27),harness/core/model-openai/rag-simple/redis/skill-postgresql 均 2.0.5;本地仓库 D:\soft\repository\io\agentscope\*\2.0.5 齐全(含 sources jar)。
  • agentscope-core-2.0.5.jar 含 io.agentscope.core.event.ThinkingBlockStartEvent / ThinkingBlockDeltaEvent / ThinkingBlockEndEvent、message.ThinkingBlock、agent.accumulator.ThinkingAccumulator。
  • agentscope-extensions-model-openai-2.0.5-sources.jar 含 17 处 reasoning_content 引用(OpenAIResponseParser/OpenAIMessageConverter/dto.OpenAIMessage)→ 框架已把模型 reasoning_content 解析成 ThinkingBlock 事件。
  • 但 AiStreamEventBridge.handle 对 Thinking 事件走兜底 log.debug("忽略的 AgentScope 事件:{}")(Bridge:181)——能力在边界上唾手可得,只差三个分支。
  • 聊天模型经 AgentModelFactory.buildChatModel(config)(:112)构造,无 thinking 覆盖;重载 buildChatModel(config, Boolean enableThinkingOverride)(:119)已存在,非空时 ob.additionalBodyParam("enable_thinking", ...)(:146-151),目前仅 LlmService 辅助调用使用。AgentAssembler:290 调的是无覆盖版本 → 是否吐 reasoning 取决于模型/供应商配置(见 §12 R1 验证步骤)。

2.7 缺口小结

缺口 落点
思考流未透出 Bridge 加 Thinking 三分支(§4/§10)
无步骤时间线/每步结论 新增 AiProcessTimeline + step_* 事件(§3/§5)
专家输出只在 done 后回填、无实时过程感 text_delta 加 speaker 字段 + 前端镜像(§5.4)
步骤不持久化、历史顺序近似 新表 ai_message_step + steps REST + 前端精确回放(§6/§7/§8.8)

3. 总体设计

3.1 架构

flowchart LR
    M["模型 API<br/>(reasoning_content + content)"] --> FW["AgentScope 2.0.5<br/>ThinkingBlock* / ToolCall* / TextBlock* 事件"]
    FW --> BR["AiStreamEventBridge<br/>(既有桥接 + 新增 thinking/tool 钩子)"]
    BR --> TL["AiProcessTimeline (新增)<br/>内存步骤累积 + seq + 结论生成"]
    TL -->|"step_start / step_delta / step_end"| SSE["SSE 无名帧 JSON 信封"]
    BR -->|"text_delta(+speaker) / tool_* / phase / done..."| SSE
    SSE --> FE["前端 ProcessPanel (新增)<br/>步骤时间线 + 专家输出镜像"]
    TL -->|"收尾/暂停批量落库 (try/catch 只告警)"| DB[("ai_message_step (新表)")]
    DB --> REST["GET /ai/chat/session/{sid}/steps (新增)"]
    REST -->|"刷新/切会话精确回放"| FE

3.2 后端权威时间线(为什么不是前端聚合)

新增 AiProcessTimeline(B/core/agent/AiProcessTimeline.java,与 AiStreamState 同包同生命周期模型):

  • 每轮一个实例,按事件到达顺序生成步骤(seq 单调递增),实时下发 step 事件,收尾批量落库。
  • 不选前端聚合:① 专家内部工具事件 forwardToolEvents=false 不下发,前端拿不到;② HITL 跨请求分段,前端拼不出权威顺序;③ answer_reset 语义复杂;④ 「刷新后所见 == 流式所见」必须靠落库。
  • 不选 Hook/Middleware:Thinking 事件已到达 Bridge.handle,只需加 instanceof 分支;AgentAssembler.buildMiddlewares(:625-641)完全不动(硬约束:编排逻辑不变)。

3.3 生命周期与跨段共享

  • 装配:Facade.streamChat 建好 state 后 new AiProcessTimeline(emitter, sessionId, 0),挂到 AiStreamState.process(新字段,可空)与 AiRouteContext.timeline(新字段)。
  • 专家段:Orchestrator.runExpert 把专家 state 的 process 指向 route.timeline(共享同一实例),speaker 用已有 speakerExpertName。
  • 整合段:AiIntegrationDriver 同样挂 route.timeline。
  • HITL 恢复段:Facade.streamResume / AiExpertResumeDriver 新建 timeline,seqStart = stepService.maxSeq(messageId);步骤键与暂停段一致 → 落库按 (message_id, step_key) upsert(confirm 步 waiting→终态、expert 步同键续跑,seq 保留原值),恢复段新步 seq=maxSeq+n。
  • 线程约束:timeline 方法 synchronized + seq AtomicInteger(入口订阅线程与专家 boundedElastic 线程先后访问,事实串行但无 happens-before 保证);遵守 AiStreamState 注释的「不引入 subscribeOn/publishOn」约束,钩子全部在既有回调线程内同步调用。
  • emitter 为 null(无人值守链路)时只累积不下发,与 AiSseSupport 同口径。

3.4 存量数据边界(D3)

  • 不回填、不迁移:数据库中已有历史会话/消息不写任何 backfill 脚本,不重建过程。
  • 旧消息 steps REST 无行 → 前端走现有 toLocalMessage/appendRouteParts 卡片渲染(现状原样)。
  • 新表只承接开关启用后新产生的对话;审计保留任务统一清理(含新表),无额外保留策略。
  • 实施时严禁顺手做存量迁移;验收含「存量旧会话打开仍为现有卡片渲染」一项(§13)。

3.5 兼容与降级策略

场景 行为
旧前端 step_* 事件未注册即忽略;text_delta/done/aborted 新增字段为可选,旧前端不读 → 零影响
无 reasoning 模型 无 Thinking 事件 → 无 thinking 步,面板仅执行步
纯自答零步骤轮 面板不渲染,与现状完全一致
存量旧消息 steps 无行 → legacy 卡片渲染(D3)
总开关关闭 processStepsEnabled=false → timeline 不建,全链路回到现状(逐帧一致,仅多可选字段)
步骤落库失败 try/catch 只告警,回答落库不受影响(与 memoryPipeline 同口径)

3.6 配置项(B/config/AiProperties.java Chat 内新增)

配置 默认 说明
processStepsEnabled true 总开关;false 时 timeline 不建、不落库、不发 step 事件
thinkingDetailMaxChars 8000 思考全文落库上限(内存上限 16000)
stepConclusionChars 80 一行结论截断长度
maxStepsPerMessage 200 单消息步骤上限,超出只计数

4. SSE 事件协议

4.1 信封与分发

沿用无名帧 + JSON 信封(AiSseSupport.send),新增事件对旧前端零影响(chatSse.ts:119-127 按 type 分发,未注册即忽略)。

4.2 stepKey 规则(轮内唯一,恢复段靠它 upsert 同一步骤)

kind stepKey 粒度说明
thinking think:{replyId}#{blockId} 每个 ThinkingBlock 一步(ReAct 每次模型调用前各一步,不合并)
route route:{routeRunId} 一次编排一步;self/pinned 同样建步
tool tool:{toolCallId} 与既有工具事件同键关联
expert expert:{expertAgentId}#{attemptNo} 恢复段续跑同一步骤(不重复开卡,与现有 expert_start 抑制口径一致)
confirm confirm:{pendingReplyId} 每次暂停一步;键含 pendingReplyId 区分二次暂停批次
integration integ:{routeRunId} 整合轮一步

4.3 新增事件 schema

// step_start —— 步骤开始
{ "type": "step_start", "stepKey": "think:r1#b0", "seq": 1,
  "kind": "thinking", "title": "深度思考", "status": "running",
  "speaker": "entry",            // entry | expert
  "expertName": null,             // speaker=expert 时非空
  "refKey": null }                // tool→toolCallId;expert→agentId#attempt

// step_delta —— 步骤增量(仅 thinking 步;已过安全守卫,口径与 text_delta 相同)
{ "type": "step_delta", "stepKey": "think:r1#b0", "delta": "用户想要查询…" }

// step_end —— 步骤终态(可对同一 stepKey 重发以更新结论,如 route_fallback)
{ "type": "step_end", "stepKey": "tool:call_9", "status": "success",
  "conclusion": "查询到 12 条车辆登记记录",   // ≤80 字,后端拼好,前端只渲染
  "durationMs": 842,
  "detail": { } }               // 可选;仅 route 步随事件下发 {action,reason,confidence}
  • tool 详情不随 step 事件重复下发(走既有 tool_call_* 事件,前端 findLinkedPart 关联)。
  • expert 完整原文不随 SSE 下发(live 走镜像 + 既有回填,回放走 steps REST 的 detailJson)。
  • status 枚举:running / success / error / skipped / waiting / approved / rejected / expired / aborted。

4.4 既有事件追加可选字段(旧前端忽略)

// text_delta 追加 speaker/expertName/stepKey —— 供前端镜像专家输出(零额外流式体积,不重复发 delta)
{ "type": "text_delta", "replyId": "r2", "blockId": "b0", "delta": "根据查询结果…",
  "speaker": "expert", "expertName": "车辆分析专家", "stepKey": "expert:1024#1" }

// done / aborted 追加 stepCount / thinkingDurationMs(各 thinking 步耗时之和)
{ "type": "done", "messageId": 9001, "durationMs": 12345, "toolCallCount": 3,
  "stepCount": 7, "thinkingDurationMs": 4200 }

phase 事件原样保留(无步骤时的兜底播报 + 旧前端兼容)。

4.5 时序图

普通轮(思考 + 工具):

sequenceDiagram
    participant U as 前端
    participant B as Bridge/Timeline
    participant M as 模型/工具
    M->>B: ThinkingBlockStart/Delta/End
    B->>U: step_start(thinking) / step_delta×N / step_end(结论+耗时)
    M->>B: ToolCallStart/Delta/ResultEnd
    B->>U: step_start(tool) + 既有 tool_call_start/delta/result
    B->>U: step_end(tool, 结论)
    M->>B: TextBlockDelta (最终回答)
    B->>U: text_delta(speaker=entry)×N
    B->>U: done(+stepCount/thinkingDurationMs)
    Note over B: 收尾批量落库 ai_message_step

专家轮(输出镜像 + 回填):

sequenceDiagram
    participant U as 前端
    participant O as Orchestrator/Timeline
    participant E as 专家 Agent
    O->>U: step_start(route) + route_decision
    O->>U: step_end(route, 判定理由)
    O->>U: step_start(expert) + expert_start
    E->>O: ThinkingBlock* (专家思考)
    O->>U: step_start/step_delta/step_end(thinking, speaker=expert)
    E->>O: TextBlockDelta (专家回答)
    O->>U: text_delta(speaker=expert, stepKey)×N
    Note over U: 正文追加(现状不变) + 镜像进 expert 步详情
    E->>O: 专家完成
    O->>U: step_end(expert, 结论) + expert_result
    O->>U: done
    U->>O: GET routeRuns / steps (回填专家原文)
    Note over O: 收尾落库 (expert detail_json 含 rawOutput)

HITL 暂停-恢复(upsert 续接):

sequenceDiagram
    participant U as 前端
    participant F as Facade/Timeline
    participant R as Redis Pending
    F->>U: step_start(confirm, waiting) + tool_confirm
    Note over F: finishPending 落库 (confirm 步 waiting)
    U->>F: POST /confirm (允许/记住/拒绝)
    F->>R: 写 decisions
    U->>F: GET /resume
    Note over F: 新 timeline, seqStart=maxSeq(messageId)
    F->>U: step_end(confirm:{pendingReplyId}, approved/rejected)
    F->>U: step_start/... (续跑, 同键 expert 步续接)
    F->>U: done
    Note over F: saveSteps 按 (message_id,step_key) upsert

中止:

sequenceDiagram
    participant U as 前端
    participant F as Facade/Timeline
    U->>F: 停止 / SSE 断连
    Note over F: timeline.abortRunning("用户停止生成")
    F->>U: step_end(running 步, aborted) (可能收不到, 前端本地兜底)
    Note over F: finishCancelled 落库 (aborted 步)
    F->>U: aborted(+stepCount)

5. 步骤模型与结论生成

5.1 内部累积模型(AiProcessTimeline 内,包级可见,照 AiToolCallAcc 风格)

final class AiStepAcc {
    String stepKey; int seq; String kind; String title;
    String speaker; String expertName; Long agentId; String refKey;
    String status;                 // running → 终态
    StringBuilder thinking;        // 仅 thinking 步,内存上限 16000 字符
    StringBuilder safetyPending;   // 思考流安全尾部缓冲(复用 text_delta 机制)
    String conclusion; String detailJson;
    long startNanos; Long durationMs;
}

timeline 公开方法:startStep / updateStep / endStep / thinkingDelta / abortRunning(reason) / toStepLogs(messageId) / summarize();构造入参 (SseEmitter, sessionId, seqStart)。

5.2 kind / 标题 / 图标

kind 标题(后端拼好) 前端图标(i-mdi)
thinking 深度思考;专家侧=专家「X」思考 brain
route 路由决策 share-variant-outline
tool 调用「{toolLabel}」(toolLabelResolver 中文名) tools
expert 咨询专家「X」;attemptNo>1 追加(第 N 次) account-tie-outline
confirm 人工确认 lock-outline
integration 汇总整合 playlist-check

5.3 结论生成规则(确定性,零 LLM 成本;timeline 内静态方法)

kind conclusion(≤80 字) detail_json
thinking 思考文本首个非空行截 80 字;无文本→思考了 X 秒 {text(≤8000,截断标记), truncated}
route route:数剑判定:需咨询专家「X」+decisionJson.reason 截 60 字;self→数剑判定:本轮由自己回答;pinned→已指定专家:X;fallback 时 updateStep 为降级说明 {action, reason, confidence, taskContext(≤2000)}
tool 成功:output 首个有意义行截 80 字(跳过空行/Exit code: 0),空→执行完成;失败→执行失败:{state};DENIED→已拒绝执行 {toolCallId, toolName, input(≤2000), output(≤toolOutputPreviewChars), state, source},落库前过 safetyGuard.mask(TOOL_RESULT)(与 buildToolLogs 同口径)
expert 成功:rawOutput 首行截 80 字,空→专家「X」已回答;失败/超时→reason;暂停→等待你确认后继续 {expertAgentId, expertKey, attemptNo, callKind, rawOutput(≤8000), validationError, tools:[{toolName,state,durationMs}]}(tools 来自专家 state.tools)
confirm 等待你确认:「工具中文名」;恢复段回填已允许执行/已拒绝:原因/确认已失效 {toolCalls:[{toolCallId,toolName,toolLabel}], decisions}
integration 已汇总 N 位专家结论 {text(≤2000)}

5.4 专家输出展示专节(D4)

  1. 实时镜像:text_delta 追加 speaker/expertName/stepKey(桥接层本就持有 speakerExpertName,零额外体积)。前端当存在 running 的 expert 步且 speaker=expert 时,把 delta 同时追加进最终正文(现状不变)与该专家步详情文本 → 过程面板实时可见"专家正在输出什么"。
  2. 完成后:expert_result 时 step_end(expert) 给结论行(专家回答首行);完整原文 live 沿用 syncExpertConclusions()/syncSteps() 回填,并随步骤 detail_json 持久化(rawOutput≤8000 + 子工具列表),回放同样可见。
  3. 直答接管场景:专家正文即最终回答(answer_reset 丢弃入口正文)——面板保留入口 thinking/route 步(解释路由决策)+ 专家步(镜像输出+结论+原文),正文区照常显示专家回答;专家步完成后默认折叠,避免与正文重复刷屏。
  4. 多专家/整合:每位专家各一步(attemptNo 区分重试);整合轮 integration 步显示已汇总 N 位专家结论。
  5. 零泄漏口径不变:专家内部工具仅透出 name/state/duration(来自 state.tools),不下发也不持久化 input/output;入口侧工具步照常给入参/结果详情(落库前 mask)。

5.5 思考流安全

  • onThinkingDelta 复用 onTextDelta 的尾部缓冲 + alignCutToSafeBoundary(把该 private static 方法改为包级可见,一行改动),场景用 SafetyScene.OUTPUT。
  • BLOCK 时该思考步整体丢弃(status=skipped,conclusion=思考内容未通过安全审核),不影响正文。
  • 落库前整段再 mask 一次。

5.6 截断 / 脱敏 / 上限

项 上限 超限行为
思考文本(内存) 16000 字符 停止追加但继续计时
思考文本(落库) 8000 字符 截断 + truncated 标记
专家原文 8000 字符 既有口径
一行结论 80 字(varchar 500) 截断
单步 detail_json 16KB 截断
单消息步骤数 200 超出只计数,摘要显示200+ 个步骤
工具入参/出参 2000 / toolOutputPreviewChars 既有口径 + mask

5.7 可选 LLM 一句话结论(P3,默认关)

异步调 LlmService(enableThinking=false)为每步生成更精炼的一句话结论;配置开关默认关;失败/超时回退确定性结论。成本/时延明确后再上,P1/P2 不做。


6. 数据库设计

6.1 DDL(sql/ai_message_step.sql,幂等,照 sql/ai_orchestration.sql:639-657 约定)

create table if not exists ai_message_step (
    id           bigint       not null,
    session_id   bigint       not null,
    message_id   bigint       not null,
    seq          integer      not null,
    step_key     varchar(128) not null,
    kind         varchar(20)  not null,
    speaker      varchar(10)  default 'entry',
    expert_name  varchar(100),
    agent_id     bigint,
    title        varchar(200) not null,
    status       varchar(20)  not null,
    conclusion   varchar(500),
    detail_json  text,
    duration_ms  bigint,
    remark       varchar(500),
    create_by    bigint,
    create_time  timestamp,
    update_by    bigint,
    update_time  timestamp,
    constraint pk_ai_message_step primary key (id)
);
create unique index if not exists uk_ai_message_step_key on ai_message_step (message_id, step_key);
create index if not exists idx_ai_message_step_session on ai_message_step (session_id, message_id, seq);
comment on table ai_message_step is 'AI 助手消息执行步骤表(思考/路由/工具/专家/确认/整合,物理追加+按步键幂等更新,仅新数据写入)';
comment on column ai_message_step.id is '主键(雪花)';
comment on column ai_message_step.session_id is '所属会话(ai_session.id)';
comment on column ai_message_step.message_id is '所属助手消息(ai_message.id)';
comment on column ai_message_step.seq is '轮内步骤序号(恢复段续接 maxSeq+n)';
comment on column ai_message_step.step_key is '步骤键(轮内唯一,HITL 恢复段 upsert 依据)';
comment on column ai_message_step.kind is '步骤类型 thinking/route/tool/expert/confirm/integration';
comment on column ai_message_step.speaker is '说话人 entry/expert';
comment on column ai_message_step.expert_name is '专家名(speaker=expert 时)';
comment on column ai_message_step.agent_id is '关联智能体主键(专家步)';
comment on column ai_message_step.title is '步骤标题(后端拼好)';
comment on column ai_message_step.status is '状态 running/success/error/skipped/waiting/approved/rejected/expired/aborted';
comment on column ai_message_step.conclusion is '一行结论(≤80 字)';
comment on column ai_message_step.detail_json is '详情 JSON(思考全文/工具入参出参/专家原文+子工具/路由理由/确认处置,已脱敏)';
comment on column ai_message_step.duration_ms is '步骤耗时(毫秒)';

要点:明细表物理删除、无 del_flag、无外键;雪花 bigint 主键 + 审计四列(照 AiToolCallLog)。

6.2 upsert 语义

uk(message_id, step_key) 支撑 HITL 恢复段:暂停段 confirm 步 waiting 已落库 → 恢复段按 decisions 回填终态(update status/conclusion/detail/duration,seq 保留原值);expert 步同键续跑;恢复段新步 seq = maxSeq + n。saveSteps 实现:先查已有键,命中 update,未命中 insert。

6.3 写入时机

AiTurnFinisher 四路径(finish:229 / finishPending:346 / finishPendingResume:385 / finishCancelled:174)在消息落库成功后追加:

try {
    stepService.saveSteps(sessionId, assistant.getId(), state.process.toStepLogs(assistant.getId()));
} catch (Exception e) {
    log.warn("步骤落库失败(不影响回答),messageId={}", assistant.getId(), e);
}

与 memoryPipeline 同口径:绝不影响回答落库。finishPending 时 confirm 步 status=waiting 一并落库。error 路径(persistAssistantFailure)同样落步骤供排障。

6.4 级联删除

AiSessionServiceImpl.deleteAnswerMessages(:447-465)与 deleteChatRound 事务内追加 stepService.deleteByMessageIds(ids) → 重新生成/删轮次无残留。

6.5 审计保留

AiAuditRetentionMapper / AiAuditRetentionTask 追加 ai_message_step 的 count/delete(照 ai_tool_call_log 样式),按 create_time cutoff 统一清理。

6.6 存量边界

仅新数据写入;不回填、不迁移(D3)。旧消息无步骤行,前端 legacy 渲染。


7. REST API

7.1 新增端点(照 toolCalls 样式,Controller:238-244)

/**
 * 查询会话的消息执行步骤(供对话页精确回放过程时间线;仅新数据,存量旧消息无行)
 */
@SaCheckPermission("ai:chat:query")   // 复用既有权限码,不新增
@GetMapping("/session/{sessionId}/steps")
public R<List<AiMessageStepVo>> listSteps(@NotNull(message = "会话不能为空")
                                          @PathVariable("sessionId") Long sessionId) {
    aiSessionService.assertSessionInCurrentCase(sessionId);
    return R.ok(aiSessionService.queryOwnedSteps(sessionId));
}

queryOwnedSteps 照 queryOwnedToolCalls(AiSessionServiceImpl:1027-1031):getOwnedSession(sessionId) 归属校验 + stepService.listBySession(sessionId)(按 message_id, seq 排序)。

7.2 AiMessageStepVo 字段

字段 类型 说明
id / messageId / sessionId Long 主键/关联
seq Integer 轮内序号
stepKey String 步骤键
kind String thinking/route/tool/expert/confirm/integration
speaker / expertName / agentId String/String/Long 说话人
title String 标题
status String 终态(回放无 running)
conclusion String 一行结论
detailJson String 详情 JSON(前端解析)
durationMs Long 耗时
createTime Date 创建时间

7.3 前端 API 封装(F/workbench/api/chat.ts 追加)

export interface ChatMessageStepVO {
  id: Id; messageId: Id; seq: number; stepKey: string;
  kind: 'thinking' | 'route' | 'tool' | 'expert' | 'confirm' | 'integration';
  speaker?: 'entry' | 'expert'; expertName?: string; title: string; status: string;
  conclusion?: string; detailJson?: string; durationMs?: number; createTime?: string;
}
export function listChatSteps(sessionId: Id): Promise<ChatMessageStepVO[]> {
  return aiGet(`/ai/chat/session/${sessionId}/steps`);
}

7.4 错误与降级

steps 请求失败 → 降级空数组(照现有历史加载逐项降级风格)→ 该会话消息走 legacy 卡片渲染,不阻断会话打开。


8. 前端设计

8.1 组件树(新增 F/workbench/components/chat/)

chat/index.vue (既有,外科手术)
└─ ProcessPanel.vue (新增,容器)
   └─ ProcessStepItem.vue ×N (新增,步骤节点)
      ├─ ThinkingDetail.vue (新增,thinking 步详情)
      ├─ pre.tool-code (tool 入参/出参,复用既有样式)
      ├─ pre.tool-code (expert 镜像文本/原文 + 子工具列表)
      └─ route/confirm 只读详情

8.2 processTypes.ts(纯函数,可单测,index.vue 不膨胀)

export interface ProcessStep {
  stepKey: string; seq: number;
  kind: 'thinking' | 'route' | 'tool' | 'expert' | 'confirm' | 'integration';
  title: string; status: string;
  speaker?: 'entry' | 'expert'; expertName?: string; refKey?: string;
  conclusion?: string; durationMs?: number;
  thinkingText?: string;        // thinking 步流式累积
  mirrorText?: string;          // expert 步实时镜像
  detail?: Record<string, any>; // 解析后的 detailJson / route detail
  linkedPart?: MessagePart;     // tool 步关联的既有 tool part(入参/出参)
}
// reducer:start 追加 / delta 拼接 / end 归一;按 stepKey upsert;乱序/重复 end 容错
export function applyStepEvent(steps: ProcessStep[], event: any): void;
export function mirrorExpertDelta(steps: ProcessStep[], event: any): void;
export function buildStepsFromVo(vos: ChatMessageStepVO[]): ProcessStep[]; // 解析 detailJson
export function summarizeSteps(steps: ProcessStep[]): { count: number; thinkingMs: number; activeTitle?: string };
export function findLinkedPart(parts: MessagePart[], step: ProcessStep): MessagePart | undefined;

8.3 ProcessPanel.vue

props 类型 说明
steps ProcessStep[] 步骤列表
streaming boolean 本轮是否流式中
durationMs / thinkingMs number? 总耗时 / 思考耗时
expanded boolean 展开态(父级管理)

emits:toggle。头部状态机:

  • 流式中:脉冲点 + 当前活动步标题(正在:{activeTitle});
  • 完成:摘要行 已完成 N 个步骤 · 用时 X 秒(有思考步前缀 已深度思考 Y 秒 ·;中止 已中止 · 完成 N 个步骤;超上限 200+ 个步骤)。 折叠体:步骤纵列,左侧 1px 时间线轨;展开过渡用 max-height/opacity(照 tool-card 模式)。

8.4 ProcessStepItem.vue

props:step / expanded;emits:toggle。节点行:kind 图标 + 标题 + a-tag 状态 + 耗时 + 一行结论(--wb-text-2,单行省略)。展开详情按 kind 分发:

kind 详情内容
thinking ThinkingDetail(markdown 全文 + 光标 + 耗时)
tool 调用入参 / 结果摘要 pre.tool-code(数据取 linkedPart 或 detail)
expert 镜像文本/原文 pre.tool-code + 子工具列表(name/state/duration)
route 判定理由 / 置信度 / 任务片段
confirm 只读状态(工具中文名 + 处置结果);交互按钮不在此
integration 整合说明

running 标题微光扫动;状态色映射见 §8.10。

8.5 ThinkingDetail.vue

AiMarkdown 渲染 thinkingText + 流式光标(复用 .typing-cursor)+ 底部 思考了 X 秒;流式中自动滚到容器底(仅当面板展开且 stickToBottom)。

8.6 状态模型变更

  • LocalMessage(index.vue:933)追加 steps?: ProcessStep[]、processUserToggled?: boolean;MessagePart 不动。
  • 新增 expandedProcessKeys = ref<string[]>([])(照 expandedSourceKeys:1571 模式,键=msg.id);切会话清空(:2427 旁)。

8.7 index.vue 逐点改动清单(逻辑零重写)

# 位置 改动
1 :933 LocalMessage 追加 steps / processUserToggled 字段
2 :137 bubble 内、parts 循环前 插 <ProcessPanel v-if="msg.steps?.length" ...>;旧 tool/expert/route 三分支(:140/:176/:208)各加 && !msg.steps?.length 抑制(数据照旧构建);confirm 交互卡(:212)与 text 分支不动
3 :2817 handleStreamEvent 追加 case 'step_start'/'step_delta'/'step_end' → applyStepEvent;text_delta 分支追加 speaker=expert 镜像(正文逻辑不变);step_start 且未手动操作→自动展开;done/aborted 末尾→未手动操作则自动折叠 + syncSteps(msg);answer_reset 不清 steps;phase 分支保留兜底
4 :1482-1582 展开键区 expandedProcessKeys + toggleProcess(置 processUserToggled=true,用户操作优先)
5 :2430 handleSelectSession Promise.all 增第 4 路 listChatSteps(失败降级空数组);按 messageId 分组 buildStepsFromVo 挂 local.steps;无步骤旧消息走原路径不动
6 :2740 handleStop 本地把 running 步标 aborted(与 msg.status='3' 同口径)
7 :2688 handleRegenerate backup 浅拷贝追加 steps;预检拒绝→restoreRegenerateBackup 恢复
8 滚动 沿用 scrollToBottomSoon()(每事件已调用),面板高度增长由 stickToBottom 自然跟随

syncSteps(msg):拉 steps REST 覆盖 live 构建的 steps(权威对齐,顺带带回专家 rawOutput 与子工具详情);legacy 消息保留 syncExpertConclusions()。

8.8 历史回放路径(D3)

有步骤的消息:buildStepsFromVo 精确还原顺序/结论/详情(含专家原文)→ ProcessPanel 渲染,legacy 卡抑制。 无步骤的存量旧消息:原 toLocalMessage/appendRouteParts 不动 → legacy 卡片渲染(不回填)。

8.9 交互细节

  • 自动展开/折叠与用户优先:step_start 自动展开、done/aborted 自动折叠;用户手动 toggle 后 processUserToggled=true,自动行为让位。
  • 滚动:面板展开时思考流高度增长由既有 stickToBottom 跟随;ThinkingDetail 内部独立滚动到底。
  • 动画:脉冲点 1.2s、chevron 旋转 0.2s ease、running 标题微光扫动、流式光标 1s steps(全部复用既有节奏)。
  • a11y:节点头 role="button" tabindex="0" + Enter/Space 切换 + aria-expanded(照 tool-card:141-148)。

8.10 视觉规格(全部 --wb-* 令牌,不引入新依赖)

令牌 值 用途
--wb-primary #2a50ec running 状态、时间线轨、图标
--wb-primary-soft #e8eefc 面板底色渐变 linear-gradient(135deg, var(--wb-primary-soft), transparent)
--wb-success #16a34a success/approved
--wb-warning #d97706 waiting
--wb-error #dc2626 error/rejected
--wb-text-muted #94a3b8 skipped/expired/aborted
--wb-border #e5e9f2 面板/节点边框
--wb-text-2 #64748b 结论行
--wb-radius 8px 圆角

滚动条按项目既有样式口径(宽度/轨道/滑块取色自上述令牌),不用浏览器默认。

8.11 线框图

流式中(自动展开):

┌ 助手气泡 ────────────────────────────────────────────┐
│ ┌ 执行过程 ─────────────────────────── ▾ ┐           │
│ │ ● 正在:调用「车辆登记查询」            │           │
│ │ │                                      │           │
│ │ ├ 🧠 深度思考        [成功] 3.2s       │           │
│ │ │   结论:用户想查某人名下车辆…         │           │
│ │ ├ 🔀 路由决策        [成功] 0.4s       │           │
│ │ │   结论:数剑判定:需咨询车辆分析专家  │           │
│ │ ├ 👤 咨询专家「车辆分析专家」 [运行中]  │           │
│ │ │   ┌ 专家输出(实时镜像)──────────┐  │           │
│ │ │   │ 根据查询结果,该人名下共有…▌  │  │           │
│ │ │   └─────────────────────────────┘  │           │
│ │ └ 🔧 调用「车辆登记查询」 [运行中]     │           │
│ └────────────────────────────────────────┘           │
│ (正文区:专家回答流式输出中…)                        │
└──────────────────────────────────────────────────────┘

完成后(自动折叠):

┌ 助手气泡 ────────────────────────────────────────────┐
│ ▸ 已深度思考 3.2 秒 · 已完成 6 个步骤 · 用时 12.3 秒   │
│                                                      │
│ 根据查询结果,该人名下共有 2 辆车辆登记记录…(正文)   │
│ 📎 参考来源(折叠)                                  │
└──────────────────────────────────────────────────────┘

展开回看(含专家原文):

│ ▾ 已深度思考 3.2 秒 · 已完成 6 个步骤 · 用时 12.3 秒   │
│ ├ 🧠 深度思考 [成功] 3.2s  结论:用户想查某人名下车辆… │
│ │   ▸ 展开查看思考全文(markdown)                    │
│ ├ 🔀 路由决策 [成功] 0.4s  结论:需咨询车辆分析专家    │
│ ├ 👤 咨询专家「车辆分析专家」 [成功] 8.1s             │
│ │   结论:该人名下共有 2 辆车辆登记记录               │
│ │   ▾ 专家原始结论(原文留证)                        │
│ │     ┌────────────────────────────────────────┐     │
│ │     │ 根据车辆登记库查询…(rawOutput 全文)   │     │
│ │     └────────────────────────────────────────┘     │
│ │     子工具:车辆登记查询 [成功] 842ms               │
│ ├ 🔧 调用「车辆登记查询」 [成功] 842ms                │
│ │   结论:查询到 2 条车辆登记记录                     │
│ │   ▸ 入参 / 结果摘要                                 │
│ └ …                                                  │

8.12 窄屏(P3)

900px 以下单列适配:面板全宽、详情 pre 横向滚动、结论行省略不折行。


9. 边缘场景与兼容矩阵

场景 行为
无 reasoning 模型 无 Thinking 事件→无 thinking 步,面板仅执行步;纯自答零步骤→面板不渲染(与现状一致)
中止(停止/断连) timeline.abortRunning("用户停止生成"):running 步→aborted;finishCancelled 落库;摘要已中止 · 完成 N 个步骤;前端 handleStop 本地兜底
流中错误 error 回调 abortRunning(errorMsg),失败消息也落步骤,面板保留已走步骤供排障
HITL 暂停 confirm 步 waiting + 既有 tool_confirm 交互卡原位;步骤随 finishPending 落库;SSE 关闭
HITL 恢复 seqStart=maxSeq;confirm 步按 decisions 回填终态(upsert 同键);expert 步同键续跑;新 thinking/tool 步追加;前端同一 LocalMessage 累积
二次暂停 confirm 键含 pendingReplyId 区分批次;旧 pending 卡 expired 逻辑不动
重新生成 新回答落库后级联删旧步骤;预检拒绝→backup 恢复 steps
answer_reset / 专家接管 只清 text parts;入口 thinking/route 步保留(解释路由决策);专家步 speaker=expert 追加+镜像输出
专家超时/降级 expert 步 error+reason;route 步 conclusion 更新降级说明(route_fallback → step_end 重发)
超长思考/输出 内存 16000/落库 8000 截断(停止追加继续计时)、结论 80、detail 16KB、单消息 200 步
并发会话 timeline 每轮独立实例,无共享态;seq 轮内单调
刷新/重连/切会话 步骤经 steps REST 精确回放(暂停段已落库不丢);无 Last-Event-ID(维持现状)
存量旧消息 steps 无行→legacy 卡片渲染原样,不回填不迁移(D3)
总开关关闭 全链路回到现状(逐帧一致,仅多可选字段)

10. 后端改动清单

10.1 新增文件(7 个)

路径(B 下) 内容
core/agent/AiProcessTimeline.java 时间线:startStep/updateStep/endStep/thinkingDelta/abortRunning/toStepLogs/summarize;synchronized + AtomicInteger;emitter null 只累积
domain/AiMessageStep.java @TableName("ai_message_step") extends BaseEntity,照 AiToolCallLog.java 风格(@Data/@EqualsAndHashCode/@TableId/字段 javadoc)
domain/vo/AiMessageStepVo.java 照 AiToolCallLogVo
mapper/AiMessageStepMapper.java extends BaseMapperPlus<AiMessageStep, AiMessageStepVo>
service/IAiMessageStepService.java + service/impl/AiMessageStepServiceImpl.java saveSteps(upsert)、listBySession、deleteByMessageIds、maxSeq
sql/ai_message_step.sql(仓库根 sql/) §6.1 DDL

10.2 修改文件(钩子全部为追加行/追加分支)

文件 改动
core/agent/AiStreamEventBridge.java ① handle 加三个 instanceof ThinkingBlock*Event 分支(:181 兜底前)→ onThinkingStart/Delta/End;② onToolCallStart 末尾追加 startStep(放在 forwardToolEvents 判断之前,专家内部工具也记步骤,但 SSE 下发受 forwardToolEvents 门控);③ onToolResultEnd 追加 endStep;④ text_delta 载荷追加 speaker/expertName/stepKey(取 state.speakerExpertName);⑤ alignCutToSafeBoundary 改包级可见
core/agent/AiStreamState.java 加字段 AiProcessTimeline process;(可空→未装配零行为变化)
core/agent/AiRouteContext.java 加字段 volatile AiProcessTimeline timeline;
core/agent/AiChatFacade.java ① streamChat:state 建好后装配 timeline 挂 state.process + route.timeline;② streamResume(:688 附近):seqStart=maxSeq,新建 timeline;恢复开始即对 confirm:{pendingReplyId} 发 step_end(approved/rejected,取 pending.decisions);③ error 回调 abortRunning + 失败消息落步骤
core/agent/AiRouteOrchestrator.java ① route_decision 处(:213-217)startStep+endStep(route)(self/pinned 同样建步);② runExpert:state.process=route.timeline;expert_start 处 startStep,expert_result/取消/超时/暂停各分支 endStep(暂停→waiting 不发终态,与现有口径一致);③ route_fallback 处 updateStep(route 结论)
core/agent/AiIntegrationDriver.java 整合轮 state 挂 route.timeline;PHASE_INTEGRATING 处 startStep(integration),收尾 endStep
core/agent/AiExpertResumeDriver.java 恢复段 state 挂 timeline(seqStart=maxSeq);续跑专家步复用 expert:{agentId}#{attempt} 键
core/agent/AiTurnFinisher.java finish/finishPending/finishPendingResume/finishCancelled 四处消息落库成功后追加 saveSteps(try/catch 只告警);done/aborted 载荷追加 stepCount/thinkingDurationMs;finishPending 时 confirm 步 waiting 落库
service/impl/AiSessionServiceImpl.java deleteAnswerMessages/deleteChatRound 事务内追加 deleteByMessageIds;新增 queryOwnedSteps(照 queryOwnedToolCalls:1027)
controller/AiChatController.java 新增 steps 端点(§7.1,复用 ai:chat:query)
AiAuditRetentionMapper.java / AiAuditRetentionTask.java 追加 ai_message_step count/delete
config/AiProperties.java Chat 内新增 §3.6 四配置

10.3 改动纪律

  • 全部增量追加;不改既有事件语义、不改编排逻辑、不动 buildMiddlewares、不新增权限码。
  • RouteDecisionTool / 专家直答接管 / detectWriteTools 等审计逻辑不动。
  • steps=展示权威,toolCalls/routeRuns=审计权威,双份数据并存不互斥。

11. 分阶段实施计划

Phase 1 — 实时过程可见(独立可发布,无 DB 变更)

后端:AiProcessTimeline(内存+SSE)、AiStreamState.process、Bridge thinking 分支 + tool 钩子 + text_delta speaker、AiRouteContext.timeline、Facade.streamChat 装配、Orchestrator route/expert/fallback 钩子、Properties 开关。 前端:processTypes.ts、ProcessPanel/ProcessStepItem/ThinkingDetail、chat.ts 类型、index.vue 第 1/2/3/4/6/7 点。

验收:思考模型流式可见思考步 + 工具/专家步 + 结论行;专家输出实时镜像;done 自动折叠摘要;HITL 暂停/恢复步骤续接(内存态);无思考模型仅执行步;旧消息渲染不变。

Phase 2 — 持久化与历史回放(仅新数据,存量不回填)

后端:sql/ai_message_step.sql、实体/VO/Mapper/Service(upsert)、TurnFinisher 四收尾落库 + done/aborted 追加字段、streamResume/ExpertResumeDriver/IntegrationDriver 挂接 + seqStart、confirm 步、steps 端点、级联删除、审计保留、error 路径落库。 前端:listChatSteps、handleSelectSession 第 4 路、buildStepsFromVo、syncSteps、regenerate backup steps。

验收:刷新/切会话后步骤顺序/结论/详情(含专家原文)与流式一致;HITL 暂停→恢复步骤连续且 confirm 终态正确;重新生成旧步骤清除;保留任务清理生效;存量旧会话渲染不变(无回填)。

Phase 3 — 打磨与可选增强

integration 步详情完善、专家步子工具列表渲染、步骤详情复制/导出、与审计 trace 页互跳(a-timeline 参照 audit/trace:237)、900px 窄屏适配、可选 LLM 一句话结论(§5.7)、可选模型级 enable_thinking 配置列(ai_model_config 加列 + AgentAssembler:290 传覆盖,null 保持现状)。


12. 风险与缓解

# 风险 缓解
R1 模型不吐 reasoning(qwen 系默认可能关) P1 验收用 deepseek-reasoner 类模型;验证步骤:jshell 查 ai_model_config 确认模型/供应商 → curl 直连 stream 观察是否有 Thinking 事件(或临时加 debug 日志);P3 可选 enable_thinking 列;不全局强制开启(LlmService:345 教训)
R2 线程可见性(入口订阅线程 vs 专家 boundedElastic) timeline synchronized + seq AtomicInteger;遵守「不引入 subscribeOn/publishOn」约束,钩子在既有回调线程同步调用
R3 思考流 PII 泄漏(逐片下发切断连续串) 复用尾部缓冲 + alignCutToSafeBoundary(项目已验证方案);落库整段再 mask;BLOCK 整步 skipped
R4 SSE 体积/频率 专家输出用 text_delta speaker 镜像,不重复发 delta;step 事件每步 2~3 帧;大文本走 REST;总开关一键回退
R5 落库失败拖垮回答 try/catch 只告警(memoryPipeline 同口径),回答事务不受影响
R6 双份数据重复渲染 有 steps 抑制 legacy 卡;toolCalls/routeRuns 审计链路不动
R7 框架签名差异 已核实 2.0.5 jar 含全部 Thinking 事件(含 sources);实施第一步 javap 复核 ThinkingBlock*Event 的 getReplyId/getBlockId/getDelta 签名

13. 测试与验证计划

13.1 单元

  • AiProcessTimeline:结论生成/截断/upsert 键规则/abortRunning/summarize。
  • processTypes.ts reducer:start/delta/end、乱序、重复 end、恢复段 upsert、mirrorExpertDelta。

13.2 SSE 注入与真实帧核对

  • dev 环境 devtools 覆写 openChatStream handlers 逐帧注入(thinking 多轮 / expert 镜像 / HITL 暂停-恢复 / aborted),验证前端状态机。
  • curl 直连 GET /js/a/ai/chat/stream?sessionId&messageId(带 x-token)核对真实帧序与 text_delta speaker 字段。

13.3 浏览器实测(:3100 → 代理 :8980,admin/admin123)

  • 思考模型多轮工具问答:思考步流式 + 工具步 + 结论行 + done 折叠摘要
  • 专家路由问答:专家输出实时镜像 + 结论 + 原文展开 + 子工具列表
  • HITL 允许/记住/拒绝/过期:confirm 步 waiting→终态,交互卡原位
  • 流中停止:running 步 aborted,摘要正确
  • 重新生成(含写工具预检拒绝回滚):旧步骤清除/backup 恢复
  • 流中刷新 / 切会话:步骤精确回放(顺序/结论/详情含专家原文)
  • 双会话并发:互不串扰
  • 长思考(>8000 字):截断展示 + truncated 标记
  • 存量旧会话打开:仍为现有卡片渲染(无回填)
  • 桌面 + 900px 窄屏:无溢出/遮挡/滚动条样式正确

13.4 DB 核对(jshell + PG 驱动,192.168.0.106:5432/zsjz-ai,本机无 psql)

jshell --class-path D:/soft/repository/org/postgresql/postgresql/42.7.13/postgresql-42.7.13.jar script.jsh
  • ai_message_step seq 连续性、(message_id,step_key) 唯一
  • 恢复段 upsert 无重复行(confirm waiting→终态同键)
  • detail_json 已脱敏(无明文手机号/身份证等)
  • deleteChatRound/regenerate 后无残留
  • 保留任务 cutoff 清理生效
  • 存量消息无步骤行(未回填)

13.5 回归

  • processStepsEnabled=false:全链路与改动前逐帧一致(仅多可选字段)。
  • 旧历史会话渲染不变;无人值守链路(emitter=null)只累积不下发,行为不变。

14. 附录

A. 对标产品体验对照

维度 DeepSeek ChatGPT o 系列 Manus 本方案
思考展示 原始推理流式 摘要(LLM 生成) 无独立思考块 原始推理流式(D2),可选 LLM 摘要(P3)
过程形态 单思考块 折叠活动行 步骤时间线/双栏 统一折叠面板 + 纵向时间线(D1)
每步结论 无 部分 有(结果摘要) 有(确定性,≤80 字)
专家/子代理输出 — — 实时可见 实时镜像 + 原文持久化(D4)
历史回放 思考可回看 可回看 可回看 steps REST 精确回放(D3,存量不回填)
完成后 折叠"已深度思考 X 秒" 折叠"Thought for Xs" 任务完成态 折叠"已完成 N 步 · 用时 X 秒"

B. 术语表

术语 含义
入口智能体 数剑(ai_entry_agent),负责路由与自答
专家 ai_expert_agent,经 route_decision 咨询的领域智能体
直答接管 专家正文直传为最终回答,入口正文经 answer_reset 丢弃
HITL Human-in-the-loop,工具需人工确认(tool_confirm→confirm→resume)
步骤键 stepKey 轮内唯一步骤标识,HITL 恢复段 upsert 依据
镜像 专家 text_delta 同时追加进正文与专家步详情(零额外流式体积)
存量数据 开关启用前数据库中已有的会话/消息(不回填不迁移)

C. 参考文件索引

  • 后端:B/core/agent/{AiStreamEventBridge, AiPhaseSupport, AiSseSupport, AiStreamState, AiRouteContext, AiChatFacade, AiRouteOrchestrator, AiIntegrationDriver, AiExpertResumeDriver, AiTurnFinisher, AgentModelFactory, AgentAssembler}.java、B/domain/{AiMessage, AiToolCallLog, AiTrace, AiRouteRun, AiRouteExpertCall}.java、B/controller/AiChatController.java、B/service/impl/AiSessionServiceImpl.java、B/config/AiProperties.java
  • 前端:F/workbench/views/chat/index.vue、F/workbench/api/{chat.ts, chatSse.ts}、F/workbench/components/AiMarkdown.vue、F/workbench/styles/workbench.less、F/core/http/aiConstants.ts、F/workbench/views/audit/trace/index.vue
  • 框架:D:\soft\repository\io\agentscope\agentscope-core\2.0.5\(含 sources)、agentscope-extensions-model-openai\2.0.5\(含 sources)
  • SQL 约定:sql/ai_orchestration.sql:639-657