# 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 架构
```mermaid
flowchart LR
M["模型 API
(reasoning_content + content)"] --> FW["AgentScope 2.0.5
ThinkingBlock* / ToolCall* / TextBlock* 事件"]
FW --> BR["AiStreamEventBridge
(既有桥接 + 新增 thinking/tool 钩子)"]
BR --> TL["AiProcessTimeline (新增)
内存步骤累积 + seq + 结论生成"]
TL -->|"step_start / step_delta / step_end"| SSE["SSE 无名帧 JSON 信封"]
BR -->|"text_delta(+speaker) / tool_* / phase / done..."| SSE
SSE --> FE["前端 ProcessPanel (新增)
步骤时间线 + 专家输出镜像"]
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
```jsonc
// 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 既有事件追加可选字段(旧前端忽略)
```jsonc
// 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 时序图
普通轮(思考 + 工具):
```mermaid
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
```
专家轮(输出镜像 + 回填):
```mermaid
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 续接):
```mermaid
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
```
中止:
```mermaid
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 风格)
```java
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` 约定)
```sql
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)在**消息落库成功后**追加:
```java
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)
```java
/**
* 查询会话的消息执行步骤(供对话页精确回放过程时间线;仅新数据,存量旧消息无行)
*/
@SaCheckPermission("ai:chat:query") // 复用既有权限码,不新增
@GetMapping("/session/{sessionId}/steps")
public R> 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` 追加)
```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 {
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 不膨胀)
```ts
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; // 解析后的 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([])`(照 expandedSourceKeys:1571 模式,键=msg.id);切会话清空(:2427 旁)。
### 8.7 index.vue 逐点改动清单(逻辑零重写)
| # | 位置 | 改动 |
|---|---|---|
| 1 | :933 LocalMessage | 追加 steps / processUserToggled 字段 |
| 2 | :137 bubble 内、parts 循环前 | 插 ``;旧 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` |
| `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`