Skip to main content

​
概述

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

​
节点创建步骤

​
1. 创建节点文件夹

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

​
2. 创建节点组件

在节点文件夹中创建 index.vue 文件，这是节点的主要组件： 
<!-- my-custom-node/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 文件，定义节点的配置信息： 
// my-custom-node/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;

​
4. 配置说明

​
节点类型 (type)

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

​
节点分类 (nodeType)

  • NodeTypeEnum.Common: 普通节点
  • NodeTypeEnum.Start: 开始节点
  • NodeTypeEnum.End: 结束节点
  • NodeTypeEnum.IF: 条件节点
  • NodeTypeEnum.Global: 全局节点

​
节点分组 (group)

  • GroupEnum.AI: AI能力
  • GroupEnum.Base: 基础节点
  • GroupEnum.Mcp: Mcp应用
  • GroupEnum.Message: 消息渠道
  • GroupEnum.Model: 多模态
  • GroupEnum.Output: 输入&输出
  • GroupEnum.Tool: 工具

​
输入类型 (inputType)

  • InputType.INPUT: 直接输入
  • InputType.REFERENCE: 引用其他节点输出

​
输出配置 (outputs)

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

​
节点组件开发规范

​
1. 使用 NodeLayout 组件

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

​
2. 使用 useNode 钩子

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

const { node } = useNode();

​
3. 数据绑定

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

​
4. 状态管理

节点支持执行状态管理，可以通过 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;

​
测试新节点

​
1. 开发模式

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

​
2. 验证节点

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

​
3. 调试技巧

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

​
注意事项

  1. 命名规范: 文件夹名称使用 kebab-case，节点类型使用 PascalCase + Node
  2. 配置完整性: 确保 config.ts 包含所有必需的字段
  3. 类型安全: 使用 TypeScript 确保类型安全
  4. 向后兼容: 保持与现有节点相同的接口和结构
  5. 性能考虑: 避免在节点组件中进行重计算或复杂操作

​
故障排除

​
节点不显示

  • 检查文件夹名称是否正确
  • 验证 config.ts 文件是否存在且格式正确
  • 确认 index.vue 文件存在

​
配置不生效

  • 检查 config.ts 中的字段名是否正确
  • 验证导入路径是否正确
  • 确认类型定义是否匹配

​
组件错误

  • 检查 Vue 组件语法是否正确
  • 验证依赖组件是否正确导入
  • 确认 TypeScript 类型定义

​
更多资源

  • 查看现有节点实现作为参考
  • 阅读 Vue Flow 文档了解节点开发
  • 参考 TypeScript 类型定义文件