AI_POC/TERES_web_frontend

Fork 0

Files

guangfei.zhao 889d385709 feat(agent): implement agent management UI and operations

2025-11-05 17:20:58 +08:00

12 KiB

Raw Blame History

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 等）。

关键数据流（端到端）

初始化
- 进入详情页时，useFetchDataOnMount 拉取当前 Agent 的图与配置。
- useSetGraphInfo 将后端返回的 nodes、edges 写入 useGraphStore。
- 画布 AgentCanvas 根据 Store 渲染节点与边。
编辑
- 在画布上添加/连接节点（use-add-node.ts 管理初值与连边）。
- 选中节点打开 FormSheet，填写并校验表单（如 AgentForm）。
- 表单更改更新 Store 中的节点数据（通过上下文与 Hook）。
保存
- 点击保存或运行前，useSaveGraph 将 nodes/edges 转为 DSL 并提交后端。
运行与日志
- useRunDataflow 触发运行，后端通过 SSE 推送消息。
- LogSheet 展示运行过程与结果，PipelineRunSheet 支持文件输入场景。
设置与外层能力
- 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（若存在）

附：新增节点类型操作指南（示例）

在 constant.ts 中：
- 增加枚举：Operator.MyNode
- 增加初始值：initialMyNodeValues
在 canvas/index.tsx 中：
- 注册节点类型映射：nodeTypes = { MyNode: MyNodeComponent, ... }
在 form-sheet/next.tsx 中：
- 在类型映射里添加表单组件：{ Operator.MyNode: MyNodeForm, ... }
在 utils.ts 中：
- 扩展 DSL 构建逻辑，确保 MyNode 的参数能正确序列化到后端期望的字段。
若需要服务端对接：
- 查看/扩展 src/services/agent_service.ts 中相关接口调用。

附：运行与日志调用流程（简化时序）

点击运行 → useRunDataflow
调 useSaveGraph 保存当前图（DSL）
发送运行请求（SSE）到后端
打开 LogSheet 并持续接收事件
显示工作流时间线与每步输出（含文件数据）

附：术语与约定

Operator：画布节点的类型枚举。
NodeHandleId：节点句柄标识，控制连边的输入输出端（如 End、Tool）。
DSL：后端可执行的流程定义 JSON，由画布 nodes/edges 转换而来。

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

12 KiB Raw Blame History Unescape Escape