fastgpt-workflow-generator

FastGPT ワークフロー生成ツール

自然言語の要件から、本番環境で使える FastGPT ワークフロー JSON を自動生成します

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• ワークフローをゼロから新規作成する：「X の目的で FastGPT ワークフローを作成して」とユーザーが依頼した場合
• テンプレートに基づいて生成する：既存のパターン（ドキュメント処理、AI チャット、データ分析、マルチエージェントシステムなど）に似たワークフローを作成したい場合
• 既存のワークフローを変更する：既存のワークフロー JSON にノードを追加、削除、更新したい場合
• ワークフロー JSON を検証する：確認や修正が必要なワークフロー JSON がある場合
• マルチエージェントシステムを設計する：並列処理、エージェントの連携、ワークフローのオーケストレーションについて言及された場合
• ワークフロー作成を自動化する：要件ドキュメントを提示され、実行可能な JSON が必要な場合
• 要件を JSON に変換する：仕様があり、FastGPT 互換のワークフローにしたい場合

トリガーキーワード：FastGPT、ワークフロー、JSON、マルチエージェント、工作流、テンプレートマッチング、ワークフロー自動化、ノード設定、ワークフロー検証

---

基本的なワークフロー

このスキルでは、本番環境で使えるワークフロー JSON を生成するために、5 つのフェーズで処理します。

フェーズ 1：要件分析

目標：自然言語の入力から、構造化された要件を抽出します

処理：

1. 依頼の種類を特定する：

   • ゼロから作成
   • テンプレートに基づいて作成
   • 既存のワークフローを変更
   • 既存の JSON を検証／修正

2. AI の意味解析を使って主要な情報を抽出する：

   {
     "purpose": "Workflow objective (e.g., 'Travel planning assistance')",
     "domain": "Application domain (travel/event/document/data/general)",
     "complexity": "simple | medium | complex",
     "features": ["aiChat", "knowledgeBase", "httpRequest", "parallel"],
     "inputs": ["userChatInput", "city", "date"],
     "outputs": ["Complete plan", "Recommendations"],
     "externalIntegrations": ["Weather API", "Feishu API"],
     "specialRequirements": ["Multi-agent", "Real-time data"]
   }
   

3. 完全性を確認する：情報が不十分な場合は、対話を通じて明確にします

出力：構造化された要件オブジェクト

---

フェーズ 2：テンプレートマッチング

目標：最も類似した組み込みテンプレートを見つけます

組み込みテンプレート（templates/ ディレクトリに保存）：

• templates/文档翻译助手.json - シンプルなワークフロー（ドキュメント処理）
• templates/销售陪练大师.json - 中程度の複雑さ（会話型 AI）
• templates/简历筛选助手_飞书.json - 複雑なワークフロー（データ処理＋外部連携）
• templates/AI金融日报.json - スケジュールトリガー＋マルチエージェント（ニュース集約）

マッチング戦略：

ステップ 1：粗い絞り込み（メタデータに基づく）

Calculate similarity scores:
- Domain match: travel vs travel = 1.0, travel vs event = 0.3
- Complexity match: simple vs simple = 1.0, simple vs complex = 0.3
- Feature overlap: Jaccard similarity of feature sets
- Node count similarity: 1 - |count1 - count2| / max(count1, count2)

Combined score = 0.3 * domain + 0.2 * complexity + 0.3 * features + 0.2 * nodeCount

Select Top 3 candidate templates

ステップ 2：詳細な絞り込み（意味的類似度）

For Top 3 candidates:
1. Analyze user requirements vs template characteristics
2. Evaluate workflow structure similarity
3. Calculate comprehensive score

Final score = 0.3 * domain + 0.2 * complexity + 0.3 * features + 0.2 * semantic

ステップ 3：選択戦略

- Highest score < 0.5: Start from blank template
- Highest score 0.5-0.7: Use template as reference, major modifications
- Highest score > 0.7: Use template as base, minor adjustments

出力：

• 最も適合するテンプレートの JSON オブジェクト
• マッチング分析レポート
• 変更提案のリスト

---

フェーズ 3：JSON の生成

シナリオ 1：テンプレートに基づいて生成

1. Copy template structure

2. Modify nodes
   - Keep: structurally similar nodes (workflowStart, userGuide)
   - Modify: nodes requiring prompt/parameter adjustments
   - Delete: unnecessary nodes
   - Add: new requirement nodes

3. Regenerate NodeId
   function generateNodeId(nodeType, nodeName, existingIds) {
     // Fixed ID mapping
     if (nodeType === 'workflowStart') return 'workflowStart';
     if (nodeType === 'userGuide' || nodeType === 'systemConfig') return 'userGuide';

     // Generate semantic ID (camelCase)
     const baseName = nodeName.replace(/[\s\u4e00-\u9fa5]+/g, '');
     let nodeId = baseName ? `${baseName}Node` : `${nodeType}Node`;

     // Ensure uniqueness
     let counter = 1;
     while (existingIds.has(nodeId)) {
       nodeId = `${baseName}Node_${counter}`;
       counter++;
     }

     return nodeId;
   }

4. Update references
   - Traverse all inputs, replace old nodeId with new nodeId
   - Update edges' source/target
   - Handle two reference formats:
     - Array: ["nodeId", "key"]
     - Template: {{$nodeId.key$}}  (Note: double braces with single $)

5. Auto-layout positions (hierarchical layout algorithm)
   function autoLayout(nodes, edges) {
     // Topological sort to determine layers
     const layers = topologicalLayering(nodes, edges);

     // Calculate positions for each layer
     const LAYER_GAP_X = 350;
     const NODE_GAP_Y = 150;

     layers.forEach((layer, layerIndex) => {
       const x = -200 + layerIndex * LAYER_GAP_X;
       const totalHeight = (layer.length - 1) * NODE_GAP_Y;
       const startY = -totalHeight / 2;

       layer.forEach((nodeId, nodeIndex) => {
         positions[nodeId] = {
           x: x,
           y: startY + nodeIndex * NODE_GAP_Y
         };
       });
     });

     // Fixed position for special nodes
     positions['userGuide'] = { x: -600, y: -250 };
   }

6. Update configuration
   - Modify chatConfig.welcomeText
   - Update chatConfig.variables

シナリオ 2：ゼロから作成

1. Determine node list
   - Required: workflowStart, userGuide
   - Add based on features: chatNode, datasetSearchNode, httpRequest468, etc.
   - Required: answerNode (output node)

2. Generate nodes and connections
   - Use standard node templates
   - Fill required fields
   - Customize inputs/outputs based on requirements

3. Calculate positions and generate configuration

出力：完全な FastGPT ワークフロー JSON

---

フェーズ 4：検証

レベル 1：JSON 形式の検証

✅ JSON is parseable
✅ Top level contains nodes, edges, chatConfig
✅ Each node contains: nodeId, name, flowNodeType, position, inputs, outputs
✅ flowNodeType is in valid type list (40+ types)
✅ position contains x, y numeric coordinates

レベル 2：ノード接続の検証

✅ edges' source/target nodes exist
✅ sourceHandle/targetHandle format correct (nodeId-source-right, nodeId-target-left)
✅ Node input references' nodes and output keys exist
✅ Reference types match (string → string)
✅ Template references {{$nodeId.key$}} nodes and keys exist
✅ No self-loops, no duplicate connections

レベル 3：ロジックの完全性の検証

✅ Required nodes exist (workflowStart, userGuide, at least one output node)
✅ All nodes reachable from workflowStart (connectivity)
✅ No illegal cycles (unless using loop node)
✅ loop nodes correctly configured with parentNodeId and childrenNodeIdList
✅ No dead ends (non-output nodes without outgoing edges)
✅ All required inputs have values

出力：検証レポート（エラー、警告、修正提案を含む）

---

フェーズ 5：段階的な変更（任意）

用途：ノードの追加／削除／変更

処理手順：

1. 変更の意図を把握する

Use AI to analyze user request, extract:
{
  "action": "add" | "delete" | "modify" | "reconnect",
  "targetNodes": ["aiChatNode"],
  "insertBefore": "aiChatNode",
  "newNodes": [{ "type": "datasetSearchNode", "name": "Knowledge Base Search" }],
  "modifications": {
    "aiChatNode": {
      "inputs": { "quoteQA": ["knowledgeBaseSearch", "searchResult"] }
    }
  }
}

2. 変更を実行する

- Add node: generate new node, reconnect, calculate position
- Delete node: remove node, bypass reconnect, clean references
- Modify node: update inputs/outputs, validate references

3. レイアウトを再調整して検証する

---

例

例 1：シンプルな AI 質疑応答ワークフロー

ユーザーの依頼：

"Create a simple AI Q&A workflow where users input questions and AI responds directly"

スキルの処理：

1. 要件分析

   {
     "purpose": "AI question answering",
     "domain": "general",
     "complexity": "simple",
     "features": ["aiChat"],
     "inputs": ["userChatInput"],
     "outputs": ["AI response"]
   }
   

2. テンプレートマッチング

   • 文档翻译助手.json - スコア：0.85（シンプルなワークフロー、直接処理）

3. JSON の生成

   • テンプレートを使用し、systemPrompt と welcomeText を変更

4. 検証結果

   • ✅ 3 つのレベルすべてで検証に合格

生成された JSON（主要部分）：

{
  "nodes": [
    {
      "nodeId": "userGuide",
      "name": "System Configuration",
      "flowNodeType": "userGuide",
      "position": {"x": -600, "y": -250}
    },
    {
      "nodeId": "workflowStart",
      "name": "Start",
      "flowNodeType": "workflowStart",
      "position": {"x": -150, "y": 100},
      "outputs": [
        {"key": "userChatInput", "type": "static", "valueType": "string"}
      ]
    },
    {
      "nodeId": "aiChatNode",
      "name": "AI Response",
      "flowNodeType": "chatNode",
      "position": {"x": 200, "y": 100},
      "inputs": [
        {
          "key": "model",
          "valueType": "string",
          "value": "gpt-4"
        },
        {
          "key": "systemPrompt",
          "valueType": "string",
          "value": "You are a professional AI assistant that can answer various questions. Please provide accurate and helpful answers based on user questions."
        },
        {
          "key": "userChatInput",
          "valueType": "string",
          "value": ["workflowStart", "userChatInput"]
        }
      ],
      "outputs": [
        {"key": "answerText", "type": "static", "valueType": "string"}
      ]
    },
    {
      "nodeId": "outputNode",
      "name": "Output Answer",
      "flowNodeType": "answerNode",
      "position": {"x": 550, "y": 100},
      "inputs": [
        {
          "key": "text",
          "valueType": "string",
          "value": ["aiChatNode", "answerText"]
        }
      ]
    }
  ],
  "edges": [
    {
      "source": "workflowStart",
      "target": "aiChatNode",
      "sourceHandle": "workflowStart-source-right",
      "targetHandle": "aiChatNode-target-left"
    },
    {
      "source": "aiChatNode",
      "target": "outputNode",
      "sourceHandle": "aiChatNode-source-right",
      "targetHandle": "outputNode-target-left"
    }
  ],
  "chatConfig": {
    "welcomeText": "Welcome to the AI Q&A assistant! Please enter your question.",
    "variables": []
  }
}

---

例 2：ドキュメント翻訳ワークフロー（テンプレートに基づく）

ユーザーリクエスト：

"Create a document translation workflow that translates user-uploaded documents from Chinese to English"

スキルによる処理：

1. 要件分析

   {
     "purpose": "Document translation",
     "domain": "document",
     "complexity": "medium",
     "features": ["readFiles", "aiChat", "textOutput"],
     "inputs": ["userFiles"],
     "outputs": ["translated document"]
   }
   

2. テンプレートの照合

   • 文档翻译助手.json - スコア：0.95（完全に一致！）

3. JSON の生成

   • テンプレートをそのまま使用し、プロンプトの言語の方向だけを調整します

生成されたワークフロー構造：

workflowStart → readFiles → translateNode → outputNode

主要なノード設定：

• readFiles ノード：ユーザーがアップロードしたファイルを読み込みます
• translateNode（chatNode）：専用のプロンプトを使用して AI が翻訳します
• outputNode（answerNode）：翻訳されたテキストを出力します

---

例 3：段階的な変更（ナレッジベースの追加）

ユーザーリクエスト：

"I have an existing AI Q&A workflow (simple_qa_workflow.json),
I want to search the knowledge base first before AI answers,
find relevant information then generate response"

既存のワークフロー構造：

workflowStart → aiChatNode → outputNode

変更の目標：

workflowStart → knowledgeBaseSearch → aiChatNode → outputNode

スキルによる処理：

1. 変更の意図を分析

   {
     "action": "add",
     "targetNodes": ["aiChatNode"],
     "insertBefore": "aiChatNode",
     "newNodes": [
       {
         "type": "datasetSearchNode",
         "name": "Knowledge Base Search"
       }
     ],
     "modifications": {
       "aiChatNode": {
         "inputs": {
           "quoteQA": ["knowledgeBaseSearch", "searchResult"]
         }
       }
     }
   }
   

2. 変更を実行

   • knowledgeBaseSearch ノードを追加
   • エッジを変更：workflowStart → knowledgeBaseSearch
   • エッジを追加：knowledgeBaseSearch → aiChatNode
   • aiChatNode の入力を変更（quoteQA を追加）

3. 位置を再配置

   • workflowStart：(-150, 100)
   • knowledgeBaseSearch： (50, 100) ← 新しく挿入
   • aiChatNode： (400, 100) ← 右に移動
   • outputNode： (750, 100) ← 右に移動

4. 検証結果

   • ✅ すべての検証に合格

変更後の JSON（新規および変更された部分）：

{
  "nodes": [
    {
      "nodeId": "knowledgeBaseSearch",
      "name": "Knowledge Base Search",
      "flowNodeType": "datasetSearchNode",
      "position": {"x": 50, "y": 100},
      "inputs": [
        {
          "key": "datasetIds",
          "valueType": "selectDataset",
          "value": [],
          "required": true
        },
        {
          "key": "searchQuery",
          "valueType": "string",
          "value": ["workflowStart", "userChatInput"],
          "required": true
        },
        {
          "key": "similarity",
          "valueType": "number",
          "value": 0.5
        },
        {
          "key": "limitCount",
          "valueType": "number",
          "value": 5
        }
      ],
      "outputs": [
        {
          "key": "searchResult",
          "type": "static",
          "valueType": "datasetQuote"
        }
      ]
    },
    {
      "nodeId": "aiChatNode",
      "inputs": [
        {
          "key": "quoteQA",
          "valueType": "datasetQuote",
          "value": ["knowledgeBaseSearch", "searchResult"]
        }
      ]
    }
  ],
  "edges": [
    {
      "source": "workflowStart",
      "target": "knowledgeBaseSearch"
    },
    {
      "source": "knowledgeBaseSearch",
      "target": "aiChatNode"
    },
    {
      "source": "aiChatNode",
      "target": "outputNode"
    }
  ]
}

変更の概要レポート：

• ✅ ノードを 1 つ追加：knowledgeBaseSearch（datasetSearchNode）
• ✅ ノードを 1 つ変更：aiChatNode（quoteQA 入力を追加）
• ✅ エッジを 1 つ追加：knowledgeBaseSearch → aiChatNode
• ✅ エッジを 1 つ変更：workflowStart → knowledgeBaseSearch（元は workflowStart → aiChatNode）
• ✅ すべての位置を再配置

---

技術的な実装

NodeId 生成アルゴリズム

ルール：

1. 固定 ID：workflowStart、userGuide（systemConfig）
2. 意味に基づく命名：ノード名に基づいて生成します（スペースと中国語を削除し、キャメルケースに変換）
3. 一意性の確保：競合する場合は、_1、_2 の接尾辞を追加します

例：

• generateNodeId('chatNode', 'Travel Planning Assistant') → TravelPlanningAssistantNode
• generateNodeId('httpRequest468', 'Weather Query') → WeatherQueryNode
• generateNodeId('chatNode', 'Assistant', {TravelPlanningAssistantNode}) → AssistantNode_1

位置の自動レイアウトアルゴリズム

アルゴリズム：階層レイアウト

手順：

1. トポロジカルソートを行い、階層を決定します（BFS）
2. 各階層の水平位置と垂直方向の間隔を計算します
3. 特殊ノードの位置を固定します（userGuide：{x: -600, y: -250}）

パラメーター：

• LAYER_GAP_X = 350（階層間の水平間隔）
• NODE_GAP_Y = 150（同一階層内の垂直間隔）
• START_X = -200, START_Y = 0

参照形式の説明

2 種類の参照形式：

1. 配列形式（値を直接参照）：

"value": ["workflowStart", "userChatInput"]

2. テンプレート構文（文字列の連結）：

"value": "Please create a plan for me.\n\nDestination: {{$workflowStart.userChatInput$}}\n\nWeather: {{$weatherQueryNode.httpRawResponse$}}"

重要：テンプレート構文は {{$nodeId.key$}} です（二重波括弧と単一の $）

特殊ノードの処理

loop ノード：

• childrenNodeIdList フィールドが必須です
• 子ノードには parentNodeId フィールドが必要です
• 子ノードには loopStart、[処理ノード...]、loopEnd が含まれます

ifElse ノード：

• 複数の出力分岐があります
• 各分岐は異なる条件に対応します

---

ベストプラクティス

推奨事項（ベストプラクティス）

• ✅ 常に3つのレベルで検証する - 形式、接続、ロジックを検証します
• ✅ 意味のある nodeId を使用する - 意味が分かる名前を使用します（例：weatherQueryNode）
• ✅ テンプレートマッチングを優先する - テンプレートベースの生成は、一から作成するよりも信頼性が高くなります
• ✅ 直接値には配列形式の参照を使用する - ["nodeId", "key"]
• ✅ 文字列の連結にはテンプレート形式の参照を使用する - {{$nodeId.key$}}
• ✅ 位置を自動レイアウトする - 自動レイアウトアルゴリズムを使用します
• ✅ システム設定ノードを含める - 必ず userGuide を含めます
• ✅ 検証してテストする - FastGPT にインポートする前に、組み込みの検証機能を使用します
• ✅ 分かりやすいエラーメッセージを表示する - 発生箇所と修正方法の提案を含めます
• ✅ 変更内容を記録する - 変更概要レポートを生成します

禁止事項

• ❌ 検証を省略しない - 検証を省略してはいけません
• ❌ 無効なノードタイプを使用しない - flowNodeType が有効か確認します
• ❌ ループノードなしで循環参照を作成しない - 不正な循環を作成してはいけません
• ❌ 必須フィールドを忘れない - nodeId、name、flowNodeType、position、inputs、outputs
• ❌ 誤った参照形式を使用しない - 禁止：{{nodeId.key}}（$ がありません）
• ❌ 警告を無視しない - 警告は修正してください
• ❌ 位置を固定値にしない - userGuide を除き、自動レイアウトを使用します
• ❌ 到達不能なノードを作成しない - workflowStart から到達可能であることを確認します
• ❌ 複雑すぎるワークフローを生成しない - 20 個を超えるノードを含むワークフローは分割してください

---

トラブルシューティング

FAQ

Q1：FastGPT へのインポート時に「Invalid node type」と表示されます

A：flowNodeType フィールドを確認し、サポートされているタイプを使用してください。references/node_types_reference.md を参照してください。よくあるエラー：

• 正しくは chatNode です（aiChat ではありません）
• 数字のサフィックス（httpRequest468 など）はそのまま残してください

Q2：ノード間の参照が機能しません

A：参照形式を確認してください：

• ✅ 正しい形式：["workflowStart", "userChatInput"] または {{$workflowStart.userChatInput$}}
• ❌ 誤った形式：{$workflowStart.userChatInput$}（波括弧が1組です。2組にする必要があります）

Q3：実行時に一部のノードが実行されません

A：組み込みの検証機能でレベル 3 を確認し、すべてのノードが workflowStart から到達可能であることを確認してください

Q4：並列ノードが並列に実行されません

A：複数のノードの接続先が同じ集約ノードであること、およびこれらのノードに依存関係がないことを確認してください

Q5：ループワークフローでエラーが発生します

A：flowNodeType: "loop" のノードを使用し、parentNodeId と childrenNodeIdList を設定する必要があります

デバッグチェックリスト

## Phase 1: JSON Format Check
- [ ] JSON is parseable
- [ ] Contains nodes, edges, chatConfig
- [ ] All strings use double quotes
- [ ] No trailing commas

## Phase 2: Node Check
- [ ] workflowStart node exists
- [ ] At least one output node exists
- [ ] All flowNodeType valid
- [ ] All nodeId unique
- [ ] All position contains x, y

## Phase 3: Connection Check
- [ ] All edges' source and target exist
- [ ] All handle format correct
- [ ] No duplicate edges, no self-loops

## Phase 4: Reference Check
- [ ] All array references' nodes and keys exist
- [ ] All template references' nodes and keys exist
- [ ] Reference types match

## Phase 5: Logic Check
- [ ] All nodes reachable from workflowStart
- [ ] No illegal cycles
- [ ] No dead-end nodes
- [ ] All required inputs have values

## Phase 6: Runtime Test
- [ ] Import to FastGPT without errors
- [ ] Configure necessary parameters
- [ ] Run test cases
- [ ] Check output meets expectations

---

クイックリファレンス

組み込みテンプレートファイル

• templates/文档翻译助手.json - シンプルなワークフロー、ドキュメント処理
• templates/销售陪练大师.json - 中程度の複雑さ、対話型 AI
• templates/简历筛选助手_飞书.json - 複雑なワークフロー、データと外部連携
• templates/AI金融日报.json - スケジュールトリガー、マルチエージェント

詳細ドキュメント

• references/node_types_reference.md - 40 種類以上のノードタイプの完全なリファレンス
• references/validation_rules.md - 3 層の検証ルールの詳細
• references/template_matching.md - テンプレートマッチングアルゴリズム
• references/json_structure_spec.md - FastGPT JSON 構造の完全な仕様

サンプルドキュメント

• examples/example1_simple_qa.md - 完全なサンプル：シンプルな Q&A ワークフロー
• examples/example2_travel_planning.md - 完全なサンプル：旅行計画ワークフロー
• examples/example3_incremental_modify.md - 完全なサンプル：段階的な変更

よく使うコマンド

# Validate workflow JSON
node scripts/validate_workflow.js path/to/workflow.json

# Copy template
cp templates/文档翻译助手.json my_workflow.json

# View template list
ls -lh templates/

---

バージョン：1.0 最終更新日：2025-01-02 互換性：FastGPT v4.8+