Skip to main content

​
创建前端工作流节点

本指南将帮助您快速创建新的工作流节点。新的动态注册系统使得创建节点变得非常简单，只需要按照标准结构创建文件即可。

​
快速开始

​
1. 创建节点文件夹

在 langchat-ui/apps/langchat/src/views/workflows/node/ 目录下创建新的文件夹，文件夹名称使用 kebab-case 格式： 
mkdir my-custom-node

​
2. 创建节点组件

在节点文件夹中创建 index.vue 文件，这是节点的主要组件： 
<script lang="ts" setup>
import { useNode } from '@vue-flow/core';
import NodeLayout from '#/views/workflows/layout/NodeLayout.vue';

const { node } = useNode();
</script>

<template>
  <NodeLayout :node="node">
    <template #content>
      <!-- 在这里添加节点的具体内容 -->
      <div class="flex flex-col gap-2">
        <!-- 节点配置表单 -->
        <div class="p-2">
          <h3>我的自定义节点</h3>
          <!-- 添加配置选项 -->
        </div>
      </div>
    </template>
  </NodeLayout>
</template>

​
3. 创建节点配置

在节点文件夹中创建 config.ts 文件，定义节点的配置信息： 
import { NodeTypeEnum, GroupEnum, InputType } from '../../types/nodeConfig';

const config = {
  type: 'MyCustomNode', // 节点类型名称（PascalCase + Node）
  nodeType: NodeTypeEnum.Common, // 节点分类
  label: '我的自定义节点', // 显示名称
  description: '这是一个自定义节点的描述', // 描述信息
  group: GroupEnum.Tool, // 分组
  color: '#875bf7', // 颜色
  icon: 'svg:custom-icon', // 图标
  data: {
    // 默认数据配置
    content: '',
    inputType: InputType.REFERENCE,
    outputs: [
      { field: 'text', type: 'string', description: '输出结果' }
    ],
  },
};

export default config;

​
配置详解

​
节点类型 (type)

  • 使用 PascalCase 格式
  • 必须以 “Node” 结尾
  • 例如：MyCustomNode, DataProcessorNode

​
节点分类 (nodeType)

NodeTypeEnum.Common // 普通节点

​
节点分组 (group)

GroupEnum.AI // AI能力

​
输入类型 (inputType)

InputType.INPUT // 直接输入

​
输出配置 (outputs)

outputs: [
  {
    field: 'text', // 输出字段名
    type: 'string', // 数据类型
    description: '输出描述' // 描述信息
  }
]

​
组件开发规范

​
使用 NodeLayout 组件

所有节点都应该使用 NodeLayout 组件作为容器，这样可以保持一致的样式和行为： 
<template>
  <NodeLayout :node="node">
    <template #content>
      <!-- 节点内容 -->
    </template>
  </NodeLayout>
</template>

​
使用 useNode 钩子

在组件中使用 useNode() 钩子获取节点实例： 
import { useNode } from '@vue-flow/core';

const { node } = useNode();

​
数据绑定

节点的配置数据存储在 node.data 中，可以直接修改： 
// 更新节点数据
node.data.content = '新的内容';
node.data.someConfig = '配置值';

​
状态管理

节点支持执行状态管理，可以通过 node.data.executionStatus 获取状态： 
const executionStatus = computed(() => {
  return node.data?.executionStatus || 'idle';
});

​
完整示例

​
文件结构

my-custom-node/
├── index.vue      # 节点组件
├── config.ts      # 节点配置
└── components/    # 子组件（可选）
    └── ConfigForm.vue

​
节点组件 (index.vue)

<script lang="ts" setup>
import { computed } from 'vue';
import { useNode } from '@vue-flow/core';
import NodeLayout from '#/views/workflows/layout/NodeLayout.vue';
import NodeArgInfoCard from '#/views/workflows/common/NodeArgInfoCard.vue';

const { node } = useNode();

const executionStatus = computed(() => {
  return node.data?.executionStatus || 'idle';
});
</script>

<template>
  <NodeLayout :node="node">
    <template #content>
      <div class="flex flex-col gap-2">
        <NodeArgInfoCard title="配置">
          <template #default>
            <div class="p-2">
              <input 
                v-model="node.data.content"
                placeholder="输入内容"
                class="w-full p-2 border rounded"
              />
            </div>
          </template>
        </NodeArgInfoCard>

        <NodeArgInfoCard :args="node.data.outputs" title="输出变量" />
      </div>
    </template>
  </NodeLayout>
</template>

​
节点配置 (config.ts)

import { NodeTypeEnum, GroupEnum, InputType } from '../../types/nodeConfig';

const config = {
  type: 'MyCustomNode',
  nodeType: NodeTypeEnum.Common,
  label: '我的自定义节点',
  description: '这是一个示例自定义节点',
  group: GroupEnum.Tool,
  color: '#875bf7',
  icon: 'svg:settings',
  data: {
    content: '',
    inputType: InputType.REFERENCE,
    outputs: [
      { field: 'text', type: 'string', description: '处理结果' }
    ],
  },
};

export default config;

​
测试和验证

​
开发模式

在开发模式下，新节点会自动被扫描和注册，无需重启服务器。

​
验证节点

  • 检查节点是否出现在节点面板中
  • 验证拖拽创建是否正常工作
  • 测试节点配置是否正确保存

​
调试技巧

  • 使用浏览器开发者工具查看节点数据
  • 检查控制台是否有错误信息
  • 验证配置文件格式是否正确

​
最佳实践

​
命名规范

  • 文件夹名称使用 kebab-case
  • 节点类型使用 PascalCase + Node

​
配置完整性

确保 config.ts 包含所有必需的字段：
  • type: 节点类型
  • nodeType: 节点分类
  • label: 显示名称
  • description: 描述信息
  • group: 分组
  • color: 颜色
  • icon: 图标
  • data: 默认数据

​
类型安全

使用 TypeScript 确保类型安全： 
interface NodeData {
  content: string;
  inputType: InputType;
  outputs: Array<{
    field: string;
    type: string;
    description: string;
  }>;
}

​
性能考虑

  • 避免在节点组件中进行重计算
  • 使用 computed 和 watch 优化响应式
  • 合理使用 v-memo 减少不必要的渲染

​
故障排除

​
节点不显示

检查以下项目：
  • 文件夹名称是否正确
  • config.ts 文件是否存在且格式正确
  • index.vue 文件是否存在

​
配置不生效

可能的原因：
  • config.ts 中的字段名不正确
  • 导入路径错误
  • 类型定义不匹配

​
组件错误

常见问题：
  • Vue 组件语法错误
  • 依赖组件未正确导入
  • TypeScript 类型定义问题

​
更多资源

  • 查看现有节点实现作为参考
  • 阅读 Vue Flow 文档 了解节点开发
  • 参考 TypeScript 类型定义文件
  • 查看项目中的其他节点示例

​
下一步

创建完前端节点后，您可能还需要：
  1. 创建对应的后端节点实现
  2. 配置节点间的连接关系
  3. 测试完整的工作流流程
  4. 添加单元测试和集成测试
如果您需要创建后端节点，请参考 创建后端工作流节点 指南。