= {
completed: 'success',
pending: 'warning',
failed: 'danger',
}
return themeMap[status] || 'default'
}
```
资料来源：[component-badge.md:25-35]()
### Popover 组件
`N8nPopover` 组件提供弹出式内容展示功能。资料来源：[component-popover.md:1]()
#### 核心属性
| 属性 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| side | 'top' \| 'bottom' \| 'left' \| 'right' | 'bottom' | 弹出方向 |
| width | string | '300px' | 弹出框宽度 |
| teleported | boolean | true | 是否传送到 body |
| side-offset | number | 8 | 与触发器的偏移量 |
#### 使用示例
**带触发的下拉菜单：**
```vue
```
资料来源：[component-popover.md:10-25]()
**使用关闭函数：**
```vue
```
资料来源：[component-popover.md:70-80]()
---
## Markdown 渲染选项
### useChatHubMarkdownOptions
`useChatHubMarkdownOptions` 是聊天中心使用的 Markdown 渲染配置 hook。资料来源：[useChatHubMarkdownOptions.ts:1]()
### 插件列表
| 插件名称 | 功能 |
|---------|------|
| linksNewTabPlugin | 将链接在新标签页打开 |
| codeBlockPlugin | 代码块渲染增强 |
| tablePlugin | 表格渲染支持 |
| mathPlugin | 数学公式渲染 |
| footnotePlugin | 脚注功能（隐藏显示，仅保留胶囊） |
### 脚注处理
聊天中心对脚注进行了特殊处理，将脚注块隐藏，仅保留可点击的脚注引用胶囊：
```typescript
const footnotePlugin = () => {
// Hide the footnote block — the pill is the only UI for footnote content
md.renderer.rules.footnote_block_open = () => '';
md.renderer.rules.footnote_block_close = () => '
';
md.renderer.rules.footnote_open = () => '';
md.renderer.rules.footnote_close = () => '';
md.renderer.rules.footnote_anchor = () => '';
};
```
资料来源：[useChatHubMarkdownOptions.ts:25-32]()
### 链接新标签页处理
链接在新标签页打开时会显示完整的 URL 作为 tooltip：
```typescript
const linksNewTabPlugin = () => {
const defaultRender = md.renderer.rules.link_open || /* ... */;
md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
const aIndex = tokens[idx].attrIndex('target');
if (aIndex < 0) {
tokens[idx].attrPush(['target', '_blank']);
} else {
tokens[idx].attrs[aIndex][1] = '_blank';
}
// ...
const escapedFull = encoder.encode(fullHref);
const escapedTruncated = encoder.encode(truncatedHref);
return `${escapedTruncated}`;
};
};
```
资料来源：[useChatHubMarkdownOptions.ts:8-24]()
---
## SSO/SAML 认证
### SAML 2.0 协议支持
n8n 提供了完整的 SAML 2.0 协议支持，包括以下核心功能：
- **Artifact 处理**：支持 SAML Artifact 绑定
- **单点登出 (SLO)**：支持 ManageNameID 和 LogoutRequest
- **名称标识管理**：支持 NameID 的加密和转换
资料来源：[saml-schema-protocol-2.0.xsd.ts:1]()
### Web 服务安全策略
WS-SecurityPolicy 1.2 定义了 SOAP 消息的安全策略，包括：
| 策略类型 | 说明 |
|---------|------|
| TransportBinding | 传输层绑定 |
| SymmetricBinding | 对称密钥绑定 |
| X509Token | X.509 证书令牌 |
| Trust13 | Trust 1.3 断言 |
| AlgorithmSuite | 加密算法套件 |
资料来源：[ws-securitypolicy-1.2.xsd.ts:1]()
---
## 常见问题
### 如何调试 AI 工作流？
使用 `PromptBuilder` 的 `build()` 方法可以预览最终的提示词内容：
```typescript
const builder = new PromptBuilder();
builder.addSection('instruction', '回答用户问题');
builder.addExamples(['示例1', '示例2']);
console.log(builder.build());
```
### Web 获取工具返回的内容被截断了怎么办？
工具默认会对超长内容进行截断。如果需要完整内容，可以在工具配置中调整 `maxContentLength` 参数。
### 设计系统组件在 SSR 环境中使用注意事项？
`N8nPopover` 默认使用 `teleported` 模式，会将内容传送到 `body`。在 SSR 环境中，建议设置 `:teleported="false"` 以保持 DOM 层级一致：
```vue
```
---
## 下一步
- 查看 [CONTRIBUTING.md](https://github.com/n8n-io/n8n/blob/main/CONTRIBUTING.md) 了解贡献指南
- 探索更多 [AI 工作流示例](https://github.com/n8n-io/n8n/tree/main/packages/@n8n/ai-workflow-builder.ee)
- 阅读 [设计系统文档](https://github.com/n8n-io/n8n/tree/main/packages/frontend/@n8n/design-system)
---
## 系统架构概览
### 相关页面
相关主题：[包结构与模块组织](#page-package-structure), [工作流 SDK 与构建器](#page-workflow-sdk)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)
- [packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts)
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)
- [packages/cli/src/modules/sso-saml/schema/ws-securitypolicy-1.2.xsd.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/modules/sso-saml/schema/ws-securitypolicy-1.2.xsd.ts)
- [packages/frontend/@n8n/design-system/src/locale/lang/en.ts](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/locale/lang/en.ts)
- [packages/frontend/@n8n/design-system/src/v2/components/Badge/component-badge.md](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/v2/components/Badge/component-badge.md)
# 系统架构概览
## 概述
n8n 是一个开源的工作流自动化平台，其核心架构围绕模块化设计构建。系统架构概览旨在帮助开发者理解 n8n 平台的关键组件、它们之间的交互关系以及扩展机制。
从源码层面分析，n8n 的架构涵盖以下几个核心领域：
| 模块 | 功能描述 | 所在包 |
|------|---------|--------|
| AI Workflow Builder | 支持 AI 功能的工作流构建器 | `@n8n/ai-workflow-builder.ee` |
| Prompt Builder | 动态提示词构建工具 | `@n8n/ai-workflow-builder.ee/src/prompts` |
| Web Fetch Tool | 网页内容抓取与提取 | `@n8n/ai-workflow-builder.ee/src/tools` |
| Design System | UI 组件库与国际化 | `@n8n/design-system` |
| CLI Core | 命令行核心模块 | `@n8n/cli` |
## 核心组件架构
### PromptBuilder 提示词构建器
`PromptBuilder` 是 n8n AI 工作流构建器中的核心工具类，提供类型安全的链式 API 用于组合 LLM 提示词。
```mermaid
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](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)
### SectionEntry 数据结构
```typescript
interface SectionEntry {
name: string;
content: ContentOrFactory;
options: SectionOptions;
}
type ContentOrFactory = string | (() => string | null);
```
每个节（Section）包含以下属性：
| 属性 | 类型 | 说明 |
|------|------|------|
| `name` | `string` | 节的显示名称，用于生成标签 |
| `content` | `ContentOrFactory` | 字符串内容或延迟求值的工厂函数 |
| `options` | `SectionOptions` | 可选配置项 |
资料来源：[prompt-builder.ts:44-49](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)
### WebFetchTool 网页抓取工具
`WebFetchTool` 是 n8n AI 工作流中的网页内容抓取与提取工具，负责从 URL 获取网页内容并进行可读性处理。
```mermaid
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. 记录安全相关状态更新
```typescript
const responseLines = [
'',
`${url}`,
`${extracted.title}`,
'',
extracted.content,
'',
'',
]
```
资料来源：[web-fetch.tool.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts)
## 安全策略模块
### WS-SecurityPolicy 1.2 XSD 架构
n8n 的 SSO-SAML 模块包含完整的 WS-SecurityPolicy 1.2 XSD Schema 定义，用于配置 Web 服务安全策略。
**主要策略类型：**
| 类型 | 说明 | 代码参考 |
|------|------|----------|
| `NestedPolicyType` | 嵌套策略类型 | `tns:NestedPolicyType` |
| `QNameAssertionType` | QName 断言类型 | `tns:QNameAssertionType` |
| `TokenAssertionType` | Token 断言类型 | `tns:TokenAssertionType` |
**核心安全断言：**
- **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 规范支持
```xml
7.1 AlgorithmSuite Assertion
```
资料来源：[ws-securitypolicy-1.2.xsd.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/modules/sso-saml/schema/ws-securitypolicy-1.2.xsd.ts)
## 设计系统架构
### Badge 组件
n8n 设计系统提供了统一的 Badge 组件，用于在工作流界面中展示状态信息。
```typescript
interface FileStatus {
status: 'completed' | 'pending' | 'failed'
}
const getStatusTheme = (status: string): BadgeTheme => {
const themeMap: Record = {
completed: 'success',
pending: 'warning',
failed: 'danger',
}
return themeMap[status] || 'default'
}
```
**主题映射：**
| 状态 | 主题 | 颜色语义 |
|------|------|---------|
| completed | success | 成功/绿色 |
| pending | warning | 警告/黄色 |
| failed | danger | 危险/红色 |
**组件使用示例：**
```vue
Read Only
Setup Required
```
资料来源：[component-badge.md](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/v2/components/Badge/component-badge.md)
### 国际化配置
n8n 设计系统支持多语言配置，主要通过 `en.ts` 文件定义英文翻译键值对。
```typescript
'codeDiff.couldNotReplace': 'Could not replace code',
'codeDiff.codeReplaced': 'Code replaced',
'codeDiff.replaceMyCode': 'Replace my code',
'codeDiff.replacing': 'Replacing...',
'codeDiff.undo': 'Undo',
```
**AI Builder 相关翻译：**
```typescript
'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](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/locale/lang/en.ts)
## 指南系统架构
### 节点类型指南
AI Workflow Builder 提供了可扩展的节点指南系统，支持按节点类型和条件动态匹配指南内容。
```typescript
export const MY_NODE_GUIDE: NodeTypeGuide = {
patterns: ['n8n-nodes-base.myNode'], // 匹配的节点类型
condition: (ctx) => true, // 可选：额外条件
content: `Your guide content here...`,
};
```
**当前指南覆盖：**
| 指南 | 模式 | 用途 |
|------|------|------|
| Set Node | `n8n-nodes-base.set` | 赋值结构与类型 |
| IF Node | `n8n-nodes-base.if` | 过滤条件与运算符 |
| Switch Node | `n8n-nodes-base.switch` | 规则与路由 |
| HTTP Request | `n8n-nodes-base.httpRequest` | URL、头、请求体、认证 |
| Tool Nodes | `*Tool` | $fromAI 表达式 |
| Resource Locator | `*` (条件) | __rl 结构与模式 |
| System Message | `*` (条件) | AI 节点消息分离 |
**条件指南示例：**
```typescript
export const RESOURCE_LOCATOR_GUIDE: NodeTypeGuide = {
patterns: ['*'], // 匹配所有节点
condition: (ctx) => ctx.hasResourceLocatorParams === true,
content: `...`,
};
```
资料来源：[README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)
## 模块交互关系
```mermaid
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 配置
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `format` | `SectionFormat` | `'xml'` | 输出格式：xml 或 markdown |
| `separator` | `string` | `'\n\n'` | 节之间的分隔符 |
### SectionOptions 配置
| 选项 | 类型 | 说明 |
|------|------|------|
| `format` | `SectionFormat` | 覆盖全局格式设置 |
| `tag` | `string` | 自定义标签名称 |
## 最佳实践
### 提示词构建规范
1. **使用条件节**：对于可能缺失的内容使用 `sectionIf()` 避免空值问题
2. **延迟求值**：复杂内容使用工厂函数而非直接字符串
3. **格式一致性**：在同一项目中保持统一的输出格式
4. **示例驱动**：使用 `examples()` 方法提供少样本学习示例
### 指南扩展规范
1. 在 `guides/` 目录创建新的指南文件
2. 从 `guides/index.ts` 导出新指南
3. 将指南添加到 `registry.ts` 的注册数组中
4. 使用条件匹配实现上下文相关的指南内容
## 总结
n8n 的系统架构体现了现代工作流自动化平台的设计理念：
- **模块化设计**：各功能模块解耦，便于独立维护和扩展
- **类型安全**：TypeScript 优先，确保编译期错误检测
- **可扩展性**：通过指南系统和提示词模板支持自定义行为
- **国际化**：完整的 i18n 支持，便于多语言适配
这些架构特性使得 n8n 能够同时支持传统工作流和 AI 增强工作流的开发需求。
---
## 包结构与模块组织
### 相关页面
相关主题：[系统架构概览](#page-architecture), [工作流 SDK 与构建器](#page-workflow-sdk)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts)
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)
- [packages/@n8n/node-cli/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/node-cli/README.md)
- [packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md)
- [packages/testing/janitor/README.md](https://github.com/n8n-io/n8n/blob/main/packages/testing/janitor/README.md)
- [packages/frontend/@n8n/design-system/README.md](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/README.md)
# 包结构与模块组织
## 概述
n8n 是一个开源的工作流自动化平台，采用 **Monorepo（单体仓库）** 架构组织代码。项目使用 pnpm 作为包管理器，通过 `pnpm-workspace.yaml` 定义工作区配置。整体架构划分为多个功能明确的子包（packages），涵盖工作流核心、CLI 工具、UI 组件、AI 构建器、数据库层和测试基础设施等模块。
## 核心包结构
n8n 的包结构遵循 **功能分离** 原则，每个包都有明确的职责边界和对外 API 接口。
| 包路径 | 用途说明 |
|--------|----------|
| `packages/cli` | CLI 主入口，处理命令行交互和服务器初始化 |
| `packages/@n8n/workflow-sdk` | 工作流核心 SDK，定义节点、连接、表达式等核心概念 |
| `packages/@n8n/agents` | AI Agent 能力封装 |
| `packages/@n8n/db` | 数据库抽象层 |
| `packages/frontend/editor-ui` | 工作流编辑器前端界面 |
| `packages/frontend/@n8n/design-system` | 统一设计系统和 UI 组件库 |
| `packages/@n8n/node-cli` | 节点开发脚手架工具 |
| `packages/@n8n/ai-workflow-builder.ee` | AI 工作流构建器（企业版） |
| `packages/testing` | 测试工具和基础设施 |
## 模块层次架构
n8n 采用 **分层架构** 设计，从底层到上层依次为：
```mermaid
graph TD
A["packages/@n8n/db
数据库抽象层"] --> B["packages/@n8n/workflow-sdk
工作流核心"]
B --> C["packages/@n8n/agents
AI Agent 层"]
C --> D["packages/@n8n/ai-workflow-builder.ee
AI 工作流构建器"]
B --> E["packages/cli
CLI 与服务层"]
E --> F["packages/frontend/editor-ui
前端编辑器"]
F --> G["packages/frontend/@n8n/design-system
设计系统"]
```
## 工作流核心 SDK
`packages/@n8n/workflow-sdk` 是整个平台的核心，封装了工作流执行的全部基础能力。
### 核心职责
- 定义节点（Node）和凭证（Credentials）接口
- 实现工作流执行引擎
- 提供表达式解析和求值
- 管理连接和数据流转
### 包导出模式
SDK 包使用 ** barrel export** 模式统一对外暴露 API，通过 `src/index.ts` 作为唯一入口点：
```typescript
// 资料来源：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 都有明确的职责分工：
| Agent | 职责 | 说明 |
|-------|------|------|
| **Supervisor** | 路由协调 | 接收用户请求并分发给合适的专家 Agent |
| **Discovery** | 节点发现 | 识别相关 n8n 节点并分类技术方案 |
| **Builder** | 构建执行 | 创建工作流结构并配置节点参数 |
| **Responder** | 响应生成 | 生成面向用户的回复内容 |
资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md]()
### 提示词构建器（PromptBuilder）
核心模块使用 **PromptBuilder** 工具类实现提示词的组合式构建：
```typescript
// 资料来源：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 关键特性
| 特性 | 说明 |
|------|------|
| **流式 API** | 支持链式调用，方法返回 `this` |
| **条件节** | `sectionIf()` 根据条件动态包含内容 |
| **惰性求值** | 工厂函数仅在构建时执行 |
| **双格式输出** | 支持 XML 标签和 Markdown 标题两种格式 |
| **LangChain 集成** | 支持 `cache_control` 缓存控制 |
### 提示词模板结构
代码构建器提示词由多个标准节组成：
```mermaid
graph LR
A[""] --> B[""]
B --> C[""]
C --> D[""]
D --> E[""]
E --> F[""]
F --> G[""]
```
资料来源：[packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts]()
## CLI 工具与节点开发
### 节点脚手架工具
`packages/@n8n/node-cli` 提供节点开发的标准化工具体系：
```bash
# 创建新节点
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` 字段：
```json
{
"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 的统一视觉语言：
```bash
# 开发预览
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：
```typescript
// 资料来源：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` 是端到端测试编排工具，支持分片并行执行：
```bash
# 分 14 片执行
playwright-janitor orchestrate --shards=14
# 仅执行受 Git 变更影响的测试
playwright-janitor orchestrate --shards=14 --impact
```
资料来源：[packages/testing/janitor/README.md]()
### 架构规则
测试框架定义了严格的架构规则：
| 规则 | 严重级别 | 说明 |
|------|----------|------|
| `boundary-protection` | error | 禁止页面对象直接导入其他页面 |
| `scope-lockdown` | error | 页面对象必须有 `container` 或导航方法 |
| `test-data-hygiene` | warning | 检测孤立/通用的测试数据文件 |
| `duplicate-logic` | warning | 检测代码重复（AST 结构指纹） |
### 页面对象隔离原则
```typescript
// 资料来源：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 配置、迁移管理和连接池等基础设施问题。
### 包导出模式
```typescript
// 资料来源：packages/@n8n/db/src/index.ts
export * from './connection';
export * from './repositories';
export * from './migrations';
```
## 模块间依赖关系
```mermaid
graph TD
CLI["packages/cli
CLI 入口"]
SDK["packages/@n8n/workflow-sdk
工作流 SDK"]
DB["packages/@n8n/db
数据库层"]
AGENTS["packages/@n8n/agents
AI Agent"]
AI_BUILDER["packages/@n8n/ai-workflow-builder.ee
AI 构建器"]
EDITOR["packages/frontend/editor-ui
编辑器 UI"]
DESIGN["packages/frontend/@n8n/design-system
设计系统"]
DB --> SDK
SDK --> CLI
SDK --> AGENTS
AGENTS --> AI_BUILDER
CLI --> EDITOR
EDITOR --> DESIGN
```
## 命名规范与导出约定
### Barrel Export 模式
所有包遵循统一的 Barrel Export 模式组织导出：
```typescript
// src/index.ts - 包入口文件
export * from './core'; // 核心功能
export * from './types'; // 类型定义
export * from './constants'; // 常量
export { SpecificClass } from './internal/specific'; // 按需导出
```
### 命名空间约定
| 层级 | 命名方式 | 示例 |
|------|----------|------|
| 包名 | `@n8n/功能名` | `@n8n/workflow-sdk` |
| 导出类 | PascalCase | `WorkflowExecutor` |
| 导出函数 | camelCase | `executeWorkflow` |
| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
| 类型/接口 | PascalCase + 后缀 | `WorkflowNode`, `NodeCredentials` |
## 扩展机制
### 节点开发扩展
通过 `n8n-nodes-` 前缀注册自定义节点：
```json
{
"name": "n8n-nodes-my-service",
"n8n": {
"nodes": ["dist/nodes/MyNode/MyNode.node.js"]
}
}
```
### 提示词指南扩展
AI 构建器支持通过模式匹配注入节点指南：
```typescript
// 资料来源：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 与构建器
### 相关页面
相关主题：[工作流执行引擎](#page-execution-engine), [系统架构概览](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)
- [packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts)
- [packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts)
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/guides/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/guides/README.md)
# 工作流 SDK 与构建器
## 概述
工作流 SDK 与构建器（Workflow SDK and Builder）是 n8n 平台中用于通过 AI 能力自动生成、构建和优化工作流的综合技术栈。该系统由多个核心组件构成，包括提示构建器（PromptBuilder）、语义图（Semantic Graph）、代码生成器（Code Generator）以及多代理协调系统。这些组件协同工作，使开发者能够通过自然语言描述或结构化指令来自动生成复杂的工作流配置。
n8n 的工作流构建系统采用了分层的架构设计，将工作流的语义表示与实际的代码生成解耦。这种设计允许不同的生成策略（如基于规则的生成、基于 AI 的生成）共享同一套语义模型，从而保证了生成结果的一致性和可维护性。
## 核心架构
### 系统组件关系
```mermaid
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** | 负责构建结构化的 LLM 提示，支持条件化、可组合的提示段 | prompt-builder.ts |
| **Code Generator** | 将语义图转换为实际的代码输出 | code-generator.ts |
| **Semantic Graph** | 管理工作流的语义表示和节点关系 | semantic-graph.ts |
| **Workflow Builder** | 提供工作流构建的高级 API | workflow-builder.ts |
| **多代理系统** | 协调不同专业代理完成复杂任务 | agents/ 目录 |
## 提示构建器（PromptBuilder）
### 设计理念
PromptBuilder 是一个类型安全的、流畅式（Fluent）API，用于组合 LLM 提示。该类支持条件化内容块、延迟求值、多种输出格式以及与 LangChain 的深度集成。资料来源：[prompt-builder.ts:1-100]()
PromptBuilder 的核心设计原则包括：
1. **可组合性**：通过 `merge()` 方法可以合并多个 PromptBuilder 实例
2. **延迟求值**：工厂函数仅在构建时求值，避免不必要的计算
3. **条件渲染**：通过 `sectionIf()` 和 `examplesIf()` 支持条件化内容
4. **格式灵活性**：支持 XML 标签格式和 Markdown 格式
### 核心方法
```typescript
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[];
}
```
### 使用示例
```typescript
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` 类型定义：
| 格式 | 说明 | 示例输出 |
|------|------|----------|
| `xml` | XML 标签格式（默认） | `内容` |
| `markdown` | Markdown 标题格式 | `## Section Name\n内容` |
### 段落选项配置
```typescript
interface SectionOptions {
format?: SectionFormat; // 覆盖默认格式
tag?: string; // 自定义标签名
}
```
## 代码构建器提示系统
### 系统提示构建流程
```mermaid
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]()
### 提示组件列表
| 组件 | 用途 | XML 标签 |
|------|------|----------|
| `ROLE` | 定义 AI 角色和行为 | `` |
| `RESPONSE_STYLE` | 规定响应格式和风格 | `` |
| `WORKFLOW_RULES` | 工作流构建规则 | `` |
| `WORKFLOW_PATTERNS` | 常见工作流模式 | `` |
| `EXPRESSION_REFERENCE` | 表达式语法参考 | `` |
| `ADDITIONAL_FUNCTIONS` | 额外可用函数 | `` |
| `mandatory_workflow_process` | 强制性工作流处理流程 | `` |
### 用户消息构建
用户消息部分通过 `buildUserMessageParts()` 函数构建，包含以下可选组件：
1. **当前工作流上下文**：当存在正在进行的工作流时提供
2. **历史上下文**：多轮对话中的历史记录
3. **工作流文件状态**：检查是否存在现有工作流代码
4. **已批准的计划输出**：计划模式的结果
5. **预搜索结果**：提前获取的搜索结果以节省 LLM 交互
```typescript
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 的上下文缓存：
```typescript
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]()
| 代理 | 职责 | 说明 |
|------|------|------|
| **Supervisor** | 路由用户请求 | 将请求分发到合适的专业代理 |
| **Discovery** | 发现和分类 | 识别相关 n8n 节点并分类技术 |
| **Builder** | 构建工作流 | 创建工作流结构并配置节点参数 |
| **Responder** | 生成响应 | 生成面向用户的结果输出 |
### 链式提示系统
`chains/` 目录包含用于特定 LLM 链操作的提示：
| 链 | 用途 | 说明 |
|-----|------|------|
| **Categorization** | 分析用户提示 | 识别工作流技术和模式 |
| **Compact** | 压缩对话 | 总结对话以便后续处理 |
## 节点与参数指南系统
### 指南注册机制
n8n 提供了基于模式的节点指南系统，通过 `NodeTypeGuide` 接口定义：
```typescript
interface NodeTypeGuide {
patterns: string[]; // 匹配节点类型的模式
condition?: (ctx: GuideContext) => boolean; // 额外条件
content: string; // 指南内容
}
```
### 内置指南列表
| 指南 | 节点模式 | 用途 |
|------|----------|------|
| Set Node | `n8n-nodes-base.set` | 赋值结构与类型 |
| IF Node | `n8n-nodes-base.if` | 过滤条件与运算符 |
| Switch Node | `n8n-nodes-base.switch` | 规则和路由 |
| HTTP Request | `n8n-nodes-base.httpRequest` | URL、头、请求体、认证 |
| Tool Nodes | `*Tool` | $fromAI 表达式 |
| Resource Locator | `*` (条件性) | __rl 结构和模式 |
| System Message | `*` (条件性) | AI 节点消息分离 |
| Text Fields | `*` (条件性) | 表达式处理 |
资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/guides/README.md]()
### 添加新指南
1. 在 `guides/` 目录创建新的指南文件
2. 从 `guides/index.ts` 导出
3. 在 `registry.ts` 的注册数组中添加
## 工具系统
### Web 获取工具
`WebFetchTool` 提供了网页内容抓取能力，使用可读内容提取器处理 HTML 响应：
```mermaid
graph TD
A[URL 输入] --> B[URL 验证]
B --> C[安全检查]
C --> D[HTTP 请求]
D --> E[内容提取]
E --> F[可读内容提取]
F --> G[状态记录]
G --> H[响应构建]
H --> I[]
```
### 工具响应格式
```xml
原始URL
最终URL
页面标题
提取的内容
截断说明（可选）
```
资料来源：[packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts]()
## 构建与生成流程
### 工作流生成流程
```mermaid
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）负责：
- 管理工作流节点和连接的语义表示
- 提供节点关系的查询接口
- 支持工作流的语义验证
## 类型系统
### 关键类型定义
```typescript
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 配置选项
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `format` | `SectionFormat` | `'xml'` | 默认输出格式 |
| `separator` | `string` | `'\n\n'` | 段落分隔符 |
### 段落格式配置
```typescript
// 使用自定义分隔符
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 的深度集成。这些设计使得工作流构建系统既灵活又高效，能够满足不同场景下的工作流生成需求。
---
## 工作流执行引擎
### 相关页面
相关主题：[工作流 SDK 与构建器](#page-workflow-sdk), [数据库实体与数据管理](#page-database-entities)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts)
- [packages/cli/src/active-workflow-manager.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/active-workflow-manager.ts)
- [packages/cli/src/executions/execution.service.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/executions/execution.service.ts)
- [packages/@n8n/expression-runtime/src/evaluator/expression-evaluator.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/expression-runtime/src/evaluator/expression-evaluator.ts)
- [packages/@n8n/workflow-sdk/src/ast-interpreter/interpreter.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/workflow-sdk/src/ast-interpreter/interpreter.ts)
# 工作流执行引擎
## 概述
n8n 的工作流执行引擎是自动化工作流的运行时核心，负责协调节点的执行顺序、管理数据流转、处理表达式求值以及维护执行状态。该引擎支持手动执行和生产执行两种模式，能够在不同的触发条件下激活工作流实例。
工作流执行引擎的核心职责包括：
1. **节点调度**：根据工作流定义的有向图结构，确定节点的执行顺序
2. **数据传递**：在节点之间传递输入输出数据，处理二进制和 JSON 数据
3. **表达式求值**：在运行时解析和计算表达式，支持变量引用和函数调用
4. **版本管理**：支持工作流的草稿版本和生产版本区分
5. **错误处理**：捕获节点执行异常，提供重试和错误恢复机制
## 核心架构
### 执行模式
n8n 工作流执行引擎支持两种主要执行模式：
| 执行模式 | 描述 | 适用场景 |
|---------|------|---------|
| `manual` | 手动触发执行 | 调试、测试、单次运行 |
| `production` | 生产环境执行 | 定时任务、Webhook、API 调用 |
生产模式执行时，系统会验证工作流是否已激活并具有活跃版本。若工作流没有已发布（active）的版本，执行将被拒绝并抛出 `WorkflowAccessError` 错误。
```typescript
资料来源：[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',
);
}
```
### 版本数据管理
工作流执行引擎根据执行模式选择对应的版本数据：
```mermaid
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` 函数根据执行模式选择正确的版本数据：
```typescript
资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:14-24]()
const getVersionDataForExecution = (
workflow: FoundWorkflow,
workflowId: string,
executionMode: z.infer['executionMode'],
) => {
const nodes =
executionMode === 'production'
? (workflow.activeVersion?.nodes ?? [])
: (workflow.nodes ?? []);
const connections =
executionMode === 'production'
? (workflow.activeVersion?.connections ?? {})
: (workflow.connections ?? {});
return { nodes, connections };
};
```
## 触发节点机制
### 支持的触发节点
工作流执行引擎仅支持特定类型的触发节点。系统定义了 `getSupportedTriggerNamesForMode` 函数来获取当前执行模式支持的触发器名称列表：
```typescript
资料来源：[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，用于队列模式下的关联和追踪：
```typescript
资料来源：[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 而非字符串解析方式处理表达式，具有以下优势：
| 特性 | 传统方式 | AST 方式 |
|------|---------|---------|
| 解析速度 | 每次求值重新解析 | 预编译为 AST |
| 错误检测 | 运行时才发现 | 预编译时验证 |
| 优化能力 | 有限 | 支持常量折叠 |
| 调试能力 | 困难 | 可追踪执行路径 |
## 错误处理机制
### 验证错误
引擎使用 Zod 进行输入验证，当验证失败时会创建 `ValidationError` 并记录详细错误信息：
```typescript
资料来源：[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`，错误类型包括：
| 错误类型 | 触发条件 |
|---------|---------|
| `workflow_not_active` | 生产模式执行但工作流未激活 |
| `unsupported_trigger` | 工作流不包含支持的触发节点 |
## 执行服务
### 执行服务架构
执行服务（Execution Service）负责管理执行的生命周期，包括：
1. **执行创建**：初始化新的执行实例
2. **执行排队**：将执行请求加入执行队列
3. **执行监控**：跟踪执行进度和状态
4. **执行完成**：保存执行结果并清理资源
### 活跃工作流管理器
活跃工作流管理器（Active Workflow Manager）维护当前活跃工作流的注册表，负责：
- 工作流激活与停用
- 触发器注册与移除
- 活跃连接管理
```mermaid
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 执行工具的核心功能：
- 接收外部执行请求
- 验证工作流和用户权限
- 选择正确的执行模式
- 返回执行结果
### 执行模式配置
引擎支持通过配置选项自定义执行行为：
```typescript
// 执行请求输入模式定义
const inputSchema = z.object({
executionMode: z.enum(['production', 'manual']),
inputs: z.record(z.any()).optional(),
});
```
## 数据流处理
### 输入数据处理
工作流执行引擎支持通过 `inputs` 参数向工作流传递初始数据：
```mermaid
graph TD
A[外部输入] --> B[inputs 验证]
B --> C{验证通过?}
C -->|是| D[注入到触发节点]
C -->|否| E[返回验证错误]
D --> F[开始节点执行]
```
### 输出数据返回
执行完成后，引擎收集所有节点的输出数据，整理为统一的响应格式返回给调用方。
## 相关组件
| 组件 | 包路径 | 职责 |
|------|-------|------|
| 执行服务 | `packages/cli/src/executions/` | 执行生命周期管理 |
| 活跃工作流管理器 | `packages/cli/src/active-workflow-manager.ts` | 工作流激活状态管理 |
| 表达式求值器 | `packages/@n8n/expression-runtime/src/evaluator/` | 表达式运行时解析 |
| AST 解释器 | `packages/@n8n/workflow-sdk/src/ast-interpreter/` | 高级表达式处理 |
| MCP 执行工具 | `packages/cli/src/modules/mcp/tools/` | 外部协议集成 |
---
## AI Agent 运行时
### 相关页面
相关主题：[LangChain 节点集成](#page-langchain-nodes), [AI 工作流构建器](#page-ai-workflow-builder)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@n8n/agents/src/runtime/agent-runtime.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/agents/src/runtime/agent-runtime.ts)
- [packages/@n8n/agents/src/runtime/mcp-tool-resolver.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/agents/src/runtime/mcp-tool-resolver.ts)
- [packages/@n8n/agents/src/sdk/agent.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/agents/src/sdk/agent.ts)
- [packages/@n8n/agents/src/runtime/message-list.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/agents/src/runtime/message-list.ts)
# AI Agent 运行时
## 概述
AI Agent 运行时（Agent Runtime）是 n8n 平台中负责执行 AI 代理的核心组件系统。该运行时负责管理代理的生命周期、消息处理、工具调用以及与外部系统（如 MCP 服务器）的集成。运行时架构设计遵循模块化原则，将核心逻辑与具体实现解耦，使得系统具备良好的可扩展性和可维护性。
运行时系统的核心职责包括：
- **消息管理**：维护对话历史，处理用户输入与模型输出的流转
- **工具解析**：解析并执行 MCP（Model Context Protocol）工具调用
- **状态管理**：跟踪代理执行状态，处理错误恢复
- **上下文维护**：管理代理的长期记忆和会话状态
## 核心组件架构
AI Agent 运行时由多个协同工作的组件构成，每个组件承担特定的职责。以下是主要组件及其功能：
```mermaid
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 工具
- 验证工具参数
- 执行工具调用
- 处理工具返回结果
## 消息处理流程
运行时采用事件驱动的消息处理模式，确保每条消息都能得到正确处理并返回相应的响应。
```mermaid
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` 中实现。
工具描述生成流程：
```typescript
// 工具描述自动生成逻辑
const descriptionType: INodeProperties = {
displayName: 'Tool Description',
name: 'descriptionType',
type: 'options',
options: [
{ name: 'Set Automatically', value: 'auto' },
{ name: 'Set Manually', value: 'manual' },
],
default: 'auto',
};
```
### 工具属性处理
运行时支持两种工具描述设置模式：
| 模式 | 说明 | 适用场景 |
|------|------|----------|
| 自动设置（auto） | 基于 resource 和 operation 参数自动推断描述 | 标准 n8n 节点 |
| 手动设置（manual） | 用户提供自定义工具描述 | 复杂或特殊用途工具 |
当节点包含 `resource` 和 `operation` 属性时，运行时可以自动生成语义化的工具描述，使 LLM 能够更准确地理解和调用工具。
## Prompt 构建系统
AI Workflow Builder 使用 `PromptBuilder` 组件构建发送给 LLM 的提示词。该构建器采用流式 API 设计，支持灵活的提示词组装。
### PromptBuilder 核心特性
```mermaid
graph LR
A[section] --> B[sectionIf]
A --> C[examples]
A --> D[examplesIf]
B --> E[build]
C --> E
D --> E
```
主要方法：
| 方法 | 说明 | 用途 |
|------|------|------|
| `section()` | 添加静态内容区块 | 基础提示词组装 |
| `sectionIf()` | 条件性添加区块 | 动态内容控制 |
| `examples()` | 添加少样本示例 | Few-shot 学习 |
| `examplesIf()` | 条件性添加示例 | 条件化示例注入 |
| `merge()` | 合并多个构建器 | 提示词复用 |
| `build()` | 生成最终提示词 | 输出结果 |
### 示例格式化
`PromptBuilder` 支持多种输出格式：
```typescript
// Markdown 格式
const markdownOutput = `## Examples\n${examplesContent}`;
// XML 格式
const xmlOutput = `\n${examplesContent}\n`;
```
构建器会根据配置自动选择合适的格式化方式，确保与不同 LLM API 的兼容性。
## Web Fetch 工具
运行时不直接提供网络获取功能，而是通过 `web-fetch.tool.ts` 实现网页内容提取。该工具将获取的网页转换为 LLM 可处理的结构化文本。
处理流程：
1. 发送 HTTP 请求获取页面内容
2. 提取可读文本和标题
3. 处理内容截断和错误情况
4. 返回结构化结果
返回格式示例：
```xml
https://example.com
页面标题
提取的正文内容...
```
## MCP 浏览器集成
n8n 提供了 MCP（Model Context Protocol）浏览器工具，用于在开发环境中测试 MCP 服务器功能。该工具支持多种 AI 客户端配置，包括 Claude Desktop、Cursor、Windsurf 等。
### 开发环境配置
```bash
# 启动 MCP 服务器
npx @n8n/mcp-browser --transport http --port 3100
```
### 客户端配置示例
```json
{
"mcpServers": {
"n8n-browser": {
"url": "http://localhost:3100/mcp"
}
}
}
```
## 错误处理机制
运行时实现了完善的错误处理机制，确保代理在遇到异常情况时能够优雅地降级或恢复：
- **验证错误**：通过 Zod 进行输入参数验证
- **工具执行错误**：捕获并记录工具调用异常
- **网络错误**：处理 MCP 服务器连接问题
- **上下文溢出**：管理令牌使用量，避免超出限制
```typescript
// 验证错误处理示例
if (error instanceof z.ZodError) {
const validationError = new ValidationError('Invalid URL input', {
extra: { errors: error.errors },
});
reporter.error(validationError);
}
```
## 数据流总结
```mermaid
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
```
## 相关配置
运行时的行为可通过多种方式配置：
| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| 上下文窗口 | 单次请求的最大消息数 | 依赖模型限制 |
| 工具超时 | 单个工具调用的最大执行时间 | 30秒 |
| 重试次数 | 工具调用失败时的重试次数 | 3 |
| 日志级别 | 运行时的日志详细程度 | info |
## 扩展指南
### 添加新的工具解析器
要扩展工具系统，需要实现 `ToolResolver` 接口：
```typescript
interface ToolResolver {
resolve(toolCall: ToolCall): Promise;
getAvailableTools(): ToolDefinition[];
validateParams(params: unknown): boolean;
}
```
### 集成新的 MCP 服务器
1. 在 MCP 配置中注册服务器端点
2. 实现服务器端的工具定义
3. 配置 `MCPToolResolver` 连接参数
## 总结
AI Agent 运行时是 n8n 平台智能化能力的核心支撑。通过模块化的组件设计，系统实现了高效的消息处理、灵活的提示词构建和完善的工具调用机制。开发者可以通过扩展现有组件或集成新的 MCP 服务器来增强运行时功能，以满足各种复杂的 AI 工作流需求。
---
## LangChain 节点集成
### 相关页面
相关主题：[AI Agent 运行时](#page-agents-runtime)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)
- [packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts)
- [packages/frontend/@n8n/design-system/src/locale/lang/en.ts](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/locale/lang/en.ts)
- [packages/frontend/editor-ui/src/features/shared/editors/composables/useCodeEditor.ts](https://github.com/n8n-io/n8n/blob/main/packages/frontend/editor-ui/src/features/shared/editors/composables/useCodeEditor.ts)
# LangChain 节点集成
## 概述
LangChain 节点集成是 n8n 工作流自动化平台中用于构建 AI 驱动工作流的**核心组件体系**。该集成通过提供标准化的节点、工具和提示构建系统，使开发者能够在 n8n 工作流中无缝调用 LangChain 的语言模型、代理（Agent）和工具链能力。
LangChain 节点集成的主要功能包括：
- **语言模型（LLM）节点**：支持 OpenAI、Anthropic 等多种语言模型的调用
- **代理（Agent）节点**：基于 LangChain 构建的 AI 代理，支持多种推理策略
- **工具（Tools）节点**：提供 Web 抓取、代码执行等工具扩展
- **提示构建系统**：基于 `PromptBuilder` 的类型安全、fluent API
## 架构设计
### 整体架构
LangChain 节点集成采用分层架构设计，各组件之间通过标准接口进行通信：
```mermaid
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：
| 特性 | 说明 |
|------|------|
| 流式 API | 支持方法链式调用 |
| 条件部分 | `sectionIf()` 支持动态内容 |
| 延迟求值 | 工厂函数仅在构建时执行 |
| 输出格式 | 支持 XML 标签和 Markdown 标题 |
| LangChain 集成 | 支持 message blocks 和 cache_control |
## 提示构建系统
### PromptBuilder 类接口
`PromptBuilder` 类位于 `packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts`，提供以下核心方法：
```typescript
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]()
### 使用示例
```typescript
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`。其工作流程如下：
```mermaid
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 结构，包含以下元素：
| 元素 | 说明 |
|------|------|
| `` | 原始请求 URL |
| `` | 最终重定向后的 URL（可选） |
| `` | 网页标题 |
| `<content>` | 提取的内容 |
| `<note>` | 截断说明（当内容被截断时） |
```xml
<web_fetch_result>
<url>https://example.com</url>
<title>Example Domain
[提取的内容]
```
资料来源：[web-fetch.tool.ts:26-43]()
## 节点指南系统
### 指南注册机制
n8n 的 AI workflow builder 通过指南系统（Guides）为不同类型的节点提供上下文相关的帮助信息：
```mermaid
graph LR
A[用户操作] --> B{匹配节点类型}
B -->|Set 节点| C[赋值结构与类型指南]
B -->|IF 节点| D[过滤条件与操作符指南]
B -->|HTTP Request| E[URL、Header、Body、认证指南]
B -->|Tool 节点| F[$fromAI 表达式指南]
```
### 指南配置结构
每个节点指南的定义包含以下属性：
| 属性 | 类型 | 说明 |
|------|------|------|
| `patterns` | `string[]` | 匹配节点类型的模式 |
| `condition` | `(ctx) => boolean` | 可选：额外的上下文条件 |
| `content` | `string` | 指南内容 |
```typescript
export const MY_NODE_GUIDE: NodeTypeGuide = {
patterns: ['n8n-nodes-base.myNode'],
condition: (ctx) => true,
content: `Your guide content here...`,
};
```
资料来源：[README.md (prompts)](packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)
## 前端编辑器集成
### 代码编辑器组件
n8n 前端使用 CodeMirror 6 实现代码编辑器，位于 `packages/frontend/editor-ui/src/features/shared/editors/composables/useCodeEditor.ts`：
```typescript
const editor = ref();
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 相关的界面文本：
| 文本键 | 说明 |
|--------|------|
| `assistantChat.builder.name` | AI Builder 界面名称 |
| `assistantChat.builder.generatingFinalWorkflow` | 生成最终工作流时的提示 |
| `assistantChat.builder.configuredNodes` | 已配置节点 |
| `assistantChat.rating.thumbsUp` | 有帮助 |
| `assistantChat.rating.thumbsDown` | 没有帮助 |
| `assistantChat.rating.feedbackPlaceholder` | 反馈占位符 |
## 多代理提示系统
### 代理类型
提示系统支持多种专业化代理：
| 代理 | 功能 |
|------|------|
| **Supervisor** | 将用户请求路由到合适的专业代理 |
| **Discovery** | 识别相关 n8n 节点并分类技术 |
| **Builder** | 创建工作流结构并配置节点参数 |
| **Responder** | 生成面向用户的响应 |
所有代理提示都使用 `PromptBuilder` 进行统一组合。
### 链式提示
除了代理提示外，系统还包含用于特定 LLM 链式操作的提示：
| 链 | 功能 |
|----|------|
| **Categorization** | 分析用户提示以识别工作流技术 |
| **Compact** | 压缩对话以节省上下文 |
## 安全性与状态管理
### 安全状态追踪
WebFetch 工具实现了安全状态追踪机制：
```typescript
const stateUpdates: Record = {
...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](https://docs.n8n.io/)
- LangChain 官方文档：[LangChain.js](https://js.langchain.com/)
- 源码仓库：[n8n-io/n8n](https://github.com/n8n-io/n8n)
---
## AI 工作流构建器
### 相关页面
相关主题：[AI Agent 运行时](#page-agents-runtime), [工作流 SDK 与构建器](#page-workflow-sdk)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts)
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)
- [packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)
- [packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts)
- [packages/testing/rules-engine/README.md](https://github.com/n8n-io/n8n/blob/main/packages/testing/rules-engine/README.md)
# AI 工作流构建器
## 概述
AI 工作流构建器是 n8n 平台中一个基于大语言模型（LLM）的智能工作流创建系统。该系统通过多代理（Multi-Agent）架构，允许用户使用自然语言描述需求，自动生成 n8n 工作流代码。该模块位于 `packages/@n8n/ai-workflow-builder.ee` 包中，是 n8n 企业版的重要组成部分。
AI 工作流构建器的主要特点包括：
- **自然语言驱动**：用户通过自然语言描述工作流需求
- **多代理协作**：多个专业代理协同工作，各司其职
- **代码生成**：自动生成可执行的工作流代码（JavaScript/TypeScript）
- **上下文感知**：能够理解当前工作流状态并进行多轮优化
- **工具集成**：支持网络搜索、文档获取等辅助工具
## 系统架构
### 多代理架构
AI 工作流构建器采用多代理架构设计，每个代理拥有特定的角色和职责：
| 代理 | 用途 | 说明 |
|------|------|------|
| **Supervisor** | 主管代理 | 路由用户请求到合适的专业代理 |
| **Discovery** | 发现代理 | 识别相关 n8n 节点并分类技术 |
| **Builder** | 构建代理 | 创建工作流结构并配置节点参数 |
| **Responder** | 响应代理 | 生成面向用户的响应 |
资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)
```mermaid
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](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)
### 核心功能
```typescript
const systemPrompt = prompt()
.section('role', 'You are an assistant')
.sectionIf(hasContext, 'context', () => buildContext())
.examples('examples', data, (ex) => `${ex.input} → ${ex.output}`)
.build();
```
| 方法 | 说明 |
|------|------|
| `section(name, content)` | 添加始终包含的部分 |
| `sectionIf(condition, name, content)` | 根据条件添加部分 |
| `examples(name, data, formatter)` | 添加少样本示例 |
| `merge(other)` | 合并另一个 PromptBuilder |
| `build()` | 构建最终的提示词字符串 |
| `buildAsMessageBlocks()` | 构建为 LangChain 消息块 |
### 格式化选项
PromptBuilder 支持两种输出格式：
| 格式 | 说明 | 示例 |
|------|------|------|
| `xml` | XML 标签格式（默认） | `...` |
| `markdown` | Markdown 标题格式 | `## Role\n...` |
## 代码构建器
### 系统提示词构建
代码构建器通过 `buildCodeBuilderPrompt` 函数构建完整的系统提示词，该函数整合多个组件：
```typescript
export function buildCodeBuilderPrompt(
currentWorkflow?: WorkflowJSON,
historyContext?: HistoryContext,
options?: BuildCodeBuilderPromptOptions,
): ChatPromptTemplate
```
资料来源：[packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts)
### 提示词组成部分
系统提示词由以下部分组成：
```mermaid
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` 函数构建，支持以下可选组件：
| 组件 | 条件 | 说明 |
|------|------|------|
| 当前工作流 JSON | 始终存在 | 工作流的当前状态 |
| 对话历史 | historyContext 存在 | 多轮对话上下文 |
| 计划输出 | planOutput 存在 | 规划代理的输出结果 |
| 预搜索结果 | preSearchResults 存在 | 预先获取的节点搜索结果 |
```typescript
function buildUserMessageParts(
currentWorkflow?: WorkflowJSON,
historyContext?: HistoryContext,
options?: BuildCodeBuilderPromptOptions,
): string[]
```
资料来源：[packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts)
### XML 标签包装
系统使用 XML 标签封装不同类型的信息，便于解析：
| 标签 | 用途 |
|------|------|
| `...` | 代理角色定义 |
| `...` | 响应风格指导 |
| `...` | 工作流生成规则 |
| `...` | 工作流文件内容 |
| `...` | 已批准的计划 |
| `...` | 节点搜索结果 |
| `...` | 用户请求 |
| `...` | 网页抓取结果 |
## 工具系统
### 网页抓取工具
`WebFetchTool` 允许 AI 代理获取网页内容以辅助决策：
```mermaid
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](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts)
### 工具响应格式
工具执行完成后返回结构化的响应，包含状态更新信息：
```typescript
interface ToolResponse {
status: 'success' | 'error';
url?: string;
finalUrl?: string;
truncated?: boolean;
}
const stateUpdates: Record = {
...security.getStateUpdates(),
fetchedUrlContent: [{
url,
status: 'success' as const,
title: extracted.title,
content: extracted.content,
}],
};
```
### 安全状态追踪
网页抓取工具集成了安全状态追踪机制，记录所有抓取操作并生成相应的状态更新：
- `security.recordFetch()` - 记录抓取操作
- `security.getStateUpdates()` - 获取状态更新
## 节点指南系统
### 指南注册表
n8n 为常见节点提供专门的指南，帮助 AI 代理正确理解和配置节点：
| 指南 | 节点模式 | 用途 |
|------|----------|------|
| Set Node | `n8n-nodes-base.set` | 赋值结构与类型 |
| IF Node | `n8n-nodes-base.if` | 过滤条件与运算符 |
| Switch Node | `n8n-nodes-base.switch` | 规则和路由 |
| HTTP Request | `n8n-nodes-base.httpRequest` | URL、头部、请求体、认证 |
| Tool Nodes | `*Tool` | $fromAI 表达式 |
| Resource Locator | `*` | __rl 结构与模式 |
| System Message | `*` | AI 节点消息分离 |
| Text Fields | `*` | 表达式输入框 |
资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)
### 条件化指南
某些指南仅在特定上下文中适用，使用 `condition` 属性控制：
```typescript
export const RESOURCE_LOCATOR_GUIDE: NodeTypeGuide = {
patterns: ['*'], // 匹配所有节点
condition: (ctx) => ctx.hasResourceLocatorParams === true,
content: `...`,
};
```
## LangChain 集成
### 消息块构建
PromptBuilder 支持构建 LangChain 兼容的消息块，带有缓存控制支持：
```typescript
return ChatPromptTemplate.fromMessages([
['system', [{
type: 'text',
text: systemMessage,
cache_control: { type: 'ephemeral' }
}]],
['user', userMessageTemplate],
]);
```
### 缓存策略
系统使用 LangChain 的 `cache_control` 机制进行提示词缓存优化：
- `ephemeral` - 临时缓存，仅在当前请求周期内有效
- 适用于频繁使用但频繁变化的内容
## 工作流状态管理
工作流状态由 `workflow-state.ts` 管理，跟踪工作流的当前配置和历史变更。状态信息在多代理协作中流转，确保每个代理都能访问一致的工作流上下文。
## 代码节点编辑器补全
### 输入方法补全
AI 工作流构建器为 `$input` 对象提供智能补全支持：
| 方法 | 模式 | 说明 |
|------|------|------|
| `first()` | `$input.first().` | 获取第一个输入项 |
| `last()` | `$input.last().` | 获取最后一个输入项 |
| `item` | `$input.item.` | 获取当前项 |
| `all()[index]` | `$input.all()[index].` | 获取指定索引项 |
补全选项包括 `.json` 和 `.binary` 两种数据类型访问方式。
资料来源：[packages/frontend/editor-ui/src/features/shared/editors/components/CodeNodeEditor/completions/itemField.completions.ts](https://github.com/n8n-io/n8n/blob/main/packages/frontend/editor-ui/src/features/shared/editors/components/CodeNodeEditor/completions/itemField.completions.ts)
## 规则引擎
### 架构规则
AI 工作流构建器的测试框架使用规则引擎进行架构验证：
| 规则 | 严重性 | 说明 |
|------|--------|------|
| `boundary-protection` | error | 防止页面间直接导入 |
| `scope-lockdown` | error | 强制页面对象的显式架构意图 |
资料来源：[packages/testing/rules-engine/README.md](https://github.com/n8n-io/n8n/blob/main/packages/testing/rules-engine/README.md)
## 最佳实践
### 提示词构建
1. **使用条件化部分**：通过 `sectionIf()` 按需包含内容，减少不必要的上下文
2. **延迟求值**：使用工厂函数避免不必要的计算
3. **适当格式化**：XML 格式便于程序解析，Markdown 格式便于调试
4. **缓存控制**：对频繁使用的系统提示词部分使用缓存标记
### 代理协作
1. **职责分离**：每个代理应专注于特定任务
2. **状态传递**：通过标准化的工作流状态对象在各代理间传递信息
3. **错误处理**：工具执行应包含完整的错误处理和状态回滚机制
## 相关链接
- [n8n 官方文档](https://docs.n8n.io/)
- [n8n GitHub 仓库](https://github.com/n8n-io/n8n)
- [AI 工作流构建器源码](https://github.com/n8n-io/n8n/tree/main/packages/@n8n/ai-workflow-builder.ee)
---
## 数据库实体与数据管理
### 相关页面
相关主题：[工作流执行引擎](#page-execution-engine), [系统架构概览](#page-architecture)
根据提供的上下文，我没有找到查询中要求的相关数据库实体文件（如 `workflow-entity.ts`、`execution-entity.ts`、`credentials-entity.ts`、`workflow.repository.ts` 等）。
提供的上下文主要包含以下内容：
- **前端国际化文件**：`packages/frontend/@n8n/design-system/src/locale/lang/en.ts`
- **前端组件测试**：`packages/frontend/editor-ui/src/app/components/MainHeader/MainHeader.test.ts`
- **AI工作流构建器**：`packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts`、`web-fetch.tool.ts`、`prompt-builder.ts`
- **SSO SAML认证**：各种XSD schema文件
- **测试框架文档**：`packages/testing/janitor/README.md`
- **节点开发CLI**：`packages/@n8n/node-cli/README.md`
- **评估框架**：`packages/@n8n/ai-workflow-builder.ee/evaluations/README.md`
- **UI组件文档**：`packages/frontend/@n8n/design-system/src/components/N8nSwitch/component-switch.md`
---
如果您能提供数据库实体相关的源文件（如 `packages/@n8n/db/src/entities/*.ts`），我可以为您生成关于"数据库实体与数据管理"的完整技术文档。
或者，如果您希望我基于当前上下文中实际存在的文件生成文档，我可以撰写以下主题：
1. **n8n前端国际化系统**
2. **AI工作流构建器提示词系统**
3. **Playwright测试框架架构**
4. **n8n节点CLI开发工具**
请告知您希望处理哪个方向。
---
---
## Doramagic 踩坑日志
项目：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