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` 连线。
  - 容器内新增子节点时可能触发父容器宽度调整以容纳子节点。
- 典型用法：
  ```ts
  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 与数据正确性。