概述

n8n（发音为 "n-eight-n"）是一个强大的开源工作流自动化平台，采用 MIT 许可证发布。它允许用户通过可视化界面或代码方式连接各种应用程序、服务和 API，构建自动化工作流程。n8n 的核心理念是让技术用户和非技术人员都能轻松实现业务流程自动化，无需编写大量胶水代码。

该平台的核心优势包括：

• 可视化工作流编辑器：直观的拖拽式界面，支持实时预览工作流执行
• 丰富的节点生态系统：内置 400+ 预构建节点，覆盖主流 SaaS 服务和协议
• 灵活的代码执行：支持 JavaScript 和 Python 编写自定义逻辑
• AI 集成能力：内置 AI 工作流构建器，支持多代理系统和 LLM 调用
• 自托管部署：完全自主掌控数据和基础设施

资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md:1-15

架构设计

核心模块结构

n8n 采用 monorepo 架构组织代码，主要包含以下核心模块：

工作流执行架构

graph TD
    A[用户触发/定时器] --> B[工作流引擎]
    B --> C{节点类型判断}
    C -->|普通节点| D[节点执行器]
    C -->|代码节点| E[代码沙箱]
    C -->|AI 节点| F[AI 代理系统]
    D --> G[数据转换]
    E --> G
    F --> G
    G --> H[输出传递到下一节点]
    H --> C
    I{还有更多节点?} -->|是| D
    I -->|否| J[工作流完成]

节点执行模型

n8n 的节点是工作流的基本构建单元，每个节点负责特定的数据处理或集成任务。

graph LR
    A[输入数据] --> B[节点处理器]
    B --> C[数据转换]
    C --> D[执行操作]
    D --> E[输出数据]
    
    F[错误处理] -->|发生错误| G[错误工作流]
    G --> H[重试机制]
    H -->|重试成功| D
    H -->|重试耗尽| I[标记失败]

资料来源：packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts:1-50

节点系统

节点分类

n8n 中的节点按功能可分为以下几类：

节点匹配模式

n8n 使用模式匹配来识别和处理不同类型的节点：

// 节点匹配示例
const patterns = {
    set: 'n8n-nodes-base.set',      // Set 节点
    if: 'n8n-nodes-base.if',        // IF 条件节点
    switch: 'n8n-nodes-base.switch', // Switch 路由节点
    httpRequest: 'n8n-nodes-base.httpRequest' // HTTP 请求节点
};

资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md:80-95

代码节点

概述

代码节点允许用户在 n8n 工作流中执行自定义 JavaScript 或 Python 代码。这是实现复杂业务逻辑的关键功能。

输入数据访问

代码节点提供多种方式访问输入数据：

代码补全支持

n8n 的代码编辑器提供智能代码补全功能：

// JavaScript 模式
const prefix = '$';
// Python 模式
const prefix = '_';

// 支持的补全选项
const options = [
    { label: `${matcher}.json`, info: 'JSON 数据访问' },
    { label: `${matcher}.binary`, info: '二进制数据访问' }
];

资料来源：packages/frontend/editor-ui/src/features/shared/editors/components/CodeNodeEditor/completions/itemField.completions.ts:1-60

AI 工作流构建器

概述

n8n 的 AI 工作流构建器（AI Workflow Builder）是一个高级功能，允许用户通过自然语言描述创建和修改工作流。该系统采用多代理架构，协同完成从用户意图到可执行工作流的转换。

代理系统架构

graph TD
    A[用户自然语言请求] --> B[Supervisor 代理]
    B --> C[Discovery 代理]
    B --> D[Builder 代理]
    B --> E[Responder 代理]
    C -->|识别节点| C1[节点分类]
    C --> C2[技术识别]
    D --> D1[结构创建]
    D --> D2[参数配置]
    E --> F[用户响应]

资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md:40-55

PromptBuilder 工具

PromptBuilder 是一个类型安全的流式构建器，用于组合 LLM 提示词：

const systemPrompt = prompt()
    .section('role', 'You are an assistant')
    .sectionIf(hasContext, 'context', () => buildContext())
    .examples('examples', data, (ex) => `${ex.input} → ${ex.output}`)
    .build();

#### 核心特性

#### 构建流程

graph LR
    A[Section 定义] --> B[内容解析]
    B --> C{内容为空?}
    C -->|是| D[跳过该部分]
    C -->|否| E[格式化输出]
    E --> F[使用指定格式]
    F --> G[合并分隔符]
    G --> H[最终提示词]

#### 主要方法

class PromptBuilder {
    section(name: string, content: string | FactoryFn): this
    sectionIf(condition: boolean, name: string, content: FactoryFn): this
    examples(name: string, items: unknown[], renderer: RendererFn): this
    examplesIf(condition: boolean, name: string, items: unknown[], renderer: RendererFn): this
    merge(other: PromptBuilder): this
    build(): string
    buildAsMessageBlocks(): BaseMessage[]
}

资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts:1-100

Web 抓取工具

n8n 提供 Web 抓取功能作为 AI 代理的可调用工具：

interface WebFetchConfig {
    url: string;
    options?: {
        extractImages?: boolean;
        descriptionLength?: number;
    };
}

// 返回格式
interface WebFetchResult {
    url: string;
    finalUrl?: string;
    title: string;
    content: string;
    truncated: boolean;
    truncateReason?: string;
}

#### 抓取结果结构

<web_fetch_result>
    <url>原始 URL</url>
    <final_url>重定向后 URL</final_url>
    <title>页面标题</title>
    <note>截断说明（如果被截断）</note>
    <content>
        提取的页面内容
    </content>
</web_fetch_result>

资料来源：packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts:1-80

用户界面

设计系统

n8n 使用统一的设计系统（Design System）确保界面一致性：

// 徽章组件示例
<N8nBadge theme="success">Completed</N8nBadge>
<N8nBadge theme="warning">Pending</N8nBadge>
<N8nBadge theme="danger">Failed</N8nBadge>

#### 主题类型

国际化

n8n 支持多语言界面，主要文本资源存储在本地化文件中：

// 英文本地化示例
'codeNodeEditor.completer.json': 'JSON 数据访问',
'codeNodeEditor.completer.binary': '二进制数据访问',
'sticky.markdownHint': 'You can style with Markdown',
'askAssistantButton.askAssistant': 'n8n AI',

#### AI Builder 界面文本

资料来源：packages/frontend/@n8n/design-system/src/locale/lang/en.ts:1-50

安全性

SSO/SAML 认证

n8n 企业版支持 SAML 2.0 单点登录，集成了 WS-SecurityPolicy 1.2 标准：

#### 支持的安全策略

#### X.509 令牌支持

n8n 支持多种 X.509 证书格式：

#### 信任配置

<!-- Trust13 断言配置 -->
<xs:element name="Trust13" type="tns:NestedPolicyType">
    <xs:annotation>
        <xs:documentation>10.1 Trust13 Assertion</xs:documentation>
    </xs:annotation>
</xs:element>

支持的可选配置：

• MustSupportClientChallenge：客户端挑战
• MustSupportServerChallenge：服务端挑战
• RequireClientEntropy：客户端熵
• RequireServerEntropy：服务端熵
• MustSupportIssuedTokens：支持颁发令牌

#### 算法套件

支持多种加密算法套件：

#### 引用类型

支持多种密钥引用方式：

资料来源：packages/cli/src/modules/sso-saml/schema/ws-securitypolicy-1.2.xsd.ts:1-200

部署方式

部署模式

n8n 支持多种部署方式：

环境配置

关键环境变量：

总结

n8n 是一个功能全面的开源工作流自动化平台，通过其模块化架构和丰富的节点生态系统，能够满足从简单任务自动化到复杂 AI 工作流的各种需求。平台的 AI 工作流构建器代表了工作流自动化领域的创新方向，让非技术用户也能通过自然语言描述创建自动化流程。同时，完善的 SSO/SAML 支持确保了企业级部署的安全性要求。

概述

n8n 是一个强大的工作流自动化平台，支持通过可视化界面或代码方式构建自动化流程。本快速入门指南旨在帮助开发者快速上手 n8n 平台的核心功能，包括 AI 工作流构建器、聊天中心（Chat Hub）服务、Web 获取工具以及 UI 组件系统的使用方法。

本指南涵盖的范围包括：

• AI 工作流构建器：用于构建 AI 驱动的自动化工作流
• 聊天中心服务：提供对话式 AI 交互能力
• Web 获取工具：从外部 URL 抓取内容并整合到工作流中
• 设计系统组件：提供统一的 UI 组件库

概述

n8n 是一个开源的工作流自动化平台，其核心架构围绕模块化设计构建。系统架构概览旨在帮助开发者理解 n8n 平台的关键组件、它们之间的交互关系以及扩展机制。

从源码层面分析，n8n 的架构涵盖以下几个核心领域：

核心组件架构

PromptBuilder 提示词构建器

PromptBuilder 是 n8n AI 工作流构建器中的核心工具类，提供类型安全的链式 API 用于组合 LLM 提示词。

classDiagram
    class PromptBuilder {
        -sections: SectionEntry[]
        -format: SectionFormat
        -separator: string
        +section(name, content, options): this
        +sectionIf(condition, name, content, options): this
        +examples(name, data, formatter): this
        +merge(other: PromptBuilder): this
        +build(): string
    }
    
    class SectionEntry {
        +name: string
        +content: ContentOrFactory
        +options: SectionOptions
    }
    
    PromptBuilder *-- SectionEntry

主要特性：

• 链式 API：支持方法链式调用，便于阅读的提示词组合方式
• 条件节：通过 sectionIf() 实现动态内容包含
• 延迟求值：工厂函数仅在构建时调用
• 多格式输出：支持 XML 标签（默认）和 Markdown 标题两种格式

资料来源：prompt-builder.ts

SectionEntry 数据结构

interface SectionEntry {
    name: string;
    content: ContentOrFactory;
    options: SectionOptions;
}

type ContentOrFactory = string | (() => string | null);

每个节（Section）包含以下属性：

资料来源：prompt-builder.ts:44-49

WebFetchTool 网页抓取工具

WebFetchTool 是 n8n AI 工作流中的网页内容抓取与提取工具，负责从 URL 获取网页内容并进行可读性处理。

flowchart TD
    A[输入 URL] --> B[验证 URL 格式]
    B --> C{验证是否通过}
    C -->|通过| D[发起 HTTP 请求]
    C -->|失败| E[返回验证错误]
    D --> F[提取可读内容]
    F --> G[构建响应结果]
    G --> H[记录安全状态]
    H --> I[返回结构化数据]

处理流程：

1. 接收并验证 URL 输入
2. 执行 HTTP 请求获取网页内容
3. 提取标题和正文内容
4. 构建结构化的 XML 格式响应
5. 记录安全相关状态更新

const responseLines = [
    '<web_fetch_result>',
    `<url>${url}</url>`,
    `<title>${extracted.title}</title>`,
    '<content>',
    extracted.content,
    '</content>',
    '</web_fetch_result>',
]

资料来源：web-fetch.tool.ts

安全策略模块

WS-SecurityPolicy 1.2 XSD 架构

n8n 的 SSO-SAML 模块包含完整的 WS-SecurityPolicy 1.2 XSD Schema 定义，用于配置 Web 服务安全策略。

主要策略类型：

核心安全断言：

• AlgorithmSuite Assertion (7.1)：定义加密算法套件，支持 Basic256、Basic192、Basic128、TripleDes 等
• Layout Assertion (7.2)：定义消息布局规则，包括 Strict、Lax、LaxTsFirst、LaxTsLast
• TransportBinding (7.3)：传输层绑定配置
• SymmetricBinding (7.4)：对称密钥绑定
• Trust13 Assertion (10.1)：WS-Trust 1.3 规范支持

<xs:element name="AlgorithmSuite" type="tns:QNameAssertionType">
    <xs:annotation>
        <xs:documentation xml:lang="en">
            7.1 AlgorithmSuite Assertion
        </xs:documentation>
    </xs:annotation>
</xs:element>

资料来源：ws-securitypolicy-1.2.xsd.ts

设计系统架构

Badge 组件

n8n 设计系统提供了统一的 Badge 组件，用于在工作流界面中展示状态信息。

interface FileStatus {
    status: 'completed' | 'pending' | 'failed'
}

const getStatusTheme = (status: string): BadgeTheme => {
    const themeMap: Record<string, BadgeTheme> = {
        completed: 'success',
        pending: 'warning',
        failed: 'danger',
    }
    return themeMap[status] || 'default'
}

主题映射：

组件使用示例：

<N8nBadge v-if="isReadOnly" theme="tertiary" :bold="true">
    Read Only
</N8nBadge>

<N8nBadge v-if="needsSetup" theme="warning">
    Setup Required
</N8nBadge>

资料来源：component-badge.md

国际化配置

n8n 设计系统支持多语言配置，主要通过 en.ts 文件定义英文翻译键值对。

'codeDiff.couldNotReplace': 'Could not replace code',
'codeDiff.codeReplaced': 'Code replaced',
'codeDiff.replaceMyCode': 'Replace my code',
'codeDiff.replacing': 'Replacing...',
'codeDiff.undo': 'Undo',

AI Builder 相关翻译：

'assistantChat.builder.name': 'AI Builder',
'assistantChat.builder.generatingFinalWorkflow': 'Generating final workflow...',
'assistantChat.builder.configuredNodes': 'Configured nodes',
'assistantChat.builder.thumbsUp': 'Helpful',
'assistantChat.builder.thumbsDown': 'Not helpful',

资料来源：en.ts

指南系统架构

节点类型指南

AI Workflow Builder 提供了可扩展的节点指南系统，支持按节点类型和条件动态匹配指南内容。

export const MY_NODE_GUIDE: NodeTypeGuide = {
    patterns: ['n8n-nodes-base.myNode'],  // 匹配的节点类型
    condition: (ctx) => true,              // 可选：额外条件
    content: `Your guide content here...`,
};

当前指南覆盖：

条件指南示例：

export const RESOURCE_LOCATOR_GUIDE: NodeTypeGuide = {
    patterns: ['*'],  // 匹配所有节点
    condition: (ctx) => ctx.hasResourceLocatorParams === true,
    content: `...`,
};

资料来源：README.md

模块交互关系

graph TD
    A[User Input] --> B[AI Workflow Builder]
    B --> C[PromptBuilder]
    C --> D{Section Type}
    D -->|Conditional| E[sectionIf]
    D -->|Examples| F[examples]
    D -->|Static| G[section]
    E --> H[buildAsMessageBlocks]
    G --> H
    F --> H
    H --> I[LLM Response]
    I --> J[Execute Nodes]
    J --> K[WebFetchTool]
    K --> L[Extract Content]
    L --> J
    J --> M[Return Result]
    
    N[Design System] --> O[Badge Component]
    N --> P[i18n Strings]
    O --> Q[UI Render]
    P --> Q

配置选项

PromptBuilder 配置

SectionOptions 配置

最佳实践

提示词构建规范

1. 使用条件节：对于可能缺失的内容使用 sectionIf() 避免空值问题
2. 延迟求值：复杂内容使用工厂函数而非直接字符串
3. 格式一致性：在同一项目中保持统一的输出格式
4. 示例驱动：使用 examples() 方法提供少样本学习示例

指南扩展规范

1. 在 guides/ 目录创建新的指南文件
2. 从 guides/index.ts 导出新指南
3. 将指南添加到 registry.ts 的注册数组中
4. 使用条件匹配实现上下文相关的指南内容

总结

n8n 的系统架构体现了现代工作流自动化平台的设计理念：

• 模块化设计：各功能模块解耦，便于独立维护和扩展
• 类型安全：TypeScript 优先，确保编译期错误检测
• 可扩展性：通过指南系统和提示词模板支持自定义行为
• 国际化：完整的 i18n 支持，便于多语言适配

这些架构特性使得 n8n 能够同时支持传统工作流和 AI 增强工作流的开发需求。

概述

n8n 是一个开源的工作流自动化平台，采用 Monorepo（单体仓库） 架构组织代码。项目使用 pnpm 作为包管理器，通过 pnpm-workspace.yaml 定义工作区配置。整体架构划分为多个功能明确的子包（packages），涵盖工作流核心、CLI 工具、UI 组件、AI 构建器、数据库层和测试基础设施等模块。

核心包结构

n8n 的包结构遵循 功能分离 原则，每个包都有明确的职责边界和对外 API 接口。

模块层次架构

n8n 采用 分层架构 设计，从底层到上层依次为：

graph TD
    A["packages/@n8n/db<br/>数据库抽象层"] --> B["packages/@n8n/workflow-sdk<br/>工作流核心"]
    B --> C["packages/@n8n/agents<br/>AI Agent 层"]
    C --> D["packages/@n8n/ai-workflow-builder.ee<br/>AI 工作流构建器"]
    B --> E["packages/cli<br/>CLI 与服务层"]
    E --> F["packages/frontend/editor-ui<br/>前端编辑器"]
    F --> G["packages/frontend/@n8n/design-system<br/>设计系统"]

工作流核心 SDK

packages/@n8n/workflow-sdk 是整个平台的核心，封装了工作流执行的全部基础能力。

核心职责

• 定义节点（Node）和凭证（Credentials）接口
• 实现工作流执行引擎
• 提供表达式解析和求值
• 管理连接和数据流转

包导出模式

SDK 包使用 barrel export 模式统一对外暴露 API，通过 src/index.ts 作为唯一入口点：

// 资料来源：packages/@n8n/workflow-sdk/src/index.ts
export * from './nodes';
export * from './credentials';
export * from './workflow';
export * from './expression';

AI 工作流构建器架构

packages/@n8n/ai-workflow-builder.ee 是企业级 AI 辅助工作流构建模块，包含完整的提示词工程和 Agent 协作系统。

多 Agent 协作体系

AI 工作流构建器采用 多 Agent 路由架构，每个 Agent 都有明确的职责分工：

资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md

提示词构建器（PromptBuilder）

核心模块使用 PromptBuilder 工具类实现提示词的组合式构建：

// 资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts
const systemPrompt = prompt()
  .section('role', 'You are an assistant')
  .sectionIf(hasContext, 'context', () => buildContext())
  .examples('examples', data, (ex) => `${ex.input} → ${ex.output}`)
  .build();

#### PromptBuilder 关键特性

提示词模板结构

代码构建器提示词由多个标准节组成：

graph LR
    A["<role>"] --> B["<response_style>"]
    B --> C["<workflow_rules>"]
    C --> D["<workflow_patterns>"]
    D --> E["<expression_reference>"]
    E --> F["<mandatory_workflow_process>"]
    F --> G["<user_request>"]

资料来源：packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts

CLI 工具与节点开发

节点脚手架工具

packages/@n8n/node-cli 提供节点开发的标准化工具体系：

# 创建新节点
npm create @n8n/node my-awesome-node
cd my-awesome-node

# 启动开发模式
npm run dev

资料来源：packages/@n8n/node-cli/README.md

节点项目结构规范

n8n 要求节点项目遵循统一的目录结构：

my-node/
├── src/
│   ├── nodes/
│   │   └── MyNode/
│   │       ├── MyNode.node.ts      # 节点主实现
│   │       └── MyNode.node.json    # 节点元数据
│   └── credentials/
│       └── MyNodeAuth.credentials.ts
├── package.json
└── tsconfig.json

资料来源：packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md

package.json 配置约定

节点包必须在 package.json 中声明 n8n 字段：

{
  "name": "n8n-nodes-example",
  "version": "1.0.0",
  "n8n": {
    "n8nNodesApiVersion": 1,
    "nodes": ["dist/nodes/MyNode/MyNode.node.js"],
    "credentials": ["dist/credentials/MyNodeAuth.credentials.js"]
  }
}

前端组件体系

设计系统

packages/frontend/@n8n/design-system 封装了 n8n 的统一视觉语言：

# 开发预览
pnpm storybook

# 构建静态页面
pnpm build:storybook

# 构建 CSS 主题
pnpm build:theme

# 监听并自动构建
pnpm watch:theme

资料来源：packages/frontend/@n8n/design-system/README.md

编辑器组件测试

编辑器使用 Vue 3 + Composition API 开发，测试采用 Vue Test Utils：

// 资料来源：packages/frontend/editor-ui/src/app/components/MainHeader/MainHeader.test.ts
describe('MainHeader', () => {
  beforeEach(() => {
    workflowsStore = mockedStore(useWorkflowsStore);
    workflowDocumentStore.hydrate({
      id: '1',
      name: 'Test Workflow',
      active: false,
      // ...
    });
  });
});

测试基础设施

Playwright Janitor

packages/testing/janitor 是端到端测试编排工具，支持分片并行执行：

# 分 14 片执行
playwright-janitor orchestrate --shards=14

# 仅执行受 Git 变更影响的测试
playwright-janitor orchestrate --shards=14 --impact

资料来源：packages/testing/janitor/README.md

架构规则

测试框架定义了严格的架构规则：

页面对象隔离原则

// 资料来源：packages/testing/janitor/README.md

// 不推荐 - 页面间耦合
export class WorkflowPage {
  async openSettings() {
    await this.settingsPage.open();
  }
}

// 推荐 - 页面独立，组合在 flows 层
export class WorkflowPage {
  async getWorkflowName() {
    return this.header.getByTestId('workflow-name').textContent();
  }
}

数据库模块

packages/@n8n/db 提供数据库访问的统一抽象层，处理 ORM 配置、迁移管理和连接池等基础设施问题。

包导出模式

// 资料来源：packages/@n8n/db/src/index.ts
export * from './connection';
export * from './repositories';
export * from './migrations';

模块间依赖关系

graph TD
    CLI["packages/cli<br/>CLI 入口"]
    SDK["packages/@n8n/workflow-sdk<br/>工作流 SDK"]
    DB["packages/@n8n/db<br/>数据库层"]
    AGENTS["packages/@n8n/agents<br/>AI Agent"]
    AI_BUILDER["packages/@n8n/ai-workflow-builder.ee<br/>AI 构建器"]
    EDITOR["packages/frontend/editor-ui<br/>编辑器 UI"]
    DESIGN["packages/frontend/@n8n/design-system<br/>设计系统"]

    DB --> SDK
    SDK --> CLI
    SDK --> AGENTS
    AGENTS --> AI_BUILDER
    CLI --> EDITOR
    EDITOR --> DESIGN

命名规范与导出约定

Barrel Export 模式

所有包遵循统一的 Barrel Export 模式组织导出：

// src/index.ts - 包入口文件
export * from './core';           // 核心功能
export * from './types';          // 类型定义
export * from './constants';      // 常量
export { SpecificClass } from './internal/specific';  // 按需导出

命名空间约定

扩展机制

节点开发扩展

通过 n8n-nodes- 前缀注册自定义节点：

{
  "name": "n8n-nodes-my-service",
  "n8n": {
    "nodes": ["dist/nodes/MyNode/MyNode.node.js"]
  }
}

提示词指南扩展

AI 构建器支持通过模式匹配注入节点指南：

// 资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md
export const MY_NODE_GUIDE: NodeTypeGuide = {
  patterns: ['n8n-nodes-base.myNode'],
  condition: (ctx) => true,
  content: `指南内容...`,
};

总结

n8n 的包结构设计体现了以下核心原则：

1. 职责分离 - 每个包有明确边界，通过接口而非实现通信
2. 可扩展性 - 节点系统和 AI 构建器都支持插件式扩展
3. 层次清晰 - 依赖关系自底向上，CLI 和 UI 依赖核心 SDK
4. 统一规范 - Barrel Export、命名约定、文档结构保持一致
5. 测试完备 - 专门的测试基础设施支持 E2E 和单元测试

概述

工作流 SDK 与构建器（Workflow SDK and Builder）是 n8n 平台中用于通过 AI 能力自动生成、构建和优化工作流的综合技术栈。该系统由多个核心组件构成，包括提示构建器（PromptBuilder）、语义图（Semantic Graph）、代码生成器（Code Generator）以及多代理协调系统。这些组件协同工作，使开发者能够通过自然语言描述或结构化指令来自动生成复杂的工作流配置。

n8n 的工作流构建系统采用了分层的架构设计，将工作流的语义表示与实际的代码生成解耦。这种设计允许不同的生成策略（如基于规则的生成、基于 AI 的生成）共享同一套语义模型，从而保证了生成结果的一致性和可维护性。

核心架构

系统组件关系

graph TD
    A[用户输入] --> B[多代理协调器]
    B --> C[发现代理 Discovery]
    B --> D[构建代理 Builder]
    B --> E[响应代理 Responder]
    C --> F[节点分类系统]
    D --> G[PromptBuilder]
    G --> H[ChatPromptTemplate]
    H --> I[LLM 服务]
    I --> J[代码生成]
    J --> K[Semantic Graph]
    K --> L[Code Generator]
    L --> M[Workflow JSON]

组件职责矩阵

提示构建器（PromptBuilder）

设计理念

PromptBuilder 是一个类型安全的、流畅式（Fluent）API，用于组合 LLM 提示。该类支持条件化内容块、延迟求值、多种输出格式以及与 LangChain 的深度集成。资料来源：prompt-builder.ts:1-100

PromptBuilder 的核心设计原则包括：

1. 可组合性：通过 merge() 方法可以合并多个 PromptBuilder 实例
2. 延迟求值：工厂函数仅在构建时求值，避免不必要的计算
3. 条件渲染：通过 sectionIf() 和 examplesIf() 支持条件化内容
4. 格式灵活性：支持 XML 标签格式和 Markdown 格式

核心方法

class PromptBuilder {
  // 添加始终包含的段落
  section(name: string, content: ContentOrFactory, options?: SectionOptions): this;
  
  // 条件性添加段落
  sectionIf(condition: unknown, name: string, content: ContentOrFactory, options?: SectionOptions): this;
  
  // 添加示例段落
  examples(name: string, data: unknown[], formatter: ExampleFormatter): this;
  
  // 条件性添加示例
  examplesIf(condition: unknown, name: string, data: unknown[], formatter: ExampleFormatter): this;
  
  // 合并另一个 PromptBuilder
  merge(other: PromptBuilder): this;
  
  // 构建最终提示字符串
  build(): string;
  
  // 构建为 LangChain 消息块
  buildAsMessageBlocks(): BaseMessage[];
}

使用示例

const systemPrompt = prompt()
  .section('ROLE', 'You are an assistant')
  .sectionIf(hasContext, 'CONTEXT', () => buildContext())
  .examples('EXAMPLES', data, (ex) => `${ex.input} → ${ex.output}`)
  .build();

资料来源：prompt-builder.ts:100-150

输出格式

PromptBuilder 支持两种主要的输出格式，通过 SectionFormat 类型定义：

段落选项配置

interface SectionOptions {
  format?: SectionFormat;  // 覆盖默认格式
  tag?: string;            // 自定义标签名
}

代码构建器提示系统

系统提示构建流程

graph LR
    A[buildCodeBuilderPrompt] --> B[buildMandatoryWorkflow]
    B --> C[ROLE]
    B --> D[RESPONSE_STYLE]
    B --> E[WORKFLOW_RULES]
    B --> F[WORKFLOW_PATTERNS]
    C --> G[EXPRESSION_REFERENCE]
    D --> H[ADDITIONAL_FUNCTIONS]
    E --> I[ChatPromptTemplate]
    F --> J[系统消息]
    G --> J
    H --> J
    J --> K[cache_control配置]

代码构建器使用 buildCodeBuilderPrompt() 函数生成完整的系统提示，该函数整合了多个预定义的提示组件。资料来源：packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts

提示组件列表

用户消息构建

用户消息部分通过 buildUserMessageParts() 函数构建，包含以下可选组件：

1. 当前工作流上下文：当存在正在进行的工作流时提供
2. 历史上下文：多轮对话中的历史记录
3. 工作流文件状态：检查是否存在现有工作流代码
4. 已批准的计划输出：计划模式的结果
5. 预搜索结果：提前获取的搜索结果以节省 LLM 交互

function buildUserMessageParts(
  currentWorkflow?: WorkflowJSON,
  historyContext?: HistoryContext,
  options?: BuildCodeBuilderPromptOptions,
): string[]

资料来源：packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts

LangChain 集成

系统提示通过 ChatPromptTemplate.fromMessages() 包装，并配置了 cache_control 选项以支持 LLM 的上下文缓存：

return ChatPromptTemplate.fromMessages([
  ['system', [{ 
    type: 'text', 
    text: systemMessage, 
    cache_control: { type: 'ephemeral' } 
  }]],
  ['user', userMessageTemplate]
]);

多代理工作流系统

代理架构

n8n 采用多代理架构来协调复杂的工作流构建任务。代理目录包含针对不同专业领域的专门提示。资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md

链式提示系统

chains/ 目录包含用于特定 LLM 链操作的提示：

节点与参数指南系统

指南注册机制

n8n 提供了基于模式的节点指南系统，通过 NodeTypeGuide 接口定义：

interface NodeTypeGuide {
  patterns: string[];           // 匹配节点类型的模式
  condition?: (ctx: GuideContext) => boolean;  // 额外条件
  content: string;              // 指南内容
}

内置指南列表

资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/guides/README.md

添加新指南

1. 在 guides/ 目录创建新的指南文件
2. 从 guides/index.ts 导出
3. 在 registry.ts 的注册数组中添加

工具系统

Web 获取工具

WebFetchTool 提供了网页内容抓取能力，使用可读内容提取器处理 HTML 响应：

graph TD
    A[URL 输入] --> B[URL 验证]
    B --> C[安全检查]
    C --> D[HTTP 请求]
    D --> E[内容提取]
    E --> F[可读内容提取]
    F --> G[状态记录]
    G --> H[响应构建]
    H --> I[<web_fetch_result>]

工具响应格式

<web_fetch_result>
  <url>原始URL</url>
  <final_url>最终URL</final_url>
  <title>页面标题</title>
  <content>提取的内容</content>
  <note>截断说明（可选）</note>
</web_fetch_result>

资料来源：packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts

构建与生成流程

工作流生成流程

graph TD
    A[自然语言描述] --> B[Discovery 代理]
    B --> C[节点分类]
    C --> D[Builder 代理]
    D --> E[PromptBuilder 组装]
    E --> F[LLM 生成]
    F --> G[Semantic Graph]
    G --> H[Code Generator]
    H --> I[Workflow JSON]
    I --> J[执行验证]
    J --> K[工作流部署]

代码生成策略

工作流 SDK 支持多种代码生成策略：

1. 基于模板的生成：使用预定义模板填充参数
2. 基于 AI 的生成：通过 LLM 理解语义并生成
3. 混合生成：结合模板和 AI 能力

语义图管理

语义图（Semantic Graph）负责：

• 管理工作流节点和连接的语义表示
• 提供节点关系的查询接口
• 支持工作流的语义验证

类型系统

关键类型定义

type ContentOrFactory = string | (() => string | null);

type SectionFormat = 'xml' | 'markdown';

type ExampleFormatter = (item: unknown) => string;

interface SectionEntry {
  name: string;
  content: ContentOrFactory;
  options: SectionOptions;
}

interface SectionOptions {
  format?: SectionFormat;
  tag?: string;
}

interface PromptBuilderOptions {
  format?: SectionFormat;
  separator?: string;
}

配置与扩展

PromptBuilder 配置选项

段落格式配置

// 使用自定义分隔符
const prompt = new PromptBuilder({ separator: '\n---\n' });

// 使用 Markdown 格式
const prompt = new PromptBuilder({ format: 'markdown' });

// 自定义段落格式
prompt.section('custom', 'content', { 
  format: 'markdown',
  tag: 'CustomSection'
});

最佳实践

提示构建最佳实践

1. 保持简洁：每个段落应专注于单一概念
2. 使用条件化段落：避免不必要的空内容
3. 延迟求值：复杂计算使用工厂函数
4. 合理使用分隔符：清晰的段落分隔提高可读性

代码生成最佳实践

1. 语义优先：先生成语义图，再转换为代码
2. 验证语义：在生成前验证工作流语义的正确性
3. 版本控制：保持生成结果的可追溯性

总结

工作流 SDK 与构建器是 n8n 智能工作流生成系统的核心基础设施。通过 PromptBuilder 提供的类型安全、流畅式 API，开发者可以轻松构建复杂的 LLM 提示。多代理系统则协调各个专业代理完成从需求理解到工作流生成的完整流程。语义图和代码生成器将高层语义转换为可执行的工作流配置，确保了生成结果的质量和一致性。

该系统的设计体现了几个关键原则：可组合性（通过 merge 和 section 方法）、延迟求值（通过工厂函数）、条件化渲染（通过 sectionIf 方法）以及与 LangChain 的深度集成。这些设计使得工作流构建系统既灵活又高效，能够满足不同场景下的工作流生成需求。

概述

n8n 的工作流执行引擎是自动化工作流的运行时核心，负责协调节点的执行顺序、管理数据流转、处理表达式求值以及维护执行状态。该引擎支持手动执行和生产执行两种模式，能够在不同的触发条件下激活工作流实例。

工作流执行引擎的核心职责包括：

1. 节点调度：根据工作流定义的有向图结构，确定节点的执行顺序
2. 数据传递：在节点之间传递输入输出数据，处理二进制和 JSON 数据
3. 表达式求值：在运行时解析和计算表达式，支持变量引用和函数调用
4. 版本管理：支持工作流的草稿版本和生产版本区分
5. 错误处理：捕获节点执行异常，提供重试和错误恢复机制

核心架构

执行模式

n8n 工作流执行引擎支持两种主要执行模式：

生产模式执行时，系统会验证工作流是否已激活并具有活跃版本。若工作流没有已发布（active）的版本，执行将被拒绝并抛出 WorkflowAccessError 错误。

资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:8-12]()

if (executionMode === 'production' && !workflow.activeVersionId) {
    throw new WorkflowAccessError(
        `Workflow '${workflowId}' has no published (active) version to execute`,
        'workflow_not_active',
    );
}

版本数据管理

工作流执行引擎根据执行模式选择对应的版本数据：

graph TD
    A[开始执行] --> B{执行模式是 production?}
    B -->|是| C[使用 activeVersion]
    B -->|否| D[使用草稿版本]
    C --> E[提取 nodes 和 connections]
    D --> E
    E --> F[查找触发节点]
    F --> G[生成 MCP 消息ID]
    G --> H[构建运行数据]
    
    style C fill:#e1f5fe
    style D fill:#fff3e0

引擎通过 getVersionDataForExecution 函数根据执行模式选择正确的版本数据：

资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:14-24]()

const getVersionDataForExecution = (
    workflow: FoundWorkflow,
    workflowId: string,
    executionMode: z.infer<typeof inputSchema>['executionMode'],
) => {
    const nodes =
        executionMode === 'production' 
            ? (workflow.activeVersion?.nodes ?? []) 
            : (workflow.nodes ?? []);
    const connections =
        executionMode === 'production'
            ? (workflow.activeVersion?.connections ?? {})
            : (workflow.connections ?? {});
    return { nodes, connections };
};

触发节点机制

支持的触发节点

工作流执行引擎仅支持特定类型的触发节点。系统定义了 getSupportedTriggerNamesForMode 函数来获取当前执行模式支持的触发器名称列表：

资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:36-39]()

if (!triggerNode) {
    throw new WorkflowAccessError(
        `Only workflows with the following trigger nodes can be executed: ${getSupportedTriggerNamesForMode(executionMode).join(', ')}.`,
        'unsupported_trigger',
    );
}

触发节点查找

引擎使用 findMcpSupportedTrigger 函数在工作流节点列表中查找符合条件的触发节点，该函数会扫描所有节点并识别支持 MCP 协议的触发器。

执行数据构建

运行数据结构

工作流执行引擎构建 IWorkflowExecutionDataProcess 类型的运行数据，该数据结构包含执行工作流所需的全部信息，包括：

• 工作流定义（节点和连接）
• 执行模式
• 用户上下文
• 触发节点信息
• 输入数据

MCP 消息标识

为每次执行生成唯一的 MCP 消息 ID，用于队列模式下的关联和追踪：

资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:42-44]()

const mcpMessageId = `mcp-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;

消息 ID 格式：mcp-{时间戳}-{随机字符串}，确保在分布式环境中的唯一性。

表达式运行时

表达式求值器

表达式求值器是工作流执行引擎的关键组件，负责在运行时解析包含变量引用和函数的表达式。求值器支持：

• 简单变量替换：{{ $json.name }}
• 复杂表达式计算：{{ Math.ceil($json.price * 1.1) }}
• 条件表达式：{{ $json.value > 10 ? '高' : '低' }}
• 节点输出引用：{{ $json("NodeName").value }}

AST 解释器

抽象语法树（AST）解释器是表达式运行时的新一代实现，采用 AST 而非字符串解析方式处理表达式，具有以下优势：

错误处理机制

验证错误

引擎使用 Zod 进行输入验证，当验证失败时会创建 ValidationError 并记录详细错误信息：

资料来源：[packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts:68-73]()

if (error instanceof z.ZodError) {
    const validationError = new ValidationError('Invalid URL input', {
        extra: { errors: error.errors },
    });
    reporter.error(validationError);
}

工作流访问错误

当工作流状态不符合执行条件时，引擎抛出 WorkflowAccessError，错误类型包括：

执行服务

执行服务架构

执行服务（Execution Service）负责管理执行的生命周期，包括：

1. 执行创建：初始化新的执行实例
2. 执行排队：将执行请求加入执行队列
3. 执行监控：跟踪执行进度和状态
4. 执行完成：保存执行结果并清理资源

活跃工作流管理器

活跃工作流管理器（Active Workflow Manager）维护当前活跃工作流的注册表，负责：

• 工作流激活与停用
• 触发器注册与移除
• 活跃连接管理

graph LR
    A[用户激活工作流] --> B[ActiveWorkflowManager]
    B --> C[注册触发器]
    C --> D[添加到活跃列表]
    
    E[触发事件到达] --> F[查找对应工作流]
    F --> G[创建执行实例]
    G --> H[执行引擎调度]
    
    I[用户停用工作流] --> J[移除触发器]
    J --> K[从活跃列表删除]

扩展机制

MCP 工具集成

n8n 支持通过 MCP（Model Context Protocol）协议扩展执行引擎的能力。MCP 工具允许外部系统调用 n8n 工作流，实现与 AI 代理和其他自动化系统的集成。

MCP 执行工具的核心功能：

• 接收外部执行请求
• 验证工作流和用户权限
• 选择正确的执行模式
• 返回执行结果

执行模式配置

引擎支持通过配置选项自定义执行行为：

// 执行请求输入模式定义
const inputSchema = z.object({
    executionMode: z.enum(['production', 'manual']),
    inputs: z.record(z.any()).optional(),
});

数据流处理

输入数据处理

工作流执行引擎支持通过 inputs 参数向工作流传递初始数据：

graph TD
    A[外部输入] --> B[inputs 验证]
    B --> C{验证通过?}
    C -->|是| D[注入到触发节点]
    C -->|否| E[返回验证错误]
    D --> F[开始节点执行]

输出数据返回

执行完成后，引擎收集所有节点的输出数据，整理为统一的响应格式返回给调用方。

相关组件

概述

AI Agent 运行时（Agent Runtime）是 n8n 平台中负责执行 AI 代理的核心组件系统。该运行时负责管理代理的生命周期、消息处理、工具调用以及与外部系统（如 MCP 服务器）的集成。运行时架构设计遵循模块化原则，将核心逻辑与具体实现解耦，使得系统具备良好的可扩展性和可维护性。

运行时系统的核心职责包括：

• 消息管理：维护对话历史，处理用户输入与模型输出的流转
• 工具解析：解析并执行 MCP（Model Context Protocol）工具调用
• 状态管理：跟踪代理执行状态，处理错误恢复
• 上下文维护：管理代理的长期记忆和会话状态

核心组件架构

AI Agent 运行时由多个协同工作的组件构成，每个组件承担特定的职责。以下是主要组件及其功能：

graph TD
    A[Agent SDK] --> B[AgentRuntime]
    B --> C[MessageList]
    B --> D[MCPToolResolver]
    D --> E[MCP Servers]
    B --> F[AI Workflow Builder]
    F --> G[PromptBuilder]
    G --> H[工具定义]
    G --> I[示例生成]

AgentRuntime（代理运行时引擎）

AgentRuntime 是整个运行时的核心引擎，负责协调各个组件的工作。它处理代理的初始化、执行循环和结果返回。

主要功能包括：

• 初始化运行时环境
• 执行主循环，处理用户消息
• 调用工具并处理返回结果
• 管理会话状态和错误处理

MessageList（消息列表）

MessageList 组件负责管理对话消息的历史记录。它维护一个有序的消息队列，支持消息的添加、检索和上下文管理。

核心功能：

• 存储对话历史
• 支持消息角色区分（用户、助手、系统）
• 提供上下文窗口管理
• 支持消息格式转换

MCPToolResolver（工具解析器）

MCPToolResolver 负责解析和执行 MCP 协议定义的工具调用。它充当 n8n 运行时与外部 MCP 服务器之间的桥梁。

主要职责：

• 发现可用的 MCP 工具
• 验证工具参数
• 执行工具调用
• 处理工具返回结果

消息处理流程

运行时采用事件驱动的消息处理模式，确保每条消息都能得到正确处理并返回相应的响应。

sequenceDiagram
    participant User as 用户
    participant Runtime as AgentRuntime
    participant Messages as MessageList
    participant Tools as MCPToolResolver
    participant LLM as AI 模型
    
    User->>Runtime: 发送消息
    Runtime->>Messages: 添加用户消息
    Runtime->>LLM: 发送完整上下文
    LLM->>Runtime: 返回响应/工具调用
    alt 工具调用
        Runtime->>Tools: 解析工具请求
        Tools->>Tools: 执行 MCP 工具
        Tools-->>Runtime: 返回结果
        Runtime->>LLM: 发送工具结果
        LLM->>Runtime: 生成最终响应
    end
    Runtime->>Messages: 添加助手消息
    Runtime-->>User: 返回响应

工具系统集成

AI Tools 生成

n8n 的 AI Tools 系统负责将 n8n 节点转换为 AI 模型可调用的工具。这一过程在 packages/cli/src/tool-generation/ai-tools.ts 中实现。

工具描述生成流程：

// 工具描述自动生成逻辑
const descriptionType: INodeProperties = {
    displayName: 'Tool Description',
    name: 'descriptionType',
    type: 'options',
    options: [
        { name: 'Set Automatically', value: 'auto' },
        { name: 'Set Manually', value: 'manual' },
    ],
    default: 'auto',
};

工具属性处理

运行时支持两种工具描述设置模式：

当节点包含 resource 和 operation 属性时，运行时可以自动生成语义化的工具描述，使 LLM 能够更准确地理解和调用工具。

Prompt 构建系统

AI Workflow Builder 使用 PromptBuilder 组件构建发送给 LLM 的提示词。该构建器采用流式 API 设计，支持灵活的提示词组装。

PromptBuilder 核心特性

graph LR
    A[section] --> B[sectionIf]
    A --> C[examples]
    A --> D[examplesIf]
    B --> E[build]
    C --> E
    D --> E

主要方法：

示例格式化

PromptBuilder 支持多种输出格式：

// Markdown 格式
const markdownOutput = `## Examples\n${examplesContent}`;

// XML 格式
const xmlOutput = `<examples>\n${examplesContent}\n</examples>`;

构建器会根据配置自动选择合适的格式化方式，确保与不同 LLM API 的兼容性。

Web Fetch 工具

运行时不直接提供网络获取功能，而是通过 web-fetch.tool.ts 实现网页内容提取。该工具将获取的网页转换为 LLM 可处理的结构化文本。

处理流程：

1. 发送 HTTP 请求获取页面内容
2. 提取可读文本和标题
3. 处理内容截断和错误情况
4. 返回结构化结果

返回格式示例：

<web_fetch_result>
<url>https://example.com</url>
<title>页面标题</title>
<content>
提取的正文内容...
</content>
</web_fetch_result>

MCP 浏览器集成

n8n 提供了 MCP（Model Context Protocol）浏览器工具，用于在开发环境中测试 MCP 服务器功能。该工具支持多种 AI 客户端配置，包括 Claude Desktop、Cursor、Windsurf 等。

开发环境配置

# 启动 MCP 服务器
npx @n8n/mcp-browser --transport http --port 3100

客户端配置示例

{
  "mcpServers": {
    "n8n-browser": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

错误处理机制

运行时实现了完善的错误处理机制，确保代理在遇到异常情况时能够优雅地降级或恢复：

• 验证错误：通过 Zod 进行输入参数验证
• 工具执行错误：捕获并记录工具调用异常
• 网络错误：处理 MCP 服务器连接问题
• 上下文溢出：管理令牌使用量，避免超出限制

// 验证错误处理示例
if (error instanceof z.ZodError) {
    const validationError = new ValidationError('Invalid URL input', {
        extra: { errors: error.errors },
    });
    reporter.error(validationError);
}

数据流总结

graph TD
    subgraph 输入层
        A[用户消息] --> B[MessageList]
    end
    
    subgraph 处理层
        B --> C[PromptBuilder]
        C --> D[AI 模型]
        D --> E[响应/工具调用]
    end
    
    subgraph 执行层
        E --> F{MCPToolResolver}
        F --> G[MCP 工具]
        G --> H[外部服务]
    end
    
    subgraph 输出层
        E --> I[格式化响应]
        I --> J[返回用户]
    end

相关配置

运行时的行为可通过多种方式配置：

扩展指南

添加新的工具解析器

要扩展工具系统，需要实现 ToolResolver 接口：

interface ToolResolver {
    resolve(toolCall: ToolCall): Promise<ToolResult>;
    getAvailableTools(): ToolDefinition[];
    validateParams(params: unknown): boolean;
}

集成新的 MCP 服务器

1. 在 MCP 配置中注册服务器端点
2. 实现服务器端的工具定义
3. 配置 MCPToolResolver 连接参数

总结

AI Agent 运行时是 n8n 平台智能化能力的核心支撑。通过模块化的组件设计，系统实现了高效的消息处理、灵活的提示词构建和完善的工具调用机制。开发者可以通过扩展现有组件或集成新的 MCP 服务器来增强运行时功能，以满足各种复杂的 AI 工作流需求。

概述

LangChain 节点集成是 n8n 工作流自动化平台中用于构建 AI 驱动工作流的核心组件体系。该集成通过提供标准化的节点、工具和提示构建系统，使开发者能够在 n8n 工作流中无缝调用 LangChain 的语言模型、代理（Agent）和工具链能力。

LangChain 节点集成的主要功能包括：

• 语言模型（LLM）节点：支持 OpenAI、Anthropic 等多种语言模型的调用
• 代理（Agent）节点：基于 LangChain 构建的 AI 代理，支持多种推理策略
• 工具（Tools）节点：提供 Web 抓取、代码执行等工具扩展
• 提示构建系统：基于 PromptBuilder 的类型安全、fluent API

架构设计

整体架构

LangChain 节点集成采用分层架构设计，各组件之间通过标准接口进行通信：

graph TD
    subgraph "表现层"
        A[编辑器 UI] --> B[节点配置面板]
        B --> C[代码编辑器]
    end
    
    subgraph "节点层"
        D[LLM 节点] --> E[代理节点]
        E --> F[工具节点]
        F --> G[PromptBuilder]
    end
    
    subgraph "集成层"
        H[LangChain Core] --> I[模型适配器]
        I --> J[工具适配器]
    end
    
    subgraph "外部服务"
        K[OpenAI API] --> I
        L[Anthropic API] --> I
        M[外部工具] --> J
    end
    
    style A fill:#e1f5fe
    style D fill:#fff3e0
    style H fill:#e8f5e9

PromptBuilder 核心组件

PromptBuilder 是 LangChain 节点集成中的提示构建核心类，提供类型安全的流式 API：

提示构建系统

PromptBuilder 类接口

PromptBuilder 类位于 packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts，提供以下核心方法：

class PromptBuilder {
  private readonly sections: SectionEntry[];
  private readonly format: SectionFormat;
  private readonly separator: string;

  constructor(options: PromptBuilderOptions = {});
  
  // 添加固定部分
  section(name: string, content: ContentOrFactory, options?: SectionOptions): this;
  
  // 添加条件部分
  sectionIf(condition: unknown, name: string, content: ContentOrFactory, options?: SectionOptions): this;
  
  // 添加示例
  examples(name: string, data: unknown[], formatter: ExampleFormatter): this;
  examplesIf(condition: unknown, name: string, data: unknown[], formatter: ExampleFormatter): this;
  
  // 合并多个 PromptBuilder
  merge(other: PromptBuilder): this;
  
  // 构建最终提示字符串
  build(): string;
}

资料来源：prompt-builder.ts:48-90

使用示例

const systemPrompt = prompt()
  .section('ROLE', 'You are an assistant')
  .sectionIf(hasContext, 'CONTEXT', () => buildContext())
  .examples('EXAMPLES', data, (ex) => `${ex.input} → ${ex.output}`)
  .build();

上述代码通过 fluent API 构建了一个包含角色定义、上下文信息和示例的提示词，最终通过 build() 方法生成字符串输出。

工具节点系统

WebFetch 工具

WebFetch 工具是 AI workflow builder 中用于获取网页内容的核心工具，位置在 packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts。其工作流程如下：

graph TD
    A[输入 URL] --> B[验证 URL 格式]
    B --> C{验证通过?}
    C -->|否| D[返回 ValidationError]
    C -->|是| E[发起 HTTP 请求]
    E --> F[提取可读内容]
    F --> G[构建响应 XML]
    G --> H[记录安全状态]
    H --> I[返回 SuccessResponse]
    
    style D fill:#ffcdd2
    style I fill:#c8e6c9

响应格式

WebFetch 工具返回的响应采用 XML 结构，包含以下元素：

<web_fetch_result>
  <url>https://example.com</url>
  <title>Example Domain</title>
  <content>
    [提取的内容]
  </content>
</web_fetch_result>

资料来源：web-fetch.tool.ts:26-43

节点指南系统

指南注册机制

n8n 的 AI workflow builder 通过指南系统（Guides）为不同类型的节点提供上下文相关的帮助信息：

graph LR
    A[用户操作] --> B{匹配节点类型}
    B -->|Set 节点| C[赋值结构与类型指南]
    B -->|IF 节点| D[过滤条件与操作符指南]
    B -->|HTTP Request| E[URL、Header、Body、认证指南]
    B -->|Tool 节点| F[$fromAI 表达式指南]

指南配置结构

每个节点指南的定义包含以下属性：

export const MY_NODE_GUIDE: NodeTypeGuide = {
  patterns: ['n8n-nodes-base.myNode'],
  condition: (ctx) => true,
  content: `Your guide content here...`,
};

资料来源：README.md (prompts)

前端编辑器集成

代码编辑器组件

n8n 前端使用 CodeMirror 6 实现代码编辑器，位于 packages/frontend/editor-ui/src/features/shared/editors/composables/useCodeEditor.ts：

const editor = ref<EditorView>();
const hasFocus = ref(false);
const hasChanges = ref(false);
const autocompleteStatus = ref<'pending' | 'active' | null>(null);

编辑器支持的语言包括多种代码语言，并提供语法高亮、自动完成等功能。

AI Builder 界面文本

前端国际化文件 packages/frontend/@n8n/design-system/src/locale/lang/en.ts 包含 AI Builder 相关的界面文本：

多代理提示系统

代理类型

提示系统支持多种专业化代理：

所有代理提示都使用 PromptBuilder 进行统一组合。

链式提示

除了代理提示外，系统还包含用于特定 LLM 链式操作的提示：

安全性与状态管理

安全状态追踪

WebFetch 工具实现了安全状态追踪机制：

const stateUpdates: Record<string, unknown> = {
  ...security.getStateUpdates(),
  fetchedUrlContent: [
    {
      url,
      status: 'success' as const,
      title: extracted.title,
      content: extracted.content,
    },
  ],
};

安全系统记录每次抓取请求，并在返回响应时附带安全状态更新，确保工作流执行的可追溯性。

最佳实践

提示构建

1. 使用条件部分：对于可选内容，使用 sectionIf() 避免不必要的延迟求值
2. 链式调用：利用流式 API 的可读性组织提示构建逻辑
3. 示例格式化：通过 examples() 方法添加少样本示例时，使用清晰的格式化函数

工具使用

1. URL 验证：WebFetch 工具会自动验证 URL 格式，无效输入将抛出 ValidationError
2. 内容截断：大型页面内容可能被截断，应检查 truncated 标志
3. 错误处理：工具返回的错误包含 Zod 验证详情，便于调试

相关资源

• 官方文档：n8n AI Workflow Builder
• LangChain 官方文档：LangChain.js
• 源码仓库：n8n-io/n8n

概述

AI 工作流构建器是 n8n 平台中一个基于大语言模型（LLM）的智能工作流创建系统。该系统通过多代理（Multi-Agent）架构，允许用户使用自然语言描述需求，自动生成 n8n 工作流代码。该模块位于 packages/@n8n/ai-workflow-builder.ee 包中，是 n8n 企业版的重要组成部分。

AI 工作流构建器的主要特点包括：

• 自然语言驱动：用户通过自然语言描述工作流需求
• 多代理协作：多个专业代理协同工作，各司其职
• 代码生成：自动生成可执行的工作流代码（JavaScript/TypeScript）
• 上下文感知：能够理解当前工作流状态并进行多轮优化
• 工具集成：支持网络搜索、文档获取等辅助工具

系统架构

多代理架构

AI 工作流构建器采用多代理架构设计，每个代理拥有特定的角色和职责：

资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md

graph TD
    A[用户请求] --> B[Supervisor 主管代理]
    B --> C[Discovery 发现代理]
    B --> D[Builder 构建代理]
    B --> E[Responder 响应代理]
    C --> F[节点搜索结果]
    D --> G[工作流代码]
    F --> D
    D --> H[工作流状态]
    H --> B
    G --> E
    E --> I[用户响应]

核心组件

packages/@n8n/ai-workflow-builder.ee/
├── src/
│   ├── code-builder/           # 代码构建器核心
│   │   └── prompts/            # 代码生成提示词
│   ├── agents/                 # 多代理系统
│   │   ├── planner.agent.ts    # 规划代理
│   │   └── ...
│   ├── prompts/                # 提示词构建系统
│   │   ├── builder/            # PromptBuilder 工具
│   │   ├── chains/             # 链式提示词
│   │   └── guides/             # 节点和参数指南
│   ├── tools/                  # 工具集
│   │   ├── web-fetch.tool.ts   # 网页抓取工具
│   │   └── builder-tools.ts    # 构建器专用工具
│   └── workflow-state.ts       # 工作流状态管理

PromptBuilder 提示词构建器

概述

PromptBuilder 是一个类型安全的链式 API，用于组合 LLM 提示词。它支持条件化部分、延迟求值和 LangChain 集成。

资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts

核心功能

const systemPrompt = prompt()
  .section('role', 'You are an assistant')
  .sectionIf(hasContext, 'context', () => buildContext())
  .examples('examples', data, (ex) => `${ex.input} → ${ex.output}`)
  .build();

格式化选项

PromptBuilder 支持两种输出格式：

代码构建器

系统提示词构建

代码构建器通过 buildCodeBuilderPrompt 函数构建完整的系统提示词，该函数整合多个组件：

export function buildCodeBuilderPrompt(
	currentWorkflow?: WorkflowJSON,
	historyContext?: HistoryContext,
	options?: BuildCodeBuilderPromptOptions,
): ChatPromptTemplate

资料来源：packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts

提示词组成部分

系统提示词由以下部分组成：

graph LR
    A[buildCodeBuilderPrompt] --> B[ROLE 角色定义]
    A --> C[RESPONSE_STYLE 响应风格]
    A --> D[WORKFLOW_RULES 工作流规则]
    A --> E[WORKFLOW_PATTERNS 工作流模式]
    A --> F[EXPRESSION_REFERENCE 表达式参考]
    A --> G[ADDITIONAL_FUNCTIONS 附加函数]
    A --> H[MANDATORY_WORKFLOW_PROCESS 强制流程]

用户消息构建

用户消息部分通过 buildUserMessageParts 函数构建，支持以下可选组件：

function buildUserMessageParts(
	currentWorkflow?: WorkflowJSON,
	historyContext?: HistoryContext,
	options?: BuildCodeBuilderPromptOptions,
): string[]

资料来源：packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts

XML 标签包装

系统使用 XML 标签封装不同类型的信息，便于解析：

工具系统

网页抓取工具

WebFetchTool 允许 AI 代理获取网页内容以辅助决策：

sequenceDiagram
    代理->>WebFetchTool: fetch(url)
    WebFetchTool->>URL: 发起 HTTP 请求
    URL-->>WebFetchTool: 返回 HTML 内容
    WebFetchTool->>WebFetchTool: extractReadableContent()
    WebFetchTool->>安全检查: recordFetch()
    WebFetchTool-->>代理: 返回结构化结果

资料来源：packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts

工具响应格式

工具执行完成后返回结构化的响应，包含状态更新信息：

interface ToolResponse {
	status: 'success' | 'error';
	url?: string;
	finalUrl?: string;
	truncated?: boolean;
}

const stateUpdates: Record<string, unknown> = {
	...security.getStateUpdates(),
	fetchedUrlContent: [{
		url,
		status: 'success' as const,
		title: extracted.title,
		content: extracted.content,
	}],
};

安全状态追踪

网页抓取工具集成了安全状态追踪机制，记录所有抓取操作并生成相应的状态更新：

• security.recordFetch() - 记录抓取操作
• security.getStateUpdates() - 获取状态更新

节点指南系统

指南注册表

n8n 为常见节点提供专门的指南，帮助 AI 代理正确理解和配置节点：

资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md

条件化指南

某些指南仅在特定上下文中适用，使用 condition 属性控制：

export const RESOURCE_LOCATOR_GUIDE: NodeTypeGuide = {
	patterns: ['*'],  // 匹配所有节点
	condition: (ctx) => ctx.hasResourceLocatorParams === true,
	content: `...`,
};

LangChain 集成

消息块构建

PromptBuilder 支持构建 LangChain 兼容的消息块，带有缓存控制支持：

return ChatPromptTemplate.fromMessages([
	['system', [{
		type: 'text',
		text: systemMessage,
		cache_control: { type: 'ephemeral' }
	}]],
	['user', userMessageTemplate],
]);

缓存策略

系统使用 LangChain 的 cache_control 机制进行提示词缓存优化：

• ephemeral - 临时缓存，仅在当前请求周期内有效
• 适用于频繁使用但频繁变化的内容

工作流状态管理

工作流状态由 workflow-state.ts 管理，跟踪工作流的当前配置和历史变更。状态信息在多代理协作中流转，确保每个代理都能访问一致的工作流上下文。

代码节点编辑器补全

输入方法补全

AI 工作流构建器为 $input 对象提供智能补全支持：

补全选项包括 .json 和 .binary 两种数据类型访问方式。

资料来源：packages/frontend/editor-ui/src/features/shared/editors/components/CodeNodeEditor/completions/itemField.completions.ts

规则引擎

架构规则

AI 工作流构建器的测试框架使用规则引擎进行架构验证：

资料来源：packages/testing/rules-engine/README.md

最佳实践

提示词构建

1. 使用条件化部分：通过 sectionIf() 按需包含内容，减少不必要的上下文
2. 延迟求值：使用工厂函数避免不必要的计算
3. 适当格式化：XML 格式便于程序解析，Markdown 格式便于调试
4. 缓存控制：对频繁使用的系统提示词部分使用缓存标记

代理协作

1. 职责分离：每个代理应专注于特定任务
2. 状态传递：通过标准化的工作流状态对象在各代理间传递信息
3. 错误处理：工具执行应包含完整的错误处理和状态回滚机制

相关链接

• n8n 官方文档
• n8n GitHub 仓库
• AI 工作流构建器源码

Pitfall Log / 踩坑日志

项目：n8n-io/n8n

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:193215554 | https://github.com/n8n-io/n8n | README/documentation is current enough for a first validation pass.

2. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 建议检查：确认是否有离线 demo、mock 数据或可替代服务。
• 防护动作：外部服务依赖未明确时，不把本地安装成功等同于能力可用。
• 证据：packet_text.keyword_scan | github_repo:193215554 | https://github.com/n8n-io/n8n | matched external service / cloud / webhook / database keyword

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:193215554 | https://github.com/n8n-io/n8n | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:193215554 | https://github.com/n8n-io/n8n | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | release_recency=unknown