agentic_huge_data_base / wiki
页面 RAGFlow · 8.5 状态与变量管理·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 8.5

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

复杂文档理解与引用检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目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

状态与变量管理

相关源文件

本章引用的主要源码文件：

  • 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
  • web/src/pages/agent/form/agent-form/index.tsx
  • web/src/pages/agent/form/agent-form/use-show-structured-output-dialog.ts
  • web/src/pages/agent/form/agent-form/use-values.ts
  • web/src/pages/agent/form/agent-form/use-watch-change.ts
  • web/src/pages/agent/form/begin-form/index.tsx
  • web/src/pages/agent/form/begin-form/query-table.tsx
  • web/src/pages/agent/form/begin-form/use-edit-query.ts
  • web/src/pages/agent/form/begin-form/use-values.ts
  • web/src/pages/agent/form/begin-form/use-watch-change.ts
  • web/src/pages/agent/form/components/prompt-editor/index.css
  • web/src/pages/agent/form/components/prompt-editor/index.tsx
  • web/src/pages/agent/form/components/prompt-editor/utils.ts
  • web/src/pages/agent/form/components/prompt-editor/variable-node.tsx
  • web/src/pages/agent/form/components/prompt-editor/variable-on-change-plugin.tsx
  • web/src/pages/agent/form/components/prompt-editor/variable-picker-plugin.tsx
  • web/src/pages/agent/form/components/query-variable.tsx
  • web/src/pages/agent/form/components/select-with-secondary-menu.tsx
  • web/src/pages/agent/form/components/structured-output-secondary-menu.tsx
  • web/src/pages/agent/form/invoke-form/variable-table.tsx
  • web/src/pages/agent/form/message-form/use-values.ts
  • web/src/pages/agent/form/variable-assigner-form/dynamic-variables.tsx
  • web/src/pages/agent/form/variable-assigner-form/index.tsx
  • web/src/pages/agent/hooks/use-build-structured-output.ts
  • web/src/pages/agent/hooks/use-get-begin-query.tsx
  • web/src/pages/agent/utils/filter-agent-structured-output.ts

目的与范围

本文档描述了 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 类作为工作流执行期间变量解析的中央编排器。

关键解析函数
  1. get_value_with_variable(value)：字符串插值的入口点。它会扫描字符串中的 {{variable}} 模式，并将其替换为解析后的值 agent/canvas.py:168-193。
  2. 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。

组件中的变量生命周期
  1. 输入映射：组件通过解析提示词或脚本内容来识别其依赖的变量 agent/component/llm.py:103-110。
  2. 解析：在执行之前，组件将这些引用解析为实际值。例如，LLM 组件使用 string_format 来解析系统提示词和用户提示词中的变量 agent/component/llm.py:125-127。
  3. 输出设置：执行后，组件调用 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

变量解析数据流

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

提示词到代码实体的映射
RAGFlow · 提示词到代码实体的映射 · 图 1
RAGFlow · 提示词到代码实体的映射 · 图 1

来源： 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。

RAGFlow · 变量选择界面逻辑 · 图 2
RAGFlow · 变量选择界面逻辑 · 图 2

来源： 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