企业官网建设流程全解析

QVerisFlow 是一款面向多智能体工作流的开源平台，其 Web 控制台支持实时执行监控：通过 WebSocket 推送把每个节点的执行状态秒级同步到浏览器，并允许你在运行时暂停执行、跳过节点、注入上下文等人工干预，让 AI 工作流从"黑盒"变成"透明驾驶舱" 🚀

一、为什么多智能体工作流需要实时执行监控？

当你让多个 AI Agent 协作完成"数据采集 → 分析 → 报告生成"这样的长流程时，通常要跑几分钟甚至更久。如果只能干等最终结果，你会遇到三个痛点：

下面带你从零看懂这套"监控 + 干预"体系是如何实现的。

二、通信架构：Socket.IO 与 WebSocket 双通道

QVerisFlow 的后端基于 FastAPI，同时提供两条实时通信通道（见 src/web/app.py）：

• Socket.IO（主通道）：自带心跳（ping_interval=25秒）、断线重连和房间广播，是前端当前使用的默认通道；
• 传统 WebSocket（兼容通道）：/ws/{session_id}端点保留，方便老客户端继续接入（见 src/web/app.py）。

两条通道都要求携带 JWT token 认证，未登录无法建立连接 👮

断线了？消息自动缓存，重连即回放

实时监控最怕"网络抖一下就丢状态"。QVerisFlow 的连接管理器（src/web/websocket/manager.py）内置了断连消息队列：

1. 连接断开期间，发给你的消息不会丢弃，而是进入每个会话专属的队列（上限 100 条，最旧的自动淘汰）；
2. 你重新连上时，管理器立即把缓存消息一次性补发给你（_flush_message_queue，见 src/web/websocket/manager.py）；
3. 如果本地消息还缺得更多，前端可以主动发sync_messages请求，服务端按limit + offset分页批量补发（src/web/websocket/handlers.py）。

💡 一个贴心细节：进度类消息不缓存。节点正在"思考"、"流式输出"这类实时状态重发没有意义，所以它们走"立即发送"通道，发送失败就丢弃，避免重连时刷屏（src/web/socketio/handlers.py）。

三、实时推送：13 种执行事件，覆盖全流程

执行引擎在运行过程中会发出统一的事件流，全部类型定义在 src/orchestration/events.py：

工作流级事件：workflow_started、workflow_completed、workflow_failed、workflow_paused、workflow_resumed、workflow_cancelled

节点级事件：node_started、node_completed、node_failed、node_skipped、node_progress（工具调用等中间状态）、node_thinking（Agent 推理流）、node_stream（内容 token 流）、node_activity（富活动更新）

进度事件：progress_update

每个事件还带有全局递增序列号（src/orchestration/events.py），前端可以据此检测事件是否丢失或乱序。

前端收到事件后，在 web-ui/src/hooks/useWebSocket.ts 中把node_started映射为节点"运行中"、node_completed映射为"已完成"……画布上的节点颜色、耗时、连线动画随之实时更新。你还能看到 Agent 的"思考过程"逐字流式输出，监控体验接近"看直播"。

完整协议文档

如果你想深入消息格式与前后端交互时序图，官方设计文档写得很细：docs/overall_design/13_web_ui.md，其中第 7 节有一段"用户 → 前端 → 后端"的典型交互时序图，建议对照阅读 📖

四、运行时暂停：一个状态机如何"优雅叫停"

4.1 状态机：暂停只是合法状态之一

每次执行都受一个**执行状态机（ExecutionFSM）**约束，状态迁移规则写在 src/orchestration/execution_fsm.py 的头部注释里：

IDLE ──start──▶ RUNNING ──pause──▶ PAUSED │ │ ├──complete──▶ COMPLETED ├──fail─────▶ FAILED └──stop─────▶ CANCELLED ▲ PAUSED ──stop─┘ PAUSED ──resume──▶ RUNNING

只有 RUNNING 才能暂停、只有 PAUSED 才能恢复；已完成/已失败的执行不接受任何事件（转移表见 src/orchestration/execution_fsm.py）。这保证了你不会对一个已跑完的任务"乱按暂停"。

4.2 暂停的实现原理：不杀进程，而是"让出跑道"

暂停并不是粗暴地中断 Agent，状态机内部有一个asyncio.Event（见 src/orchestration/execution_fsm.py）：

• 暂停时：事件被clear()，执行循环走到检查点时执行await fsm.pause_event.wait()，原地挂起，已完成的节点结果、检查点全部保留；
• 恢复时：事件被set()，循环从挂起点继续；
• 如果在暂停期间按了"停止"，状态机还会主动唤醒执行循环以安全退出（见 src/orchestration/execution_fsm.py），避免"叫不醒"的僵死状态。

执行引擎的节点循环里就有这段"检查暂停标志"的逻辑（src/orchestration/workflow_engine.py）：发出workflow_paused事件 → 等待 → 恢复后发出workflow_resumed事件，前端画布立刻从"转圈"变成"暂停中" ⏸️

4.3 三种暂停方式，由你选择

1. 界面按钮：执行期间，对话面板顶部会出现"暂停 / 继续 / 停止"按钮，状态自动切换（web-ui/src/components/ChatPanel/index.tsx）；
2. 自然语言：直接输入"暂停"、"等一下"、"稍等"、"pause"，意图识别器都会识别为暂停命令并调用pause_execution（src/evolution/dialogue_agent.py、src/evolution/workflow_operations.py）；
3. REST API：POST /api/execution/{session_id}/intervene传{"action": "pause"}即可，方便接入你的自动化脚本（src/web/routers/execution.py）。

底层的pause()/resume_execution()都做了严格的状态校验，非法操作会直接返回失败而不是产生脏状态（src/orchestration/workflow_engine.py）。

五、人工干预：5 种让工作流"听你指挥"的手法

暂停只是干预的第一步。QVerisFlow 的干预接口（src/web/routers/execution.py）共支持 5 种动作，全部会实时推送状态变化回前端：

其中"跳过节点"在执行引擎中被显式支持：被跳过的节点会记为skipped状态并广播事件，下游依赖它的节点按规则处理（src/orchestration/workflow_engine.py）。而"注入上下文"会在下一个节点执行前自动合并进上下文，相当于给 AI"悄悄塞一张纸条" 📝

新手建议的干预节奏

1. 执行开始 → 盯着画布确认前 1~2 个节点输出符合预期；
2. 发现偏差 → 立即"暂停"，在节点详情面板查看中间结果；
3. 小问题 →inject_context补充说明后"继续"；大问题 → "停止"并调整工作流后重跑。

六、快速上手：启动监控界面

后端启动后会自动挂载前端并开启 Socket.IO（src/web/app.py），常用命令：

# 启动 Web 服务（端口 8000） uvicorn src.web.app:app --host 0.0.0.0 --port 8000 # 开发模式：前端热更新 cd web-ui && npm run dev

浏览器打开后，登录后进入对话面板描述你的工作流，批准执行即可看到实时画布 + 暂停/停止按钮。更多环境变量与部署细节见 docs/overall_design/13_web_ui.md 第 8 节。

七、总结

QVerisFlow 把"监控"和"干预"做成了同一套实时通道上的两种能力：

• 推送侧：Socket.IO + WebSocket 双通道、事件序列号防丢失、断连缓存 + 分页补发，保证你看到的进度"不断片"；
• 控制侧：FSM 状态机约束下的暂停/恢复/停止、跳过节点、注入上下文、在线改 Prompt，让多智能体工作流第一次变得"可控、可纠偏、可解释"。

对新手而言，这套机制意味着：不必盯着终端日志，也不必祈祷 AI 一次做对——你随时都在驾驶座上 🎯