TERES_web_frontend/docs/agent-hooks-guide.md

Agent Hooks GUI 学习与复现指南

本指南逐一梳理 src/pages/agent/hooks 目录下的所有 Agent 相关 Hooks，帮助你理解画布、抽屉、运行与日志的全链路逻辑，并可据此复现功能。文档涵盖职责、导出、参数与返回、关键逻辑、典型用法及注意事项。

约定：useGraphStore 为画布状态中心（维护 nodes/edges 及更新方法）；@xyflow/react 用于节点/边渲染与交互；Operator、NodeHandleId、NodeMap 定义节点类型、句柄及渲染映射。

---

图数据获取与构建

use-fetch-data.ts

• 作用：页面挂载时获取 Agent 详情并注入画布。
• 导出：useFetchDataOnMount() → { loading, flowDetail }
• 关键逻辑：
  • 读取 useFetchAgent() 的 data.dsl.graph，通过 useSetGraphInfo() 写入 nodes/edges。
  • 首次挂载 refetch() 刷新详情。
• 用法：在页面 useEffect 中调用以初始化画布。
• 注意：data.dsl.graph 可能为空，已做空处理。

use-set-graph.ts

• 作用：将后端返回的 IGraph 写入画布。
• 导出：useSetGraphInfo() → setGraphInfo({ nodes = [], edges = [] }: IGraph)
• 关键逻辑：有数据才更新，避免清空现有状态。
• 关联：与 useFetchDataOnMount 搭配使用。

use-build-dsl.ts

• 作用：根据当前 nodes/edges 构建可保存的 DSL 数据对象，并过滤占位符节点（Operator.Placeholder）。
• 导出：useBuildDslData() → { buildDslData(currentNodes?) }
• 关键逻辑：
  • 过滤占位符节点与相关边。
  • buildDslComponentsByGraph(filteredNodes, filteredEdges, data.dsl.components) 生成组件列表。
  • 返回 { ...data.dsl, graph, components }。
• 用法：保存前构建 DSL；导出 JSON 时使用。

use-export-json.ts

• 作用：导出当前画布图为 JSON 文件。
• 导出：useHandleExportJsonFile() → { handleExportJson }
• 关键逻辑：downloadJsonFile(buildDslData().graph, \ \${data.title}.json`)`

use-save-graph.ts

• 作用：保存画布到后端；在打开调试时确保最新 DSL。
• 导出：
  • useSaveGraph(showMessage?: boolean) → { saveGraph(currentNodes?), loading }
  • useSaveGraphBeforeOpeningDebugDrawer(show) → { handleRun(nextNodes?), loading }
  • useWatchAgentChange(chatDrawerVisible) → 自动 debounce 保存，并回显更新时间字符串。
• 关键逻辑：
  • 基于路由 id + data.title + buildDslData 组装 dsl 调用 useSetAgent。
  • 打开调试前先 saveGraph()，再 resetAgent() 清空旧消息。
  • useDebounceEffect：每 20 秒在节点/边变化时自动保存（聊天抽屉打开时不保存）。

---

节点创建与拖拽

use-add-node.ts

• 作用：核心节点添加逻辑，含初始参数、坐标计算、特殊类型处理（Agent/Tool/Iteration/Note）。
• 导出：
  • useInitializeOperatorParams() → { initializeOperatorParams, initialFormValuesMap }
  • useGetNodeName() → 根据 Operator 返回国际化默认名称。
  • useCalculateNewlyChildPosition() → 计算新增子节点位置避免覆盖。
  • useAddNode(reactFlowInstance?) → { addCanvasNode, addNoteNode }
• 内部逻辑：useAddChildEdge()、useAddToolNode()、useResizeIterationNode()。
• 关键逻辑：
  • 初始化各 Operator 的 form 默认值；Agent/Extractor 等会注入 llm_id、默认 prompts。
  • 迭代节点 Operator.Iteration 自动创建 Operator.IterationStart 子节点并设为 extent='parent'。
  • Agent 底部子 Agent 的水平分布通过已有子节点 x 轴最大值计算，避免重叠；Tool 节点仅允许一个（检查是否已有 NodeHandleId.Tool 连接）。
  • 通过 reactFlowInstance.screenToFlowPosition 将点击位置转换为画布坐标；右侧新增子节点时自动用 NodeHandleId 连线。
  • 容器内新增子节点时可能触发父容器宽度调整以容纳子节点。
• 典型用法：

  const { addCanvasNode } = useAddNode(reactFlowInstance);
  // 在菜单点击或连接拖拽结束时：
  addCanvasNode(Operator.Agent, { nodeId, position: Position.Right, id: NodeHandleId.Start })(event);
  

• 注意：
  • Operator.Placeholder 节点 draggable=false。
  • Tool 节点唯一性；容器内节点可能触发 resize。

use-connection-drag.ts

• 作用：连接拖拽起止处理；在拖拽终止位置弹出节点选择下拉，创建占位符节点并连线。
• 导出：useConnectionDrag(reactFlowInstance, onConnect, showModal, hideModal, setDropdownPosition, setCreatedPlaceholderRef, calculateDropdownPosition, removePlaceholderNode, clearActiveDropdown, checkAndRemoveExistingPlaceholder) → { nodeId, onConnectStart, onConnectEnd, handleConnect, getConnectionStartContext, shouldPreventClose, onMove }
• 关键逻辑：
  • onConnectStart 记录起点节点/句柄及鼠标起始位置，区分点击/拖拽（<5px 移动视为点击）。
  • onConnectEnd 计算下拉面板位置；点击则清理状态并关闭下拉；拖拽时先移除旧占位符，再创建新占位符并连线。
  • onMove 在画布滚动/缩放时隐藏下拉并清理占位符。

use-dropdown-position.ts

• 作用：屏幕与 Flow 坐标互转，计算下拉菜单位置使其对齐占位节点。
• 导出：useDropdownPosition(reactFlowInstance) → { calculateDropdownPosition, getPlaceholderNodePosition, flowToScreenPosition, screenToFlowPosition }
• 关键逻辑：按常量 HALF_PLACEHOLDER_NODE_WIDTH、DROPDOWN_HORIZONTAL_OFFSET、DROPDOWN_VERTICAL_OFFSET 计算偏移。

use-placeholder-manager.ts

• 作用：占位符节点的创建、删除与状态追踪；替换为真实节点后自动建立连接并同步位置。
• 导出：usePlaceholderManager(reactFlowInstance) → { removePlaceholderNode, onNodeCreated, setCreatedPlaceholderRef, resetUserSelectedFlag, checkAndRemoveExistingPlaceholder, createdPlaceholderRef, userSelectedNodeRef }
• 关键逻辑：
  • 保证面板上仅有一个占位符。
  • onNodeCreated(newNodeId)：真实节点位置与占位符对齐；按占位符的起点连线；删除占位符及相关边。
  • 使用 reactFlowInstance.deleteElements 执行批量删除。

use-before-delete.tsx

• 作用：拦截删除操作，保护 Operator.Begin、容器首节点（Operator.IterationStart 非成对删除时阻止）及下游 Agent/Tool 的联动删除。
• 导出：useBeforeDelete() → { handleBeforeDelete }
• 关键逻辑：
  • UndeletableNodes：Begin 与 IterationStart 的特殊保护。
  • 当包含 Agent 节点时，额外删除其下游 Agent/Tool（节点与边）。
• 用法：作为 React Flow 的 onBeforeDelete 回调。

use-change-node-name.ts

• 作用：处理节点名称与 Tool 名称变更，避免重复命名并同步到画布。
• 导出：useHandleNodeNameChange({ id, data }) → { name, handleNameBlur, handleNameChange }
• 关键逻辑：
  • Tool 名称变更写入父 Agent 的 tools 字段，通过 updateNodeForm(agentId, nextTools, ['tools'])。
  • 普通节点名通过 updateNodeName(id, name) 更新；同一画布内不可重名，重复则提示 message.error('The name cannot be repeated')。

use-agent-tool-initial-values.ts

• 作用：为 Agent Tool（非画布节点）生成初始参数（裁剪/重组）以适配对话调用。
• 导出：useAgentToolInitialValues() → { initializeAgentToolValues(operatorName) }
• 关键逻辑：对不同 Operator 精简参数，如去除 query/sql/stock_code，或仅保留 smtp_* 邮件字段等。

use-form-values.ts

• 作用：表单初始值合并，优先使用节点已有 data.form，否则回退为 defaultValues。
• 导出：useFormValues(defaultValues, node?)

use-watch-form-change.ts

• 作用：监听 react-hook-form 表单变化并同步到画布节点 form。
• 导出：useWatchFormChange(id?, form?)
• 关键逻辑：手动获取 form.getValues()，再 updateNodeForm(id, values)。

use-move-note.ts

• 作用：便签（Note）悬浮预览位置跟随鼠标。
• 导出：useMoveNote() → { ref, showImage, hideImage, mouse, imgVisible }
• 关键逻辑：使用 useMouse() 监听坐标，更新 ref.current.style.top/left。

---

运行与日志

use-run-dataflow.ts

• 作用：保存画布后触发数据流运行（SSE），打开日志抽屉并设置当前 messageId。
• 导出：useRunDataflow({ showLogSheet, setMessageId }) → { run(fileResponseData), loading, uploadedFileData }
• 关键逻辑：
  • 先 saveGraph()，再 send({ id, query: '', session_id: null, files: [file] }) 到 api.runCanvas。
  • 校验响应成功后设置 uploadedFileData/file 与 messageId。

use-cancel-dataflow.ts

• 作用：取消当前数据流，并停止日志拉取。
• 导出：useCancelCurrentDataflow({ messageId, stopFetchTrace }) → { handleCancel }
• 关键逻辑：cancelDataflow(messageId) 返回 code===0 时调用 stopFetchTrace()。

use-fetch-pipeline-log.ts

• 作用：拉取运行日志（trace），判断是否完成与是否为空，控制轮询。
• 导出：useFetchPipelineLog(logSheetVisible) → { logs, isLogEmpty, isCompleted, loading, isParsing, messageId, setMessageId, stopFetchTrace }
• 关键逻辑：
  • END 且 trace[0].message 非空视为完成，随后 stopFetchTrace()；抽屉打开时重置 isStopFetchTrace=false 继续拉取。

use-download-output.ts

• 作用：从日志中提取 END 节点输出并下载 JSON。
• 导出：findEndOutput(list), isEndOutputEmpty(list), useDownloadOutput(data?) → { handleDownloadJson }

---

抽屉与面板显示

use-show-drawer.tsx

• 作用：统一管理“运行/聊天抽屉”、“单节点调试抽屉”、“表单抽屉”、“日志抽屉”的显示逻辑。
• 导出：
  • useShowFormDrawer() → { formDrawerVisible, hideFormDrawer, showFormDrawer(e, nodeId), clickedNode }
  • useShowSingleDebugDrawer() → { singleDebugDrawerVisible, hideSingleDebugDrawer, showSingleDebugDrawer }
  • useShowDrawer({ drawerVisible, hideDrawer }) → { chatVisible, runVisible, onPaneClick, singleDebugDrawerVisible, showSingleDebugDrawer, hideSingleDebugDrawer, formDrawerVisible, showFormDrawer, clickedNode, onNodeClick, hideFormDrawer, hideRunOrChatDrawer, showChatModal }
  • useShowLogSheet({ setCurrentMessageId }) → { logSheetVisible, hideLogSheet, showLogSheet(messageId) }
  • useHideFormSheetOnNodeDeletion({ hideFormDrawer }) → 在节点被删除时自动关闭表单抽屉。
• 关键逻辑：
  • 当 drawerVisible=true：若 Begin 有输入则显示“运行”抽屉；否则显示“聊天”抽屉。
  • 点击节点打开表单抽屉（排除 Note/Placeholder/File）；点击节点上的“播放”图标打开单节点调试抽屉。
  • hideRunOrChatDrawer 同时关闭运行/聊天抽屉与外层抽屉。

---

Begin 相关选项与变量

use-get-begin-query.tsx

• 作用：围绕 Begin 节点数据构建输入、输出、变量与组件引用选项。
• 导出：
  • useSelectBeginNodeDataInputs() → Begin 的输入 BeginQuery[]
  • useIsTaskMode(isTask?) → 返回是否任务模式（从 Begin 的 form.mode 或传入）。
  • useGetBeginNodeDataQuery() → 读取 Begin 的 inputs 并转换为列表。
  • useBuildNodeOutputOptions(nodeId?) → 输出引用选项（带 OperatorIcon）。
  • useBuildVariableOptions(nodeId?, parentId?) → Begin 变量与节点输出选项合并。
  • useBuildComponentIdOptions(nodeId?, parentId?) → 组件引用（排除某些节点，容器内仅引用同层或外部节点）。
  • useBuildComponentIdAndBeginOptions(nodeId?, parentId?) → Begin + 组件引用。
  • useGetComponentLabelByValue(nodeId) / useGetVariableLabelByValue(nodeId) → 根据值反查标签。
• 注意：容器内节点引用受限：子节点只能引用同容器同层节点或外部节点，不能引用父节点。

use-build-options.tsx

• 作用：轻量版，仅构建节点输出选项。
• 导出：useBuildNodeOutputOptions(nodeId?)

use-is-pipeline.ts

• 作用：读取路由查询判断是否显示数据流画布（AgentQuery.Category === DataflowCanvas）。
• 导出：useIsPipeline()

---

聊天与共享

use-chat-logic.ts

• 作用：对话中处理“等待用户填写”的表单组件逻辑，组装提交时的 beginInputs。
• 导出：useAwaitCompentData({ derivedMessages, sendFormMessage, canvasId }) → { getInputs, buildInputList, handleOk, isWaitting }
• 关键逻辑：将消息中的 data.inputs 与用户填写值合并后发送。

use-cache-chat-log.ts

• 作用：聊天事件按 message_id 分片缓存，支持过滤与清空。
• 导出：useCacheChatLog() → { eventList, currentEventListWithoutMessage, currentEventListWithoutMessageById, setEventList, clearEventList, addEventList, filterEventListByEventType, filterEventListByMessageId, setCurrentMessageId, currentMessageId }
• 关键逻辑：排除 Message/MessageEnd 事件，保留节点事件日志用于“运行日志”展示。

use-send-shared-message.ts

• 作用：分享页的消息发送逻辑（可任务模式），包含参数弹窗与自动触发任务。
• 导出：
  • useSendButtonDisabled(value) → 空字符串时禁用。
  • useGetSharedChatSearchParams() → 从 URL 解析 from/shared_id/locale 等。
  • useSendNextSharedMessage(addEventList) → { sendMessage, hasError, parameterDialogVisible, inputsData, isTaskMode, hideParameterDialog, showParameterDialog, ok }
• 关键逻辑：
  • url 动态拼接：agentbots 或 chatbots。
  • 任务模式且 inputs 为空时自动触发一次空参数运行。

---

外部资源与工具

use-find-mcp-by-id.ts

• 作用：在 MCP 服务列表中按 ID 查找服务器对象。
• 导出：useFindMcpById() → { findMcpById(id) }

use-open-document.ts

• 作用：打开在线文档（Agent 组件说明）。
• 导出：useOpenDocument() → openDocument()（window.open 到 https://ragflow.io/docs/dev/category/agent-components）。

use-show-dialog.ts

• 作用：系统 API Key 管理与分享预览。
• 导出：
  • useOperateApiKey(idKey, dialogId?) → { removeToken, createToken, tokenList, creatingLoading, listLoading }
  • usePreviewChat(idKey) → { handlePreview }
  • useSelectChartStatsList() → 将统计数据转换为图表用的 { xAxis, yAxis }[]。
• 关键逻辑：创建/删除系统 token；打开分享页预览 URL（根据 idKey 判断 Agent 或 Chat）。

---

布局与其他

use-calculate-sheet-right.ts

• 作用：根据 body 宽度返回抽屉的右侧定位类名。
• 导出：useCalculateSheetRight() → 'right-[620px]' | 'right-1/3'

use-iteration.ts

• 作用：当前文件为空，预留迭代相关的后续逻辑。
• 导出：暂无（空文件）。

---

复现建议与流程

• 画布初始化：

  • 页面挂载时调用 useFetchDataOnMount()，保证 nodes/edges 与后端一致。
  • 如需区分是否数据流画布，调用 useIsPipeline() 控制界面模式。

• 节点与连接交互：

  • 连接拖拽中，使用 useConnectionDrag 的 onConnectStart/onConnectEnd/onMove 管理占位符与下拉。
  • 选择节点类型后，配合 usePlaceholderManager.onNodeCreated(newNodeId) 落地真实节点并连线。
  • 添加节点通过 useAddNode.addCanvasNode(type,{ nodeId, position, id })(event)，自动计算位置与连线。

• 表单与抽屉：

  • 点击节点打开 useShowFormDrawer.showFormDrawer(e, nodeId)；点击“播放”打开 useShowSingleDebugDrawer。
  • 外层抽屉控制 useShowDrawer；运行/聊天抽屉根据 Begin 输入状态切换。
  • 表单变更用 useWatchFormChange(id, form) 将 react-hook-form 值同步到 data.form。

• 运行与日志：

  • 上传文件后，调用 useRunDataflow.run(fileResponseData)；在日志抽屉中用 useFetchPipelineLog(logSheetVisible) 拉取状态。
  • 取消运行用 useCancelCurrentDataflow.handleCancel()；下载输出用 useDownloadOutput.handleDownloadJson()。

• 保存与导出：

  • 使用 useSaveGraphBeforeOpeningDebugDrawer 在每次调试前保存并重置状态。
  • 自动保存：useWatchAgentChange(chatDrawerVisible) 在无聊天抽屉时 debounce 落库。
  • 导出 JSON：useHandleExportJsonFile.handleExportJson()。

---

易踩坑与注意事项

• 占位符节点必须在保存 DSL 时过滤，否则会污染组件图（useBuildDslData 已处理）。
• Tool 节点只允许有一个；useAddNode 中对 Tool 的添加有唯一性校验。
• 容器类（Iteration）中的引用受限：子节点只能引用同容器同层节点或外部节点，不能引用父节点（useBuildComponentIdOptions）。
• 名称唯一性：画布内节点与 Agent 下的 Tool name 均需唯一（useChangeNodeName）。
• 聊天日志拉取需在 END 且 trace 有 message 时停止，否则会持续轮询（useFetchPipelineLog）。
• 运行/聊天抽屉切换逻辑依赖 Begin 输入是否存在（useShowDrawer）。

---

关联常量与工具（理解 hooks 需要）

• Operator、NodeHandleId、NodeMap：定义节点类型和画布渲染类型。
• generateNodeNamesWithIncreasingIndex：为新增节点生成不重复的默认名称。
• getNodeDragHandle(type)：为不同节点类型定义可拖拽句柄范围。
• buildNodeOutputOptions、buildBeginInputListFromObject、buildBeginQueryWithObject：构建下拉选项与输入/变量结构。

---

如需按模块拆分为多页或增加“最小复现代码片段”，可进一步细化。也可以优先从“连接拖拽 + 占位符 + 节点添加”链路开始，逐步验证 UI 与数据正确性。