工作流文档

KMatrix 的工作流（Workflow）是系统的核心“大脑”，它不仅仅是一个简单的步骤列表，而是一个基于有向图（Graph）的智能编排引擎。它利用Kmatrix的工作流能力，极大的扩展了文档处理的空间。

它的机制和应用工作流一样的，为了帮您深挖这个机制，我们可以从以下四个维度来理解：

1. 核心引擎：基于 LangGraph 的状态机

KMatrix 的工作流底层依托于 LangGraph4j。

• 图结构执行：与传统的线性执行不同，KMatrix 支持条件分支、循环和复杂跳转。这意味着你可以设计一个流程，如果 AI 觉得知识库检索结果不够好，可以跳转回上一步重新检索，或者切换到不同的模型。
• DSL 驱动：前端 Vue Flow 生成的可视化图表会被转化为一套 JSON 格式的 DSL (领域特定语言)。后端 WorkflowExecutor 负责解析这套 DSL 并构建出可执行的图节点。

2. 状态交换机制：WorkflowState (核心秘密)

工作流中节点之间是如何传递数据的？KMatrix 设计了一套非常巧妙的 State (状态) 机制：

• 全局状态 (Global State)：存储整个会话的公共信息，如 userInput（用户最初的问题）、sessionId、userId 等。
• 节点输出 (Node Outputs)：这是数据流的关键。每一个节点执行完后，都会产生 NodeOutput。
• 变量引用：后置节点可以通过 {{node_id.output_key}} 的语法，精准地引用前置任何一个节点的输出结果。例如，LLM_CHAT 节点可以引用 KNOWLEDGE_RETRIEVAL 节点的检索结果作为上下文。

3. 节点模型：原子化与高内聚

每一个工作流节点（Node）都是一个独立的“功能组件”，它们都继承自 AbstractAiWorkflowNode：

• 输入解析：节点启动前，会自动解析配置中的变量引用，从 WorkflowState 中提取所需的真实数据。
• 流式反馈 (SSE)：这是 KMatrix 体验流畅的原因。节点在执行时，会通过 SseEmitter 实时推送中间状态。例如，LLM 节点在生成每一个字时、或者工具在执行 Trace 时，前端都能立即感知并显示。
• 自愈能力：节点具备独立的异常处理机制，如果某个节点执行失败，工作流引擎可以根据配置决定是报错停止，还是走“异常分支”。

4. 运行模式：调试与正式环境的解耦

KMatrix 对工作流的执行做了严格的场景区分：

• 正式模式 (Instance-based)：每次用户在对话窗口聊天，都会生成一个 InstanceID，全量记录每一个节点的输入、输出、耗时和 Token 消耗。这为后续的 逻辑溯源和成本分析 提供了数据支持。
• 调试模式 (Debug Mode)：在工作流编辑器中点击“预览”时，系统走的是轻量化的执行路径，不写数据库日志，但会返回极其详尽的 Trace 信息，方便开发者排查逻辑错误。

5. 扩展性设计

KMatrix 的工作流设计是面向未来的：

• 新节点增加：如果你想增加一个“发送企业微信通知”的节点，只需要实现 AbstractAiWorkflowNode 接口，定义好它的输入输出规范，前端注册对应的图标即可。
• 会话变量持久化：支持 SessionVariableAssignNode，允许工作流在运行过程中修改会话级别的长期变量（比如记录用户的偏好、姓名等），这些变量会持久化到数据库，下次对话依然有效。

一句话总结：
KMatrix 的工作流是一个“以状态图为骨架、以 SSE 为通信手段、以变量引用为血脉”的高度解耦的智能执行系统。它将复杂的 AI 逻辑拆解为一个个可观测、可调试的原子节点。