125 lines
6.5 KiB
Markdown
125 lines
6.5 KiB
Markdown
# `agent` & `agents` 目录代码结构解析
|
||
|
||
本文档旨在详细解析 `ragflow_core_v0.21.1` 项目中 `src/pages/agent` 和 `src/pages/agents` 两个核心目录的结构、功能和关系。
|
||
|
||
- **`src/pages/agent`**: Agent/数据流的可视化编排器，是构建和调试单个 Agent 的工作区。
|
||
- **`src/pages/agents`**: Agent 的管理中心，负责列表展示、创建、模板管理和日志查看。
|
||
|
||
---
|
||
|
||
## 1. `src/pages/agent` - Agent 可视化编排器
|
||
|
||
此目录是整个 RAGFlow 的核心功能所在，提供了一个基于 `@xyflow/react` 的可视化画布，用户可以通过拖拽节点和连接边的方式来构建复杂的数据处理流（DSL）。
|
||
|
||
### 1.1. 目录结构概览
|
||
|
||
```
|
||
agent/
|
||
├── canvas/ # 画布核心组件
|
||
│ ├── node/ # 所有自定义节点的实现
|
||
│ └── edge/ # 自定义边的实现
|
||
├── form/ # 所有节点的配置表单
|
||
│ ├── agent-form/
|
||
│ └── ...
|
||
├── hooks/ # 画布相关的 Hooks
|
||
│ ├── use-build-dsl.ts
|
||
│ └── use-save-graph.ts
|
||
├── chat/ # 调试用的聊天面板
|
||
├── constant/ # Agent 相关的常量
|
||
├── index.tsx # Agent 页面主入口
|
||
└── store.ts # Zustand store，管理画布状态
|
||
```
|
||
|
||
### 1.2. 关键子目录解析
|
||
|
||
#### `canvas/` - 画布与节点
|
||
|
||
- **`canvas/index.tsx`**: 画布主组件，负责整合节点、边、背景、小地图等，并处理拖拽、连接、删除等基本交互。
|
||
- **`canvas/node/`**: 定义了所有内置的节点类型。每个节点文件（如 `begin-node.tsx`, `retrieval-form/`) 负责节点的 UI 渲染、Handles（连接点）的定位和基本逻辑。
|
||
- `node-wrapper.tsx`: 为所有节点提供统一的包裹层，处理选中、错误、运行状态等通用 UI 逻辑。
|
||
- `card.tsx`: 节点内部内容的标准卡片布局。
|
||
- **`canvas/edge/`**: 自定义边的实现，可能包含特殊的路径、箭头或交互。
|
||
|
||
#### `form/` - 节点配置表单
|
||
|
||
当用户在画布上选中一个节点时，会弹出一个表单用于配置该节点的参数。此目录存放了所有节点对应的表单组件。
|
||
|
||
- 目录结构与节点类型一一对应，例如 `retrieval-form/` 对应检索节点。
|
||
- 每个表单组件负责：
|
||
1. 渲染配置项（如输入框、下拉框、开关等）。
|
||
2. 从节点数据中初始化表单。
|
||
3. 将用户的输入实时或在保存时更新回节点的 `data` 属性中。
|
||
- `form/components/` 包含了一些表单内复用的组件，如标准的输出配置 (`output.tsx`)。
|
||
|
||
#### `hooks/` - 核心逻辑 Hooks
|
||
|
||
此目录封装了画布的核心业务逻辑，使主页面 `index.tsx` 保持整洁。
|
||
|
||
- **`use-build-dsl.ts`**: 将画布上的节点和边（Graph a object）转换为后端可执行的领域特定语言（DSL JSON）。这是从前端图形表示到后端逻辑表示的关键转换。
|
||
- **`use-save-graph.ts`**: 负责保存当前的图结构（节点和边的位置、数据等）到后端。通常在用户手动点击保存或自动保存时触发。
|
||
- **`use-run-dataflow.ts`**: 触发当前 Agent 的运行，并处理返回的日志、结果等。
|
||
- **`use-set-graph.ts`**: 从后端获取图数据并将其渲染到画布上，用于加载已保存的 Agent。
|
||
|
||
#### `chat/`, `debug-content/`, `log-sheet/` - 调试与运行
|
||
|
||
- **`chat/`**: Agent 调试时使用的聊天界面，用于发送输入并实时查看 Agent 的回复。
|
||
- **`debug-content/`**: 调试抽屉的内容，可能包含更详细的输入/输出或日志信息。
|
||
- **`log-sheet/`**: 展示 Agent 运行历史日志的面板。
|
||
|
||
#### `store.ts`
|
||
|
||
基于 Zustand 的状态管理，全局维护画布的状态，例如：
|
||
- `nodes`, `edges`: 画布上的节点和边数组。
|
||
- `onNodesChange`, `onEdgesChange`: `@xyflow/react` 需要的回调。
|
||
- 当前选中的节点、画布的缩放/平移状态等。
|
||
- 其他 UI 状态，如配置面板是否打开。
|
||
|
||
---
|
||
|
||
## 2. `src/pages/agents` - Agent 管理中心
|
||
|
||
此目录负责管理所有的 Agent 实例，是用户与 Agent 交互的入口页面。
|
||
|
||
### 2.1. 目录结构概览
|
||
|
||
```
|
||
agents/
|
||
├── hooks/
|
||
│ ├── use-create-agent.ts
|
||
│ └── use-selelct-filters.ts
|
||
├── agent-card.tsx # 单个 Agent 的卡片展示
|
||
├── agent-log-page.tsx # Agent 运行日志列表页
|
||
├── agent-templates.tsx # Agent 模板页
|
||
├── create-agent-dialog.tsx # 创建 Agent 的对话框
|
||
├── index.tsx # Agent 列表页面主入口
|
||
└── use-rename-agent.ts # 重命名 Agent 的 Hook
|
||
```
|
||
|
||
### 2.2. 关键文件解析
|
||
|
||
- **`index.tsx`**: Agent 列表的主页面。通常会从后端获取所有 Agent 的列表，并使用 `agent-card.tsx` 将它们渲染出来。包含搜索、筛选和分页等功能。
|
||
- **`agent-card.tsx`**: 以卡片形式展示单个 Agent 的摘要信息，如名称、描述、更新时间等。点击卡片通常会导航到 `src/pages/agent` 页面，并传入对应的 Agent ID。
|
||
- **`create-agent-dialog.tsx` / `create-agent-form.tsx`**: 提供创建新 Agent 的表单和对话框。`use-create-agent.ts` Hook 封装了向后端发送创建请求的逻辑。
|
||
- **`agent-templates.tsx`**: 展示可供用户选择的预置 Agent 模板，帮助用户快速启动。
|
||
- **`agent-log-page.tsx`**: 展示所有 Agent 的历史运行日志，提供查询和筛选功能。点击某条日志可以查看详情。
|
||
- **`hooks/`**: 存放与 Agent 列表管理相关的业务逻辑。
|
||
- `use-create-agent.ts`: 封装创建 Agent 的 API 调用。
|
||
- `use-selelct-filters.ts`: 管理列表页的筛选条件。
|
||
|
||
---
|
||
|
||
## 3. 关系与数据流
|
||
|
||
1. **从 `agents` 到 `agent`**:
|
||
- 用户在 `agents` 列表页 (`/agents`) 点击一个 Agent 卡片。
|
||
- 应用导航到 `agent` 编排页 (`/agent/{agent_id}`)。
|
||
- `agent` 页面的 `use-set-graph.ts` Hook 被触发，使用 `agent_id` 从后端获取该 Agent 的图数据。
|
||
- 获取到的图数据通过 `store.ts` 设置到全局状态，画布 (`canvas/index.tsx`) 监听到状态变化后，渲染出对应的节点和边。
|
||
|
||
2. **从 `agent` 保存与返回**:
|
||
- 用户在 `agent` 页面修改了图结构。
|
||
- `use-save-graph.ts` Hook 将新的图结构保存到后端。
|
||
- `use-build-dsl.ts` 将图结构转换为 DSL 并一同保存。
|
||
- 用户返回 `agents` 列表页，可以看到 Agent 的更新时间等信息已变化。
|
||
|
||
这两个目录共同构成了一个完整的 Agent 创建、管理、编排和调试的闭环。 |