8.5 · 状态与变量管理（State and Variable Management）

复杂文档理解与引用检索 · 本章是 RAGFlow DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目RAGFlow 章节8.5 状态全文译文模块智能体运行时、记忆与上下文、检索、召回与索引、界面与交互

项目要点页2.5 参考项目项目章节目录RAGFlow DeepWiki 原始章节State and Variable Management 上一章8.4 下一章8.6

源码线索

agent/canvas.py
agent/component/agent_with_tools.py
agent/component/base.py
agent/component/categorize.py
agent/component/llm.py
agent/tools/base.py
common/mcp_tool_call_conn.py
rag/prompts/generator.py
web/src/components/llm-setting-items/use-watch-change.ts
web/src/components/ui/command.tsx

模块标签

智能体运行时
记忆与上下文
检索、召回与索引
界面与交互
图谱与关系

中文译文

状态与变量管理（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/infiniflow/ragflow/8.5-state-and-variable-management

翻译时间：2026-05-27T08:44:41.286Z

翻译模型：deepseek-chat

原文字符数：12208

项目：RAGFlow (ragflow)

---

状态与变量管理

目的与范围

本文档描述了 RAGFlow 的 Agent 和工作流引擎（Canvas）中的状态与变量管理系统。它涵盖了变量在 Python 后端执行环境和基于 React 的前端中如何命名、作用域划分以及解析。该系统支持组件之间的动态数据流，维护对话上下文，并提供了跨工作流图引用数据的标准化语法。

来源： agent/canvas.py:43-82，web/src/pages/agent/constant.ts:16-30

变量命名约定与作用域

RAGFlow 使用三种主要的变量作用域，通过特定的前缀或分隔符来标识：

作用域	语法	示例	用途
系统变量	`sys.<名称>`	`sys.query`，`sys.user_id`	由引擎管理的内置工作流状态。
环境变量	`env.<名称>`	`env.api_key`	用户定义的持久化变量（对话变量）。
组件输出	`<组件ID>@<输出名称>`	`retrieval_0@content`	特定组件产生的输出值。

在提示词或参数中引用变量时使用双花括号：{{sys.query}}。后端使用正则表达式模式进行解析，该模式同时支持单花括号和双花括号格式 agent/canvas.py:169-169。

来源： agent/canvas.py:168-193，web/src/pages/agent/hooks/use-get-begin-query.tsx:174-183

后端变量解析机制

agent/canvas.py 中的 Graph 类作为工作流执行期间变量解析的中央编排器。

关键解析函数

get_value_with_variable(value)：字符串插值的入口点。它会扫描字符串中的 {{variable}} 模式，并将其替换为解析后的值 agent/canvas.py:168-193。
get_variable_value(exp)：确定作用域的核心逻辑。如果表达式包含 @，则将其拆分为 cpn_id 和 var_nm，通过 self.get_component(cpn_id) 从组件输出中获取值 agent/canvas.py:195-207。

数据类型与处理

解析系统处理多种数据类型，以确保与大语言模型（LLM）提示词的兼容性：

生成器/部分对象：如果变量引用的是流（例如大语言模型（LLM）响应或检索生成器），则会迭代生成器以生成组合字符串 agent/canvas.py:179-183。
字符串：直接返回 agent/canvas.py:184-185。
复杂对象：非字符串对象（列表、字典）会使用 json.dumps 并设置 ensure_ascii=False 序列化为 JSON agent/canvas.py:187-187。

来源： agent/canvas.py:168-207

系统变量（sys.*）

系统变量在 Canvas DSL 的 globals 字典中初始化。它们跟踪当前执行任务的状态，对于为 Retrieval 或 LLM 等组件提供上下文至关重要。

变量名称	描述
`sys.query`	当前轮次的用户输入字符串 `agent/canvas.py:76-76`。
`sys.user_id`	执行流程的租户/用户的唯一标识符 `agent/canvas.py:77-77`。
`sys.conversation_turns`	当前会话中的轮次计数器 `agent/canvas.py:78-78`。
`sys.files`	当前轮次提供的文件或附件列表 `agent/canvas.py:79-79`。

来源： agent/canvas.py:75-80，web/src/pages/agent/hooks/use-get-begin-query.tsx:211-230

组件状态与输出

每个组件都继承自 ComponentBase，并在其 param 对象（派生自 ComponentParamBase）中维护自己的 inputs 和 outputs 字典 agent/component/base.py:43-44。

组件中的变量生命周期

输入映射：组件通过解析提示词或脚本内容来识别其依赖的变量 agent/component/llm.py:103-110。
解析：在执行之前，组件将这些引用解析为实际值。例如，LLM 组件使用 string_format 来解析系统提示词和用户提示词中的变量 agent/component/llm.py:125-127。
输出设置：执行后，组件调用 set_output(key, value) 来存储结果。例如，Categorize 组件设置 category_name 和 _next agent/component/categorize.py:157-158。

结构化输出

像 Agent 这样的高级组件支持结构化 JSON 输出。Agent 组件可以从其参数中提取模式，并通过 structured_output_prompt 将其提供给大语言模型（LLM），从而允许用户引用 Agent 响应的特定属性 agent/component/agent_with_tools.py:165-171，rag/prompts/generator.py:188-188。

来源： agent/component/base.py:40-52，agent/component/llm.py:103-127，agent/component/agent_with_tools.py:165-171，agent/component/categorize.py:157-158

变量解析数据流

下图将提示词中的自然语言引用映射到解析它们的代码实体。

提示词到代码实体的映射

flowchart TD
    subgraph "自然语言空间（提示词）"
        P["'Hello {{retrieval_0@content}}, help me with {{sys.query}}'"]
    end

    subgraph "代码实体空间（Python 后端）"
        GraphObj["Graph (agent/canvas.py)"]
        Res["get_value_with_variable()"]
        VarRes["get_variable_value()"]
        Comp["ComponentBase (agent/component/base.py)"]
        Globals["self.globals (dict)"]
    end

    P -->|输入字符串| Res
    Res -->|提取 'sys.query'| VarRes
    VarRes -->|查找| Globals
    Res -->|提取 'retrieval_0@content'| VarRes
    VarRes -->|查找组件| Comp
    Comp -->|返回| OutVal["param.outputs['content']"]

    OutVal --> Res
    Globals --> Res
    Res -->|最终插值字符串| Final["'Hello relevant_doc_text, help me with user_input'"]

来源： agent/canvas.py:168-207，agent/component/base.py:40-52

前端状态管理

前端通过 useGraphStore（Zustand）和用于构建选择菜单的专用钩子来管理变量。

变量选择界面逻辑

前端提供了一个变量选择器，可以根据图结构过滤可用选项。它使用 useBuildUpstreamNodeOutputOptions 来确保节点只能引用其祖先节点的输出 web/src/pages/agent/hooks/use-get-begin-query.tsx:95-106。Lexical 编辑器的 VariablePickerPlugin 便于将这些变量插入到提示词中 web/src/pages/agent/form/components/prompt-editor/variable-picker-plugin.tsx:35-40。

sequenceDiagram
    participant Editor as VariablePickerPlugin (web/src/pages/agent/form/components/prompt-editor/variable-picker-plugin.tsx)
    participant Hook1 as useBuildUpstreamNodeOutputOptions
    participant Hook2 as useBuildGlobalWithBeginVariableOptions
    participant Store as useGraphStore (web/src/pages/agent/store.ts)

    Editor->>Hook1: 获取可用节点输出
    Hook1->>Store: nodes & edges
    Store-->>Hook1: RFState 图结构
    Hook1-->>Editor: 组件@输出 列表

    Editor->>Hook2: 获取 sys.* 和 env.*
    Hook2->>Store: getNode(BeginId)
    Store-->>Hook2: 开始节点配置
    Hook2-->>Editor: sys.query, sys.files 等列表

来源： web/src/pages/agent/hooks/use-get-begin-query.tsx:95-106，web/src/pages/agent/hooks/use-get-begin-query.tsx:208-238，web/src/pages/agent/form/components/prompt-editor/variable-picker-plugin.tsx:67-106

持久化与记忆

全局状态持久化

DSL 的 globals 部分持久化存储在 dsl JSON 对象中。这包括 sys.* 默认值和用户定义的任何 env.* 变量 agent/canvas.py:75-81。

运行时的变量更新

组件可以动态更新变量。例如，Categorize 组件在调用大语言模型（LLM）之前，会根据提供的类别描述和示例更新其系统提示词 agent/component/categorize.py:59-97。然后，它将选定的类别设置为输出，供下游组件使用 agent/component/categorize.py:157-158。

来源： agent/canvas.py:75-81，agent/component/categorize.py:59-97，agent/component/categorize.py:157-158