feat(agent): implement agent management UI and operations
This commit is contained in:
309
docs/agent-page-guide.md
Normal file
309
docs/agent-page-guide.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# Agent 页面功能与结构说明（ragflow_core_v0.21.1）
|
||||
|
||||
本文档面向实现与维护，系统性梳理 `src/pages/agent` 的页面结构、数据流、关键组件与 Hook，以及常见功能点的改造入口，便于快速定位与扩展。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- 入口与路由
|
||||
- 上下文与状态
|
||||
- 页面生命周期与数据加载
|
||||
- 画布层（渲染与交互）
|
||||
- 表单层（节点配置）
|
||||
- 保存与 DSL 构建
|
||||
- 运行与日志
|
||||
- 设置与头像
|
||||
- 常量与类型
|
||||
- 关键数据流（端到端）
|
||||
- 常见功能点定位（修改入口）
|
||||
- 报错与排查建议（头像 ERR_INVALID_URL）
|
||||
- 扩展与实现建议
|
||||
- 快速定位清单
|
||||
- 附：新增节点类型操作指南
|
||||
- 附：运行与日志调用流程
|
||||
- 附：术语与约定
|
||||
|
||||
---
|
||||
|
||||
## 入口与路由
|
||||
|
||||
- `src/pages/agent/index.tsx`
|
||||
- 页面主入口，渲染核心区域与抽屉/对话框：
|
||||
- 画布：`AgentCanvas`
|
||||
- 配置：`FormSheet`
|
||||
- 调试运行：`RunSheet`
|
||||
- 日志：`LogSheet`
|
||||
- 版本：`VersionDialog`
|
||||
- 嵌入：`EmbedDialog`
|
||||
- 设置：`SettingDialog`
|
||||
- 流水线：`PipelineRunSheet`、`PipelineLogSheet`
|
||||
- 使用 `useParams` 读取 `agentId`；用 `useTranslation` 做国际化。
|
||||
- 使用 `useSetModalState` 管理抽屉/对话框开关；与多个 Hook 交互。
|
||||
|
||||
- `src/routes/index.tsx`
|
||||
- 路由注册，包含 `AgentList` 和 `Agent` 详情入口。
|
||||
|
||||
---
|
||||
|
||||
## 上下文与状态
|
||||
|
||||
- `src/pages/agent/context.ts`
|
||||
- `AgentFormContext`：表单上下文（当前节点配置、提交、重置）。
|
||||
- `AgentInstanceContext`：Agent 实例与持久化相关数据。
|
||||
- `AgentChatContext` / `AgentChatLogContext`：聊天与日志面板状态。
|
||||
- `HandleContext`：画布句柄事件（连接、拖拽、选择）。
|
||||
|
||||
- `src/pages/agent/store.ts`（Zustand + Immer）
|
||||
- 全局画布状态：`nodes`、`edges`、选择状态、连接处理。
|
||||
- 常用方法：`addNode`、`updateNode`、`removeNode`、`addEdge`、`removeEdge`、`setNodes`、`setEdges`、`getNode`。
|
||||
- 用于画布交互与保存 DSL 的数据源。
|
||||
|
||||
---
|
||||
|
||||
## 页面生命周期与数据加载
|
||||
|
||||
- `src/pages/agent/hooks/use-fetch-data.ts`
|
||||
- `useFetchDataOnMount`：组件挂载时加载 Agent 数据（含图信息），并调用 `useSetGraphInfo` 设置 `nodes`/`edges`。
|
||||
|
||||
- `src/pages/agent/hooks/use-set-graph.ts`
|
||||
- `useSetGraphInfo(IGraph)`：批量设置 `nodes` 与 `edges`，用于从后端 DSL/存储中初始化画布。
|
||||
|
||||
---
|
||||
|
||||
## 画布层（渲染与交互）
|
||||
|
||||
- `src/pages/agent/canvas/index.tsx`
|
||||
- 基于 `ReactFlow` 的主画布组件，注册节点类型与边类型：
|
||||
- 节点：如 `BeginNode`、`RagNode`、`GenerateNode`、`CategorizeNode` 等。
|
||||
- 边：`ButtonEdge`（包含自定义交互按钮）。
|
||||
- 交互逻辑：
|
||||
- 连接（`onConnect`）、拖拽（`onDragStart`/`onDrop`）、选择与删除。
|
||||
- 与表单抽屉联动（选中节点时打开对应配置）。
|
||||
- 与调试运行、日志抽屉联动（运行前保存、展示日志）。
|
||||
- 与 Store 对接：读写 `nodes`、`edges`；对接上下文与 Hooks。
|
||||
|
||||
- 典型交互 Hook：`src/pages/agent/hooks/use-add-node.ts`
|
||||
- `useInitializeOperatorParams`：各 `Operator` 的初始表单值（含 `llm_id` 注入）。
|
||||
- `useGetNodeName`：本地化节点名生成（依赖 i18n 文案键 `flow.*`）。
|
||||
- `useCalculateNewlyBackChildPosition`：新增子节点坐标计算（避免覆盖）。
|
||||
- `useAddChildEdge`：按句柄类型自动连边（例如右侧输出到目标节点 `End`）。
|
||||
- `useAddToolNode`：在 `Agent` 节点下添加 `Tool` 子节点，并限制工具节点唯一性与坐标位置。
|
||||
- 句柄约定：`NodeHandleId`（如 `End`、`Tool` 等），用于源/目标句柄命名与连边规则。
|
||||
|
||||
---
|
||||
|
||||
## 表单层（节点配置）
|
||||
|
||||
- `src/pages/agent/form-sheet/next.tsx`
|
||||
- `FormSheet`：节点配置侧边抽屉。
|
||||
- 根据当前选中节点类型渲染对应表单组件（通过类型映射）。
|
||||
- 支持节点重命名、单步调试入口、关闭重置。
|
||||
- 与 `AgentFormContext` 协作（提交、校验、状态）。
|
||||
|
||||
- `src/pages/agent/agent-form/index.tsx`
|
||||
- `AgentForm`：Agent 节点核心配置：
|
||||
- 系统提示与用户提示、LLM 设置（模型、温度、`top_p`、`max_tokens`）。
|
||||
- 消息历史窗口、重试次数、错误延迟、异常处理方法等。
|
||||
- 使用 `react-hook-form + zod` 进行表单状态与校验。
|
||||
- 表单保存与 DSL 映射在 `useSaveGraph` 中完成。
|
||||
|
||||
- 表单映射入口说明
|
||||
- 类型到表单组件的映射一般在 `FormSheet` 内部维护；若寻找 `form-config-map.ts` 未找到，建议在 `FormSheet` 内搜索类型映射来源或相关导入。
|
||||
|
||||
---
|
||||
|
||||
## 保存与 DSL 构建
|
||||
|
||||
- `src/pages/agent/hooks/use-save-graph.ts`
|
||||
- `useSaveGraph`：将画布上的 `nodes` 与 `edges` 构建为 DSL 数据并提交后端保存 Agent（包含图与表单配置）。
|
||||
- `useSaveGraphBeforeOpeningDebugDrawer`：打开调试抽屉前保存图，并重置 Agent 实例数据。
|
||||
- `useWatchAgentChange`：监听 Agent 变化进行自动保存（防丢失）。
|
||||
|
||||
- `src/pages/agent/utils.ts`
|
||||
- 工具方法：构建 Agent 异常跳转、判断上下游关系、Agent 工具分类、操作符参数转换等。
|
||||
- 与保存逻辑配合，确保 DSL 参数与 UI 表单一致。
|
||||
|
||||
---
|
||||
|
||||
## 运行与日志
|
||||
|
||||
- `src/pages/agent/hooks/use-run-dataflow.ts`
|
||||
- `useRunDataflow`：运行前保存图、拉起日志面板；通过 SSE 发送运行请求，处理返回的消息 ID 与文件数据（如图像、附件）。
|
||||
|
||||
- `src/pages/agent/log-sheet/index.tsx`
|
||||
- `LogSheet`：侧边日志面板，展示工作流时间线与事件列表（`WorkFlowTimeline`）。
|
||||
|
||||
- `src/pages/agent/hooks/use-fetch-pipeline-log.ts`
|
||||
- `useFetchPipelineLog`：获取流水线日志，处理加载/完成状态与停止逻辑。
|
||||
|
||||
- `src/pages/agent/run-sheet/index.tsx`
|
||||
- `RunSheet`：测试运行抽屉（集成 `DebugContent`），使用 `useSaveGraphBeforeOpeningDebugDrawer` 与 `useGetBeginNodeDataInputs` 获取初始输入。
|
||||
|
||||
- `src/pages/agent/pipeline-run-sheet/index.tsx`
|
||||
- `PipelineRunSheet`：流水线运行面板，集成 `UploaderForm`（上传输入文件）。
|
||||
|
||||
---
|
||||
|
||||
## 设置与头像
|
||||
|
||||
- `src/pages/agent/setting-dialog/index.tsx`
|
||||
- `SettingDialog`：Agent 设置保存对话框。
|
||||
- 处理头像文件转 base64，并随保存 payload 一并提交。
|
||||
|
||||
> 说明：如果后端截断 `data:image/png;base64,...` 导致前端加载 `ERR_INVALID_URL`，需要后端允许存储完整 base64 或改用文件存储 + URL 返回。前端转码逻辑本身是正确的。
|
||||
|
||||
---
|
||||
|
||||
## 常量与类型
|
||||
|
||||
- `src/pages/agent/options.ts`
|
||||
- 常量选项，如 `LanguageOptions` 等。
|
||||
|
||||
- `src/pages/agent/interface.ts`
|
||||
- 类型与接口定义：`IOperatorForm`、`IGenerateParameter`、`IInvokeVariable`、`IPosition`、`BeginQuery`、`IInputs` 等。
|
||||
|
||||
- `src/pages/agent/constant.ts`（在 `use-add-node.ts` 中引用）
|
||||
- `Operator` 枚举与各节点初始值 `initial*Values`（如 `initialAgentValues`、`initialRetrievalValues` 等）。
|
||||
|
||||
---
|
||||
|
||||
## 关键数据流（端到端）
|
||||
|
||||
1. 初始化
|
||||
- 进入详情页时，`useFetchDataOnMount` 拉取当前 Agent 的图与配置。
|
||||
- `useSetGraphInfo` 将后端返回的 `nodes`、`edges` 写入 `useGraphStore`。
|
||||
- 画布 `AgentCanvas` 根据 Store 渲染节点与边。
|
||||
|
||||
2. 编辑
|
||||
- 在画布上添加/连接节点（`use-add-node.ts` 管理初值与连边）。
|
||||
- 选中节点打开 `FormSheet`，填写并校验表单（如 `AgentForm`）。
|
||||
- 表单更改更新 Store 中的节点数据（通过上下文与 Hook）。
|
||||
|
||||
3. 保存
|
||||
- 点击保存或运行前，`useSaveGraph` 将 `nodes`/`edges` 转为 DSL 并提交后端。
|
||||
|
||||
4. 运行与日志
|
||||
- `useRunDataflow` 触发运行，后端通过 SSE 推送消息。
|
||||
- `LogSheet` 展示运行过程与结果，`PipelineRunSheet` 支持文件输入场景。
|
||||
|
||||
5. 设置与外层能力
|
||||
- `SettingDialog` 保存头像与显示配置；`VersionDialog` 管理版本；`EmbedDialog` 提供嵌入能力。
|
||||
|
||||
---
|
||||
|
||||
## 常见功能点定位（修改入口）
|
||||
|
||||
- 画布行为
|
||||
- 新增节点初始参数：`hooks/use-add-node.ts` → `useInitializeOperatorParams`
|
||||
- 节点命名与本地化：`useGetNodeName`（依赖 `locales` 文案键 `flow.*`）
|
||||
- 子节点自动布局：`useCalculateNewlyBackChildPosition`
|
||||
- 工具节点添加与唯一性限制：`useAddToolNode`
|
||||
|
||||
- 保存与 DSL
|
||||
- 转换/提交：`hooks/use-save-graph.ts`（调整 DSL 结构或保存字段）
|
||||
- 参数转换与分类：`utils.ts`
|
||||
|
||||
- 运行与日志
|
||||
- 运行触发与 SSE 处理：`hooks/use-run-dataflow.ts`
|
||||
- 流水线日志轮询：`hooks/use-fetch-pipeline-log.ts`
|
||||
- 时间线展示：`log-sheet/index.tsx`
|
||||
|
||||
- 表单渲染
|
||||
- 抽屉入口与类型映射：`form-sheet/next.tsx`（及类型映射配置）
|
||||
- Agent 节点表单字段与校验：`agent-form/index.tsx`
|
||||
|
||||
- 全局状态
|
||||
- 节点/边增删改查：`store.ts`
|
||||
- 初始图设置：`hooks/use-set-graph.ts`
|
||||
|
||||
- 页面装配
|
||||
- 入口聚合与抽屉/对话框组织：`index.tsx`
|
||||
|
||||
---
|
||||
|
||||
## 报错与排查建议（头像 ERR_INVALID_URL）
|
||||
|
||||
- 问题表现：控制台出现对 `data:image/png;base64,...` 的 `GET`，报错 `ERR_INVALID_URL`。
|
||||
- 根因：后端字段长度或存储策略导致 Base64 被截断，前端加载失败。
|
||||
- 方案：
|
||||
- 后端允许存储完整 Base64；或改用文件存储并返回 URL。
|
||||
- 前端无需改动转码逻辑，仅需按后端新策略使用头像 URL。
|
||||
|
||||
---
|
||||
|
||||
## 扩展与实现建议
|
||||
|
||||
- 新增节点类型
|
||||
- 在 `src/pages/agent/constant.ts` 增加 `Operator` 枚举与 `initial*Values`。
|
||||
- 在 `src/pages/agent/canvas/index.tsx` 注册节点组件。
|
||||
- 在 `src/pages/agent/form-sheet/next.tsx` 添加表单类型映射。
|
||||
- 在 `src/pages/agent/utils.ts` 中处理新节点 DSL 字段与参数转换。
|
||||
- 如需新表单组件：在 `src/pages/agent/agent-form/` 或对应目录编写组件并导出。
|
||||
|
||||
- 调整保存策略
|
||||
- 在 `useSaveGraph` 中扩展 DSL 构建、校验与错误提示。
|
||||
- `useWatchAgentChange` 可增加节流或差异保存，降低后端压力。
|
||||
|
||||
- 增强运行体验
|
||||
- 在 `useRunDataflow` 中处理更多事件类型与文件数据（图像/附件流转）。
|
||||
- 在 `LogSheet` 增加过滤与分组能力，提升可读性。
|
||||
|
||||
---
|
||||
|
||||
## 快速定位清单
|
||||
|
||||
- 入口渲染与抽屉组织：`src/pages/agent/index.tsx`
|
||||
- 全局画布状态：`src/pages/agent/store.ts`
|
||||
- 画布渲染与交互：`src/pages/agent/canvas/index.tsx`
|
||||
- 初始化加载：`src/pages/agent/hooks/use-fetch-data.ts`、`src/pages/agent/hooks/use-set-graph.ts`
|
||||
- 保存 DSL：`src/pages/agent/hooks/use-save-graph.ts`
|
||||
- 运行数据流：`src/pages/agent/hooks/use-run-dataflow.ts`
|
||||
- 日志与流水线：`src/pages/agent/log-sheet/index.tsx`、`src/pages/agent/pipeline-run-sheet/index.tsx`、`src/pages/agent/hooks/use-fetch-pipeline-log.ts`
|
||||
- 表单抽屉：`src/pages/agent/form-sheet/next.tsx`
|
||||
- Agent 表单：`src/pages/agent/agent-form/index.tsx`
|
||||
- 工具与类型：`src/pages/agent/utils.ts`、`src/pages/agent/options.ts`、`src/pages/agent/interface.ts`
|
||||
- 添加节点与连边：`src/pages/agent/hooks/use-add-node.ts`
|
||||
- 列表页与基础查询：`src/hooks/agent-hooks.ts`、`src/pages/agent/list.tsx`（若存在）
|
||||
|
||||
---
|
||||
|
||||
## 附：新增节点类型操作指南（示例）
|
||||
|
||||
1. 在 `constant.ts` 中：
|
||||
- 增加枚举：`Operator.MyNode`
|
||||
- 增加初始值：`initialMyNodeValues`
|
||||
|
||||
2. 在 `canvas/index.tsx` 中：
|
||||
- 注册节点类型映射：`nodeTypes = { MyNode: MyNodeComponent, ... }`
|
||||
|
||||
3. 在 `form-sheet/next.tsx` 中：
|
||||
- 在类型映射里添加表单组件：`{ Operator.MyNode: MyNodeForm, ... }`
|
||||
|
||||
4. 在 `utils.ts` 中：
|
||||
- 扩展 DSL 构建逻辑，确保 `MyNode` 的参数能正确序列化到后端期望的字段。
|
||||
|
||||
5. 若需要服务端对接：
|
||||
- 查看/扩展 `src/services/agent_service.ts` 中相关接口调用。
|
||||
|
||||
---
|
||||
|
||||
## 附：运行与日志调用流程（简化时序）
|
||||
|
||||
1. 点击运行 → `useRunDataflow`
|
||||
2. 调 `useSaveGraph` 保存当前图（DSL）
|
||||
3. 发送运行请求（SSE）到后端
|
||||
4. 打开 `LogSheet` 并持续接收事件
|
||||
5. 显示工作流时间线与每步输出（含文件数据）
|
||||
|
||||
---
|
||||
|
||||
## 附：术语与约定
|
||||
|
||||
- `Operator`：画布节点的类型枚举。
|
||||
- `NodeHandleId`：节点句柄标识，控制连边的输入输出端（如 `End`、`Tool`）。
|
||||
- `DSL`：后端可执行的流程定义 JSON，由画布 `nodes`/`edges` 转换而来。
|
||||
|
||||
---
|
||||
|
||||
如需我导出一份“节点 → DSL 字段”对照表或补充类型映射的完整清单，请告诉我具体节点范围，我将进一步扫描相关目录并生成结构化手册，帮助你在实现新节点或对接后端时做到“改哪里、加什么、传什么”一目了然。
|
||||
Reference in New Issue
Block a user