项目概述
萤智未来 AI Agent 平台是一个为复杂科研图像分析工具设计的可视化 AI 操作界面。它面向生物医学、病理分析等领域的科研人员，通过“左侧实时预览面板 + 右侧 LLM 对话”的双栏布局，将原本分散在多个专业模块中的复杂操作整合为结构化、可引导的流程。
平台的核心价值在于：后端通过 LLM 生成实验计划（Workplan），前端根据 Workplan 动态调度各业务子页面；用户无需理解底层工具函数的调用关系和专业参数含义，只需在左侧完成当前步骤的交互，并通过右侧对话获得实时解释、提示和结果卡片。该架构让 AI 成为流程引导者，而前端负责状态管理和页面编排，从而大幅降低复杂科研工具的学习和执行成本。
技术架构
- 前端框架与技术栈：React + TypeScript。目录结构以
src/pages/aiChat为核心，其中flow/集中管理流程状态机，subPages/承载具体业务操作，component/aiChat提供聊天组件、上下文和内联渲染。 - LLM 集成方式：通过 HTTP 流式接口
/api/v11/input-interpretation/stream与后端交互。前端使用useHistoryService维护chatHistory，逐段接收流式返回，支持实时渲染、重试、清空与附件预览。 - 与后端 API 的交互模式：后端只提供原子化工具函数 API（如图像分割、公式计算），不返回“下一页是什么”。前端通过
FlowControl读取 Workplan 中的 jobs，依据jobType映射到对应stage.step，再调用对应的Flow.enter/advance完成流程推进。 - Pipeline 设计的关键决策：
- 使用
frontend_flow（存储在dataDict.frontend_flow）记录流程游标cursor、子步骤sub_step和当前 job，实现步骤的可预测推进。 - 使用
dataDict作为运行时数据字典，存储每一步产生的中间结果（如图片资源、分割参数、ROI 候选、公式计算结果）；Flow负责流程级数据写入，subPage负责用户操作结果写入。 - 引入
dataDictOverride机制，允许子页面在调用onAdvanceFlow时携带最新数据，避免 React state 异步更新导致流程读取旧值。 - 内联组件使用自定义符号语法
{{[symbol||arg1||arg2]}}嵌入在 LLM 流式文本中，由chatComponent.tsx解析并渲染为对应的交互卡片（如workplan、approveStep、divisionMethodChoice、formulaCalculation）。
- 使用
核心功能
左侧实时预览面板
左侧面板根据 stage.step 和 stage.subStep 动态渲染对应的 subPage，例如：
workplanDesign：展示并确认后端生成的 Workplan。sizeCalibration：尺寸校准，用户配置标尺。divisionMethodChoice：选择分割方法、后处理、形态学等子页面。roiParameterChoice：ROI 参数确认与筛选。formulaCalculation：公式计算与结果展示。ending：流程结束总结。
每个 subPage 专注于当前步骤的业务操作：展示数据、提供滑动条/画布/按钮等控件、调用接口获取预览或结果、将用户选择写入 dataDict，并通过 onAdvanceFlow 推进流程。预览面板与右侧联动的方式是：Flow 在进入阶段时设置 stage 并发送提示消息或内联卡片，用户完成操作后，subPage 将结果写回 dataDict，随后 FlowControl.advanceFlow 读取结果、调用当前 Flow.advance，进入下一个 job。整个过程形成一个可感知的“操作 → 反馈 → 推进”循环。
右侧 LLM 对话交互
右侧 AiChat 组件负责聊天界面、流式请求和历史管理。LLM 返回的文本与结构化内联组件混合渲染：
- 普通文本直接显示在气泡中；
- 内联标签（例如
{{[workplan||json]}}）被解析为对应的 React 组件，嵌入消息体内。
Flow 可以通过 addMessage、updateMessageById 主动发送或更新消息，以在关键节点展示确认卡片、结果卡片等。聊天能力包括重试、清空、回到底部、附件预览等，保证用户在长会话中也能高效操作。
复杂业务逻辑的可视化
平台将复杂的科研流程抽象为受 Workplan 驱动的状态机：
- 后端流式返回 Workplan JSON，内联组件解析并调用
onRegisterWorkplan。 FlowControl.registerWorkplan将工作流写入dataDict，并进入WorkplanDesignFlow。- 用户确认 Workplan 后，
FlowControl根据当前 cursor 找到 job，通过resolveStageFromJob将jobType映射为stage。 - 对应的
Flow.enter准备数据、发送消息、切换左侧页面。 - 用户在
subPage完成操作并写入dataDict后调用onAdvanceFlow。 Flow.advance处理结果，cursor 前进，进入下一个 job。
这种设计将原本需要用户手动串联的多个专业模块，转化为一个可引导的线性工作流。用户只需要关注当前步骤，而无需了解后续模块和全局状态。
独立开发挑战
- 与仅提供工具函数 API 的后端协作：后端不返回“下一页该是什么”，前端必须自行管理复杂流程。解决方案：引入
flow/目录和FlowControl作为前端流程引擎；以 Workplan 为唯一流程来源，将jobType映射为stage；通过dataDict和dataDictOverride保证数据传递的实时性和一致性。 - 性能优化（流式渲染、大数据量处理）：LLM 流式输出可能产生大量聊天消息，且内联组件需要实时解析。通过按消息 ID 更新、局部渲染内联卡片、使用 React Context 分离高频更新与低频状态，避免整树重渲染；同时聊天历史使用
useHistoryService集中管理，减少不必要的父组件更新。 - UI/UX 设计决策：在没有专业 UI 设计资源的情况下，采用左右分栏布局：左侧是操作看板，右侧是 AI 对话。通过
Splitter实现可调整比例，使用内联卡片把复杂参数和结果嵌入对话中，让用户可以在对话上下文中直接确认或调整，减少页面跳转和认知负担。
技术亮点
- 前端主导的 Workplan 驱动流程引擎：不依赖后端页面路由，将实验计划 JSON 映射为前端可调度的阶段序列，支持动态复杂工作流，且易于扩展新阶段。
- 混合消息渲染系统：将 LLM 流式文本与自定义内联组件标签结合，实现“聊天即 UI”。Workplan 确认、阈值调整、分割方法选择、ROI 参数、公式计算结果等都能以交互卡片形式出现在对话中。
- 分层数据字典与 Flow 上下文：
dataDict存储所有运行时结果，Flow管流程级数据，subPage管用户操作数据，dataDictOverride保证异步更新不丢数据。职责边界清晰，可维护性高。
