一、引言
AI Agent在企业中的应用日益广泛，但推理过程往往是不透明的黑盒------查了哪些数据源、调用了什么工具、推理了几轮，全都不透明。对于需要合规审计的企业场景，推理过程的可见性至关重要。本文基于向量空间JBoltAI平台源码，拆解Agent推理链可视化的完整技术实现。
二、整体架构
向量空间JBoltAI的推理可视化采用前后端分离加WebSocket实时通信架构。后端在ReAct推理链执行过程中，通过ChainContext（推理链上下文）推送stepProgress消息，前端监听并渲染为可折叠步骤列表。支持两种渲染场景：标准聊天窗口用Web Component（Shadow DOM即影子DOM），全屏大屏用Vue（前端框架）响应式渲染。
后端组件：StepStatus枚举定义六种步骤状态，ActionData封装消息格式，ChainContext提供步骤推送API，AbstractReActChain在推理循环中调用步骤API。前端组件：chat-step-progress.js为Web Component核心实现约659行代码，Fullscreen.vue为全屏Vue实现。
三、步骤状态与数据结构
（一）六种步骤状态
向量空间JBoltAI在StepStatus枚举中定义了六种状态：pending（等待中）、running（执行中）、done（已完成）、warning（有警告）、error（出错）、cancelled（已取消）。对应不同图标和颜色：pending灰色空心圆圈（#999），running蓝色旋转弧线（#4a90d9），done绿色对勾（#52c41a），warning橙色感叹号（#faad14），error红色叉号（#ff4d4f），cancelled灰色横线。
（二）步骤数据字段
核心字段：stepId（步骤唯一标识）、parentStepId（父步骤标识，建立层级）、title（标题）、detail（描述）、status（状态）、duration（耗时毫秒）。扩展字段：intent（意图类型）、coreQuery（核心查询）、toolName（工具名称）、toolDesc（工具描述）、toolParams（工具参数）、toolResult（工具结果）。向量空间JBoltAI通过extraFields机制支持任意结构化扩展。
四、后端实现
（一）ChainContext步骤推送API
向量空间JBoltAI的ChainContext提供四类方法：sendStep（发送新步骤）、sendSubStep（发送子步骤）、updateStep（更新状态）、finishStep（完成步骤）。内部用ConcurrentHashMap（Java并发安全哈希表）记录时间戳自动计算duration。所有方法构造ActionData对象（action为stepProgress），通过SourceChannel推送，屏蔽WebSocket和SSE差异。
（二）AbstractReActChain推理步骤序列
向量空间JBoltAI的AbstractReActChain按固定序列推送："分析查询意图"（sendStep设running，finishStep附带意图和查询）→ "生成执行计划" → "检索知识库"（含检索子步骤）→ 多轮推理（每轮父步骤"推理分析（第N轮）"，子步骤"分析并选择工具"）→ "生成回答"。ReActToolExecutor在工具执行时推送更细粒度子步骤。
五、前端实现
（一）Web Component渲染
向量空间JBoltAI的chat-step-progress.js是Web Component（Shadow DOM），用Map（映射数据结构）维护stepId到DOM元素映射。核心方法：addStep追加或按stepId去重更新，finishAllRunning兜底标记。每个步骤展示五类信息：基本信息（图标加标题加耗时）、意图分析（标签加查询列表）、工具标签（蓝色高亮卡片）、工具参数（JSON默认折叠）、工具结果（默认展开）。列表最大高度300像素，父子步骤通过缩进和竖线展示层级。
（二）Vue全屏渲染
全屏大屏用Vue响应式数据：agentSteps数组存储步骤列表，agentStepMap对象维护stepId到索引映射。handleStepProgress方法接收消息更新数组，finishAllRunningSteps兜底收尾。对话结束时over消息触发兜底，将所有running步骤批量标记为done。
六、结语
推理链可视化的核心挑战在于把ReAct推理过程实时、结构化地展示给用户。向量空间JBoltAI平台的实践表明：步骤状态用六种枚举而非简单loading、父子关系用parentStepId构建推理树、双场景用Web Component和Vue分别适配、兜底用finishAllRunning防止步骤卡死------这些工程细节才是可视化稳定运行的关键。推理可视化是向量空间JBoltAI平台ReAct推理链的内置能力，开箱即用。