# 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 字段”对照表或补充类型映射的完整清单，请告诉我具体节点范围，我将进一步扫描相关目录并生成结构化手册，帮助你在实现新节点或对接后端时做到“改哪里、加什么、传什么”一目了然。