create-node

# FlowGram Custom Node Development

## 概述

本 SKILL 用于指导在 FlowGram 项目的 `apps/demo-free-layout/src/nodes` 目录下创建新的自定义工作流节点。

## 核心概念

### 节点数据结构

节点数据在保存时会存储到后端，基本结构如下：

```typescript
{
  id: 'node_xxxxx',           // 节点 ID
  type: 'node_type',          // 节点类型
  data: {
    title: 'Node Title',      // 节点标题
    inputsValues: { ... },    // 节点表单字段的初始值（实际的值）
    inputs: { ... },          // 节点表单的 JSON Schema（定义表单结构）
    outputs: { ... },         // 节点输出的 JSON Schema（工作流执行时的输出）
    // ... 其他自定义字段
  }
}
```

### 三个核心字段

#### 1. `data.inputsValues` - 节点表单字段的初始值

存储表单中各个字段的实际值，每个字段值包含 `type` 和 `content` 两个属性：

```typescript
inputsValues: {
  url: {
    type: 'constant',          // 常量类型
    content: 'https://...',    // 实际的值
  },
  prompt: {
    type: 'template',          // 模板类型（支持变量引用）
    content: 'Hello {var}',    // 可以引用变量
  },
}
```

**`type` 的可选值**：
- `'constant'`：常量值，不支持变量引用
- `'template'`：模板值，支持 `{variableName}` 语法引用变量
- `'variable'`：变量引用

#### 2. `data.inputs` - 节点表单的 JSON Schema

使用 JSON Schema 定义表单的结构，系统会根据这个 Schema 自动生成表单界面：

```typescript
inputs: {
  type: 'object',
  required: ['url'],           // 必填字段
  properties: {
    url: {
      type: 'string',
    },
    timeout: {
      type: 'number',
      minimum: 0,
      maximum: 60000,
    },
    prompt: {
      type: 'string',
      extra: {
        formComponent: 'prompt-editor',  // 指定自定义组件
      },
    },
  },
}
```

#### 3. `data.outputs` - 节点输出的 JSON Schema

定义节点在工作流执行时的输出数据结构，供下游节点使用：

```typescript
outputs: {
  type: 'object',
  properties: {
    body: { type: 'string' },
    statusCode: { type: 'number' },
    headers: { type: 'object' },
  },
}
```

### 三者的关系

```
inputs (JSON Schema)     →  定义表单结构
inputsValues (实际值)    →  存储表单数据
[节点执行]
outputs (JSON Schema)    →  定义输出结构
```

### 字段类型与自动组件映射

在简单节点中，字段类型会自动匹配对应的表单组件：

| 字段类型 | `extra.formComponent` | 默认组件 |
|---------|---------------------|---------|
| `string` | - | Input |
| `string` | `'prompt-editor'` | PromptEditorWithVariables |
| `number` | - | InputNumber |
| `boolean` | - | Switch |
| `object` | - | JsonCodeEditor |
| `array` | - | JsonCodeEditor |

## 节点开发模式

### 1. 简单节点（自动表单模式）

- **适用场景**：节点配置较为简单，不需要复杂的自定义 UI
- **特点**：根据 `inputs` Schema 自动生成表单
- **示例**：LLM 节点
- **文件结构**：只需要 `index.ts` 文件
- **模板位置**：`./templates/simple-node/index.ts`

### 2. 复杂节点（自定义 UI 模式）

- **适用场景**：需要自定义表单布局、特殊交互或复杂的 UI 组件
- **特点**：完全控制表单渲染和交互逻辑
- **示例**：HTTP 节点
- **文件结构**：
  ```
  {节点名}/
  ├── index.tsx                # 节点注册配置
  ├── form-meta.tsx            # 自定义表单渲染
  ├── types.tsx                # TypeScript 类型定义
  └── components/              # 自定义组件
      └── *.tsx
  ```
- **模板位置**：`./templates/complex-node/`

## 开发流程

### Step 1: 规划节点

确定节点的核心信息：
- **节点类型 ID**：唯一标识，如 `database`、`webhook`
- **节点功能**：明确节点要做什么
- **输入参数**：节点需要哪些配置项
- **输出数据**：节点执行后返回什么数据
- **UI 复杂度**：是否需要自定义 UI

### Step 2: 选择开发模式

```
是否需要自定义 UI？
├─ 否 → 使用简单节点模式（复制 templates/simple-node/）
└─ 是 → 使用复杂节点模式（复制 templates/complex-node/）
```

### Step 3: 复制模板并修改

#### 简单节点

```bash
# 复制模板
cp .claude/skills/create-node/templates/simple-node/index.ts \
   apps/demo-free-layout/src/nodes/{节点名}/index.ts

# 修改模板中的 TODO 标记
# - {NODE_NAME} → 节点名（PascalCase）
# - {NODE_TYPE} → 节点类型枚举值
# - {node_name} → 节点名（kebab-case）
# - {node_type} → 节点类型（小写）
```

#### 复杂节点

```bash
# 复制模板目录
cp -r .claude/skills/create-node/templates/complex-node \
      apps/demo-free-layout/src/nodes/{节点名}

# 修改所有文件中的 TODO 标记
```

### Step 4: 添加节点类型常量

编辑 `apps/demo-free-layout/src/nodes/constants.ts`：

```typescript
export enum WorkflowNodeType {
  // ... 现有节点
  {节点类型} = '{节点类型}',
}
```

### Step 5: 注册节点

编辑 `apps/demo-free-layout/src/nodes/index.ts`：

```typescript
// 导入节点
export { {节点名}NodeRegistry } from './{节点名}';

// 添加到注册列表
export const nodeRegistries: FlowNodeRegistry[] = [
  // ... 现有节点
  {节点名}NodeRegistry,
];
```

### Step 6: 准备节点图标

在 `apps/demo-free-layout/src/assets/` 目录下添加节点图标（SVG 或 JPG 格式）：

```
apps/demo-free-layout/src/assets/icon-{节点名}.svg
```

### Step 7: 测试验证

```bash
# 启动开发服务器
rush dev:demo-free-layout

# 在浏览器中测试节点功能
```

## 常用组件和工具

### FlowGram 组件

从 `@flowgram.ai/form-materials` 导入：

```typescript
import {
  PromptEditorWithVariables,  // 带变量的提示词编辑器
  VariableSelector,            // 变量选择器
  JsonCodeEditor,              // JSON 代码编辑器
  CodeEditor,                  // 代码编辑器
  DisplayOutputs,              // 输出字段展示
  DynamicValueInput,           // 动态值输入
  createInferInputsPlugin,     // 输入推断插件
} from '@flowgram.ai/form-materials';
```

### Semi UI 组件

从 `@douyinfe/semi-ui` 导入：

```typescript
import {
  Input,
  InputNumber,
  Select,
  Switch,
  Button,
  Divider,
} from '@douyinfe/semi-ui';
```

### 表单工具

```typescript
import { Field } from '@flowgram.ai/free-layout-editor';
import { FormItem, FormHeader, FormContent } from '../../form-components';
import { useNodeRenderContext } from '../../hooks';
```

## 最佳实践

### 1. 节点设计

- **单一职责**：一个节点只做一件事
- **清晰的 Schema**：明确定义 inputs 和 outputs
- **合理的默认值**：提供有意义的初始配置
- **友好的描述**：为节点和字段提供清晰的描述

### 2. Schema 设计

```typescript
// ✅ 好的做法：清晰的 Schema
inputs: {
  type: 'object',
  required: ['url', 'method'],
  properties: {
    url: {
      type: 'string',
      description: 'API endpoint URL',
    },
    method: {
      type: 'string',
      enum: ['GET', 'POST', 'PUT', 'DELETE'],
    },
  },
}

// ❌ 不好的做法：缺少约束
inputs: {
  type: 'object',
  properties: {
    url: { type: 'string' },
    method: { type: 'string' },
  },
}
```

### 3. 表单组件使用

```typescript
// ✅ 好的做法：使用 Field 绑定表单状态
<Field<string> name="api.url">
  {({ field }) => (
    <Input
      value={field.value}
      onChange={(value) => field.onChange(value)}
    />
  )}
</Field>

// ❌ 不好的做法：手动管理状态
const [url, setUrl] = useState('');
<Input value={url} onChange={setUrl} />
```

### 4. 只读状态处理

```typescript
export function CustomComponent() {
  const { readonly } = useNodeRenderContext();

  return (
    <Input disabled={readonly} {...props} />
  );
}
```

## 常见问题

### Q1: 如何选择简单节点还是复杂节点？

**判断标准**：
- 字段简单 + 默认布局满足需求 → 简单节点
- 需要自定义布局/特殊交互 → 复杂节点

### Q2: 如何使用变量功能？

在 `inputs` Schema 中使用 `formComponent: 'prompt-editor'`，并在 `inputsValues` 中使用 `type: 'template'`。

### Q3: 如何定义必填字段？

在 `inputs` Schema 的 `required` 数组中列出必填字段名。

### Q4: `inputsValues` 和 `inputs` 必须一致吗？

是的。`inputsValues` 中的字段必须在 `inputs.properties` 中有对应的定义。

### Q5: 节点图标支持什么格式？

支持 SVG、JPG、PNG 格式，推荐使用 SVG。

### Q6: 如何调试节点？

1. 使用浏览器开发者工具查看 console.log
2. 在 FormRender 组件中添加 `console.log(form.getValues())`
3. 使用 React DevTools 查看组件状态

## 参考资源

### 代码示例

- **简单节点**: `apps/demo-free-layout/src/nodes/llm/`
- **复杂节点**: `apps/demo-free-layout/src/nodes/http/`
- **表单组件**: `apps/demo-free-layout/src/form-components/`
- **默认表单**: `apps/demo-free-layout/src/nodes/default-form-meta.tsx`

### 模板文件

- **简单节点模板**: `.claude/skills/create-node/templates/simple-node/`
- **复杂节点模板**: `.claude/skills/create-node/templates/complex-node/`

### 相关文档

- FlowGram 官方文档: https://flowgram.ai
- JSON Schema 规范: https://json-schema.org/
- Semi UI 组件库: https://semi.design/

### 开发命令

```bash
# 启动开发服务器
rush dev:demo-free-layout

# 构建项目
rush build

# 类型检查
rush ts-check

# 代码检查
rush lint
```

## 快速开始检查清单

创建新节点时，按照此检查清单执行：

- [ ] 规划节点功能和数据结构
- [ ] 选择开发模式（简单 vs 复杂）
- [ ] 复制对应的模板文件
- [ ] 修改模板中的 TODO 标记
- [ ] 在 `constants.ts` 中添加节点类型
- [ ] 在 `index.ts` 中注册节点
- [ ] 准备节点图标文件
- [ ] 启动开发服务器测试
- [ ] 验证节点功能正常