= {\n completed: 'success',\n pending: 'warning',\n failed: 'danger',\n }\n return themeMap[status] || 'default'\n}\n```\n\n资料来源：[component-badge.md:25-35]()\n\n### Popover 组件\n\n`N8nPopover` 组件提供弹出式内容展示功能。资料来源：[component-popover.md:1]()\n\n#### 核心属性\n\n| 属性 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| side | 'top' \\| 'bottom' \\| 'left' \\| 'right' | 'bottom' | 弹出方向 |\n| width | string | '300px' | 弹出框宽度 |\n| teleported | boolean | true | 是否传送到 body |\n| side-offset | number | 8 | 与触发器的偏移量 |\n\n#### 使用示例\n\n**带触发的下拉菜单：**\n\n```vue\n\n \n \n \n \n \n \n\n```\n\n资料来源：[component-popover.md:10-25]()\n\n**使用关闭函数：**\n\n```vue\n\n \n \n \n \n \n \n\n```\n\n资料来源：[component-popover.md:70-80]()\n\n---\n\n## Markdown 渲染选项\n\n### useChatHubMarkdownOptions\n\n`useChatHubMarkdownOptions` 是聊天中心使用的 Markdown 渲染配置 hook。资料来源：[useChatHubMarkdownOptions.ts:1]()\n\n### 插件列表\n\n| 插件名称 | 功能 |\n|---------|------|\n| linksNewTabPlugin | 将链接在新标签页打开 |\n| codeBlockPlugin | 代码块渲染增强 |\n| tablePlugin | 表格渲染支持 |\n| mathPlugin | 数学公式渲染 |\n| footnotePlugin | 脚注功能（隐藏显示，仅保留胶囊） |\n\n### 脚注处理\n\n聊天中心对脚注进行了特殊处理，将脚注块隐藏，仅保留可点击的脚注引用胶囊：\n\n```typescript\nconst footnotePlugin = () => {\n // Hide the footnote block — the pill is the only UI for footnote content\n md.renderer.rules.footnote_block_open = () => '';\n md.renderer.rules.footnote_block_close = () => '
';\n md.renderer.rules.footnote_open = () => '';\n md.renderer.rules.footnote_close = () => '';\n md.renderer.rules.footnote_anchor = () => '';\n};\n```\n\n资料来源：[useChatHubMarkdownOptions.ts:25-32]()\n\n### 链接新标签页处理\n\n链接在新标签页打开时会显示完整的 URL 作为 tooltip：\n\n```typescript\nconst linksNewTabPlugin = () => {\n const defaultRender = md.renderer.rules.link_open || /* ... */;\n md.renderer.rules.link_open = (tokens, idx, options, env, self) => {\n const aIndex = tokens[idx].attrIndex('target');\n if (aIndex < 0) {\n tokens[idx].attrPush(['target', '_blank']);\n } else {\n tokens[idx].attrs[aIndex][1] = '_blank';\n }\n // ...\n const escapedFull = encoder.encode(fullHref);\n const escapedTruncated = encoder.encode(truncatedHref);\n return `${escapedTruncated}`;\n };\n};\n```\n\n资料来源：[useChatHubMarkdownOptions.ts:8-24]()\n\n---\n\n## SSO/SAML 认证\n\n### SAML 2.0 协议支持\n\nn8n 提供了完整的 SAML 2.0 协议支持，包括以下核心功能：\n\n- **Artifact 处理**：支持 SAML Artifact 绑定\n- **单点登出 (SLO)**：支持 ManageNameID 和 LogoutRequest\n- **名称标识管理**：支持 NameID 的加密和转换\n\n资料来源：[saml-schema-protocol-2.0.xsd.ts:1]()\n\n### Web 服务安全策略\n\nWS-SecurityPolicy 1.2 定义了 SOAP 消息的安全策略，包括：\n\n| 策略类型 | 说明 |\n|---------|------|\n| TransportBinding | 传输层绑定 |\n| SymmetricBinding | 对称密钥绑定 |\n| X509Token | X.509 证书令牌 |\n| Trust13 | Trust 1.3 断言 |\n| AlgorithmSuite | 加密算法套件 |\n\n资料来源：[ws-securitypolicy-1.2.xsd.ts:1]()\n\n---\n\n## 常见问题\n\n### 如何调试 AI 工作流？\n\n使用 `PromptBuilder` 的 `build()` 方法可以预览最终的提示词内容：\n\n```typescript\nconst builder = new PromptBuilder();\nbuilder.addSection('instruction', '回答用户问题');\nbuilder.addExamples(['示例1', '示例2']);\nconsole.log(builder.build());\n```\n\n### Web 获取工具返回的内容被截断了怎么办？\n\n工具默认会对超长内容进行截断。如果需要完整内容，可以在工具配置中调整 `maxContentLength` 参数。\n\n### 设计系统组件在 SSR 环境中使用注意事项？\n\n`N8nPopover` 默认使用 `teleported` 模式，会将内容传送到 `body`。在 SSR 环境中，建议设置 `:teleported=\"false\"` 以保持 DOM 层级一致：\n\n```vue\n\n \n\n```\n\n---\n\n## 下一步\n\n- 查看 [CONTRIBUTING.md](https://github.com/n8n-io/n8n/blob/main/CONTRIBUTING.md) 了解贡献指南\n- 探索更多 [AI 工作流示例](https://github.com/n8n-io/n8n/tree/main/packages/@n8n/ai-workflow-builder.ee)\n- 阅读 [设计系统文档](https://github.com/n8n-io/n8n/tree/main/packages/frontend/@n8n/design-system)\n\n---\n\n\n\n## 系统架构概览\n\n### 相关页面\n\n相关主题：[包结构与模块组织](#page-package-structure), [工作流 SDK 与构建器](#page-workflow-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# 系统架构概览\n\n## 概述\n\nn8n 是一个开源的工作流自动化平台，其核心架构围绕模块化设计构建。系统架构概览旨在帮助开发者理解 n8n 平台的关键组件、它们之间的交互关系以及扩展机制。\n\n从源码层面分析，n8n 的架构涵盖以下几个核心领域：\n\n| 模块 | 功能描述 | 所在包 |\n|------|---------|--------|\n| AI Workflow Builder | 支持 AI 功能的工作流构建器 | `@n8n/ai-workflow-builder.ee` |\n| Prompt Builder | 动态提示词构建工具 | `@n8n/ai-workflow-builder.ee/src/prompts` |\n| Web Fetch Tool | 网页内容抓取与提取 | `@n8n/ai-workflow-builder.ee/src/tools` |\n| Design System | UI 组件库与国际化 | `@n8n/design-system` |\n| CLI Core | 命令行核心模块 | `@n8n/cli` |\n\n## 核心组件架构\n\n### PromptBuilder 提示词构建器\n\n`PromptBuilder` 是 n8n AI 工作流构建器中的核心工具类，提供类型安全的链式 API 用于组合 LLM 提示词。\n\n```mermaid\nclassDiagram\n class PromptBuilder {\n -sections: SectionEntry[]\n -format: SectionFormat\n -separator: string\n +section(name, content, options): this\n +sectionIf(condition, name, content, options): this\n +examples(name, data, formatter): this\n +merge(other: PromptBuilder): this\n +build(): string\n }\n \n class SectionEntry {\n +name: string\n +content: ContentOrFactory\n +options: SectionOptions\n }\n \n PromptBuilder *-- SectionEntry\n```\n\n**主要特性：**\n\n- **链式 API**：支持方法链式调用，便于阅读的提示词组合方式\n- **条件节**：通过 `sectionIf()` 实现动态内容包含\n- **延迟求值**：工厂函数仅在构建时调用\n- **多格式输出**：支持 XML 标签（默认）和 Markdown 标题两种格式\n\n资料来源：[prompt-builder.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)\n\n### SectionEntry 数据结构\n\n```typescript\ninterface SectionEntry {\n name: string;\n content: ContentOrFactory;\n options: SectionOptions;\n}\n\ntype ContentOrFactory = string | (() => string | null);\n```\n\n每个节（Section）包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `name` | `string` | 节的显示名称，用于生成标签 |\n| `content` | `ContentOrFactory` | 字符串内容或延迟求值的工厂函数 |\n| `options` | `SectionOptions` | 可选配置项 |\n\n资料来源：[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)\n\n### WebFetchTool 网页抓取工具\n\n`WebFetchTool` 是 n8n AI 工作流中的网页内容抓取与提取工具，负责从 URL 获取网页内容并进行可读性处理。\n\n```mermaid\nflowchart TD\n A[输入 URL] --> B[验证 URL 格式]\n B --> C{验证是否通过}\n C -->|通过| D[发起 HTTP 请求]\n C -->|失败| E[返回验证错误]\n D --> F[提取可读内容]\n F --> G[构建响应结果]\n G --> H[记录安全状态]\n H --> I[返回结构化数据]\n```\n\n**处理流程：**\n\n1. 接收并验证 URL 输入\n2. 执行 HTTP 请求获取网页内容\n3. 提取标题和正文内容\n4. 构建结构化的 XML 格式响应\n5. 记录安全相关状态更新\n\n```typescript\nconst responseLines = [\n '',\n `${url}`,\n `${extracted.title}`,\n '',\n extracted.content,\n '',\n '',\n]\n```\n\n资料来源：[web-fetch.tool.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts)\n\n## 安全策略模块\n\n### WS-SecurityPolicy 1.2 XSD 架构\n\nn8n 的 SSO-SAML 模块包含完整的 WS-SecurityPolicy 1.2 XSD Schema 定义，用于配置 Web 服务安全策略。\n\n**主要策略类型：**\n\n| 类型 | 说明 | 代码参考 |\n|------|------|----------|\n| `NestedPolicyType` | 嵌套策略类型 | `tns:NestedPolicyType` |\n| `QNameAssertionType` | QName 断言类型 | `tns:QNameAssertionType` |\n| `TokenAssertionType` | Token 断言类型 | `tns:TokenAssertionType` |\n\n**核心安全断言：**\n\n- **AlgorithmSuite Assertion** (7.1)：定义加密算法套件，支持 Basic256、Basic192、Basic128、TripleDes 等\n- **Layout Assertion** (7.2)：定义消息布局规则，包括 Strict、Lax、LaxTsFirst、LaxTsLast\n- **TransportBinding** (7.3)：传输层绑定配置\n- **SymmetricBinding** (7.4)：对称密钥绑定\n- **Trust13 Assertion** (10.1)：WS-Trust 1.3 规范支持\n\n```xml\n\n \n \n 7.1 AlgorithmSuite Assertion\n \n \n\n```\n\n资料来源：[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)\n\n## 设计系统架构\n\n### Badge 组件\n\nn8n 设计系统提供了统一的 Badge 组件，用于在工作流界面中展示状态信息。\n\n```typescript\ninterface FileStatus {\n status: 'completed' | 'pending' | 'failed'\n}\n\nconst getStatusTheme = (status: string): BadgeTheme => {\n const themeMap: Record = {\n completed: 'success',\n pending: 'warning',\n failed: 'danger',\n }\n return themeMap[status] || 'default'\n}\n```\n\n**主题映射：**\n\n| 状态 | 主题 | 颜色语义 |\n|------|------|---------|\n| completed | success | 成功/绿色 |\n| pending | warning | 警告/黄色 |\n| failed | danger | 危险/红色 |\n\n**组件使用示例：**\n\n```vue\n\n Read Only\n\n\n\n Setup Required\n\n```\n\n资料来源：[component-badge.md](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/v2/components/Badge/component-badge.md)\n\n### 国际化配置\n\nn8n 设计系统支持多语言配置，主要通过 `en.ts` 文件定义英文翻译键值对。\n\n```typescript\n'codeDiff.couldNotReplace': 'Could not replace code',\n'codeDiff.codeReplaced': 'Code replaced',\n'codeDiff.replaceMyCode': 'Replace my code',\n'codeDiff.replacing': 'Replacing...',\n'codeDiff.undo': 'Undo',\n```\n\n**AI Builder 相关翻译：**\n\n```typescript\n'assistantChat.builder.name': 'AI Builder',\n'assistantChat.builder.generatingFinalWorkflow': 'Generating final workflow...',\n'assistantChat.builder.configuredNodes': 'Configured nodes',\n'assistantChat.builder.thumbsUp': 'Helpful',\n'assistantChat.builder.thumbsDown': 'Not helpful',\n```\n\n资料来源：[en.ts](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/locale/lang/en.ts)\n\n## 指南系统架构\n\n### 节点类型指南\n\nAI Workflow Builder 提供了可扩展的节点指南系统，支持按节点类型和条件动态匹配指南内容。\n\n```typescript\nexport const MY_NODE_GUIDE: NodeTypeGuide = {\n patterns: ['n8n-nodes-base.myNode'], // 匹配的节点类型\n condition: (ctx) => true, // 可选：额外条件\n content: `Your guide content here...`,\n};\n```\n\n**当前指南覆盖：**\n\n| 指南 | 模式 | 用途 |\n|------|------|------|\n| Set Node | `n8n-nodes-base.set` | 赋值结构与类型 |\n| IF Node | `n8n-nodes-base.if` | 过滤条件与运算符 |\n| Switch Node | `n8n-nodes-base.switch` | 规则与路由 |\n| HTTP Request | `n8n-nodes-base.httpRequest` | URL、头、请求体、认证 |\n| Tool Nodes | `*Tool` | $fromAI 表达式 |\n| Resource Locator | `*` (条件) | __rl 结构与模式 |\n| System Message | `*` (条件) | AI 节点消息分离 |\n\n**条件指南示例：**\n\n```typescript\nexport const RESOURCE_LOCATOR_GUIDE: NodeTypeGuide = {\n patterns: ['*'], // 匹配所有节点\n condition: (ctx) => ctx.hasResourceLocatorParams === true,\n content: `...`,\n};\n```\n\n资料来源：[README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)\n\n## 模块交互关系\n\n```mermaid\ngraph TD\n A[User Input] --> B[AI Workflow Builder]\n B --> C[PromptBuilder]\n C --> D{Section Type}\n D -->|Conditional| E[sectionIf]\n D -->|Examples| F[examples]\n D -->|Static| G[section]\n E --> H[buildAsMessageBlocks]\n G --> H\n F --> H\n H --> I[LLM Response]\n I --> J[Execute Nodes]\n J --> K[WebFetchTool]\n K --> L[Extract Content]\n L --> J\n J --> M[Return Result]\n \n N[Design System] --> O[Badge Component]\n N --> P[i18n Strings]\n O --> Q[UI Render]\n P --> Q\n```\n\n## 配置选项\n\n### PromptBuilder 配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `format` | `SectionFormat` | `'xml'` | 输出格式：xml 或 markdown |\n| `separator` | `string` | `'\\n\\n'` | 节之间的分隔符 |\n\n### SectionOptions 配置\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `format` | `SectionFormat` | 覆盖全局格式设置 |\n| `tag` | `string` | 自定义标签名称 |\n\n## 最佳实践\n\n### 提示词构建规范\n\n1. **使用条件节**：对于可能缺失的内容使用 `sectionIf()` 避免空值问题\n2. **延迟求值**：复杂内容使用工厂函数而非直接字符串\n3. **格式一致性**：在同一项目中保持统一的输出格式\n4. **示例驱动**：使用 `examples()` 方法提供少样本学习示例\n\n### 指南扩展规范\n\n1. 在 `guides/` 目录创建新的指南文件\n2. 从 `guides/index.ts` 导出新指南\n3. 将指南添加到 `registry.ts` 的注册数组中\n4. 使用条件匹配实现上下文相关的指南内容\n\n## 总结\n\nn8n 的系统架构体现了现代工作流自动化平台的设计理念：\n\n- **模块化设计**：各功能模块解耦，便于独立维护和扩展\n- **类型安全**：TypeScript 优先，确保编译期错误检测\n- **可扩展性**：通过指南系统和提示词模板支持自定义行为\n- **国际化**：完整的 i18n 支持，便于多语言适配\n\n这些架构特性使得 n8n 能够同时支持传统工作流和 AI 增强工作流的开发需求。\n\n---\n\n\n\n## 包结构与模块组织\n\n### 相关页面\n\n相关主题：[系统架构概览](#page-architecture), [工作流 SDK 与构建器](#page-workflow-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [packages/@n8n/node-cli/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/node-cli/README.md)\n- [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)\n- [packages/testing/janitor/README.md](https://github.com/n8n-io/n8n/blob/main/packages/testing/janitor/README.md)\n- [packages/frontend/@n8n/design-system/README.md](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/README.md)\n \n\n# 包结构与模块组织\n\n## 概述\n\nn8n 是一个开源的工作流自动化平台，采用 **Monorepo（单体仓库）** 架构组织代码。项目使用 pnpm 作为包管理器，通过 `pnpm-workspace.yaml` 定义工作区配置。整体架构划分为多个功能明确的子包（packages），涵盖工作流核心、CLI 工具、UI 组件、AI 构建器、数据库层和测试基础设施等模块。\n\n## 核心包结构\n\nn8n 的包结构遵循 **功能分离** 原则，每个包都有明确的职责边界和对外 API 接口。\n\n| 包路径 | 用途说明 |\n|--------|----------|\n| `packages/cli` | CLI 主入口，处理命令行交互和服务器初始化 |\n| `packages/@n8n/workflow-sdk` | 工作流核心 SDK，定义节点、连接、表达式等核心概念 |\n| `packages/@n8n/agents` | AI Agent 能力封装 |\n| `packages/@n8n/db` | 数据库抽象层 |\n| `packages/frontend/editor-ui` | 工作流编辑器前端界面 |\n| `packages/frontend/@n8n/design-system` | 统一设计系统和 UI 组件库 |\n| `packages/@n8n/node-cli` | 节点开发脚手架工具 |\n| `packages/@n8n/ai-workflow-builder.ee` | AI 工作流构建器（企业版） |\n| `packages/testing` | 测试工具和基础设施 |\n\n## 模块层次架构\n\nn8n 采用 **分层架构** 设计，从底层到上层依次为：\n\n```mermaid\ngraph TD\n A[\"packages/@n8n/db
数据库抽象层\"] --> B[\"packages/@n8n/workflow-sdk
工作流核心\"]\n B --> C[\"packages/@n8n/agents
AI Agent 层\"]\n C --> D[\"packages/@n8n/ai-workflow-builder.ee
AI 工作流构建器\"]\n B --> E[\"packages/cli
CLI 与服务层\"]\n E --> F[\"packages/frontend/editor-ui
前端编辑器\"]\n F --> G[\"packages/frontend/@n8n/design-system
设计系统\"]\n```\n\n## 工作流核心 SDK\n\n`packages/@n8n/workflow-sdk` 是整个平台的核心，封装了工作流执行的全部基础能力。\n\n### 核心职责\n\n- 定义节点（Node）和凭证（Credentials）接口\n- 实现工作流执行引擎\n- 提供表达式解析和求值\n- 管理连接和数据流转\n\n### 包导出模式\n\nSDK 包使用 ** barrel export** 模式统一对外暴露 API，通过 `src/index.ts` 作为唯一入口点：\n\n```typescript\n// 资料来源：packages/@n8n/workflow-sdk/src/index.ts\nexport * from './nodes';\nexport * from './credentials';\nexport * from './workflow';\nexport * from './expression';\n```\n\n## AI 工作流构建器架构\n\n`packages/@n8n/ai-workflow-builder.ee` 是企业级 AI 辅助工作流构建模块，包含完整的提示词工程和 Agent 协作系统。\n\n### 多 Agent 协作体系\n\nAI 工作流构建器采用 **多 Agent 路由架构**，每个 Agent 都有明确的职责分工：\n\n| Agent | 职责 | 说明 |\n|-------|------|------|\n| **Supervisor** | 路由协调 | 接收用户请求并分发给合适的专家 Agent |\n| **Discovery** | 节点发现 | 识别相关 n8n 节点并分类技术方案 |\n| **Builder** | 构建执行 | 创建工作流结构并配置节点参数 |\n| **Responder** | 响应生成 | 生成面向用户的回复内容 |\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md]()\n\n### 提示词构建器（PromptBuilder）\n\n核心模块使用 **PromptBuilder** 工具类实现提示词的组合式构建：\n\n```typescript\n// 资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts\nconst systemPrompt = prompt()\n .section('role', 'You are an assistant')\n .sectionIf(hasContext, 'context', () => buildContext())\n .examples('examples', data, (ex) => `${ex.input} → ${ex.output}`)\n .build();\n```\n\n#### PromptBuilder 关键特性\n\n| 特性 | 说明 |\n|------|------|\n| **流式 API** | 支持链式调用，方法返回 `this` |\n| **条件节** | `sectionIf()` 根据条件动态包含内容 |\n| **惰性求值** | 工厂函数仅在构建时执行 |\n| **双格式输出** | 支持 XML 标签和 Markdown 标题两种格式 |\n| **LangChain 集成** | 支持 `cache_control` 缓存控制 |\n\n### 提示词模板结构\n\n代码构建器提示词由多个标准节组成：\n\n```mermaid\ngraph LR\n A[\"\"] --> B[\"\"]\n B --> C[\"\"]\n C --> D[\"\"]\n D --> E[\"\"]\n E --> F[\"\"]\n F --> G[\"\"]\n```\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts]()\n\n## CLI 工具与节点开发\n\n### 节点脚手架工具\n\n`packages/@n8n/node-cli` 提供节点开发的标准化工具体系：\n\n```bash\n# 创建新节点\nnpm create @n8n/node my-awesome-node\ncd my-awesome-node\n\n# 启动开发模式\nnpm run dev\n```\n\n资料来源：[packages/@n8n/node-cli/README.md]()\n\n### 节点项目结构规范\n\nn8n 要求节点项目遵循统一的目录结构：\n\n```\nmy-node/\n├── src/\n│ ├── nodes/\n│ │ └── MyNode/\n│ │ ├── MyNode.node.ts # 节点主实现\n│ │ └── MyNode.node.json # 节点元数据\n│ └── credentials/\n│ └── MyNodeAuth.credentials.ts\n├── package.json\n└── tsconfig.json\n```\n\n资料来源：[packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md]()\n\n### package.json 配置约定\n\n节点包必须在 `package.json` 中声明 `n8n` 字段：\n\n```json\n{\n \"name\": \"n8n-nodes-example\",\n \"version\": \"1.0.0\",\n \"n8n\": {\n \"n8nNodesApiVersion\": 1,\n \"nodes\": [\"dist/nodes/MyNode/MyNode.node.js\"],\n \"credentials\": [\"dist/credentials/MyNodeAuth.credentials.js\"]\n }\n}\n```\n\n## 前端组件体系\n\n### 设计系统\n\n`packages/frontend/@n8n/design-system` 封装了 n8n 的统一视觉语言：\n\n```bash\n# 开发预览\npnpm storybook\n\n# 构建静态页面\npnpm build:storybook\n\n# 构建 CSS 主题\npnpm build:theme\n\n# 监听并自动构建\npnpm watch:theme\n```\n\n资料来源：[packages/frontend/@n8n/design-system/README.md]()\n\n### 编辑器组件测试\n\n编辑器使用 Vue 3 + Composition API 开发，测试采用 Vue Test Utils：\n\n```typescript\n// 资料来源：packages/frontend/editor-ui/src/app/components/MainHeader/MainHeader.test.ts\ndescribe('MainHeader', () => {\n beforeEach(() => {\n workflowsStore = mockedStore(useWorkflowsStore);\n workflowDocumentStore.hydrate({\n id: '1',\n name: 'Test Workflow',\n active: false,\n // ...\n });\n });\n});\n```\n\n## 测试基础设施\n\n### Playwright Janitor\n\n`packages/testing/janitor` 是端到端测试编排工具，支持分片并行执行：\n\n```bash\n# 分 14 片执行\nplaywright-janitor orchestrate --shards=14\n\n# 仅执行受 Git 变更影响的测试\nplaywright-janitor orchestrate --shards=14 --impact\n```\n\n资料来源：[packages/testing/janitor/README.md]()\n\n### 架构规则\n\n测试框架定义了严格的架构规则：\n\n| 规则 | 严重级别 | 说明 |\n|------|----------|------|\n| `boundary-protection` | error | 禁止页面对象直接导入其他页面 |\n| `scope-lockdown` | error | 页面对象必须有 `container` 或导航方法 |\n| `test-data-hygiene` | warning | 检测孤立/通用的测试数据文件 |\n| `duplicate-logic` | warning | 检测代码重复（AST 结构指纹） |\n\n### 页面对象隔离原则\n\n```typescript\n// 资料来源：packages/testing/janitor/README.md\n\n// 不推荐 - 页面间耦合\nexport class WorkflowPage {\n async openSettings() {\n await this.settingsPage.open();\n }\n}\n\n// 推荐 - 页面独立，组合在 flows 层\nexport class WorkflowPage {\n async getWorkflowName() {\n return this.header.getByTestId('workflow-name').textContent();\n }\n}\n```\n\n## 数据库模块\n\n`packages/@n8n/db` 提供数据库访问的统一抽象层，处理 ORM 配置、迁移管理和连接池等基础设施问题。\n\n### 包导出模式\n\n```typescript\n// 资料来源：packages/@n8n/db/src/index.ts\nexport * from './connection';\nexport * from './repositories';\nexport * from './migrations';\n```\n\n## 模块间依赖关系\n\n```mermaid\ngraph TD\n CLI[\"packages/cli
CLI 入口\"]\n SDK[\"packages/@n8n/workflow-sdk
工作流 SDK\"]\n DB[\"packages/@n8n/db
数据库层\"]\n AGENTS[\"packages/@n8n/agents
AI Agent\"]\n AI_BUILDER[\"packages/@n8n/ai-workflow-builder.ee
AI 构建器\"]\n EDITOR[\"packages/frontend/editor-ui
编辑器 UI\"]\n DESIGN[\"packages/frontend/@n8n/design-system
设计系统\"]\n\n DB --> SDK\n SDK --> CLI\n SDK --> AGENTS\n AGENTS --> AI_BUILDER\n CLI --> EDITOR\n EDITOR --> DESIGN\n```\n\n## 命名规范与导出约定\n\n### Barrel Export 模式\n\n所有包遵循统一的 Barrel Export 模式组织导出：\n\n```typescript\n// src/index.ts - 包入口文件\nexport * from './core'; // 核心功能\nexport * from './types'; // 类型定义\nexport * from './constants'; // 常量\nexport { SpecificClass } from './internal/specific'; // 按需导出\n```\n\n### 命名空间约定\n\n| 层级 | 命名方式 | 示例 |\n|------|----------|------|\n| 包名 | `@n8n/功能名` | `@n8n/workflow-sdk` |\n| 导出类 | PascalCase | `WorkflowExecutor` |\n| 导出函数 | camelCase | `executeWorkflow` |\n| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |\n| 类型/接口 | PascalCase + 后缀 | `WorkflowNode`, `NodeCredentials` |\n\n## 扩展机制\n\n### 节点开发扩展\n\n通过 `n8n-nodes-` 前缀注册自定义节点：\n\n```json\n{\n \"name\": \"n8n-nodes-my-service\",\n \"n8n\": {\n \"nodes\": [\"dist/nodes/MyNode/MyNode.node.js\"]\n }\n}\n```\n\n### 提示词指南扩展\n\nAI 构建器支持通过模式匹配注入节点指南：\n\n```typescript\n// 资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md\nexport const MY_NODE_GUIDE: NodeTypeGuide = {\n patterns: ['n8n-nodes-base.myNode'],\n condition: (ctx) => true,\n content: `指南内容...`,\n};\n```\n\n## 总结\n\nn8n 的包结构设计体现了以下核心原则：\n\n1. **职责分离** - 每个包有明确边界，通过接口而非实现通信\n2. **可扩展性** - 节点系统和 AI 构建器都支持插件式扩展\n3. **层次清晰** - 依赖关系自底向上，CLI 和 UI 依赖核心 SDK\n4. **统一规范** - Barrel Export、命名约定、文档结构保持一致\n5. **测试完备** - 专门的测试基础设施支持 E2E 和单元测试\n\n---\n\n\n\n## 工作流 SDK 与构建器\n\n### 相关页面\n\n相关主题：[工作流执行引擎](#page-execution-engine), [系统架构概览](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# 工作流 SDK 与构建器\n\n## 概述\n\n工作流 SDK 与构建器（Workflow SDK and Builder）是 n8n 平台中用于通过 AI 能力自动生成、构建和优化工作流的综合技术栈。该系统由多个核心组件构成，包括提示构建器（PromptBuilder）、语义图（Semantic Graph）、代码生成器（Code Generator）以及多代理协调系统。这些组件协同工作，使开发者能够通过自然语言描述或结构化指令来自动生成复杂的工作流配置。\n\nn8n 的工作流构建系统采用了分层的架构设计，将工作流的语义表示与实际的代码生成解耦。这种设计允许不同的生成策略（如基于规则的生成、基于 AI 的生成）共享同一套语义模型，从而保证了生成结果的一致性和可维护性。\n\n## 核心架构\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n A[用户输入] --> B[多代理协调器]\n B --> C[发现代理 Discovery]\n B --> D[构建代理 Builder]\n B --> E[响应代理 Responder]\n C --> F[节点分类系统]\n D --> G[PromptBuilder]\n G --> H[ChatPromptTemplate]\n H --> I[LLM 服务]\n I --> J[代码生成]\n J --> K[Semantic Graph]\n K --> L[Code Generator]\n L --> M[Workflow JSON]\n```\n\n### 组件职责矩阵\n\n| 组件 | 职责 | 主要文件 |\n|------|------|----------|\n| **PromptBuilder** | 负责构建结构化的 LLM 提示，支持条件化、可组合的提示段 | prompt-builder.ts |\n| **Code Generator** | 将语义图转换为实际的代码输出 | code-generator.ts |\n| **Semantic Graph** | 管理工作流的语义表示和节点关系 | semantic-graph.ts |\n| **Workflow Builder** | 提供工作流构建的高级 API | workflow-builder.ts |\n| **多代理系统** | 协调不同专业代理完成复杂任务 | agents/ 目录 |\n\n## 提示构建器（PromptBuilder）\n\n### 设计理念\n\nPromptBuilder 是一个类型安全的、流畅式（Fluent）API，用于组合 LLM 提示。该类支持条件化内容块、延迟求值、多种输出格式以及与 LangChain 的深度集成。资料来源：[prompt-builder.ts:1-100]()\n\nPromptBuilder 的核心设计原则包括：\n\n1. **可组合性**：通过 `merge()` 方法可以合并多个 PromptBuilder 实例\n2. **延迟求值**：工厂函数仅在构建时求值，避免不必要的计算\n3. **条件渲染**：通过 `sectionIf()` 和 `examplesIf()` 支持条件化内容\n4. **格式灵活性**：支持 XML 标签格式和 Markdown 格式\n\n### 核心方法\n\n```typescript\nclass PromptBuilder {\n // 添加始终包含的段落\n section(name: string, content: ContentOrFactory, options?: SectionOptions): this;\n \n // 条件性添加段落\n sectionIf(condition: unknown, name: string, content: ContentOrFactory, options?: SectionOptions): this;\n \n // 添加示例段落\n examples(name: string, data: unknown[], formatter: ExampleFormatter): this;\n \n // 条件性添加示例\n examplesIf(condition: unknown, name: string, data: unknown[], formatter: ExampleFormatter): this;\n \n // 合并另一个 PromptBuilder\n merge(other: PromptBuilder): this;\n \n // 构建最终提示字符串\n build(): string;\n \n // 构建为 LangChain 消息块\n buildAsMessageBlocks(): BaseMessage[];\n}\n```\n\n### 使用示例\n\n```typescript\nconst systemPrompt = prompt()\n .section('ROLE', 'You are an assistant')\n .sectionIf(hasContext, 'CONTEXT', () => buildContext())\n .examples('EXAMPLES', data, (ex) => `${ex.input} → ${ex.output}`)\n .build();\n```\n\n资料来源：[prompt-builder.ts:100-150]()\n\n### 输出格式\n\nPromptBuilder 支持两种主要的输出格式，通过 `SectionFormat` 类型定义：\n\n| 格式 | 说明 | 示例输出 |\n|------|------|----------|\n| `xml` | XML 标签格式（默认） | `内容` |\n| `markdown` | Markdown 标题格式 | `## Section Name\\n内容` |\n\n### 段落选项配置\n\n```typescript\ninterface SectionOptions {\n format?: SectionFormat; // 覆盖默认格式\n tag?: string; // 自定义标签名\n}\n```\n\n## 代码构建器提示系统\n\n### 系统提示构建流程\n\n```mermaid\ngraph LR\n A[buildCodeBuilderPrompt] --> B[buildMandatoryWorkflow]\n B --> C[ROLE]\n B --> D[RESPONSE_STYLE]\n B --> E[WORKFLOW_RULES]\n B --> F[WORKFLOW_PATTERNS]\n C --> G[EXPRESSION_REFERENCE]\n D --> H[ADDITIONAL_FUNCTIONS]\n E --> I[ChatPromptTemplate]\n F --> J[系统消息]\n G --> J\n H --> J\n J --> K[cache_control配置]\n```\n\n代码构建器使用 `buildCodeBuilderPrompt()` 函数生成完整的系统提示，该函数整合了多个预定义的提示组件。资料来源：[packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts]()\n\n### 提示组件列表\n\n| 组件 | 用途 | XML 标签 |\n|------|------|----------|\n| `ROLE` | 定义 AI 角色和行为 | `` |\n| `RESPONSE_STYLE` | 规定响应格式和风格 | `` |\n| `WORKFLOW_RULES` | 工作流构建规则 | `` |\n| `WORKFLOW_PATTERNS` | 常见工作流模式 | `` |\n| `EXPRESSION_REFERENCE` | 表达式语法参考 | `` |\n| `ADDITIONAL_FUNCTIONS` | 额外可用函数 | `` |\n| `mandatory_workflow_process` | 强制性工作流处理流程 | `` |\n\n### 用户消息构建\n\n用户消息部分通过 `buildUserMessageParts()` 函数构建，包含以下可选组件：\n\n1. **当前工作流上下文**：当存在正在进行的工作流时提供\n2. **历史上下文**：多轮对话中的历史记录\n3. **工作流文件状态**：检查是否存在现有工作流代码\n4. **已批准的计划输出**：计划模式的结果\n5. **预搜索结果**：提前获取的搜索结果以节省 LLM 交互\n\n```typescript\nfunction buildUserMessageParts(\n currentWorkflow?: WorkflowJSON,\n historyContext?: HistoryContext,\n options?: BuildCodeBuilderPromptOptions,\n): string[]\n```\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts]()\n\n### LangChain 集成\n\n系统提示通过 `ChatPromptTemplate.fromMessages()` 包装，并配置了 `cache_control` 选项以支持 LLM 的上下文缓存：\n\n```typescript\nreturn ChatPromptTemplate.fromMessages([\n ['system', [{ \n type: 'text', \n text: systemMessage, \n cache_control: { type: 'ephemeral' } \n }]],\n ['user', userMessageTemplate]\n]);\n```\n\n## 多代理工作流系统\n\n### 代理架构\n\nn8n 采用多代理架构来协调复杂的工作流构建任务。代理目录包含针对不同专业领域的专门提示。资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md]()\n\n| 代理 | 职责 | 说明 |\n|------|------|------|\n| **Supervisor** | 路由用户请求 | 将请求分发到合适的专业代理 |\n| **Discovery** | 发现和分类 | 识别相关 n8n 节点并分类技术 |\n| **Builder** | 构建工作流 | 创建工作流结构并配置节点参数 |\n| **Responder** | 生成响应 | 生成面向用户的结果输出 |\n\n### 链式提示系统\n\n`chains/` 目录包含用于特定 LLM 链操作的提示：\n\n| 链 | 用途 | 说明 |\n|-----|------|------|\n| **Categorization** | 分析用户提示 | 识别工作流技术和模式 |\n| **Compact** | 压缩对话 | 总结对话以便后续处理 |\n\n## 节点与参数指南系统\n\n### 指南注册机制\n\nn8n 提供了基于模式的节点指南系统，通过 `NodeTypeGuide` 接口定义：\n\n```typescript\ninterface NodeTypeGuide {\n patterns: string[]; // 匹配节点类型的模式\n condition?: (ctx: GuideContext) => boolean; // 额外条件\n content: string; // 指南内容\n}\n```\n\n### 内置指南列表\n\n| 指南 | 节点模式 | 用途 |\n|------|----------|------|\n| Set Node | `n8n-nodes-base.set` | 赋值结构与类型 |\n| IF Node | `n8n-nodes-base.if` | 过滤条件与运算符 |\n| Switch Node | `n8n-nodes-base.switch` | 规则和路由 |\n| HTTP Request | `n8n-nodes-base.httpRequest` | URL、头、请求体、认证 |\n| Tool Nodes | `*Tool` | $fromAI 表达式 |\n| Resource Locator | `*` (条件性) | __rl 结构和模式 |\n| System Message | `*` (条件性) | AI 节点消息分离 |\n| Text Fields | `*` (条件性) | 表达式处理 |\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/guides/README.md]()\n\n### 添加新指南\n\n1. 在 `guides/` 目录创建新的指南文件\n2. 从 `guides/index.ts` 导出\n3. 在 `registry.ts` 的注册数组中添加\n\n## 工具系统\n\n### Web 获取工具\n\n`WebFetchTool` 提供了网页内容抓取能力，使用可读内容提取器处理 HTML 响应：\n\n```mermaid\ngraph TD\n A[URL 输入] --> B[URL 验证]\n B --> C[安全检查]\n C --> D[HTTP 请求]\n D --> E[内容提取]\n E --> F[可读内容提取]\n F --> G[状态记录]\n G --> H[响应构建]\n H --> I[]\n```\n\n### 工具响应格式\n\n```xml\n\n 原始URL\n 最终URL\n 页面标题\n 提取的内容\n 截断说明（可选）\n\n```\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts]()\n\n## 构建与生成流程\n\n### 工作流生成流程\n\n```mermaid\ngraph TD\n A[自然语言描述] --> B[Discovery 代理]\n B --> C[节点分类]\n C --> D[Builder 代理]\n D --> E[PromptBuilder 组装]\n E --> F[LLM 生成]\n F --> G[Semantic Graph]\n G --> H[Code Generator]\n H --> I[Workflow JSON]\n I --> J[执行验证]\n J --> K[工作流部署]\n```\n\n### 代码生成策略\n\n工作流 SDK 支持多种代码生成策略：\n\n1. **基于模板的生成**：使用预定义模板填充参数\n2. **基于 AI 的生成**：通过 LLM 理解语义并生成\n3. **混合生成**：结合模板和 AI 能力\n\n### 语义图管理\n\n语义图（Semantic Graph）负责：\n\n- 管理工作流节点和连接的语义表示\n- 提供节点关系的查询接口\n- 支持工作流的语义验证\n\n## 类型系统\n\n### 关键类型定义\n\n```typescript\ntype ContentOrFactory = string | (() => string | null);\n\ntype SectionFormat = 'xml' | 'markdown';\n\ntype ExampleFormatter = (item: unknown) => string;\n\ninterface SectionEntry {\n name: string;\n content: ContentOrFactory;\n options: SectionOptions;\n}\n\ninterface SectionOptions {\n format?: SectionFormat;\n tag?: string;\n}\n\ninterface PromptBuilderOptions {\n format?: SectionFormat;\n separator?: string;\n}\n```\n\n## 配置与扩展\n\n### PromptBuilder 配置选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `format` | `SectionFormat` | `'xml'` | 默认输出格式 |\n| `separator` | `string` | `'\\n\\n'` | 段落分隔符 |\n\n### 段落格式配置\n\n```typescript\n// 使用自定义分隔符\nconst prompt = new PromptBuilder({ separator: '\\n---\\n' });\n\n// 使用 Markdown 格式\nconst prompt = new PromptBuilder({ format: 'markdown' });\n\n// 自定义段落格式\nprompt.section('custom', 'content', { \n format: 'markdown',\n tag: 'CustomSection'\n});\n```\n\n## 最佳实践\n\n### 提示构建最佳实践\n\n1. **保持简洁**：每个段落应专注于单一概念\n2. **使用条件化段落**：避免不必要的空内容\n3. **延迟求值**：复杂计算使用工厂函数\n4. **合理使用分隔符**：清晰的段落分隔提高可读性\n\n### 代码生成最佳实践\n\n1. **语义优先**：先生成语义图，再转换为代码\n2. **验证语义**：在生成前验证工作流语义的正确性\n3. **版本控制**：保持生成结果的可追溯性\n\n## 总结\n\n工作流 SDK 与构建器是 n8n 智能工作流生成系统的核心基础设施。通过 PromptBuilder 提供的类型安全、流畅式 API，开发者可以轻松构建复杂的 LLM 提示。多代理系统则协调各个专业代理完成从需求理解到工作流生成的完整流程。语义图和代码生成器将高层语义转换为可执行的工作流配置，确保了生成结果的质量和一致性。\n\n该系统的设计体现了几个关键原则：可组合性（通过 merge 和 section 方法）、延迟求值（通过工厂函数）、条件化渲染（通过 sectionIf 方法）以及与 LangChain 的深度集成。这些设计使得工作流构建系统既灵活又高效，能够满足不同场景下的工作流生成需求。\n\n---\n\n\n\n## 工作流执行引擎\n\n### 相关页面\n\n相关主题：[工作流 SDK 与构建器](#page-workflow-sdk), [数据库实体与数据管理](#page-database-entities)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [packages/cli/src/active-workflow-manager.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/active-workflow-manager.ts)\n- [packages/cli/src/executions/execution.service.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/executions/execution.service.ts)\n- [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)\n- [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)\n \n\n# 工作流执行引擎\n\n## 概述\n\nn8n 的工作流执行引擎是自动化工作流的运行时核心，负责协调节点的执行顺序、管理数据流转、处理表达式求值以及维护执行状态。该引擎支持手动执行和生产执行两种模式，能够在不同的触发条件下激活工作流实例。\n\n工作流执行引擎的核心职责包括：\n\n1. **节点调度**：根据工作流定义的有向图结构，确定节点的执行顺序\n2. **数据传递**：在节点之间传递输入输出数据，处理二进制和 JSON 数据\n3. **表达式求值**：在运行时解析和计算表达式，支持变量引用和函数调用\n4. **版本管理**：支持工作流的草稿版本和生产版本区分\n5. **错误处理**：捕获节点执行异常，提供重试和错误恢复机制\n\n## 核心架构\n\n### 执行模式\n\nn8n 工作流执行引擎支持两种主要执行模式：\n\n| 执行模式 | 描述 | 适用场景 |\n|---------|------|---------|\n| `manual` | 手动触发执行 | 调试、测试、单次运行 |\n| `production` | 生产环境执行 | 定时任务、Webhook、API 调用 |\n\n生产模式执行时，系统会验证工作流是否已激活并具有活跃版本。若工作流没有已发布（active）的版本，执行将被拒绝并抛出 `WorkflowAccessError` 错误。\n\n```typescript\n资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:8-12]()\n\nif (executionMode === 'production' && !workflow.activeVersionId) {\n throw new WorkflowAccessError(\n `Workflow '${workflowId}' has no published (active) version to execute`,\n 'workflow_not_active',\n );\n}\n```\n\n### 版本数据管理\n\n工作流执行引擎根据执行模式选择对应的版本数据：\n\n```mermaid\ngraph TD\n A[开始执行] --> B{执行模式是 production?}\n B -->|是| C[使用 activeVersion]\n B -->|否| D[使用草稿版本]\n C --> E[提取 nodes 和 connections]\n D --> E\n E --> F[查找触发节点]\n F --> G[生成 MCP 消息ID]\n G --> H[构建运行数据]\n \n style C fill:#e1f5fe\n style D fill:#fff3e0\n```\n\n引擎通过 `getVersionDataForExecution` 函数根据执行模式选择正确的版本数据：\n\n```typescript\n资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:14-24]()\n\nconst getVersionDataForExecution = (\n workflow: FoundWorkflow,\n workflowId: string,\n executionMode: z.infer['executionMode'],\n) => {\n const nodes =\n executionMode === 'production' \n ? (workflow.activeVersion?.nodes ?? []) \n : (workflow.nodes ?? []);\n const connections =\n executionMode === 'production'\n ? (workflow.activeVersion?.connections ?? {})\n : (workflow.connections ?? {});\n return { nodes, connections };\n};\n```\n\n## 触发节点机制\n\n### 支持的触发节点\n\n工作流执行引擎仅支持特定类型的触发节点。系统定义了 `getSupportedTriggerNamesForMode` 函数来获取当前执行模式支持的触发器名称列表：\n\n```typescript\n资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:36-39]()\n\nif (!triggerNode) {\n throw new WorkflowAccessError(\n `Only workflows with the following trigger nodes can be executed: ${getSupportedTriggerNamesForMode(executionMode).join(', ')}.`,\n 'unsupported_trigger',\n );\n}\n```\n\n### 触发节点查找\n\n引擎使用 `findMcpSupportedTrigger` 函数在工作流节点列表中查找符合条件的触发节点，该函数会扫描所有节点并识别支持 MCP 协议的触发器。\n\n## 执行数据构建\n\n### 运行数据结构\n\n工作流执行引擎构建 `IWorkflowExecutionDataProcess` 类型的运行数据，该数据结构包含执行工作流所需的全部信息，包括：\n\n- 工作流定义（节点和连接）\n- 执行模式\n- 用户上下文\n- 触发节点信息\n- 输入数据\n\n### MCP 消息标识\n\n为每次执行生成唯一的 MCP 消息 ID，用于队列模式下的关联和追踪：\n\n```typescript\n资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:42-44]()\n\nconst mcpMessageId = `mcp-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;\n```\n\n消息 ID 格式：`mcp-{时间戳}-{随机字符串}`，确保在分布式环境中的唯一性。\n\n## 表达式运行时\n\n### 表达式求值器\n\n表达式求值器是工作流执行引擎的关键组件，负责在运行时解析包含变量引用和函数的表达式。求值器支持：\n\n- 简单变量替换：`{{ $json.name }}`\n- 复杂表达式计算：`{{ Math.ceil($json.price * 1.1) }}`\n- 条件表达式：`{{ $json.value > 10 ? '高' : '低' }}`\n- 节点输出引用：`{{ $json(\"NodeName\").value }}`\n\n### AST 解释器\n\n抽象语法树（AST）解释器是表达式运行时的新一代实现，采用 AST 而非字符串解析方式处理表达式，具有以下优势：\n\n| 特性 | 传统方式 | AST 方式 |\n|------|---------|---------|\n| 解析速度 | 每次求值重新解析 | 预编译为 AST |\n| 错误检测 | 运行时才发现 | 预编译时验证 |\n| 优化能力 | 有限 | 支持常量折叠 |\n| 调试能力 | 困难 | 可追踪执行路径 |\n\n## 错误处理机制\n\n### 验证错误\n\n引擎使用 Zod 进行输入验证，当验证失败时会创建 `ValidationError` 并记录详细错误信息：\n\n```typescript\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts:68-73]()\n\nif (error instanceof z.ZodError) {\n const validationError = new ValidationError('Invalid URL input', {\n extra: { errors: error.errors },\n });\n reporter.error(validationError);\n}\n```\n\n### 工作流访问错误\n\n当工作流状态不符合执行条件时，引擎抛出 `WorkflowAccessError`，错误类型包括：\n\n| 错误类型 | 触发条件 |\n|---------|---------|\n| `workflow_not_active` | 生产模式执行但工作流未激活 |\n| `unsupported_trigger` | 工作流不包含支持的触发节点 |\n\n## 执行服务\n\n### 执行服务架构\n\n执行服务（Execution Service）负责管理执行的生命周期，包括：\n\n1. **执行创建**：初始化新的执行实例\n2. **执行排队**：将执行请求加入执行队列\n3. **执行监控**：跟踪执行进度和状态\n4. **执行完成**：保存执行结果并清理资源\n\n### 活跃工作流管理器\n\n活跃工作流管理器（Active Workflow Manager）维护当前活跃工作流的注册表，负责：\n\n- 工作流激活与停用\n- 触发器注册与移除\n- 活跃连接管理\n\n```mermaid\ngraph LR\n A[用户激活工作流] --> B[ActiveWorkflowManager]\n B --> C[注册触发器]\n C --> D[添加到活跃列表]\n \n E[触发事件到达] --> F[查找对应工作流]\n F --> G[创建执行实例]\n G --> H[执行引擎调度]\n \n I[用户停用工作流] --> J[移除触发器]\n J --> K[从活跃列表删除]\n```\n\n## 扩展机制\n\n### MCP 工具集成\n\nn8n 支持通过 MCP（Model Context Protocol）协议扩展执行引擎的能力。MCP 工具允许外部系统调用 n8n 工作流，实现与 AI 代理和其他自动化系统的集成。\n\nMCP 执行工具的核心功能：\n\n- 接收外部执行请求\n- 验证工作流和用户权限\n- 选择正确的执行模式\n- 返回执行结果\n\n### 执行模式配置\n\n引擎支持通过配置选项自定义执行行为：\n\n```typescript\n// 执行请求输入模式定义\nconst inputSchema = z.object({\n executionMode: z.enum(['production', 'manual']),\n inputs: z.record(z.any()).optional(),\n});\n```\n\n## 数据流处理\n\n### 输入数据处理\n\n工作流执行引擎支持通过 `inputs` 参数向工作流传递初始数据：\n\n```mermaid\ngraph TD\n A[外部输入] --> B[inputs 验证]\n B --> C{验证通过?}\n C -->|是| D[注入到触发节点]\n C -->|否| E[返回验证错误]\n D --> F[开始节点执行]\n```\n\n### 输出数据返回\n\n执行完成后，引擎收集所有节点的输出数据，整理为统一的响应格式返回给调用方。\n\n## 相关组件\n\n| 组件 | 包路径 | 职责 |\n|------|-------|------|\n| 执行服务 | `packages/cli/src/executions/` | 执行生命周期管理 |\n| 活跃工作流管理器 | `packages/cli/src/active-workflow-manager.ts` | 工作流激活状态管理 |\n| 表达式求值器 | `packages/@n8n/expression-runtime/src/evaluator/` | 表达式运行时解析 |\n| AST 解释器 | `packages/@n8n/workflow-sdk/src/ast-interpreter/` | 高级表达式处理 |\n| MCP 执行工具 | `packages/cli/src/modules/mcp/tools/` | 外部协议集成 |\n\n---\n\n\n\n## AI Agent 运行时\n\n### 相关页面\n\n相关主题：[LangChain 节点集成](#page-langchain-nodes), [AI 工作流构建器](#page-ai-workflow-builder)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/@n8n/agents/src/runtime/agent-runtime.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/agents/src/runtime/agent-runtime.ts)\n- [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)\n- [packages/@n8n/agents/src/sdk/agent.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/agents/src/sdk/agent.ts)\n- [packages/@n8n/agents/src/runtime/message-list.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/agents/src/runtime/message-list.ts)\n \n\n# AI Agent 运行时\n\n## 概述\n\nAI Agent 运行时（Agent Runtime）是 n8n 平台中负责执行 AI 代理的核心组件系统。该运行时负责管理代理的生命周期、消息处理、工具调用以及与外部系统（如 MCP 服务器）的集成。运行时架构设计遵循模块化原则，将核心逻辑与具体实现解耦，使得系统具备良好的可扩展性和可维护性。\n\n运行时系统的核心职责包括：\n\n- **消息管理**：维护对话历史，处理用户输入与模型输出的流转\n- **工具解析**：解析并执行 MCP（Model Context Protocol）工具调用\n- **状态管理**：跟踪代理执行状态，处理错误恢复\n- **上下文维护**：管理代理的长期记忆和会话状态\n\n## 核心组件架构\n\nAI Agent 运行时由多个协同工作的组件构成，每个组件承担特定的职责。以下是主要组件及其功能：\n\n```mermaid\ngraph TD\n A[Agent SDK] --> B[AgentRuntime]\n B --> C[MessageList]\n B --> D[MCPToolResolver]\n D --> E[MCP Servers]\n B --> F[AI Workflow Builder]\n F --> G[PromptBuilder]\n G --> H[工具定义]\n G --> I[示例生成]\n```\n\n### AgentRuntime（代理运行时引擎）\n\n`AgentRuntime` 是整个运行时的核心引擎，负责协调各个组件的工作。它处理代理的初始化、执行循环和结果返回。\n\n主要功能包括：\n\n- 初始化运行时环境\n- 执行主循环，处理用户消息\n- 调用工具并处理返回结果\n- 管理会话状态和错误处理\n\n### MessageList（消息列表）\n\n`MessageList` 组件负责管理对话消息的历史记录。它维护一个有序的消息队列，支持消息的添加、检索和上下文管理。\n\n核心功能：\n\n- 存储对话历史\n- 支持消息角色区分（用户、助手、系统）\n- 提供上下文窗口管理\n- 支持消息格式转换\n\n### MCPToolResolver（工具解析器）\n\n`MCPToolResolver` 负责解析和执行 MCP 协议定义的工具调用。它充当 n8n 运行时与外部 MCP 服务器之间的桥梁。\n\n主要职责：\n\n- 发现可用的 MCP 工具\n- 验证工具参数\n- 执行工具调用\n- 处理工具返回结果\n\n## 消息处理流程\n\n运行时采用事件驱动的消息处理模式，确保每条消息都能得到正确处理并返回相应的响应。\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Runtime as AgentRuntime\n participant Messages as MessageList\n participant Tools as MCPToolResolver\n participant LLM as AI 模型\n \n User->>Runtime: 发送消息\n Runtime->>Messages: 添加用户消息\n Runtime->>LLM: 发送完整上下文\n LLM->>Runtime: 返回响应/工具调用\n alt 工具调用\n Runtime->>Tools: 解析工具请求\n Tools->>Tools: 执行 MCP 工具\n Tools-->>Runtime: 返回结果\n Runtime->>LLM: 发送工具结果\n LLM->>Runtime: 生成最终响应\n end\n Runtime->>Messages: 添加助手消息\n Runtime-->>User: 返回响应\n```\n\n## 工具系统集成\n\n### AI Tools 生成\n\nn8n 的 AI Tools 系统负责将 n8n 节点转换为 AI 模型可调用的工具。这一过程在 `packages/cli/src/tool-generation/ai-tools.ts` 中实现。\n\n工具描述生成流程：\n\n```typescript\n// 工具描述自动生成逻辑\nconst descriptionType: INodeProperties = {\n displayName: 'Tool Description',\n name: 'descriptionType',\n type: 'options',\n options: [\n { name: 'Set Automatically', value: 'auto' },\n { name: 'Set Manually', value: 'manual' },\n ],\n default: 'auto',\n};\n```\n\n### 工具属性处理\n\n运行时支持两种工具描述设置模式：\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| 自动设置（auto） | 基于 resource 和 operation 参数自动推断描述 | 标准 n8n 节点 |\n| 手动设置（manual） | 用户提供自定义工具描述 | 复杂或特殊用途工具 |\n\n当节点包含 `resource` 和 `operation` 属性时，运行时可以自动生成语义化的工具描述，使 LLM 能够更准确地理解和调用工具。\n\n## Prompt 构建系统\n\nAI Workflow Builder 使用 `PromptBuilder` 组件构建发送给 LLM 的提示词。该构建器采用流式 API 设计，支持灵活的提示词组装。\n\n### PromptBuilder 核心特性\n\n```mermaid\ngraph LR\n A[section] --> B[sectionIf]\n A --> C[examples]\n A --> D[examplesIf]\n B --> E[build]\n C --> E\n D --> E\n```\n\n主要方法：\n\n| 方法 | 说明 | 用途 |\n|------|------|------|\n| `section()` | 添加静态内容区块 | 基础提示词组装 |\n| `sectionIf()` | 条件性添加区块 | 动态内容控制 |\n| `examples()` | 添加少样本示例 | Few-shot 学习 |\n| `examplesIf()` | 条件性添加示例 | 条件化示例注入 |\n| `merge()` | 合并多个构建器 | 提示词复用 |\n| `build()` | 生成最终提示词 | 输出结果 |\n\n### 示例格式化\n\n`PromptBuilder` 支持多种输出格式：\n\n```typescript\n// Markdown 格式\nconst markdownOutput = `## Examples\\n${examplesContent}`;\n\n// XML 格式\nconst xmlOutput = `\\n${examplesContent}\\n`;\n```\n\n构建器会根据配置自动选择合适的格式化方式，确保与不同 LLM API 的兼容性。\n\n## Web Fetch 工具\n\n运行时不直接提供网络获取功能，而是通过 `web-fetch.tool.ts` 实现网页内容提取。该工具将获取的网页转换为 LLM 可处理的结构化文本。\n\n处理流程：\n\n1. 发送 HTTP 请求获取页面内容\n2. 提取可读文本和标题\n3. 处理内容截断和错误情况\n4. 返回结构化结果\n\n返回格式示例：\n\n```xml\n\nhttps://example.com\n页面标题\n\n提取的正文内容...\n\n\n```\n\n## MCP 浏览器集成\n\nn8n 提供了 MCP（Model Context Protocol）浏览器工具，用于在开发环境中测试 MCP 服务器功能。该工具支持多种 AI 客户端配置，包括 Claude Desktop、Cursor、Windsurf 等。\n\n### 开发环境配置\n\n```bash\n# 启动 MCP 服务器\nnpx @n8n/mcp-browser --transport http --port 3100\n```\n\n### 客户端配置示例\n\n```json\n{\n \"mcpServers\": {\n \"n8n-browser\": {\n \"url\": \"http://localhost:3100/mcp\"\n }\n }\n}\n```\n\n## 错误处理机制\n\n运行时实现了完善的错误处理机制，确保代理在遇到异常情况时能够优雅地降级或恢复：\n\n- **验证错误**：通过 Zod 进行输入参数验证\n- **工具执行错误**：捕获并记录工具调用异常\n- **网络错误**：处理 MCP 服务器连接问题\n- **上下文溢出**：管理令牌使用量，避免超出限制\n\n```typescript\n// 验证错误处理示例\nif (error instanceof z.ZodError) {\n const validationError = new ValidationError('Invalid URL input', {\n extra: { errors: error.errors },\n });\n reporter.error(validationError);\n}\n```\n\n## 数据流总结\n\n```mermaid\ngraph TD\n subgraph 输入层\n A[用户消息] --> B[MessageList]\n end\n \n subgraph 处理层\n B --> C[PromptBuilder]\n C --> D[AI 模型]\n D --> E[响应/工具调用]\n end\n \n subgraph 执行层\n E --> F{MCPToolResolver}\n F --> G[MCP 工具]\n G --> H[外部服务]\n end\n \n subgraph 输出层\n E --> I[格式化响应]\n I --> J[返回用户]\n end\n```\n\n## 相关配置\n\n运行时的行为可通过多种方式配置：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| 上下文窗口 | 单次请求的最大消息数 | 依赖模型限制 |\n| 工具超时 | 单个工具调用的最大执行时间 | 30秒 |\n| 重试次数 | 工具调用失败时的重试次数 | 3 |\n| 日志级别 | 运行时的日志详细程度 | info |\n\n## 扩展指南\n\n### 添加新的工具解析器\n\n要扩展工具系统，需要实现 `ToolResolver` 接口：\n\n```typescript\ninterface ToolResolver {\n resolve(toolCall: ToolCall): Promise;\n getAvailableTools(): ToolDefinition[];\n validateParams(params: unknown): boolean;\n}\n```\n\n### 集成新的 MCP 服务器\n\n1. 在 MCP 配置中注册服务器端点\n2. 实现服务器端的工具定义\n3. 配置 `MCPToolResolver` 连接参数\n\n## 总结\n\nAI Agent 运行时是 n8n 平台智能化能力的核心支撑。通过模块化的组件设计，系统实现了高效的消息处理、灵活的提示词构建和完善的工具调用机制。开发者可以通过扩展现有组件或集成新的 MCP 服务器来增强运行时功能，以满足各种复杂的 AI 工作流需求。\n\n---\n\n\n\n## LangChain 节点集成\n\n### 相关页面\n\n相关主题：[AI Agent 运行时](#page-agents-runtime)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# LangChain 节点集成\n\n## 概述\n\nLangChain 节点集成是 n8n 工作流自动化平台中用于构建 AI 驱动工作流的**核心组件体系**。该集成通过提供标准化的节点、工具和提示构建系统，使开发者能够在 n8n 工作流中无缝调用 LangChain 的语言模型、代理（Agent）和工具链能力。\n\nLangChain 节点集成的主要功能包括：\n\n- **语言模型（LLM）节点**：支持 OpenAI、Anthropic 等多种语言模型的调用\n- **代理（Agent）节点**：基于 LangChain 构建的 AI 代理，支持多种推理策略\n- **工具（Tools）节点**：提供 Web 抓取、代码执行等工具扩展\n- **提示构建系统**：基于 `PromptBuilder` 的类型安全、fluent API\n\n## 架构设计\n\n### 整体架构\n\nLangChain 节点集成采用分层架构设计，各组件之间通过标准接口进行通信：\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n A[编辑器 UI] --> B[节点配置面板]\n B --> C[代码编辑器]\n end\n \n subgraph \"节点层\"\n D[LLM 节点] --> E[代理节点]\n E --> F[工具节点]\n F --> G[PromptBuilder]\n end\n \n subgraph \"集成层\"\n H[LangChain Core] --> I[模型适配器]\n I --> J[工具适配器]\n end\n \n subgraph \"外部服务\"\n K[OpenAI API] --> I\n L[Anthropic API] --> I\n M[外部工具] --> J\n end\n \n style A fill:#e1f5fe\n style D fill:#fff3e0\n style H fill:#e8f5e9\n```\n\n### PromptBuilder 核心组件\n\n`PromptBuilder` 是 LangChain 节点集成中的提示构建核心类，提供类型安全的流式 API：\n\n| 特性 | 说明 |\n|------|------|\n| 流式 API | 支持方法链式调用 |\n| 条件部分 | `sectionIf()` 支持动态内容 |\n| 延迟求值 | 工厂函数仅在构建时执行 |\n| 输出格式 | 支持 XML 标签和 Markdown 标题 |\n| LangChain 集成 | 支持 message blocks 和 cache_control |\n\n## 提示构建系统\n\n### PromptBuilder 类接口\n\n`PromptBuilder` 类位于 `packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts`，提供以下核心方法：\n\n```typescript\nclass PromptBuilder {\n private readonly sections: SectionEntry[];\n private readonly format: SectionFormat;\n private readonly separator: string;\n\n constructor(options: PromptBuilderOptions = {});\n \n // 添加固定部分\n section(name: string, content: ContentOrFactory, options?: SectionOptions): this;\n \n // 添加条件部分\n sectionIf(condition: unknown, name: string, content: ContentOrFactory, options?: SectionOptions): this;\n \n // 添加示例\n examples(name: string, data: unknown[], formatter: ExampleFormatter): this;\n examplesIf(condition: unknown, name: string, data: unknown[], formatter: ExampleFormatter): this;\n \n // 合并多个 PromptBuilder\n merge(other: PromptBuilder): this;\n \n // 构建最终提示字符串\n build(): string;\n}\n```\n\n资料来源：[prompt-builder.ts:48-90]()\n\n### 使用示例\n\n```typescript\nconst systemPrompt = prompt()\n .section('ROLE', 'You are an assistant')\n .sectionIf(hasContext, 'CONTEXT', () => buildContext())\n .examples('EXAMPLES', data, (ex) => `${ex.input} → ${ex.output}`)\n .build();\n```\n\n上述代码通过 fluent API 构建了一个包含角色定义、上下文信息和示例的提示词，最终通过 `build()` 方法生成字符串输出。\n\n## 工具节点系统\n\n### WebFetch 工具\n\n`WebFetch` 工具是 AI workflow builder 中用于获取网页内容的核心工具，位置在 `packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts`。其工作流程如下：\n\n```mermaid\ngraph TD\n A[输入 URL] --> B[验证 URL 格式]\n B --> C{验证通过?}\n C -->|否| D[返回 ValidationError]\n C -->|是| E[发起 HTTP 请求]\n E --> F[提取可读内容]\n F --> G[构建响应 XML]\n G --> H[记录安全状态]\n H --> I[返回 SuccessResponse]\n \n style D fill:#ffcdd2\n style I fill:#c8e6c9\n```\n\n### 响应格式\n\nWebFetch 工具返回的响应采用 XML 结构，包含以下元素：\n\n| 元素 | 说明 |\n|------|------|\n| `` | 原始请求 URL |\n| `` | 最终重定向后的 URL（可选） |\n| `` | 网页标题 |\n| `<content>` | 提取的内容 |\n| `<note>` | 截断说明（当内容被截断时） |\n\n```xml\n<web_fetch_result>\n <url>https://example.com</url>\n <title>Example Domain\n \n [提取的内容]\n \n\n```\n\n资料来源：[web-fetch.tool.ts:26-43]()\n\n## 节点指南系统\n\n### 指南注册机制\n\nn8n 的 AI workflow builder 通过指南系统（Guides）为不同类型的节点提供上下文相关的帮助信息：\n\n```mermaid\ngraph LR\n A[用户操作] --> B{匹配节点类型}\n B -->|Set 节点| C[赋值结构与类型指南]\n B -->|IF 节点| D[过滤条件与操作符指南]\n B -->|HTTP Request| E[URL、Header、Body、认证指南]\n B -->|Tool 节点| F[$fromAI 表达式指南]\n```\n\n### 指南配置结构\n\n每个节点指南的定义包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `patterns` | `string[]` | 匹配节点类型的模式 |\n| `condition` | `(ctx) => boolean` | 可选：额外的上下文条件 |\n| `content` | `string` | 指南内容 |\n\n```typescript\nexport const MY_NODE_GUIDE: NodeTypeGuide = {\n patterns: ['n8n-nodes-base.myNode'],\n condition: (ctx) => true,\n content: `Your guide content here...`,\n};\n```\n\n资料来源：[README.md (prompts)](packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)\n\n## 前端编辑器集成\n\n### 代码编辑器组件\n\nn8n 前端使用 CodeMirror 6 实现代码编辑器，位于 `packages/frontend/editor-ui/src/features/shared/editors/composables/useCodeEditor.ts`：\n\n```typescript\nconst editor = ref();\nconst hasFocus = ref(false);\nconst hasChanges = ref(false);\nconst autocompleteStatus = ref<'pending' | 'active' | null>(null);\n```\n\n编辑器支持的语言包括多种代码语言，并提供语法高亮、自动完成等功能。\n\n### AI Builder 界面文本\n\n前端国际化文件 `packages/frontend/@n8n/design-system/src/locale/lang/en.ts` 包含 AI Builder 相关的界面文本：\n\n| 文本键 | 说明 |\n|--------|------|\n| `assistantChat.builder.name` | AI Builder 界面名称 |\n| `assistantChat.builder.generatingFinalWorkflow` | 生成最终工作流时的提示 |\n| `assistantChat.builder.configuredNodes` | 已配置节点 |\n| `assistantChat.rating.thumbsUp` | 有帮助 |\n| `assistantChat.rating.thumbsDown` | 没有帮助 |\n| `assistantChat.rating.feedbackPlaceholder` | 反馈占位符 |\n\n## 多代理提示系统\n\n### 代理类型\n\n提示系统支持多种专业化代理：\n\n| 代理 | 功能 |\n|------|------|\n| **Supervisor** | 将用户请求路由到合适的专业代理 |\n| **Discovery** | 识别相关 n8n 节点并分类技术 |\n| **Builder** | 创建工作流结构并配置节点参数 |\n| **Responder** | 生成面向用户的响应 |\n\n所有代理提示都使用 `PromptBuilder` 进行统一组合。\n\n### 链式提示\n\n除了代理提示外，系统还包含用于特定 LLM 链式操作的提示：\n\n| 链 | 功能 |\n|----|------|\n| **Categorization** | 分析用户提示以识别工作流技术 |\n| **Compact** | 压缩对话以节省上下文 |\n\n## 安全性与状态管理\n\n### 安全状态追踪\n\nWebFetch 工具实现了安全状态追踪机制：\n\n```typescript\nconst stateUpdates: Record = {\n ...security.getStateUpdates(),\n fetchedUrlContent: [\n {\n url,\n status: 'success' as const,\n title: extracted.title,\n content: extracted.content,\n },\n ],\n};\n```\n\n安全系统记录每次抓取请求，并在返回响应时附带安全状态更新，确保工作流执行的可追溯性。\n\n## 最佳实践\n\n### 提示构建\n\n1. **使用条件部分**：对于可选内容，使用 `sectionIf()` 避免不必要的延迟求值\n2. **链式调用**：利用流式 API 的可读性组织提示构建逻辑\n3. **示例格式化**：通过 `examples()` 方法添加少样本示例时，使用清晰的格式化函数\n\n### 工具使用\n\n1. **URL 验证**：WebFetch 工具会自动验证 URL 格式，无效输入将抛出 `ValidationError`\n2. **内容截断**：大型页面内容可能被截断，应检查 `truncated` 标志\n3. **错误处理**：工具返回的错误包含 Zod 验证详情，便于调试\n\n## 相关资源\n\n- 官方文档：[n8n AI Workflow Builder](https://docs.n8n.io/)\n- LangChain 官方文档：[LangChain.js](https://js.langchain.com/)\n- 源码仓库：[n8n-io/n8n](https://github.com/n8n-io/n8n)\n\n---\n\n\n\n## AI 工作流构建器\n\n### 相关页面\n\n相关主题：[AI Agent 运行时](#page-agents-runtime), [工作流 SDK 与构建器](#page-workflow-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [packages/testing/rules-engine/README.md](https://github.com/n8n-io/n8n/blob/main/packages/testing/rules-engine/README.md)\n \n\n# AI 工作流构建器\n\n## 概述\n\nAI 工作流构建器是 n8n 平台中一个基于大语言模型（LLM）的智能工作流创建系统。该系统通过多代理（Multi-Agent）架构，允许用户使用自然语言描述需求，自动生成 n8n 工作流代码。该模块位于 `packages/@n8n/ai-workflow-builder.ee` 包中，是 n8n 企业版的重要组成部分。\n\nAI 工作流构建器的主要特点包括：\n\n- **自然语言驱动**：用户通过自然语言描述工作流需求\n- **多代理协作**：多个专业代理协同工作，各司其职\n- **代码生成**：自动生成可执行的工作流代码（JavaScript/TypeScript）\n- **上下文感知**：能够理解当前工作流状态并进行多轮优化\n- **工具集成**：支持网络搜索、文档获取等辅助工具\n\n## 系统架构\n\n### 多代理架构\n\nAI 工作流构建器采用多代理架构设计，每个代理拥有特定的角色和职责：\n\n| 代理 | 用途 | 说明 |\n|------|------|------|\n| **Supervisor** | 主管代理 | 路由用户请求到合适的专业代理 |\n| **Discovery** | 发现代理 | 识别相关 n8n 节点并分类技术 |\n| **Builder** | 构建代理 | 创建工作流结构并配置节点参数 |\n| **Responder** | 响应代理 | 生成面向用户的响应 |\n\n资料来源：[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)\n\n```mermaid\ngraph TD\n A[用户请求] --> B[Supervisor 主管代理]\n B --> C[Discovery 发现代理]\n B --> D[Builder 构建代理]\n B --> E[Responder 响应代理]\n C --> F[节点搜索结果]\n D --> G[工作流代码]\n F --> D\n D --> H[工作流状态]\n H --> B\n G --> E\n E --> I[用户响应]\n```\n\n### 核心组件\n\n```\npackages/@n8n/ai-workflow-builder.ee/\n├── src/\n│ ├── code-builder/ # 代码构建器核心\n│ │ └── prompts/ # 代码生成提示词\n│ ├── agents/ # 多代理系统\n│ │ ├── planner.agent.ts # 规划代理\n│ │ └── ...\n│ ├── prompts/ # 提示词构建系统\n│ │ ├── builder/ # PromptBuilder 工具\n│ │ ├── chains/ # 链式提示词\n│ │ └── guides/ # 节点和参数指南\n│ ├── tools/ # 工具集\n│ │ ├── web-fetch.tool.ts # 网页抓取工具\n│ │ └── builder-tools.ts # 构建器专用工具\n│ └── workflow-state.ts # 工作流状态管理\n```\n\n## PromptBuilder 提示词构建器\n\n### 概述\n\nPromptBuilder 是一个类型安全的链式 API，用于组合 LLM 提示词。它支持条件化部分、延迟求值和 LangChain 集成。\n\n资料来源：[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)\n\n### 核心功能\n\n```typescript\nconst systemPrompt = prompt()\n .section('role', 'You are an assistant')\n .sectionIf(hasContext, 'context', () => buildContext())\n .examples('examples', data, (ex) => `${ex.input} → ${ex.output}`)\n .build();\n```\n\n| 方法 | 说明 |\n|------|------|\n| `section(name, content)` | 添加始终包含的部分 |\n| `sectionIf(condition, name, content)` | 根据条件添加部分 |\n| `examples(name, data, formatter)` | 添加少样本示例 |\n| `merge(other)` | 合并另一个 PromptBuilder |\n| `build()` | 构建最终的提示词字符串 |\n| `buildAsMessageBlocks()` | 构建为 LangChain 消息块 |\n\n### 格式化选项\n\nPromptBuilder 支持两种输出格式：\n\n| 格式 | 说明 | 示例 |\n|------|------|------|\n| `xml` | XML 标签格式（默认） | `...` |\n| `markdown` | Markdown 标题格式 | `## Role\\n...` |\n\n## 代码构建器\n\n### 系统提示词构建\n\n代码构建器通过 `buildCodeBuilderPrompt` 函数构建完整的系统提示词，该函数整合多个组件：\n\n```typescript\nexport function buildCodeBuilderPrompt(\n\tcurrentWorkflow?: WorkflowJSON,\n\thistoryContext?: HistoryContext,\n\toptions?: BuildCodeBuilderPromptOptions,\n): ChatPromptTemplate\n```\n\n资料来源：[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)\n\n### 提示词组成部分\n\n系统提示词由以下部分组成：\n\n```mermaid\ngraph LR\n A[buildCodeBuilderPrompt] --> B[ROLE 角色定义]\n A --> C[RESPONSE_STYLE 响应风格]\n A --> D[WORKFLOW_RULES 工作流规则]\n A --> E[WORKFLOW_PATTERNS 工作流模式]\n A --> F[EXPRESSION_REFERENCE 表达式参考]\n A --> G[ADDITIONAL_FUNCTIONS 附加函数]\n A --> H[MANDATORY_WORKFLOW_PROCESS 强制流程]\n```\n\n### 用户消息构建\n\n用户消息部分通过 `buildUserMessageParts` 函数构建，支持以下可选组件：\n\n| 组件 | 条件 | 说明 |\n|------|------|------|\n| 当前工作流 JSON | 始终存在 | 工作流的当前状态 |\n| 对话历史 | historyContext 存在 | 多轮对话上下文 |\n| 计划输出 | planOutput 存在 | 规划代理的输出结果 |\n| 预搜索结果 | preSearchResults 存在 | 预先获取的节点搜索结果 |\n\n```typescript\nfunction buildUserMessageParts(\n\tcurrentWorkflow?: WorkflowJSON,\n\thistoryContext?: HistoryContext,\n\toptions?: BuildCodeBuilderPromptOptions,\n): string[]\n```\n\n资料来源：[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)\n\n### XML 标签包装\n\n系统使用 XML 标签封装不同类型的信息，便于解析：\n\n| 标签 | 用途 |\n|------|------|\n| `...` | 代理角色定义 |\n| `...` | 响应风格指导 |\n| `...` | 工作流生成规则 |\n| `...` | 工作流文件内容 |\n| `...` | 已批准的计划 |\n| `...` | 节点搜索结果 |\n| `...` | 用户请求 |\n| `...` | 网页抓取结果 |\n\n## 工具系统\n\n### 网页抓取工具\n\n`WebFetchTool` 允许 AI 代理获取网页内容以辅助决策：\n\n```mermaid\nsequenceDiagram\n 代理->>WebFetchTool: fetch(url)\n WebFetchTool->>URL: 发起 HTTP 请求\n URL-->>WebFetchTool: 返回 HTML 内容\n WebFetchTool->>WebFetchTool: extractReadableContent()\n WebFetchTool->>安全检查: recordFetch()\n WebFetchTool-->>代理: 返回结构化结果\n```\n\n资料来源：[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)\n\n### 工具响应格式\n\n工具执行完成后返回结构化的响应，包含状态更新信息：\n\n```typescript\ninterface ToolResponse {\n\tstatus: 'success' | 'error';\n\turl?: string;\n\tfinalUrl?: string;\n\ttruncated?: boolean;\n}\n\nconst stateUpdates: Record = {\n\t...security.getStateUpdates(),\n\tfetchedUrlContent: [{\n\t\turl,\n\t\tstatus: 'success' as const,\n\t\ttitle: extracted.title,\n\t\tcontent: extracted.content,\n\t}],\n};\n```\n\n### 安全状态追踪\n\n网页抓取工具集成了安全状态追踪机制，记录所有抓取操作并生成相应的状态更新：\n\n- `security.recordFetch()` - 记录抓取操作\n- `security.getStateUpdates()` - 获取状态更新\n\n## 节点指南系统\n\n### 指南注册表\n\nn8n 为常见节点提供专门的指南，帮助 AI 代理正确理解和配置节点：\n\n| 指南 | 节点模式 | 用途 |\n|------|----------|------|\n| Set Node | `n8n-nodes-base.set` | 赋值结构与类型 |\n| IF Node | `n8n-nodes-base.if` | 过滤条件与运算符 |\n| Switch Node | `n8n-nodes-base.switch` | 规则和路由 |\n| HTTP Request | `n8n-nodes-base.httpRequest` | URL、头部、请求体、认证 |\n| Tool Nodes | `*Tool` | $fromAI 表达式 |\n| Resource Locator | `*` | __rl 结构与模式 |\n| System Message | `*` | AI 节点消息分离 |\n| Text Fields | `*` | 表达式输入框 |\n\n资料来源：[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)\n\n### 条件化指南\n\n某些指南仅在特定上下文中适用，使用 `condition` 属性控制：\n\n```typescript\nexport const RESOURCE_LOCATOR_GUIDE: NodeTypeGuide = {\n\tpatterns: ['*'], // 匹配所有节点\n\tcondition: (ctx) => ctx.hasResourceLocatorParams === true,\n\tcontent: `...`,\n};\n```\n\n## LangChain 集成\n\n### 消息块构建\n\nPromptBuilder 支持构建 LangChain 兼容的消息块，带有缓存控制支持：\n\n```typescript\nreturn ChatPromptTemplate.fromMessages([\n\t['system', [{\n\t\ttype: 'text',\n\t\ttext: systemMessage,\n\t\tcache_control: { type: 'ephemeral' }\n\t}]],\n\t['user', userMessageTemplate],\n]);\n```\n\n### 缓存策略\n\n系统使用 LangChain 的 `cache_control` 机制进行提示词缓存优化：\n\n- `ephemeral` - 临时缓存，仅在当前请求周期内有效\n- 适用于频繁使用但频繁变化的内容\n\n## 工作流状态管理\n\n工作流状态由 `workflow-state.ts` 管理，跟踪工作流的当前配置和历史变更。状态信息在多代理协作中流转，确保每个代理都能访问一致的工作流上下文。\n\n## 代码节点编辑器补全\n\n### 输入方法补全\n\nAI 工作流构建器为 `$input` 对象提供智能补全支持：\n\n| 方法 | 模式 | 说明 |\n|------|------|------|\n| `first()` | `$input.first().` | 获取第一个输入项 |\n| `last()` | `$input.last().` | 获取最后一个输入项 |\n| `item` | `$input.item.` | 获取当前项 |\n| `all()[index]` | `$input.all()[index].` | 获取指定索引项 |\n\n补全选项包括 `.json` 和 `.binary` 两种数据类型访问方式。\n\n资料来源：[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)\n\n## 规则引擎\n\n### 架构规则\n\nAI 工作流构建器的测试框架使用规则引擎进行架构验证：\n\n| 规则 | 严重性 | 说明 |\n|------|--------|------|\n| `boundary-protection` | error | 防止页面间直接导入 |\n| `scope-lockdown` | error | 强制页面对象的显式架构意图 |\n\n资料来源：[packages/testing/rules-engine/README.md](https://github.com/n8n-io/n8n/blob/main/packages/testing/rules-engine/README.md)\n\n## 最佳实践\n\n### 提示词构建\n\n1. **使用条件化部分**：通过 `sectionIf()` 按需包含内容，减少不必要的上下文\n2. **延迟求值**：使用工厂函数避免不必要的计算\n3. **适当格式化**：XML 格式便于程序解析，Markdown 格式便于调试\n4. **缓存控制**：对频繁使用的系统提示词部分使用缓存标记\n\n### 代理协作\n\n1. **职责分离**：每个代理应专注于特定任务\n2. **状态传递**：通过标准化的工作流状态对象在各代理间传递信息\n3. **错误处理**：工具执行应包含完整的错误处理和状态回滚机制\n\n## 相关链接\n\n- [n8n 官方文档](https://docs.n8n.io/)\n- [n8n GitHub 仓库](https://github.com/n8n-io/n8n)\n- [AI 工作流构建器源码](https://github.com/n8n-io/n8n/tree/main/packages/@n8n/ai-workflow-builder.ee)\n\n---\n\n\n\n## 数据库实体与数据管理\n\n### 相关页面\n\n相关主题：[工作流执行引擎](#page-execution-engine), [系统架构概览](#page-architecture)\n\n根据提供的上下文，我没有找到查询中要求的相关数据库实体文件（如 `workflow-entity.ts`、`execution-entity.ts`、`credentials-entity.ts`、`workflow.repository.ts` 等）。\n\n提供的上下文主要包含以下内容：\n\n- **前端国际化文件**：`packages/frontend/@n8n/design-system/src/locale/lang/en.ts`\n- **前端组件测试**：`packages/frontend/editor-ui/src/app/components/MainHeader/MainHeader.test.ts`\n- **AI工作流构建器**：`packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts`、`web-fetch.tool.ts`、`prompt-builder.ts`\n- **SSO SAML认证**：各种XSD schema文件\n- **测试框架文档**：`packages/testing/janitor/README.md`\n- **节点开发CLI**：`packages/@n8n/node-cli/README.md`\n- **评估框架**：`packages/@n8n/ai-workflow-builder.ee/evaluations/README.md`\n- **UI组件文档**：`packages/frontend/@n8n/design-system/src/components/N8nSwitch/component-switch.md`\n\n---\n\n如果您能提供数据库实体相关的源文件（如 `packages/@n8n/db/src/entities/*.ts`），我可以为您生成关于\"数据库实体与数据管理\"的完整技术文档。\n\n或者，如果您希望我基于当前上下文中实际存在的文件生成文档，我可以撰写以下主题：\n\n1. **n8n前端国际化系统**\n2. **AI工作流构建器提示词系统**\n3. **Playwright测试框架架构**\n4. **n8n节点CLI开发工具**\n\n请告知您希望处理哪个方向。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：n8n-io/n8n\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:193215554 | https://github.com/n8n-io/n8n | README/documentation is current enough for a first validation pass.\n\n## 2. 运行坑 · 运行可能依赖外部服务\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。\n- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。\n- 建议检查：确认是否有离线 demo、mock 数据或可替代服务。\n- 防护动作：外部服务依赖未明确时，不把本地安装成功等同于能力可用。\n- 证据：packet_text.keyword_scan | github_repo:193215554 | https://github.com/n8n-io/n8n | matched external service / cloud / webhook / database keyword\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:193215554 | https://github.com/n8n-io/n8n | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:193215554 | https://github.com/n8n-io/n8n | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | release_recency=unknown\n\n\n",
"markdown_key": "n8n",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:193215554",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/n8n-io/n8n"
},
{
"evidence_id": "art_c3434f0ba8174f8b94b74bd78bf766d7",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/n8n-io/n8n#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "n8n 说明书",
"toc": [
"https://github.com/n8n-io/n8n 项目说明书",
"目录",
"n8n 平台介绍",
"概述",
"架构设计",
"节点系统",
"代码节点",
"AI 工作流构建器",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "86170674b72acc16d781eafd08cd762c55a7672f",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"packages/cli/jest.config.migration.js",
"packages/cli/jest.config.js",
"packages/cli/nodemon.json",
"packages/cli/jest.config.integration.testcontainers.js",
"packages/cli/jest.config.integration.js",
"packages/cli/package.json",
"packages/cli/jest.config.unit.js",
"packages/cli/BREAKING-CHANGES.md",
"packages/cli/tsconfig.json",
"packages/cli/tsconfig.build.json",
"packages/cli/jest.config.migration.testcontainers.js",
"packages/workflow/jest.config.js",
"packages/workflow/vitest.config.ts",
"packages/workflow/tsconfig.build.esm.json",
"packages/workflow/package.json",
"packages/workflow/README.md",
"packages/workflow/tsconfig.build.cjs.json",
"packages/workflow/tsconfig.json",
"packages/nodes-base/AGENTS.md",
"packages/nodes-base/jest.config.js",
"packages/nodes-base/shims.d.ts",
"packages/nodes-base/CLAUDE.md",
"packages/nodes-base/TESTING.MD",
"packages/nodes-base/index.js",
"packages/nodes-base/vitest.integration.config.ts",
"packages/nodes-base/package.json",
"packages/nodes-base/README.md",
"packages/nodes-base/TESTING_PROMPT_WORKFLOW.md",
"packages/nodes-base/tsconfig.build.cjs.json",
"packages/nodes-base/TESTING_PROMPT.md",
"packages/nodes-base/tsconfig.json",
"packages/node-dev/package.json",
"packages/node-dev/README.md",
"packages/node-dev/tsconfig.json",
"packages/core/jest.config.js",
"packages/core/package.json",
"packages/core/README.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# n8n-monorepo - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 n8n-monorepo 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.claude/plugins/n8n/skills/community-pr-review/SKILL.md`, `.claude/plugins/n8n/skills/content-design/SKILL.md`, `.claude/plugins/n8n/skills/conventions/SKILL.md`, `.claude/plugins/n8n/skills/create-community-node-lint-rule/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.claude/plugins/n8n/skills/community-pr-review/SKILL.md`, `.claude/plugins/n8n/skills/content-design/SKILL.md`, `.claude/plugins/n8n/skills/conventions/SKILL.md`, `.claude/plugins/n8n/skills/create-community-node-lint-rule/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude/plugins/n8n/.claude-plugin/marketplace.json`, `.claude/plugins/n8n/.claude-plugin/plugin.json` Claim：`clm_0002` unverified 0.25\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md`, `packages/@n8n/cli/README.md`, `packages/@n8n/computer-use/README.md` 等 Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `npx n8n` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0009` supported 0.86, `clm_0011` supported 0.86, `clm_0012` supported 0.86 等\n- `curl -LsSf https://astral.sh/uv/install.sh | sh` 证据：`packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md` Claim：`clm_0006` supported 0.86\n- `npm install -g rust-just` 证据：`packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md` Claim：`clm_0007` supported 0.86\n- `curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to DEST` 证据：`packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md` Claim：`clm_0008` supported 0.86\n- `npx @n8n/cli workflow list` 证据：`packages/@n8n/cli/README.md` Claim：`clm_0009` supported 0.86\n- `npm install -g @n8n/cli` 证据：`packages/@n8n/cli/README.md` Claim：`clm_0010` supported 0.86\n- `npx @n8n/computer-use https://my-instance.app.n8n.cloud` 证据：`packages/@n8n/computer-use/README.md` Claim：`clm_0011` supported 0.86, `clm_0013` supported 0.86, `clm_0014` supported 0.86, `clm_0015` supported 0.86\n- `npx @n8n/computer-use http://localhost:5678 --allowed-origins http://localhost:5678` 证据：`packages/@n8n/computer-use/README.md` Claim：`clm_0012` supported 0.86\n- `npx @n8n/computer-use https://my-instance.app.n8n.cloud --dir /path/to/project` 证据：`packages/@n8n/computer-use/README.md` Claim：`clm_0013` supported 0.86\n- `npx @n8n/computer-use https://my-instance.app.n8n.cloud -d /path/to/project` 证据：`packages/@n8n/computer-use/README.md` Claim：`clm_0014` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.claude/plugins/n8n/skills/community-pr-review/SKILL.md`, `.claude/plugins/n8n/skills/content-design/SKILL.md`, `.claude/plugins/n8n/skills/conventions/SKILL.md`, `.claude/plugins/n8n/skills/create-community-node-lint-rule/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude/plugins/n8n/skills/community-pr-review/SKILL.md`, `.claude/plugins/n8n/skills/content-design/SKILL.md`, `.claude/plugins/n8n/skills/conventions/SKILL.md`, `.claude/plugins/n8n/skills/create-community-node-lint-rule/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md`, `packages/@n8n/cli/README.md`, `packages/@n8n/computer-use/README.md` 等 Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0009` supported 0.86, `clm_0011` supported 0.86, `clm_0012` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude/plugins/n8n/.claude-plugin/marketplace.json`, `.claude/plugins/n8n/.claude-plugin/plugin.json`, `.claude/plugins/n8n/skills/community-pr-review/SKILL.md`, `.claude/plugins/n8n/skills/content-design/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude/plugins/n8n/.claude-plugin/marketplace.json`, `.claude/plugins/n8n/.claude-plugin/plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md`, `packages/@n8n/cli/README.md`, `packages/@n8n/computer-use/README.md` 等\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude/plugins/n8n/.claude-plugin/marketplace.json`, `.claude/plugins/n8n/.claude-plugin/plugin.json`, `.claude/plugins/n8n/skills/community-pr-review/SKILL.md`, `.claude/plugins/n8n/skills/content-design/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude/plugins/n8n/.claude-plugin/marketplace.json`, `.claude/plugins/n8n/.claude-plugin/plugin.json`, `README.md`, `packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0029` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude/plugins/n8n/.claude-plugin/marketplace.json`, `.claude/plugins/n8n/.claude-plugin/plugin.json` Claim：`clm_0030` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md`, `packages/@n8n/cli/README.md`, `packages/@n8n/computer-use/README.md` 等 Claim：`clm_0031` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.claude/plugins/n8n/skills/community-pr-review/SKILL.md`, `.claude/plugins/n8n/skills/content-design/SKILL.md`, `.claude/plugins/n8n/skills/conventions/SKILL.md`, `.claude/plugins/n8n/skills/create-community-node-lint-rule/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude/plugins/n8n/.claude-plugin/marketplace.json`, `.claude/plugins/n8n/.claude-plugin/plugin.json`\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md`, `packages/@n8n/cli/README.md`, `packages/@n8n/computer-use/README.md` 等 Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：18129\n- 重要文件覆盖：40/18129\n- 证据索引条目：96\n- 角色 / Skill 条目：16\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 n8n-monorepo 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 n8n-monorepo 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 n8n-monorepo 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 16 个角色 / Skill / 项目文档条目。\n\n- **Community PR Review**（skill）：- 激活提示：当用户任务与“Community PR Review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/community-pr-review/SKILL.md`\n- **n8n:content-design**（skill）： 激活提示：当用户任务与“n8n:content-design”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/content-design/SKILL.md`\n- **n8n:conventions**（skill）：Quick reference for n8n patterns. Full docs /AGENTS.md 激活提示：当用户任务与“n8n:conventions”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/conventions/SKILL.md`\n- **n8n:create-community-node-lint-rule**（skill）：- 激活提示：当用户任务与“n8n:create-community-node-lint-rule”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/create-community-node-lint-rule/SKILL.md`\n- **n8n:create-issue**（skill）：Required for creating GitHub issues. Must be authenticated gh auth login 激活提示：当用户任务与“n8n:create-issue”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/create-issue/SKILL.md`\n- **n8n:create-pr**（skill）：Creates GitHub pull requests with properly formatted titles that pass the check-pr-title CI validation. Use when creating PRs, submitting changes for review, or when the user says /pr or asks to create a pull request. 激活提示：当用户任务与“n8n:create-pr”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/create-pr/SKILL.md`\n- **n8n:create-skill**（skill）：- 激活提示：当用户任务与“n8n:create-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/create-skill/SKILL.md`\n- **n8n:design-system**（skill）：Guidelines on using Design System styles and components. Use when working on .vue files in packages/frontend. Triggers for tasks that include component architecture, styling, UI changes, or feature work. 激活提示：当用户任务与“n8n:design-system”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/design-system/SKILL.md`\n- **n8n:linear-issue**（skill）：Used to download images/attachments. Typically pre-installed. 激活提示：当用户任务与“n8n:linear-issue”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/linear-issue/SKILL.md`\n- **n8n:loom-transcript**（skill）：Fetch and display the full transcript from a Loom video URL. Use when the user wants to get or read a Loom transcript. 激活提示：当用户任务与“n8n:loom-transcript”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/loom-transcript/SKILL.md`\n- **n8n:node-add-oauth**（skill）：Add OAuth2 credential support to an existing n8n node — creates the credential file, updates the node, adds tests, and keeps the CLI constant in sync. Use when the user says /node-add-oauth. 激活提示：当用户任务与“n8n:node-add-oauth”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/node-add-oauth/SKILL.md`\n- **n8n:protect-endpoints**（skill）：Applies n8n's RBAC scope decorators to REST endpoints. Use when creating a new @RestController, adding any @Get/@Post/@Put/@Patch/@Delete route to an existing controller, or reviewing endpoint authorization. Every authenticated endpoint must be gated by @ProjectScope or @GlobalScope. 激活提示：当用户任务与“n8n:protect-endpoints”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/protect-endpoints/SKILL.md`\n- **n8n:reproduce-bug**（skill）：Reproduce a bug from a Linear ticket with a failing test. Expects the full ticket context title, description, comments to be provided as input. 激活提示：当用户任务与“n8n:reproduce-bug”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/reproduce-bug/SKILL.md`\n- **n8n:setup-mcps**（skill）：- 激活提示：当用户任务与“n8n:setup-mcps”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/setup-mcps/SKILL.md`\n- **n8n:spec-driven-development**（skill）：Keeps implementation and specs in sync. Use when working on a feature that has a spec in .claude/specs/, when the user says /spec, or when starting implementation of a documented feature. Also use when the user asks to verify implementation against a spec or update a spec after changes. 激活提示：当用户任务与“n8n:spec-driven-development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/plugins/n8n/skills/spec-driven-development/SKILL.md`\n- **n8n-cli**（skill）：Use the n8n CLI to manage workflows, credentials, executions, and more on an n8n instance. Use when the user asks to interact with n8n, automate workflows, manage credentials, or operate their instance from the command line. 激活提示：当用户任务与“n8n-cli”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/@n8n/cli/skills/n8n-cli/SKILL.md`\n\n## 证据索引\n\n- 共索引 96 条证据。\n\n- **i18n in n8n**（documentation）：n8n allows for internalization of the majority of UI text: 证据：`packages/frontend/@n8n/i18n/docs/README.md`\n- **Claude Code Configuration**（documentation）：This directory contains shared Claude Code configuration for the n8n team. 证据：`.claude/README.md`\n- **.github Quick Reference**（documentation）：This folder contains n8n's GitHub Actions infrastructure. 证据：`.github/CLAUDE.md`\n- **AGENTS.md**（documentation）：This file provides guidance on how to work with the n8n repository. 证据：`AGENTS.md`\n- **Claude**（documentation）：@AGENTS.md 证据：`CLAUDE.md`\n- **n8n - Secure Workflow Automation for Technical Teams**（documentation）：! Banner image https://user-images.githubusercontent.com/10284570/173569848-c624317f-42b1-45a6-ab09-f0ea3c247648.png 证据：`README.md`\n- **n8n Claude Code Plugin**（documentation）：Shared skills, commands, and agents for n8n development. All items are namespaced under n8n: to avoid collisions with personal or third-party plugins. 证据：`.claude/plugins/n8n/README.md`\n- **n8n - Secure Workflow Automation for Technical Teams**（documentation）：! n8n.io - Workflow Automation https://user-images.githubusercontent.com/65276001/173571060-9f2f6d7b-bac0-43b6-bdb2-001da9694058.png 证据：`docker/images/n8n/README.md`\n- **n8n - Task runners n8nio/runners - PREVIEW**（documentation）：n8n - Task runners n8nio/runners - PREVIEW 证据：`docker/images/runners/README.md`\n- **AGENTS.md**（documentation）：Conventions for the @n8n/agents package. 证据：`packages/@n8n/agents/AGENTS.md`\n- **@n8n/ai-node-sdk**（documentation）：Preview: This package is in preview. The API may change without notice. AI nodes are not yet accepted for verification. 证据：`packages/@n8n/ai-node-sdk/README.md`\n- **@n8n/ai-utilities**（documentation）：Core utilities and abstractions for AI functionality in n8n. This package provides the foundational building blocks used internally by the n8n platform. 证据：`packages/@n8n/ai-utilities/README.md`\n- **Overview**（documentation）：createVectorStoreNode is a factory function that generates n8n nodes for vector store operations. It abstracts the common functionality needed for vector stores while allowing specific implementations to focus only on their unique aspects. 证据：`packages/@n8n/ai-utilities/src/utils/vector-store/createVectorStoreNode/README.md`\n- **AGENTS.md**（documentation）：Guidance for working with the AI Workflow Builder package. 证据：`packages/@n8n/ai-workflow-builder.ee/AGENTS.md`\n- **Claude**（documentation）：@AGENTS.md 证据：`packages/@n8n/ai-workflow-builder.ee/CLAUDE.md`\n- **Evaluations v2 harness**（documentation）：Internal evaluation harness for the AI Workflow Builder. Supports local CLI runs and LangSmith-backed runs, using the same evaluators. 证据：`packages/@n8n/ai-workflow-builder.ee/evaluations/README.md`\n- **n8n Workflow Comparison**（documentation）：Graph-based workflow similarity comparison using NetworkX and graph edit distance. 证据：`packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md`\n- **AI Workflow Builder Prompts**（documentation）：Centralized prompts for the n8n AI Workflow Builder. This directory contains all prompts used by agents and chains. 证据：`packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md`\n- **Anthropic Prompt Caching Strategy Visualization**（documentation）：Anthropic Prompt Caching Strategy Visualization 证据：`packages/@n8n/ai-workflow-builder.ee/src/utils/cache-control/README.md`\n- **@n8n/api-types**（documentation）：This package contains types and schema definitions for the n8n internal API, so that these can be shared between the backend and the frontend code. 证据：`packages/@n8n/api-types/README.md`\n- **n8n benchmarking tool**（documentation）：Tool for executing benchmarks against an n8n instance. 证据：`packages/@n8n/benchmark/README.md`\n- **@n8n/chat-hub**（documentation）：Common utility functions for n8n Chat Hub. 证据：`packages/@n8n/chat-hub/README.md`\n- **@n8n/cli**（documentation）：Beta — Client CLI for n8n. Manage workflows, executions, credentials, and more from the terminal. 证据：`packages/@n8n/cli/README.md`\n- **@n8n/codemirror-lang-html**（documentation）：HTML + n8n expression language support for CodeMirror 6. 证据：`packages/@n8n/codemirror-lang-html/README.md`\n- **codemirror-lang-n8n-sql**（documentation）：SQL + n8n expression language support for CodeMirror 6. 证据：`packages/@n8n/codemirror-lang-sql/README.md`\n- **@n8n/codemirror-lang**（documentation）：Language support package for CodeMirror 6 in n8n 证据：`packages/@n8n/codemirror-lang/README.md`\n- **n8n Expression language support**（documentation）：js import { parserWithMetaData as n8nParser } from '@n8n/codemirror-lang'; import { LanguageSupport, LRLanguage } from '@codemirror/language'; import { parseMixed } from '@lezer/common'; import { parser as jsParser } from '@lezer/javascript'; 证据：`packages/@n8n/codemirror-lang/src/expressions/README.md`\n- **@n8n/computer-use**（documentation）：Computer Use for n8n Assistant. Bridges a remote n8n instance with your local machine — filesystem, shell, screenshots, mouse/keyboard, and browser automation. 证据：`packages/@n8n/computer-use/README.md`\n- **@n8n/crdt**（documentation）：CRDT abstraction layer for n8n collaborative editing. Provides a unified API built on Yjs for real-time document synchronization. 证据：`packages/@n8n/crdt/README.md`\n- **@n8n/create-node**（documentation）：A powerful scaffolding tool to quickly create custom n8n community nodes with best practices built-in. 证据：`packages/@n8n/create-node/README.md`\n- **AGENTS.md**（documentation）：Extra information specific to the @n8n/db package. 证据：`packages/@n8n/db/AGENTS.md`\n- **@n8n/di**（documentation）：@n8n/di is a dependency injection DI container library, based on typedi https://github.com/typestack/typedi . 证据：`packages/@n8n/di/README.md`\n- **@n8n/engine**（documentation）：See the Engine 2.0 project https://linear.app/n8n/project/engine-20-59ba0ba60995 for context. Public API and core interfaces are still being defined; the package is currently a scaffold and is not yet wired into n8n. 证据：`packages/@n8n/engine/README.md`\n- **@n8n/eslint-plugin-community-nodes**（documentation）：ESLint plugin for linting n8n community node packages to ensure consistency and best practices. 证据：`packages/@n8n/eslint-plugin-community-nodes/README.md`\n- **@n8n/expression-runtime**（documentation）：Secure, isolated expression evaluation runtime for n8n workflows. 证据：`packages/@n8n/expression-runtime/README.md`\n- **@n8n/plugin-sdk**（documentation）：@n8n/plugin-sdk 证据：`packages/@n8n/extension-sdk/README.md`\n- **Instance AI — Development Guidelines**（documentation）：Instance AI — Development Guidelines 证据：`packages/@n8n/instance-ai/CLAUDE.md`\n- **Workflow evaluation framework**（documentation）：Tests whether workflows built by Instance AI actually work by executing them with LLM-generated mock HTTP responses. No real credentials or external services are involved. 证据：`packages/@n8n/instance-ai/evaluations/README.md`\n- **Json-Schema-to-Zod**（documentation）：A package to convert JSON schema draft 4+ objects into Zod schemas in the form of Zod objects at runtime. 证据：`packages/@n8n/json-schema-to-zod/README.md`\n- **@n8n/local-gateway**（documentation）：A native tray application that bridges an n8n cloud or self-hosted instance to capabilities on your local machine. It runs silently in the system tray and exposes a secure local HTTP gateway that n8n workflows can connect to. 证据：`packages/@n8n/local-gateway/README.md`\n- **Assets**（documentation）：Tray icons are derived from the official n8n brand guidelines: - Dark logo: https://n8n.io/brandguidelines/logo-dark.svg - White logo: https://n8n.io/brandguidelines/logo-white.svg 证据：`packages/@n8n/local-gateway/assets/README.md`\n- **@n8n/mcp-browser**（documentation）：MCP server that gives AI agents full control over Chrome. Connects to the user's real installed browser via the n8n AI Browser Bridge extension, using their actual profile, cookies, and sessions. Action tools return an accessibility snapshot with every response for single-roundtrip interaction. 证据：`packages/@n8n/mcp-browser/README.md`\n- **@n8n/node-cli**（documentation）：Official CLI for developing community nodes for n8n. 证据：`packages/@n8n/node-cli/README.md`\n- **{{nodePackageName}}**（documentation）：This is an n8n community node. It lets you use app/service name in your n8n workflows. 证据：`packages/@n8n/node-cli/src/template/templates/declarative/custom/template/README.md`\n- **{{nodePackageName}}**（documentation）：This is an n8n community node. It lets you use GitHub Issues in your n8n workflows. 证据：`packages/@n8n/node-cli/src/template/templates/declarative/github-issues/template/README.md`\n- **{{nodePackageName}}**（documentation）：This is an n8n community node. It lets you use app/service name in your n8n workflows. 证据：`packages/@n8n/node-cli/src/template/templates/programmatic/ai/memory-custom/template/README.md`\n- **{{nodePackageName}}**（documentation）：This is an n8n community node. It lets you use app/service name in your n8n workflows. 证据：`packages/@n8n/node-cli/src/template/templates/programmatic/ai/model-ai-custom-example/template/README.md`\n- **{{nodePackageName}}**（documentation）：This is an n8n community node. It lets you use app/service name in your n8n workflows. 证据：`packages/@n8n/node-cli/src/template/templates/programmatic/ai/model-ai-custom/template/README.md`\n- **{{nodePackageName}}**（documentation）：This is an n8n community node. It lets you use app/service name in your n8n workflows. 证据：`packages/@n8n/node-cli/src/template/templates/programmatic/ai/model-openai-compatible/template/README.md`\n- **{{nodePackageName}}**（documentation）：This is an n8n community node. It lets you use app/service name in your n8n workflows. 证据：`packages/@n8n/node-cli/src/template/templates/programmatic/example/template/README.md`\n- **n8n community node**（documentation）：Overview This is a project containing code for an n8n community node. n8n is a workflow automation platform where users build workflows with nodes, which are the building block of a workflow. Nodes can perform a range of actions, such as starting a workflow called a \"trigger node\" , fetching and sending data, or processing and manipulating it. Besides that there are credentials - entities that store sensitive information on how to connect to external services and APIs. A node can require some credentials to be used. Community nodes are a way for anyone to create such nodes and add them to be used in n8n. All community nodes are named in a format: n8n-nodes- or @org/n8n-nodes- . Community no… 证据：`packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md`\n- **Claude**（documentation）：@AGENTS.md 证据：`packages/@n8n/node-cli/src/template/templates/shared/default/CLAUDE.md`\n- **n8n-nodes-langchain**（documentation）：! Banner image https://user-images.githubusercontent.com/10284570/173569848-c624317f-42b1-45a6-ab09-f0ea3c247648.png 证据：`packages/@n8n/nodes-langchain/README.md`\n- **MCP Server**（documentation）：Model Context Protocol MCP server implementation for the n8n McpTrigger node. 证据：`packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md`\n- **ChatTrigger Local Development**（documentation）：This guide explains how to set up local development for the ChatTrigger node when working with the chat bundle. 证据：`packages/@n8n/nodes-langchain/nodes/trigger/ChatTrigger/README.md`\n- **n8n community-package static analysis tool**（documentation）：n8n community-package static analysis tool 证据：`packages/@n8n/scan-community-package/README.md`\n- **@n8n/stylelint-config**（documentation）：Stylelint configuration for n8n projects with custom CSS variable naming convention enforcement. 证据：`packages/@n8n/stylelint-config/README.md`\n- **Readme**（documentation）：This client is based upon the great work done in this project: https://github.com/paulgrove/node-syslog-client/tree/master 证据：`packages/@n8n/syslog-client/README.md`\n- **n8n Task Runner Python**（documentation）：- Python 3.13+ https://www.python.org/ - uv https://github.com/astral-sh/uv - just https://github.com/casey/just 证据：`packages/@n8n/task-runner-python/README.md`\n- **@n8n/tournament**（documentation）：Tournament is an output-compatible rewrite of riot-tmpl https://github.com/riot/tmpl for template expression evaluation. 证据：`packages/@n8n/tournament/README.md`\n- 其余 36 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`packages/frontend/@n8n/i18n/docs/README.md`, `.claude/README.md`, `.github/CLAUDE.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`packages/frontend/@n8n/i18n/docs/README.md`, `.claude/README.md`, `.github/CLAUDE.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **n8n 平台介绍**：importance `high`\n - source_paths: README.md, packages/cli/package.json, packages/@n8n/workflow-sdk/package.json\n- **快速入门指南**：importance `medium`\n - source_paths: CONTRIBUTING.md, docker/images/n8n/Dockerfile, packages/cli/src/commands/start.ts\n- **系统架构概览**：importance `high`\n - source_paths: packages/cli/src/abstract-server.ts, packages/@n8n/config/src/index.ts, packages/cli/package.json\n- **包结构与模块组织**：importance `high`\n - source_paths: packages/@n8n/workflow-sdk/src/index.ts, packages/@n8n/agents/src/index.ts, packages/@n8n/db/src/index.ts, packages/cli/src/index.ts\n- **工作流 SDK 与构建器**：importance `high`\n - source_paths: packages/@n8n/workflow-sdk/src/codegen/code-generator.ts, packages/@n8n/workflow-sdk/src/workflow-builder.ts, packages/@n8n/workflow-sdk/src/codegen/semantic-graph.ts, packages/@n8n/workflow-sdk/src/types/types.ts\n- **工作流执行引擎**：importance `high`\n - source_paths: packages/cli/src/active-workflow-manager.ts, packages/cli/src/executions/execution.service.ts, packages/@n8n/expression-runtime/src/evaluator/expression-evaluator.ts, packages/@n8n/workflow-sdk/src/ast-interpreter/interpreter.ts\n- **AI Agent 运行时**：importance `high`\n - source_paths: packages/@n8n/agents/src/runtime/agent-runtime.ts, packages/@n8n/agents/src/runtime/mcp-tool-resolver.ts, packages/@n8n/agents/src/sdk/agent.ts, packages/@n8n/agents/src/runtime/message-list.ts\n- **LangChain 节点集成**：importance `high`\n - source_paths: packages/@n8n/nodes-langchain/nodes/agents/Agent/V3/AgentV3.node.ts, packages/@n8n/nodes-langchain/nodes/llms/LMChatOpenAi/LmChatOpenAi.node.ts, packages/@n8n/nodes-langchain/nodes/mcp/McpClient/McpClient.node.ts, packages/@n8n/nodes-langchain/README.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `86170674b72acc16d781eafd08cd762c55a7672f`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `packages/cli/jest.config.migration.js`, `packages/cli/jest.config.js`, `packages/cli/nodemon.json`, `packages/cli/jest.config.integration.testcontainers.js`, `packages/cli/jest.config.integration.js`, `packages/cli/package.json`, `packages/cli/jest.config.unit.js`, `packages/cli/BREAKING-CHANGES.md`, `packages/cli/tsconfig.json`, `packages/cli/tsconfig.build.json`, `packages/cli/jest.config.migration.testcontainers.js`, `packages/workflow/jest.config.js`, `packages/workflow/vitest.config.ts`, `packages/workflow/tsconfig.build.esm.json`, `packages/workflow/package.json`, `packages/workflow/README.md`, `packages/workflow/tsconfig.build.cjs.json`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:193215554 | https://github.com/n8n-io/n8n | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 运行可能依赖外部服务\n\n- Trigger: 项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。\n- Host AI rule: 确认是否有离线 demo、mock 数据或可替代服务。\n- Why it matters: 本地安装成功不等于能力可用，外部服务不可用会阻断体验。\n- Evidence: packet_text.keyword_scan | github_repo:193215554 | https://github.com/n8n-io/n8n | matched external service / cloud / webhook / database keyword\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:193215554 | https://github.com/n8n-io/n8n | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:193215554 | https://github.com/n8n-io/n8n | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：n8n-io/n8n\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 运行可能依赖外部服务（medium）：本地安装成功不等于能力可用，外部服务不可用会阻断体验。 建议检查：确认是否有离线 demo、mock 数据或可替代服务。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/n8n-io/n8n 项目说明书\n\n生成时间：2026-05-11 08:46:20 UTC\n\n## 目录\n\n- [n8n 平台介绍](#page-introduction)\n- [快速入门指南](#page-quick-start)\n- [系统架构概览](#page-architecture)\n- [包结构与模块组织](#page-package-structure)\n- [工作流 SDK 与构建器](#page-workflow-sdk)\n- [工作流执行引擎](#page-execution-engine)\n- [AI Agent 运行时](#page-agents-runtime)\n- [LangChain 节点集成](#page-langchain-nodes)\n- [AI 工作流构建器](#page-ai-workflow-builder)\n- [数据库实体与数据管理](#page-database-entities)\n\n\n\n## n8n 平台介绍\n\n### 相关页面\n\n相关主题：[系统架构概览](#page-architecture), [快速入门指南](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# n8n 平台介绍\n\n## 概述\n\nn8n（发音为 \"n-eight-n\"）是一个强大的开源工作流自动化平台，采用 MIT 许可证发布。它允许用户通过可视化界面或代码方式连接各种应用程序、服务和 API，构建自动化工作流程。n8n 的核心理念是让技术用户和非技术人员都能轻松实现业务流程自动化，无需编写大量胶水代码。\n\n该平台的核心优势包括：\n\n- **可视化工作流编辑器**：直观的拖拽式界面，支持实时预览工作流执行\n- **丰富的节点生态系统**：内置 400+ 预构建节点，覆盖主流 SaaS 服务和协议\n- **灵活的代码执行**：支持 JavaScript 和 Python 编写自定义逻辑\n- **AI 集成能力**：内置 AI 工作流构建器，支持多代理系统和 LLM 调用\n- **自托管部署**：完全自主掌控数据和基础设施\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md:1-15]()\n\n## 架构设计\n\n### 核心模块结构\n\nn8n 采用 monorepo 架构组织代码，主要包含以下核心模块：\n\n| 模块路径 | 功能描述 |\n|---------|---------|\n| `packages/cli` | 命令行接口和后端服务核心 |\n| `packages/@n8n/workflow-sdk` | 工作流执行引擎和 SDK |\n| `packages/frontend/editor-ui` | 可视化工作流编辑器前端 |\n| `packages/@n8n/design-system` | 统一的 UI 组件库 |\n| `packages/@n8n/ai-workflow-builder.ee` | AI 工作流构建器（企业版） |\n\n### 工作流执行架构\n\n```mermaid\ngraph TD\n A[用户触发/定时器] --> B[工作流引擎]\n B --> C{节点类型判断}\n C -->|普通节点| D[节点执行器]\n C -->|代码节点| E[代码沙箱]\n C -->|AI 节点| F[AI 代理系统]\n D --> G[数据转换]\n E --> G\n F --> G\n G --> H[输出传递到下一节点]\n H --> C\n I{还有更多节点?} -->|是| D\n I -->|否| J[工作流完成]\n```\n\n### 节点执行模型\n\nn8n 的节点是工作流的基本构建单元，每个节点负责特定的数据处理或集成任务。\n\n```mermaid\ngraph LR\n A[输入数据] --> B[节点处理器]\n B --> C[数据转换]\n C --> D[执行操作]\n D --> E[输出数据]\n \n F[错误处理] -->|发生错误| G[错误工作流]\n G --> H[重试机制]\n H -->|重试成功| D\n H -->|重试耗尽| I[标记失败]\n```\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts:1-50]()\n\n## 节点系统\n\n### 节点分类\n\nn8n 中的节点按功能可分为以下几类：\n\n| 节点类别 | 示例节点 | 功能说明 |\n|---------|---------|---------|\n| 核心节点 | Set, IF, Switch | 数据转换和条件路由 |\n| 应用集成 | HTTP Request, Webhook | 外部服务连接 |\n| AI 节点 | AI Agent, LLM Chain | 人工智能能力 |\n| 工具节点 | *Tool | AI Agent 可调用的工具 |\n\n### 节点匹配模式\n\nn8n 使用模式匹配来识别和处理不同类型的节点：\n\n```typescript\n// 节点匹配示例\nconst patterns = {\n set: 'n8n-nodes-base.set', // Set 节点\n if: 'n8n-nodes-base.if', // IF 条件节点\n switch: 'n8n-nodes-base.switch', // Switch 路由节点\n httpRequest: 'n8n-nodes-base.httpRequest' // HTTP 请求节点\n};\n```\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md:80-95]()\n\n## 代码节点\n\n### 概述\n\n代码节点允许用户在 n8n 工作流中执行自定义 JavaScript 或 Python 代码。这是实现复杂业务逻辑的关键功能。\n\n### 输入数据访问\n\n代码节点提供多种方式访问输入数据：\n\n| 方法 | 描述 | 示例 |\n|-----|------|-----|\n| `$input.first()` | 获取第一个输入项 | `$input.first().json` |\n| `$input.last()` | 获取最后一个输入项 | `$input.last().binary` |\n| `$input.all()` | 获取所有输入项数组 | `$input.all()[index].json` |\n| `$input.item` | 当前处理项 | `$input.item.json` |\n\n### 代码补全支持\n\nn8n 的代码编辑器提供智能代码补全功能：\n\n```typescript\n// JavaScript 模式\nconst prefix = '$';\n// Python 模式\nconst prefix = '_';\n\n// 支持的补全选项\nconst options = [\n { label: `${matcher}.json`, info: 'JSON 数据访问' },\n { label: `${matcher}.binary`, info: '二进制数据访问' }\n];\n```\n\n资料来源：[packages/frontend/editor-ui/src/features/shared/editors/components/CodeNodeEditor/completions/itemField.completions.ts:1-60]()\n\n## AI 工作流构建器\n\n### 概述\n\nn8n 的 AI 工作流构建器（AI Workflow Builder）是一个高级功能，允许用户通过自然语言描述创建和修改工作流。该系统采用多代理架构，协同完成从用户意图到可执行工作流的转换。\n\n### 代理系统架构\n\n```mermaid\ngraph TD\n A[用户自然语言请求] --> B[Supervisor 代理]\n B --> C[Discovery 代理]\n B --> D[Builder 代理]\n B --> E[Responder 代理]\n C -->|识别节点| C1[节点分类]\n C --> C2[技术识别]\n D --> D1[结构创建]\n D --> D2[参数配置]\n E --> F[用户响应]\n```\n\n| 代理名称 | 职责 | 功能 |\n|---------|------|-----|\n| **Supervisor** | 任务路由 | 分析请求并分配给合适的专业代理 |\n| **Discovery** | 发现识别 | 识别相关 n8n 节点和分类技术 |\n| **Builder** | 构建器 | 创建工作流结构并配置节点参数 |\n| **Responder** | 响应器 | 生成面向用户的回复内容 |\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md:40-55]()\n\n### PromptBuilder 工具\n\nPromptBuilder 是一个类型安全的流式构建器，用于组合 LLM 提示词：\n\n```typescript\nconst systemPrompt = prompt()\n .section('role', 'You are an assistant')\n .sectionIf(hasContext, 'context', () => buildContext())\n .examples('examples', data, (ex) => `${ex.input} → ${ex.output}`)\n .build();\n```\n\n#### 核心特性\n\n| 特性 | 说明 |\n|-----|------|\n| 流式 API | 链式方法调用 |\n| 条件部分 | `sectionIf()` 和 `examplesIf()` |\n| 延迟求值 | 工厂函数仅在构建时求值 |\n| 输出格式 | 支持 XML 标签或 Markdown 标题 |\n| LangChain 集成 | `buildAsMessageBlocks()` 支持缓存控制 |\n\n#### 构建流程\n\n```mermaid\ngraph LR\n A[Section 定义] --> B[内容解析]\n B --> C{内容为空?}\n C -->|是| D[跳过该部分]\n C -->|否| E[格式化输出]\n E --> F[使用指定格式]\n F --> G[合并分隔符]\n G --> H[最终提示词]\n```\n\n#### 主要方法\n\n```typescript\nclass PromptBuilder {\n section(name: string, content: string | FactoryFn): this\n sectionIf(condition: boolean, name: string, content: FactoryFn): this\n examples(name: string, items: unknown[], renderer: RendererFn): this\n examplesIf(condition: boolean, name: string, items: unknown[], renderer: RendererFn): this\n merge(other: PromptBuilder): this\n build(): string\n buildAsMessageBlocks(): BaseMessage[]\n}\n```\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts:1-100]()\n\n### Web 抓取工具\n\nn8n 提供 Web 抓取功能作为 AI 代理的可调用工具：\n\n```typescript\ninterface WebFetchConfig {\n url: string;\n options?: {\n extractImages?: boolean;\n descriptionLength?: number;\n };\n}\n\n// 返回格式\ninterface WebFetchResult {\n url: string;\n finalUrl?: string;\n title: string;\n content: string;\n truncated: boolean;\n truncateReason?: string;\n}\n```\n\n#### 抓取结果结构\n\n```xml\n\n 原始 URL\n 重定向后 URL\n 页面标题\n 截断说明（如果被截断）\n \n 提取的页面内容\n \n\n```\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts:1-80]()\n\n## 用户界面\n\n### 设计系统\n\nn8n 使用统一的设计系统（Design System）确保界面一致性：\n\n```typescript\n// 徽章组件示例\nCompleted\nPending\nFailed\n```\n\n#### 主题类型\n\n| 主题 | 用途 | 视觉效果 |\n|-----|------|---------|\n| `success` | 成功状态 | 绿色 |\n| `warning` | 警告状态 | 黄色/橙色 |\n| `danger` | 错误/失败 | 红色 |\n| `default` | 默认状态 | 灰色 |\n| `tertiary` | 次要信息 | 浅灰色 |\n\n### 国际化\n\nn8n 支持多语言界面，主要文本资源存储在本地化文件中：\n\n```typescript\n// 英文本地化示例\n'codeNodeEditor.completer.json': 'JSON 数据访问',\n'codeNodeEditor.completer.binary': '二进制数据访问',\n'sticky.markdownHint': 'You can style with Markdown',\n'askAssistantButton.askAssistant': 'n8n AI',\n```\n\n#### AI Builder 界面文本\n\n| 文本键 | 说明 |\n|-------|------|\n| `assistantChat.builder.generatingFinalWorkflow` | 正在生成最终工作流 |\n| `assistantChat.builder.configuredNodes` | 已配置的节点 |\n| `assistantChat.builder.thumbsUp` | 有帮助 |\n| `assistantChat.builder.thumbsDown` | 没有帮助 |\n| `assistantChat.builder.feedbackPlaceholder` | 反馈占位符 |\n| `assistantChat.builder.success` | 感谢反馈 |\n| `assistantChat.builder.feedbackSubmit` | 提交反馈 |\n\n资料来源：[packages/frontend/@n8n/design-system/src/locale/lang/en.ts:1-50]()\n\n## 安全性\n\n### SSO/SAML 认证\n\nn8n 企业版支持 SAML 2.0 单点登录，集成了 WS-SecurityPolicy 1.2 标准：\n\n#### 支持的安全策略\n\n| 断言类型 | 功能说明 |\n|---------|---------|\n| `TransportBinding` | 传输层绑定 |\n| `IncludeTimestamp` | 时间戳包含 |\n| `SymmetricBinding` | 对称绑定 |\n| `X509Token` | X.509 证书令牌 |\n| `Wss11` | Web 服务安全 1.1 |\n\n#### X.509 令牌支持\n\nn8n 支持多种 X.509 证书格式：\n\n| 格式 | 说明 |\n|-----|------|\n| `WssX509V3Token10` | X.509 v3 令牌 1.0 |\n| `WssX509Pkcs7Token10` | PKCS#7 封装格式 |\n| `WssX509PkiPathV1Token10` | PKI 路径格式 |\n\n#### 信任配置\n\n```xml\n\n\n \n 10.1 Trust13 Assertion\n \n\n```\n\n支持的可选配置：\n\n- `MustSupportClientChallenge`：客户端挑战\n- `MustSupportServerChallenge`：服务端挑战\n- `RequireClientEntropy`：客户端熵\n- `RequireServerEntropy`：服务端熵\n- `MustSupportIssuedTokens`：支持颁发令牌\n\n#### 算法套件\n\n支持多种加密算法套件：\n\n| 算法类型 | 示例 |\n|---------|------|\n| 基本加密 | Basic256, Basic192, Basic128, TripleDes |\n| SHA256 变体 | Basic256Sha256, TripleDesSha256 |\n| RSA15 变体 | Basic256Rsa15, TripleDesSha256Rsa15 |\n\n#### 引用类型\n\n支持多种密钥引用方式：\n\n| 引用类型 | 说明 |\n|---------|------|\n| `RequireKeyIdentifierReference` | 密钥标识符引用 |\n| `RequireIssuerSerialReference` | 颁发者序列号引用 |\n| `RequireEmbeddedTokenReference` | 嵌入式令牌引用 |\n| `RequireThumbprintReference` | 指纹引用 |\n\n资料来源：[packages/cli/src/modules/sso-saml/schema/ws-securitypolicy-1.2.xsd.ts:1-200]()\n\n## 部署方式\n\n### 部署模式\n\nn8n 支持多种部署方式：\n\n| 部署方式 | 适用场景 | 特点 |\n|---------|---------|------|\n| Docker | 快速部署 | 环境隔离 |\n| Kubernetes | 生产环境 | 高可用、弹性伸缩 |\n| npm | 开发测试 | 简单快捷 |\n| 云托管 | SaaS | 免维护 |\n\n### 环境配置\n\n关键环境变量：\n\n| 变量名 | 说明 | 默认值 |\n|-------|------|-------|\n| `N8N_BASIC_AUTH_ACTIVE` | 启用基础认证 | `false` |\n| `N8N_HOST` | 服务地址 | `localhost` |\n| `N8N_PORT` | 服务端口 | `5678` |\n| `WEBHOOK_URL` | Webhook 基础 URL | - |\n| `EXECUTIONS_DATA_SAVE_ON_ERROR` | 错误时保存执行数据 | `all` |\n| `EXECUTIONS_DATA_SAVE_ON_SUCCESS` | 成功时保存数据 | `all` |\n\n## 总结\n\nn8n 是一个功能全面的开源工作流自动化平台，通过其模块化架构和丰富的节点生态系统，能够满足从简单任务自动化到复杂 AI 工作流的各种需求。平台的 AI 工作流构建器代表了工作流自动化领域的创新方向，让非技术用户也能通过自然语言描述创建自动化流程。同时，完善的 SSO/SAML 支持确保了企业级部署的安全性要求。\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[n8n 平台介绍](#page-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [prompt-builder.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)\n- [chat-hub-workflow.service.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts)\n- [web-fetch.tool.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts)\n- [component-badge.md](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/v2/components/Badge/component-badge.md)\n- [component-popover.md](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/components/N8nPopover/component-popover.md)\n- [useChatHubMarkdownOptions.ts](https://github.com/n8n-io/n8n/blob/main/packages/frontend/editor-ui/src/features/ai/chatHub/composables/useChatHubMarkdownOptions.ts)\n- [saml-schema-protocol-2.0.xsd.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/modules/sso-saml/schema/saml-schema-protocol-2.0.xsd.ts)\n- [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)\n \n\n# 快速入门指南\n\n## 概述\n\nn8n 是一个强大的工作流自动化平台，支持通过可视化界面或代码方式构建自动化流程。本快速入门指南旨在帮助开发者快速上手 n8n 平台的核心功能，包括 AI 工作流构建器、聊天中心（Chat Hub）服务、Web 获取工具以及 UI 组件系统的使用方法。\n\n本指南涵盖的范围包括：\n\n- **AI 工作流构建器**：用于构建 AI 驱动的自动化工作流\n- **聊天中心服务**：提供对话式 AI 交互能力\n- **Web 获取工具**：从外部 URL 抓取内容并整合到工作流中\n- **设计系统组件**：提供统一的 UI 组件库\n\n---\n\n## 环境准备\n\n### 系统要求\n\n在开始使用 n8n 之前，请确保您的开发环境满足以下基本要求：\n\n| 要求类型 | 最低配置 | 推荐配置 |\n|---------|---------|----------|\n| Node.js | 18.x | 20.x LTS |\n| 内存 | 4GB | 8GB 或以上 |\n| 磁盘空间 | 2GB | 10GB 或以上 |\n| 操作系统 | macOS/Linux/Windows | macOS/Linux |\n\n### 核心依赖包\n\nn8n 的核心功能由多个包组成，主要包括：\n\n- `packages/cli`：命令行工具和核心服务\n- `packages/@n8n/ai-workflow-builder.ee`：AI 工作流构建器（企业版）\n- `packages/frontend`：前端编辑器界面\n- `@n8n/design-system`：统一的设计系统组件库\n\n---\n\n## AI 工作流构建器\n\n### PromptBuilder 类\n\n`PromptBuilder` 是 n8n AI 工作流构建器的核心类，用于构建结构化的提示词模板。资料来源：[prompt-builder.ts:1]()\n\n**主要特性：**\n\n- 支持链式调用（方法链模式）\n- 支持动态内容解析\n- 支持多格式输出（Markdown/XML）\n- 支持与 LangChain 消息块集成\n\n### 核心方法\n\n#### 添加示例（addExamples）\n\n`addExamples` 方法用于向提示词添加示例内容：\n\n```typescript\naddExamples(examples: string[]): this {\n // ...\n const examplesContent = examples.join('\\n\\n');\n const examplesBlock = this.format === 'markdown'\n ? `## Examples\\n${examplesContent}`\n : `\\n${examplesContent}\\n`;\n // ...\n}\n```\n\n资料来源：[prompt-builder.ts:15-25]()\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| examples | string[] | 示例字符串数组 |\n\n#### 合并提示词（merge）\n\n`merge` 方法允许将另一个 `PromptBuilder` 实例的节（sections）合并到当前实例中：\n\n```typescript\nmerge(other: PromptBuilder): this {\n for (const section of other.sections) {\n this.sections.push({ ...section });\n }\n return this;\n}\n```\n\n资料来源：[prompt-builder.ts:50-55]()\n\n#### 构建输出（build）\n\n`build` 方法是最终的输出方法，它会遍历所有节，解析内容，并按照指定的分隔符和格式组装最终的提示词字符串：\n\n```typescript\nbuild(): string {\n const formatted: string[] = [];\n for (const section of this.sections) {\n const content = resolveContent(section.content);\n if (content === null) {\n continue;\n }\n const sectionFormat = section.options.format ?? this.format;\n formatted.push(formatSection(section.name, content, sectionFormat, section.options.tag));\n }\n return formatted.join(this.separator);\n}\n```\n\n资料来源：[prompt-builder.ts:63-74]()\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[创建 PromptBuilder] --> B[添加 Sections]\n B --> C[可选：添加 Examples]\n C --> D[可选：合并其他 Builder]\n D --> E[调用 build 方法]\n E --> F[生成最终提示词]\n \n G[resolveContent] --> H{内容为 null?}\n H -->|是| I[跳过该节]\n H -->|否| J[应用格式]\n J --> K[组装输出]\n```\n\n---\n\n## 聊天中心服务\n\n### ChatHubWorkflowService\n\n`ChatHubWorkflowService` 是 n8n 聊天中心的核心服务，负责处理对话式工作流的构建和管理。资料来源：[chat-hub-workflow.service.ts:1]()\n\n### 基础系统消息\n\n聊天中心使用基础系统消息来定义 AI 助手的角色和行为：\n\n```typescript\nprivate getBaseSystemMessage(history: ChatHubMessage[], timeZone: string) {\n const artifactContext = this.buildArtifactContext(history);\n return `You are a helpful assistant.\n${this.getSystemMessageMetadata(timeZone) + artifactContext}`;\n}\n```\n\n资料来源：[chat-hub-workflow.service.ts:35-40]()\n\n### 工件上下文构建\n\n聊天中心支持构建和管理工件上下文（Artifact Context），这使得 AI 能够理解和管理会话中的文档和内容。\n\n### 构建工具代理节点\n\n`buildToolsAgentNode` 方法用于构建支持流式输出的工具代理节点：\n\n```typescript\nprivate buildToolsAgentNode(\n model: ChatHubConversationModel,\n systemMessage: string,\n enableStreaming = true,\n): INode {\n return {\n parameters: {\n promptType: 'define',\n text: `={{ $('${NODE_NAMES.CHAT_TRIGGER}').item.json.chatInput }}`,\n options: {\n enableStreaming,\n maxTokensFromMemory: /* ... */\n },\n },\n };\n}\n```\n\n资料来源：[chat-hub-workflow.service.ts:47-60]()\n\n### 核心参数配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| promptType | string | 'define' | 提示词类型 |\n| enableStreaming | boolean | true | 是否启用流式输出 |\n| maxTokensFromMemory | number | - | 从记忆中获取的最大 token 数 |\n\n---\n\n## Web 获取工具\n\n### WebFetchTool 概述\n\n`WebFetchTool` 是 n8n AI 工作流构建器中的关键工具，用于从外部 URL 获取内容。资料来源：[web-fetch.tool.ts:1]()\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[接收 URL 输入] --> B[验证 URL 格式]\n B --> C[执行 HTTP 请求]\n C --> D{请求成功?}\n D -->|否| E[返回错误响应]\n D -->|是| F[提取可读内容]\n F --> G[构建响应行]\n G --> H[记录安全事件]\n H --> I[返回成功响应]\n \n J[ZodError 验证失败] --> K[返回 ValidationError]\n```\n\n### 响应格式\n\nWeb 获取工具的响应采用结构化的 XML 格式：\n\n```xml\n\n 原始 URL\n 最终 URL（重定向后）\n 页面标题\n 截断说明（如适用）\n \n 提取的内容\n \n\n```\n\n资料来源：[web-fetch.tool.ts:35-48]()\n\n### 状态管理\n\n工具会维护获取状态并记录相关的状态更新：\n\n```typescript\nconst stateUpdates: Record = {\n ...security.getStateUpdates(),\n fetchedUrlContent: [\n {\n url,\n status: 'success' as const,\n title: extracted.title,\n content: extracted.content,\n },\n ],\n};\n```\n\n资料来源：[web-fetch.tool.ts:61-70]()\n\n### 错误处理\n\n工具使用 Zod 进行输入验证，验证失败时会抛出 `ValidationError`：\n\n```typescript\nif (error instanceof z.ZodError) {\n const validationError = new ValidationError('Invalid URL input', {\n extra: { errors: error.errors },\n });\n reporter.error(validationError);\n}\n```\n\n资料来源：[web-fetch.tool.ts:77-81]()\n\n---\n\n## 设计系统组件\n\n### Badge 组件\n\nn8n 设计系统提供了统一的 Badge 组件用于状态显示。资料来源：[component-badge.md:1]()\n\n#### 主题类型\n\n| 主题值 | 用途 | 视觉样式 |\n|-------|------|---------|\n| 'success' | 成功状态 | 绿色 |\n| 'warning' | 警告状态 | 黄色/橙色 |\n| 'danger' | 危险/错误状态 | 红色 |\n| 'tertiary' | 次要/只读状态 | 灰色 |\n| 'default' | 默认状态 | 灰色 |\n\n#### 使用示例\n\n**基础用法：**\n\n```vue\n\n Completed\n\n```\n\n**动态主题绑定：**\n\n```typescript\nconst getStatusTheme = (status: string): BadgeTheme => {\n const themeMap: Record = {\n completed: 'success',\n pending: 'warning',\n failed: 'danger',\n }\n return themeMap[status] || 'default'\n}\n```\n\n资料来源：[component-badge.md:25-35]()\n\n### Popover 组件\n\n`N8nPopover` 组件提供弹出式内容展示功能。资料来源：[component-popover.md:1]()\n\n#### 核心属性\n\n| 属性 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| side | 'top' \\| 'bottom' \\| 'left' \\| 'right' | 'bottom' | 弹出方向 |\n| width | string | '300px' | 弹出框宽度 |\n| teleported | boolean | true | 是否传送到 body |\n| side-offset | number | 8 | 与触发器的偏移量 |\n\n#### 使用示例\n\n**带触发的下拉菜单：**\n\n```vue\n\n \n \n \n \n \n \n\n```\n\n资料来源：[component-popover.md:10-25]()\n\n**使用关闭函数：**\n\n```vue\n\n \n \n \n \n \n \n\n```\n\n资料来源：[component-popover.md:70-80]()\n\n---\n\n## Markdown 渲染选项\n\n### useChatHubMarkdownOptions\n\n`useChatHubMarkdownOptions` 是聊天中心使用的 Markdown 渲染配置 hook。资料来源：[useChatHubMarkdownOptions.ts:1]()\n\n### 插件列表\n\n| 插件名称 | 功能 |\n|---------|------|\n| linksNewTabPlugin | 将链接在新标签页打开 |\n| codeBlockPlugin | 代码块渲染增强 |\n| tablePlugin | 表格渲染支持 |\n| mathPlugin | 数学公式渲染 |\n| footnotePlugin | 脚注功能（隐藏显示，仅保留胶囊） |\n\n### 脚注处理\n\n聊天中心对脚注进行了特殊处理，将脚注块隐藏，仅保留可点击的脚注引用胶囊：\n\n```typescript\nconst footnotePlugin = () => {\n // Hide the footnote block — the pill is the only UI for footnote content\n md.renderer.rules.footnote_block_open = () => '';\n md.renderer.rules.footnote_block_close = () => '
';\n md.renderer.rules.footnote_open = () => '';\n md.renderer.rules.footnote_close = () => '';\n md.renderer.rules.footnote_anchor = () => '';\n};\n```\n\n资料来源：[useChatHubMarkdownOptions.ts:25-32]()\n\n### 链接新标签页处理\n\n链接在新标签页打开时会显示完整的 URL 作为 tooltip：\n\n```typescript\nconst linksNewTabPlugin = () => {\n const defaultRender = md.renderer.rules.link_open || /* ... */;\n md.renderer.rules.link_open = (tokens, idx, options, env, self) => {\n const aIndex = tokens[idx].attrIndex('target');\n if (aIndex < 0) {\n tokens[idx].attrPush(['target', '_blank']);\n } else {\n tokens[idx].attrs[aIndex][1] = '_blank';\n }\n // ...\n const escapedFull = encoder.encode(fullHref);\n const escapedTruncated = encoder.encode(truncatedHref);\n return `${escapedTruncated}`;\n };\n};\n```\n\n资料来源：[useChatHubMarkdownOptions.ts:8-24]()\n\n---\n\n## SSO/SAML 认证\n\n### SAML 2.0 协议支持\n\nn8n 提供了完整的 SAML 2.0 协议支持，包括以下核心功能：\n\n- **Artifact 处理**：支持 SAML Artifact 绑定\n- **单点登出 (SLO)**：支持 ManageNameID 和 LogoutRequest\n- **名称标识管理**：支持 NameID 的加密和转换\n\n资料来源：[saml-schema-protocol-2.0.xsd.ts:1]()\n\n### Web 服务安全策略\n\nWS-SecurityPolicy 1.2 定义了 SOAP 消息的安全策略，包括：\n\n| 策略类型 | 说明 |\n|---------|------|\n| TransportBinding | 传输层绑定 |\n| SymmetricBinding | 对称密钥绑定 |\n| X509Token | X.509 证书令牌 |\n| Trust13 | Trust 1.3 断言 |\n| AlgorithmSuite | 加密算法套件 |\n\n资料来源：[ws-securitypolicy-1.2.xsd.ts:1]()\n\n---\n\n## 常见问题\n\n### 如何调试 AI 工作流？\n\n使用 `PromptBuilder` 的 `build()` 方法可以预览最终的提示词内容：\n\n```typescript\nconst builder = new PromptBuilder();\nbuilder.addSection('instruction', '回答用户问题');\nbuilder.addExamples(['示例1', '示例2']);\nconsole.log(builder.build());\n```\n\n### Web 获取工具返回的内容被截断了怎么办？\n\n工具默认会对超长内容进行截断。如果需要完整内容，可以在工具配置中调整 `maxContentLength` 参数。\n\n### 设计系统组件在 SSR 环境中使用注意事项？\n\n`N8nPopover` 默认使用 `teleported` 模式，会将内容传送到 `body`。在 SSR 环境中，建议设置 `:teleported=\"false\"` 以保持 DOM 层级一致：\n\n```vue\n\n \n\n```\n\n---\n\n## 下一步\n\n- 查看 [CONTRIBUTING.md](https://github.com/n8n-io/n8n/blob/main/CONTRIBUTING.md) 了解贡献指南\n- 探索更多 [AI 工作流示例](https://github.com/n8n-io/n8n/tree/main/packages/@n8n/ai-workflow-builder.ee)\n- 阅读 [设计系统文档](https://github.com/n8n-io/n8n/tree/main/packages/frontend/@n8n/design-system)\n\n---\n\n\n\n## 系统架构概览\n\n### 相关页面\n\n相关主题：[包结构与模块组织](#page-package-structure), [工作流 SDK 与构建器](#page-workflow-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# 系统架构概览\n\n## 概述\n\nn8n 是一个开源的工作流自动化平台，其核心架构围绕模块化设计构建。系统架构概览旨在帮助开发者理解 n8n 平台的关键组件、它们之间的交互关系以及扩展机制。\n\n从源码层面分析，n8n 的架构涵盖以下几个核心领域：\n\n| 模块 | 功能描述 | 所在包 |\n|------|---------|--------|\n| AI Workflow Builder | 支持 AI 功能的工作流构建器 | `@n8n/ai-workflow-builder.ee` |\n| Prompt Builder | 动态提示词构建工具 | `@n8n/ai-workflow-builder.ee/src/prompts` |\n| Web Fetch Tool | 网页内容抓取与提取 | `@n8n/ai-workflow-builder.ee/src/tools` |\n| Design System | UI 组件库与国际化 | `@n8n/design-system` |\n| CLI Core | 命令行核心模块 | `@n8n/cli` |\n\n## 核心组件架构\n\n### PromptBuilder 提示词构建器\n\n`PromptBuilder` 是 n8n AI 工作流构建器中的核心工具类，提供类型安全的链式 API 用于组合 LLM 提示词。\n\n```mermaid\nclassDiagram\n class PromptBuilder {\n -sections: SectionEntry[]\n -format: SectionFormat\n -separator: string\n +section(name, content, options): this\n +sectionIf(condition, name, content, options): this\n +examples(name, data, formatter): this\n +merge(other: PromptBuilder): this\n +build(): string\n }\n \n class SectionEntry {\n +name: string\n +content: ContentOrFactory\n +options: SectionOptions\n }\n \n PromptBuilder *-- SectionEntry\n```\n\n**主要特性：**\n\n- **链式 API**：支持方法链式调用，便于阅读的提示词组合方式\n- **条件节**：通过 `sectionIf()` 实现动态内容包含\n- **延迟求值**：工厂函数仅在构建时调用\n- **多格式输出**：支持 XML 标签（默认）和 Markdown 标题两种格式\n\n资料来源：[prompt-builder.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts)\n\n### SectionEntry 数据结构\n\n```typescript\ninterface SectionEntry {\n name: string;\n content: ContentOrFactory;\n options: SectionOptions;\n}\n\ntype ContentOrFactory = string | (() => string | null);\n```\n\n每个节（Section）包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `name` | `string` | 节的显示名称，用于生成标签 |\n| `content` | `ContentOrFactory` | 字符串内容或延迟求值的工厂函数 |\n| `options` | `SectionOptions` | 可选配置项 |\n\n资料来源：[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)\n\n### WebFetchTool 网页抓取工具\n\n`WebFetchTool` 是 n8n AI 工作流中的网页内容抓取与提取工具，负责从 URL 获取网页内容并进行可读性处理。\n\n```mermaid\nflowchart TD\n A[输入 URL] --> B[验证 URL 格式]\n B --> C{验证是否通过}\n C -->|通过| D[发起 HTTP 请求]\n C -->|失败| E[返回验证错误]\n D --> F[提取可读内容]\n F --> G[构建响应结果]\n G --> H[记录安全状态]\n H --> I[返回结构化数据]\n```\n\n**处理流程：**\n\n1. 接收并验证 URL 输入\n2. 执行 HTTP 请求获取网页内容\n3. 提取标题和正文内容\n4. 构建结构化的 XML 格式响应\n5. 记录安全相关状态更新\n\n```typescript\nconst responseLines = [\n '',\n `${url}`,\n `${extracted.title}`,\n '',\n extracted.content,\n '',\n '',\n]\n```\n\n资料来源：[web-fetch.tool.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts)\n\n## 安全策略模块\n\n### WS-SecurityPolicy 1.2 XSD 架构\n\nn8n 的 SSO-SAML 模块包含完整的 WS-SecurityPolicy 1.2 XSD Schema 定义，用于配置 Web 服务安全策略。\n\n**主要策略类型：**\n\n| 类型 | 说明 | 代码参考 |\n|------|------|----------|\n| `NestedPolicyType` | 嵌套策略类型 | `tns:NestedPolicyType` |\n| `QNameAssertionType` | QName 断言类型 | `tns:QNameAssertionType` |\n| `TokenAssertionType` | Token 断言类型 | `tns:TokenAssertionType` |\n\n**核心安全断言：**\n\n- **AlgorithmSuite Assertion** (7.1)：定义加密算法套件，支持 Basic256、Basic192、Basic128、TripleDes 等\n- **Layout Assertion** (7.2)：定义消息布局规则，包括 Strict、Lax、LaxTsFirst、LaxTsLast\n- **TransportBinding** (7.3)：传输层绑定配置\n- **SymmetricBinding** (7.4)：对称密钥绑定\n- **Trust13 Assertion** (10.1)：WS-Trust 1.3 规范支持\n\n```xml\n\n \n \n 7.1 AlgorithmSuite Assertion\n \n \n\n```\n\n资料来源：[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)\n\n## 设计系统架构\n\n### Badge 组件\n\nn8n 设计系统提供了统一的 Badge 组件，用于在工作流界面中展示状态信息。\n\n```typescript\ninterface FileStatus {\n status: 'completed' | 'pending' | 'failed'\n}\n\nconst getStatusTheme = (status: string): BadgeTheme => {\n const themeMap: Record = {\n completed: 'success',\n pending: 'warning',\n failed: 'danger',\n }\n return themeMap[status] || 'default'\n}\n```\n\n**主题映射：**\n\n| 状态 | 主题 | 颜色语义 |\n|------|------|---------|\n| completed | success | 成功/绿色 |\n| pending | warning | 警告/黄色 |\n| failed | danger | 危险/红色 |\n\n**组件使用示例：**\n\n```vue\n\n Read Only\n\n\n\n Setup Required\n\n```\n\n资料来源：[component-badge.md](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/v2/components/Badge/component-badge.md)\n\n### 国际化配置\n\nn8n 设计系统支持多语言配置，主要通过 `en.ts` 文件定义英文翻译键值对。\n\n```typescript\n'codeDiff.couldNotReplace': 'Could not replace code',\n'codeDiff.codeReplaced': 'Code replaced',\n'codeDiff.replaceMyCode': 'Replace my code',\n'codeDiff.replacing': 'Replacing...',\n'codeDiff.undo': 'Undo',\n```\n\n**AI Builder 相关翻译：**\n\n```typescript\n'assistantChat.builder.name': 'AI Builder',\n'assistantChat.builder.generatingFinalWorkflow': 'Generating final workflow...',\n'assistantChat.builder.configuredNodes': 'Configured nodes',\n'assistantChat.builder.thumbsUp': 'Helpful',\n'assistantChat.builder.thumbsDown': 'Not helpful',\n```\n\n资料来源：[en.ts](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/src/locale/lang/en.ts)\n\n## 指南系统架构\n\n### 节点类型指南\n\nAI Workflow Builder 提供了可扩展的节点指南系统，支持按节点类型和条件动态匹配指南内容。\n\n```typescript\nexport const MY_NODE_GUIDE: NodeTypeGuide = {\n patterns: ['n8n-nodes-base.myNode'], // 匹配的节点类型\n condition: (ctx) => true, // 可选：额外条件\n content: `Your guide content here...`,\n};\n```\n\n**当前指南覆盖：**\n\n| 指南 | 模式 | 用途 |\n|------|------|------|\n| Set Node | `n8n-nodes-base.set` | 赋值结构与类型 |\n| IF Node | `n8n-nodes-base.if` | 过滤条件与运算符 |\n| Switch Node | `n8n-nodes-base.switch` | 规则与路由 |\n| HTTP Request | `n8n-nodes-base.httpRequest` | URL、头、请求体、认证 |\n| Tool Nodes | `*Tool` | $fromAI 表达式 |\n| Resource Locator | `*` (条件) | __rl 结构与模式 |\n| System Message | `*` (条件) | AI 节点消息分离 |\n\n**条件指南示例：**\n\n```typescript\nexport const RESOURCE_LOCATOR_GUIDE: NodeTypeGuide = {\n patterns: ['*'], // 匹配所有节点\n condition: (ctx) => ctx.hasResourceLocatorParams === true,\n content: `...`,\n};\n```\n\n资料来源：[README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)\n\n## 模块交互关系\n\n```mermaid\ngraph TD\n A[User Input] --> B[AI Workflow Builder]\n B --> C[PromptBuilder]\n C --> D{Section Type}\n D -->|Conditional| E[sectionIf]\n D -->|Examples| F[examples]\n D -->|Static| G[section]\n E --> H[buildAsMessageBlocks]\n G --> H\n F --> H\n H --> I[LLM Response]\n I --> J[Execute Nodes]\n J --> K[WebFetchTool]\n K --> L[Extract Content]\n L --> J\n J --> M[Return Result]\n \n N[Design System] --> O[Badge Component]\n N --> P[i18n Strings]\n O --> Q[UI Render]\n P --> Q\n```\n\n## 配置选项\n\n### PromptBuilder 配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `format` | `SectionFormat` | `'xml'` | 输出格式：xml 或 markdown |\n| `separator` | `string` | `'\\n\\n'` | 节之间的分隔符 |\n\n### SectionOptions 配置\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `format` | `SectionFormat` | 覆盖全局格式设置 |\n| `tag` | `string` | 自定义标签名称 |\n\n## 最佳实践\n\n### 提示词构建规范\n\n1. **使用条件节**：对于可能缺失的内容使用 `sectionIf()` 避免空值问题\n2. **延迟求值**：复杂内容使用工厂函数而非直接字符串\n3. **格式一致性**：在同一项目中保持统一的输出格式\n4. **示例驱动**：使用 `examples()` 方法提供少样本学习示例\n\n### 指南扩展规范\n\n1. 在 `guides/` 目录创建新的指南文件\n2. 从 `guides/index.ts` 导出新指南\n3. 将指南添加到 `registry.ts` 的注册数组中\n4. 使用条件匹配实现上下文相关的指南内容\n\n## 总结\n\nn8n 的系统架构体现了现代工作流自动化平台的设计理念：\n\n- **模块化设计**：各功能模块解耦，便于独立维护和扩展\n- **类型安全**：TypeScript 优先，确保编译期错误检测\n- **可扩展性**：通过指南系统和提示词模板支持自定义行为\n- **国际化**：完整的 i18n 支持，便于多语言适配\n\n这些架构特性使得 n8n 能够同时支持传统工作流和 AI 增强工作流的开发需求。\n\n---\n\n\n\n## 包结构与模块组织\n\n### 相关页面\n\n相关主题：[系统架构概览](#page-architecture), [工作流 SDK 与构建器](#page-workflow-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [packages/@n8n/node-cli/README.md](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/node-cli/README.md)\n- [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)\n- [packages/testing/janitor/README.md](https://github.com/n8n-io/n8n/blob/main/packages/testing/janitor/README.md)\n- [packages/frontend/@n8n/design-system/README.md](https://github.com/n8n-io/n8n/blob/main/packages/frontend/@n8n/design-system/README.md)\n \n\n# 包结构与模块组织\n\n## 概述\n\nn8n 是一个开源的工作流自动化平台，采用 **Monorepo（单体仓库）** 架构组织代码。项目使用 pnpm 作为包管理器，通过 `pnpm-workspace.yaml` 定义工作区配置。整体架构划分为多个功能明确的子包（packages），涵盖工作流核心、CLI 工具、UI 组件、AI 构建器、数据库层和测试基础设施等模块。\n\n## 核心包结构\n\nn8n 的包结构遵循 **功能分离** 原则，每个包都有明确的职责边界和对外 API 接口。\n\n| 包路径 | 用途说明 |\n|--------|----------|\n| `packages/cli` | CLI 主入口，处理命令行交互和服务器初始化 |\n| `packages/@n8n/workflow-sdk` | 工作流核心 SDK，定义节点、连接、表达式等核心概念 |\n| `packages/@n8n/agents` | AI Agent 能力封装 |\n| `packages/@n8n/db` | 数据库抽象层 |\n| `packages/frontend/editor-ui` | 工作流编辑器前端界面 |\n| `packages/frontend/@n8n/design-system` | 统一设计系统和 UI 组件库 |\n| `packages/@n8n/node-cli` | 节点开发脚手架工具 |\n| `packages/@n8n/ai-workflow-builder.ee` | AI 工作流构建器（企业版） |\n| `packages/testing` | 测试工具和基础设施 |\n\n## 模块层次架构\n\nn8n 采用 **分层架构** 设计，从底层到上层依次为：\n\n```mermaid\ngraph TD\n A[\"packages/@n8n/db
数据库抽象层\"] --> B[\"packages/@n8n/workflow-sdk
工作流核心\"]\n B --> C[\"packages/@n8n/agents
AI Agent 层\"]\n C --> D[\"packages/@n8n/ai-workflow-builder.ee
AI 工作流构建器\"]\n B --> E[\"packages/cli
CLI 与服务层\"]\n E --> F[\"packages/frontend/editor-ui
前端编辑器\"]\n F --> G[\"packages/frontend/@n8n/design-system
设计系统\"]\n```\n\n## 工作流核心 SDK\n\n`packages/@n8n/workflow-sdk` 是整个平台的核心，封装了工作流执行的全部基础能力。\n\n### 核心职责\n\n- 定义节点（Node）和凭证（Credentials）接口\n- 实现工作流执行引擎\n- 提供表达式解析和求值\n- 管理连接和数据流转\n\n### 包导出模式\n\nSDK 包使用 ** barrel export** 模式统一对外暴露 API，通过 `src/index.ts` 作为唯一入口点：\n\n```typescript\n// 资料来源：packages/@n8n/workflow-sdk/src/index.ts\nexport * from './nodes';\nexport * from './credentials';\nexport * from './workflow';\nexport * from './expression';\n```\n\n## AI 工作流构建器架构\n\n`packages/@n8n/ai-workflow-builder.ee` 是企业级 AI 辅助工作流构建模块，包含完整的提示词工程和 Agent 协作系统。\n\n### 多 Agent 协作体系\n\nAI 工作流构建器采用 **多 Agent 路由架构**，每个 Agent 都有明确的职责分工：\n\n| Agent | 职责 | 说明 |\n|-------|------|------|\n| **Supervisor** | 路由协调 | 接收用户请求并分发给合适的专家 Agent |\n| **Discovery** | 节点发现 | 识别相关 n8n 节点并分类技术方案 |\n| **Builder** | 构建执行 | 创建工作流结构并配置节点参数 |\n| **Responder** | 响应生成 | 生成面向用户的回复内容 |\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md]()\n\n### 提示词构建器（PromptBuilder）\n\n核心模块使用 **PromptBuilder** 工具类实现提示词的组合式构建：\n\n```typescript\n// 资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts\nconst systemPrompt = prompt()\n .section('role', 'You are an assistant')\n .sectionIf(hasContext, 'context', () => buildContext())\n .examples('examples', data, (ex) => `${ex.input} → ${ex.output}`)\n .build();\n```\n\n#### PromptBuilder 关键特性\n\n| 特性 | 说明 |\n|------|------|\n| **流式 API** | 支持链式调用，方法返回 `this` |\n| **条件节** | `sectionIf()` 根据条件动态包含内容 |\n| **惰性求值** | 工厂函数仅在构建时执行 |\n| **双格式输出** | 支持 XML 标签和 Markdown 标题两种格式 |\n| **LangChain 集成** | 支持 `cache_control` 缓存控制 |\n\n### 提示词模板结构\n\n代码构建器提示词由多个标准节组成：\n\n```mermaid\ngraph LR\n A[\"\"] --> B[\"\"]\n B --> C[\"\"]\n C --> D[\"\"]\n D --> E[\"\"]\n E --> F[\"\"]\n F --> G[\"\"]\n```\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts]()\n\n## CLI 工具与节点开发\n\n### 节点脚手架工具\n\n`packages/@n8n/node-cli` 提供节点开发的标准化工具体系：\n\n```bash\n# 创建新节点\nnpm create @n8n/node my-awesome-node\ncd my-awesome-node\n\n# 启动开发模式\nnpm run dev\n```\n\n资料来源：[packages/@n8n/node-cli/README.md]()\n\n### 节点项目结构规范\n\nn8n 要求节点项目遵循统一的目录结构：\n\n```\nmy-node/\n├── src/\n│ ├── nodes/\n│ │ └── MyNode/\n│ │ ├── MyNode.node.ts # 节点主实现\n│ │ └── MyNode.node.json # 节点元数据\n│ └── credentials/\n│ └── MyNodeAuth.credentials.ts\n├── package.json\n└── tsconfig.json\n```\n\n资料来源：[packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md]()\n\n### package.json 配置约定\n\n节点包必须在 `package.json` 中声明 `n8n` 字段：\n\n```json\n{\n \"name\": \"n8n-nodes-example\",\n \"version\": \"1.0.0\",\n \"n8n\": {\n \"n8nNodesApiVersion\": 1,\n \"nodes\": [\"dist/nodes/MyNode/MyNode.node.js\"],\n \"credentials\": [\"dist/credentials/MyNodeAuth.credentials.js\"]\n }\n}\n```\n\n## 前端组件体系\n\n### 设计系统\n\n`packages/frontend/@n8n/design-system` 封装了 n8n 的统一视觉语言：\n\n```bash\n# 开发预览\npnpm storybook\n\n# 构建静态页面\npnpm build:storybook\n\n# 构建 CSS 主题\npnpm build:theme\n\n# 监听并自动构建\npnpm watch:theme\n```\n\n资料来源：[packages/frontend/@n8n/design-system/README.md]()\n\n### 编辑器组件测试\n\n编辑器使用 Vue 3 + Composition API 开发，测试采用 Vue Test Utils：\n\n```typescript\n// 资料来源：packages/frontend/editor-ui/src/app/components/MainHeader/MainHeader.test.ts\ndescribe('MainHeader', () => {\n beforeEach(() => {\n workflowsStore = mockedStore(useWorkflowsStore);\n workflowDocumentStore.hydrate({\n id: '1',\n name: 'Test Workflow',\n active: false,\n // ...\n });\n });\n});\n```\n\n## 测试基础设施\n\n### Playwright Janitor\n\n`packages/testing/janitor` 是端到端测试编排工具，支持分片并行执行：\n\n```bash\n# 分 14 片执行\nplaywright-janitor orchestrate --shards=14\n\n# 仅执行受 Git 变更影响的测试\nplaywright-janitor orchestrate --shards=14 --impact\n```\n\n资料来源：[packages/testing/janitor/README.md]()\n\n### 架构规则\n\n测试框架定义了严格的架构规则：\n\n| 规则 | 严重级别 | 说明 |\n|------|----------|------|\n| `boundary-protection` | error | 禁止页面对象直接导入其他页面 |\n| `scope-lockdown` | error | 页面对象必须有 `container` 或导航方法 |\n| `test-data-hygiene` | warning | 检测孤立/通用的测试数据文件 |\n| `duplicate-logic` | warning | 检测代码重复（AST 结构指纹） |\n\n### 页面对象隔离原则\n\n```typescript\n// 资料来源：packages/testing/janitor/README.md\n\n// 不推荐 - 页面间耦合\nexport class WorkflowPage {\n async openSettings() {\n await this.settingsPage.open();\n }\n}\n\n// 推荐 - 页面独立，组合在 flows 层\nexport class WorkflowPage {\n async getWorkflowName() {\n return this.header.getByTestId('workflow-name').textContent();\n }\n}\n```\n\n## 数据库模块\n\n`packages/@n8n/db` 提供数据库访问的统一抽象层，处理 ORM 配置、迁移管理和连接池等基础设施问题。\n\n### 包导出模式\n\n```typescript\n// 资料来源：packages/@n8n/db/src/index.ts\nexport * from './connection';\nexport * from './repositories';\nexport * from './migrations';\n```\n\n## 模块间依赖关系\n\n```mermaid\ngraph TD\n CLI[\"packages/cli
CLI 入口\"]\n SDK[\"packages/@n8n/workflow-sdk
工作流 SDK\"]\n DB[\"packages/@n8n/db
数据库层\"]\n AGENTS[\"packages/@n8n/agents
AI Agent\"]\n AI_BUILDER[\"packages/@n8n/ai-workflow-builder.ee
AI 构建器\"]\n EDITOR[\"packages/frontend/editor-ui
编辑器 UI\"]\n DESIGN[\"packages/frontend/@n8n/design-system
设计系统\"]\n\n DB --> SDK\n SDK --> CLI\n SDK --> AGENTS\n AGENTS --> AI_BUILDER\n CLI --> EDITOR\n EDITOR --> DESIGN\n```\n\n## 命名规范与导出约定\n\n### Barrel Export 模式\n\n所有包遵循统一的 Barrel Export 模式组织导出：\n\n```typescript\n// src/index.ts - 包入口文件\nexport * from './core'; // 核心功能\nexport * from './types'; // 类型定义\nexport * from './constants'; // 常量\nexport { SpecificClass } from './internal/specific'; // 按需导出\n```\n\n### 命名空间约定\n\n| 层级 | 命名方式 | 示例 |\n|------|----------|------|\n| 包名 | `@n8n/功能名` | `@n8n/workflow-sdk` |\n| 导出类 | PascalCase | `WorkflowExecutor` |\n| 导出函数 | camelCase | `executeWorkflow` |\n| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |\n| 类型/接口 | PascalCase + 后缀 | `WorkflowNode`, `NodeCredentials` |\n\n## 扩展机制\n\n### 节点开发扩展\n\n通过 `n8n-nodes-` 前缀注册自定义节点：\n\n```json\n{\n \"name\": \"n8n-nodes-my-service\",\n \"n8n\": {\n \"nodes\": [\"dist/nodes/MyNode/MyNode.node.js\"]\n }\n}\n```\n\n### 提示词指南扩展\n\nAI 构建器支持通过模式匹配注入节点指南：\n\n```typescript\n// 资料来源：packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md\nexport const MY_NODE_GUIDE: NodeTypeGuide = {\n patterns: ['n8n-nodes-base.myNode'],\n condition: (ctx) => true,\n content: `指南内容...`,\n};\n```\n\n## 总结\n\nn8n 的包结构设计体现了以下核心原则：\n\n1. **职责分离** - 每个包有明确边界，通过接口而非实现通信\n2. **可扩展性** - 节点系统和 AI 构建器都支持插件式扩展\n3. **层次清晰** - 依赖关系自底向上，CLI 和 UI 依赖核心 SDK\n4. **统一规范** - Barrel Export、命名约定、文档结构保持一致\n5. **测试完备** - 专门的测试基础设施支持 E2E 和单元测试\n\n---\n\n\n\n## 工作流 SDK 与构建器\n\n### 相关页面\n\n相关主题：[工作流执行引擎](#page-execution-engine), [系统架构概览](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# 工作流 SDK 与构建器\n\n## 概述\n\n工作流 SDK 与构建器（Workflow SDK and Builder）是 n8n 平台中用于通过 AI 能力自动生成、构建和优化工作流的综合技术栈。该系统由多个核心组件构成，包括提示构建器（PromptBuilder）、语义图（Semantic Graph）、代码生成器（Code Generator）以及多代理协调系统。这些组件协同工作，使开发者能够通过自然语言描述或结构化指令来自动生成复杂的工作流配置。\n\nn8n 的工作流构建系统采用了分层的架构设计，将工作流的语义表示与实际的代码生成解耦。这种设计允许不同的生成策略（如基于规则的生成、基于 AI 的生成）共享同一套语义模型，从而保证了生成结果的一致性和可维护性。\n\n## 核心架构\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n A[用户输入] --> B[多代理协调器]\n B --> C[发现代理 Discovery]\n B --> D[构建代理 Builder]\n B --> E[响应代理 Responder]\n C --> F[节点分类系统]\n D --> G[PromptBuilder]\n G --> H[ChatPromptTemplate]\n H --> I[LLM 服务]\n I --> J[代码生成]\n J --> K[Semantic Graph]\n K --> L[Code Generator]\n L --> M[Workflow JSON]\n```\n\n### 组件职责矩阵\n\n| 组件 | 职责 | 主要文件 |\n|------|------|----------|\n| **PromptBuilder** | 负责构建结构化的 LLM 提示，支持条件化、可组合的提示段 | prompt-builder.ts |\n| **Code Generator** | 将语义图转换为实际的代码输出 | code-generator.ts |\n| **Semantic Graph** | 管理工作流的语义表示和节点关系 | semantic-graph.ts |\n| **Workflow Builder** | 提供工作流构建的高级 API | workflow-builder.ts |\n| **多代理系统** | 协调不同专业代理完成复杂任务 | agents/ 目录 |\n\n## 提示构建器（PromptBuilder）\n\n### 设计理念\n\nPromptBuilder 是一个类型安全的、流畅式（Fluent）API，用于组合 LLM 提示。该类支持条件化内容块、延迟求值、多种输出格式以及与 LangChain 的深度集成。资料来源：[prompt-builder.ts:1-100]()\n\nPromptBuilder 的核心设计原则包括：\n\n1. **可组合性**：通过 `merge()` 方法可以合并多个 PromptBuilder 实例\n2. **延迟求值**：工厂函数仅在构建时求值，避免不必要的计算\n3. **条件渲染**：通过 `sectionIf()` 和 `examplesIf()` 支持条件化内容\n4. **格式灵活性**：支持 XML 标签格式和 Markdown 格式\n\n### 核心方法\n\n```typescript\nclass PromptBuilder {\n // 添加始终包含的段落\n section(name: string, content: ContentOrFactory, options?: SectionOptions): this;\n \n // 条件性添加段落\n sectionIf(condition: unknown, name: string, content: ContentOrFactory, options?: SectionOptions): this;\n \n // 添加示例段落\n examples(name: string, data: unknown[], formatter: ExampleFormatter): this;\n \n // 条件性添加示例\n examplesIf(condition: unknown, name: string, data: unknown[], formatter: ExampleFormatter): this;\n \n // 合并另一个 PromptBuilder\n merge(other: PromptBuilder): this;\n \n // 构建最终提示字符串\n build(): string;\n \n // 构建为 LangChain 消息块\n buildAsMessageBlocks(): BaseMessage[];\n}\n```\n\n### 使用示例\n\n```typescript\nconst systemPrompt = prompt()\n .section('ROLE', 'You are an assistant')\n .sectionIf(hasContext, 'CONTEXT', () => buildContext())\n .examples('EXAMPLES', data, (ex) => `${ex.input} → ${ex.output}`)\n .build();\n```\n\n资料来源：[prompt-builder.ts:100-150]()\n\n### 输出格式\n\nPromptBuilder 支持两种主要的输出格式，通过 `SectionFormat` 类型定义：\n\n| 格式 | 说明 | 示例输出 |\n|------|------|----------|\n| `xml` | XML 标签格式（默认） | `内容` |\n| `markdown` | Markdown 标题格式 | `## Section Name\\n内容` |\n\n### 段落选项配置\n\n```typescript\ninterface SectionOptions {\n format?: SectionFormat; // 覆盖默认格式\n tag?: string; // 自定义标签名\n}\n```\n\n## 代码构建器提示系统\n\n### 系统提示构建流程\n\n```mermaid\ngraph LR\n A[buildCodeBuilderPrompt] --> B[buildMandatoryWorkflow]\n B --> C[ROLE]\n B --> D[RESPONSE_STYLE]\n B --> E[WORKFLOW_RULES]\n B --> F[WORKFLOW_PATTERNS]\n C --> G[EXPRESSION_REFERENCE]\n D --> H[ADDITIONAL_FUNCTIONS]\n E --> I[ChatPromptTemplate]\n F --> J[系统消息]\n G --> J\n H --> J\n J --> K[cache_control配置]\n```\n\n代码构建器使用 `buildCodeBuilderPrompt()` 函数生成完整的系统提示，该函数整合了多个预定义的提示组件。资料来源：[packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts]()\n\n### 提示组件列表\n\n| 组件 | 用途 | XML 标签 |\n|------|------|----------|\n| `ROLE` | 定义 AI 角色和行为 | `` |\n| `RESPONSE_STYLE` | 规定响应格式和风格 | `` |\n| `WORKFLOW_RULES` | 工作流构建规则 | `` |\n| `WORKFLOW_PATTERNS` | 常见工作流模式 | `` |\n| `EXPRESSION_REFERENCE` | 表达式语法参考 | `` |\n| `ADDITIONAL_FUNCTIONS` | 额外可用函数 | `` |\n| `mandatory_workflow_process` | 强制性工作流处理流程 | `` |\n\n### 用户消息构建\n\n用户消息部分通过 `buildUserMessageParts()` 函数构建，包含以下可选组件：\n\n1. **当前工作流上下文**：当存在正在进行的工作流时提供\n2. **历史上下文**：多轮对话中的历史记录\n3. **工作流文件状态**：检查是否存在现有工作流代码\n4. **已批准的计划输出**：计划模式的结果\n5. **预搜索结果**：提前获取的搜索结果以节省 LLM 交互\n\n```typescript\nfunction buildUserMessageParts(\n currentWorkflow?: WorkflowJSON,\n historyContext?: HistoryContext,\n options?: BuildCodeBuilderPromptOptions,\n): string[]\n```\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts]()\n\n### LangChain 集成\n\n系统提示通过 `ChatPromptTemplate.fromMessages()` 包装，并配置了 `cache_control` 选项以支持 LLM 的上下文缓存：\n\n```typescript\nreturn ChatPromptTemplate.fromMessages([\n ['system', [{ \n type: 'text', \n text: systemMessage, \n cache_control: { type: 'ephemeral' } \n }]],\n ['user', userMessageTemplate]\n]);\n```\n\n## 多代理工作流系统\n\n### 代理架构\n\nn8n 采用多代理架构来协调复杂的工作流构建任务。代理目录包含针对不同专业领域的专门提示。资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md]()\n\n| 代理 | 职责 | 说明 |\n|------|------|------|\n| **Supervisor** | 路由用户请求 | 将请求分发到合适的专业代理 |\n| **Discovery** | 发现和分类 | 识别相关 n8n 节点并分类技术 |\n| **Builder** | 构建工作流 | 创建工作流结构并配置节点参数 |\n| **Responder** | 生成响应 | 生成面向用户的结果输出 |\n\n### 链式提示系统\n\n`chains/` 目录包含用于特定 LLM 链操作的提示：\n\n| 链 | 用途 | 说明 |\n|-----|------|------|\n| **Categorization** | 分析用户提示 | 识别工作流技术和模式 |\n| **Compact** | 压缩对话 | 总结对话以便后续处理 |\n\n## 节点与参数指南系统\n\n### 指南注册机制\n\nn8n 提供了基于模式的节点指南系统，通过 `NodeTypeGuide` 接口定义：\n\n```typescript\ninterface NodeTypeGuide {\n patterns: string[]; // 匹配节点类型的模式\n condition?: (ctx: GuideContext) => boolean; // 额外条件\n content: string; // 指南内容\n}\n```\n\n### 内置指南列表\n\n| 指南 | 节点模式 | 用途 |\n|------|----------|------|\n| Set Node | `n8n-nodes-base.set` | 赋值结构与类型 |\n| IF Node | `n8n-nodes-base.if` | 过滤条件与运算符 |\n| Switch Node | `n8n-nodes-base.switch` | 规则和路由 |\n| HTTP Request | `n8n-nodes-base.httpRequest` | URL、头、请求体、认证 |\n| Tool Nodes | `*Tool` | $fromAI 表达式 |\n| Resource Locator | `*` (条件性) | __rl 结构和模式 |\n| System Message | `*` (条件性) | AI 节点消息分离 |\n| Text Fields | `*` (条件性) | 表达式处理 |\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/prompts/guides/README.md]()\n\n### 添加新指南\n\n1. 在 `guides/` 目录创建新的指南文件\n2. 从 `guides/index.ts` 导出\n3. 在 `registry.ts` 的注册数组中添加\n\n## 工具系统\n\n### Web 获取工具\n\n`WebFetchTool` 提供了网页内容抓取能力，使用可读内容提取器处理 HTML 响应：\n\n```mermaid\ngraph TD\n A[URL 输入] --> B[URL 验证]\n B --> C[安全检查]\n C --> D[HTTP 请求]\n D --> E[内容提取]\n E --> F[可读内容提取]\n F --> G[状态记录]\n G --> H[响应构建]\n H --> I[]\n```\n\n### 工具响应格式\n\n```xml\n\n 原始URL\n 最终URL\n 页面标题\n 提取的内容\n 截断说明（可选）\n\n```\n\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts]()\n\n## 构建与生成流程\n\n### 工作流生成流程\n\n```mermaid\ngraph TD\n A[自然语言描述] --> B[Discovery 代理]\n B --> C[节点分类]\n C --> D[Builder 代理]\n D --> E[PromptBuilder 组装]\n E --> F[LLM 生成]\n F --> G[Semantic Graph]\n G --> H[Code Generator]\n H --> I[Workflow JSON]\n I --> J[执行验证]\n J --> K[工作流部署]\n```\n\n### 代码生成策略\n\n工作流 SDK 支持多种代码生成策略：\n\n1. **基于模板的生成**：使用预定义模板填充参数\n2. **基于 AI 的生成**：通过 LLM 理解语义并生成\n3. **混合生成**：结合模板和 AI 能力\n\n### 语义图管理\n\n语义图（Semantic Graph）负责：\n\n- 管理工作流节点和连接的语义表示\n- 提供节点关系的查询接口\n- 支持工作流的语义验证\n\n## 类型系统\n\n### 关键类型定义\n\n```typescript\ntype ContentOrFactory = string | (() => string | null);\n\ntype SectionFormat = 'xml' | 'markdown';\n\ntype ExampleFormatter = (item: unknown) => string;\n\ninterface SectionEntry {\n name: string;\n content: ContentOrFactory;\n options: SectionOptions;\n}\n\ninterface SectionOptions {\n format?: SectionFormat;\n tag?: string;\n}\n\ninterface PromptBuilderOptions {\n format?: SectionFormat;\n separator?: string;\n}\n```\n\n## 配置与扩展\n\n### PromptBuilder 配置选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `format` | `SectionFormat` | `'xml'` | 默认输出格式 |\n| `separator` | `string` | `'\\n\\n'` | 段落分隔符 |\n\n### 段落格式配置\n\n```typescript\n// 使用自定义分隔符\nconst prompt = new PromptBuilder({ separator: '\\n---\\n' });\n\n// 使用 Markdown 格式\nconst prompt = new PromptBuilder({ format: 'markdown' });\n\n// 自定义段落格式\nprompt.section('custom', 'content', { \n format: 'markdown',\n tag: 'CustomSection'\n});\n```\n\n## 最佳实践\n\n### 提示构建最佳实践\n\n1. **保持简洁**：每个段落应专注于单一概念\n2. **使用条件化段落**：避免不必要的空内容\n3. **延迟求值**：复杂计算使用工厂函数\n4. **合理使用分隔符**：清晰的段落分隔提高可读性\n\n### 代码生成最佳实践\n\n1. **语义优先**：先生成语义图，再转换为代码\n2. **验证语义**：在生成前验证工作流语义的正确性\n3. **版本控制**：保持生成结果的可追溯性\n\n## 总结\n\n工作流 SDK 与构建器是 n8n 智能工作流生成系统的核心基础设施。通过 PromptBuilder 提供的类型安全、流畅式 API，开发者可以轻松构建复杂的 LLM 提示。多代理系统则协调各个专业代理完成从需求理解到工作流生成的完整流程。语义图和代码生成器将高层语义转换为可执行的工作流配置，确保了生成结果的质量和一致性。\n\n该系统的设计体现了几个关键原则：可组合性（通过 merge 和 section 方法）、延迟求值（通过工厂函数）、条件化渲染（通过 sectionIf 方法）以及与 LangChain 的深度集成。这些设计使得工作流构建系统既灵活又高效，能够满足不同场景下的工作流生成需求。\n\n---\n\n\n\n## 工作流执行引擎\n\n### 相关页面\n\n相关主题：[工作流 SDK 与构建器](#page-workflow-sdk), [数据库实体与数据管理](#page-database-entities)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [packages/cli/src/active-workflow-manager.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/active-workflow-manager.ts)\n- [packages/cli/src/executions/execution.service.ts](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/executions/execution.service.ts)\n- [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)\n- [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)\n \n\n# 工作流执行引擎\n\n## 概述\n\nn8n 的工作流执行引擎是自动化工作流的运行时核心，负责协调节点的执行顺序、管理数据流转、处理表达式求值以及维护执行状态。该引擎支持手动执行和生产执行两种模式，能够在不同的触发条件下激活工作流实例。\n\n工作流执行引擎的核心职责包括：\n\n1. **节点调度**：根据工作流定义的有向图结构，确定节点的执行顺序\n2. **数据传递**：在节点之间传递输入输出数据，处理二进制和 JSON 数据\n3. **表达式求值**：在运行时解析和计算表达式，支持变量引用和函数调用\n4. **版本管理**：支持工作流的草稿版本和生产版本区分\n5. **错误处理**：捕获节点执行异常，提供重试和错误恢复机制\n\n## 核心架构\n\n### 执行模式\n\nn8n 工作流执行引擎支持两种主要执行模式：\n\n| 执行模式 | 描述 | 适用场景 |\n|---------|------|---------|\n| `manual` | 手动触发执行 | 调试、测试、单次运行 |\n| `production` | 生产环境执行 | 定时任务、Webhook、API 调用 |\n\n生产模式执行时，系统会验证工作流是否已激活并具有活跃版本。若工作流没有已发布（active）的版本，执行将被拒绝并抛出 `WorkflowAccessError` 错误。\n\n```typescript\n资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:8-12]()\n\nif (executionMode === 'production' && !workflow.activeVersionId) {\n throw new WorkflowAccessError(\n `Workflow '${workflowId}' has no published (active) version to execute`,\n 'workflow_not_active',\n );\n}\n```\n\n### 版本数据管理\n\n工作流执行引擎根据执行模式选择对应的版本数据：\n\n```mermaid\ngraph TD\n A[开始执行] --> B{执行模式是 production?}\n B -->|是| C[使用 activeVersion]\n B -->|否| D[使用草稿版本]\n C --> E[提取 nodes 和 connections]\n D --> E\n E --> F[查找触发节点]\n F --> G[生成 MCP 消息ID]\n G --> H[构建运行数据]\n \n style C fill:#e1f5fe\n style D fill:#fff3e0\n```\n\n引擎通过 `getVersionDataForExecution` 函数根据执行模式选择正确的版本数据：\n\n```typescript\n资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:14-24]()\n\nconst getVersionDataForExecution = (\n workflow: FoundWorkflow,\n workflowId: string,\n executionMode: z.infer['executionMode'],\n) => {\n const nodes =\n executionMode === 'production' \n ? (workflow.activeVersion?.nodes ?? []) \n : (workflow.nodes ?? []);\n const connections =\n executionMode === 'production'\n ? (workflow.activeVersion?.connections ?? {})\n : (workflow.connections ?? {});\n return { nodes, connections };\n};\n```\n\n## 触发节点机制\n\n### 支持的触发节点\n\n工作流执行引擎仅支持特定类型的触发节点。系统定义了 `getSupportedTriggerNamesForMode` 函数来获取当前执行模式支持的触发器名称列表：\n\n```typescript\n资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:36-39]()\n\nif (!triggerNode) {\n throw new WorkflowAccessError(\n `Only workflows with the following trigger nodes can be executed: ${getSupportedTriggerNamesForMode(executionMode).join(', ')}.`,\n 'unsupported_trigger',\n );\n}\n```\n\n### 触发节点查找\n\n引擎使用 `findMcpSupportedTrigger` 函数在工作流节点列表中查找符合条件的触发节点，该函数会扫描所有节点并识别支持 MCP 协议的触发器。\n\n## 执行数据构建\n\n### 运行数据结构\n\n工作流执行引擎构建 `IWorkflowExecutionDataProcess` 类型的运行数据，该数据结构包含执行工作流所需的全部信息，包括：\n\n- 工作流定义（节点和连接）\n- 执行模式\n- 用户上下文\n- 触发节点信息\n- 输入数据\n\n### MCP 消息标识\n\n为每次执行生成唯一的 MCP 消息 ID，用于队列模式下的关联和追踪：\n\n```typescript\n资料来源：[packages/cli/src/modules/mcp/tools/execute-workflow.tool.ts:42-44]()\n\nconst mcpMessageId = `mcp-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;\n```\n\n消息 ID 格式：`mcp-{时间戳}-{随机字符串}`，确保在分布式环境中的唯一性。\n\n## 表达式运行时\n\n### 表达式求值器\n\n表达式求值器是工作流执行引擎的关键组件，负责在运行时解析包含变量引用和函数的表达式。求值器支持：\n\n- 简单变量替换：`{{ $json.name }}`\n- 复杂表达式计算：`{{ Math.ceil($json.price * 1.1) }}`\n- 条件表达式：`{{ $json.value > 10 ? '高' : '低' }}`\n- 节点输出引用：`{{ $json(\"NodeName\").value }}`\n\n### AST 解释器\n\n抽象语法树（AST）解释器是表达式运行时的新一代实现，采用 AST 而非字符串解析方式处理表达式，具有以下优势：\n\n| 特性 | 传统方式 | AST 方式 |\n|------|---------|---------|\n| 解析速度 | 每次求值重新解析 | 预编译为 AST |\n| 错误检测 | 运行时才发现 | 预编译时验证 |\n| 优化能力 | 有限 | 支持常量折叠 |\n| 调试能力 | 困难 | 可追踪执行路径 |\n\n## 错误处理机制\n\n### 验证错误\n\n引擎使用 Zod 进行输入验证，当验证失败时会创建 `ValidationError` 并记录详细错误信息：\n\n```typescript\n资料来源：[packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts:68-73]()\n\nif (error instanceof z.ZodError) {\n const validationError = new ValidationError('Invalid URL input', {\n extra: { errors: error.errors },\n });\n reporter.error(validationError);\n}\n```\n\n### 工作流访问错误\n\n当工作流状态不符合执行条件时，引擎抛出 `WorkflowAccessError`，错误类型包括：\n\n| 错误类型 | 触发条件 |\n|---------|---------|\n| `workflow_not_active` | 生产模式执行但工作流未激活 |\n| `unsupported_trigger` | 工作流不包含支持的触发节点 |\n\n## 执行服务\n\n### 执行服务架构\n\n执行服务（Execution Service）负责管理执行的生命周期，包括：\n\n1. **执行创建**：初始化新的执行实例\n2. **执行排队**：将执行请求加入执行队列\n3. **执行监控**：跟踪执行进度和状态\n4. **执行完成**：保存执行结果并清理资源\n\n### 活跃工作流管理器\n\n活跃工作流管理器（Active Workflow Manager）维护当前活跃工作流的注册表，负责：\n\n- 工作流激活与停用\n- 触发器注册与移除\n- 活跃连接管理\n\n```mermaid\ngraph LR\n A[用户激活工作流] --> B[ActiveWorkflowManager]\n B --> C[注册触发器]\n C --> D[添加到活跃列表]\n \n E[触发事件到达] --> F[查找对应工作流]\n F --> G[创建执行实例]\n G --> H[执行引擎调度]\n \n I[用户停用工作流] --> J[移除触发器]\n J --> K[从活跃列表删除]\n```\n\n## 扩展机制\n\n### MCP 工具集成\n\nn8n 支持通过 MCP（Model Context Protocol）协议扩展执行引擎的能力。MCP 工具允许外部系统调用 n8n 工作流，实现与 AI 代理和其他自动化系统的集成。\n\nMCP 执行工具的核心功能：\n\n- 接收外部执行请求\n- 验证工作流和用户权限\n- 选择正确的执行模式\n- 返回执行结果\n\n### 执行模式配置\n\n引擎支持通过配置选项自定义执行行为：\n\n```typescript\n// 执行请求输入模式定义\nconst inputSchema = z.object({\n executionMode: z.enum(['production', 'manual']),\n inputs: z.record(z.any()).optional(),\n});\n```\n\n## 数据流处理\n\n### 输入数据处理\n\n工作流执行引擎支持通过 `inputs` 参数向工作流传递初始数据：\n\n```mermaid\ngraph TD\n A[外部输入] --> B[inputs 验证]\n B --> C{验证通过?}\n C -->|是| D[注入到触发节点]\n C -->|否| E[返回验证错误]\n D --> F[开始节点执行]\n```\n\n### 输出数据返回\n\n执行完成后，引擎收集所有节点的输出数据，整理为统一的响应格式返回给调用方。\n\n## 相关组件\n\n| 组件 | 包路径 | 职责 |\n|------|-------|------|\n| 执行服务 | `packages/cli/src/executions/` | 执行生命周期管理 |\n| 活跃工作流管理器 | `packages/cli/src/active-workflow-manager.ts` | 工作流激活状态管理 |\n| 表达式求值器 | `packages/@n8n/expression-runtime/src/evaluator/` | 表达式运行时解析 |\n| AST 解释器 | `packages/@n8n/workflow-sdk/src/ast-interpreter/` | 高级表达式处理 |\n| MCP 执行工具 | `packages/cli/src/modules/mcp/tools/` | 外部协议集成 |\n\n---\n\n\n\n## AI Agent 运行时\n\n### 相关页面\n\n相关主题：[LangChain 节点集成](#page-langchain-nodes), [AI 工作流构建器](#page-ai-workflow-builder)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/@n8n/agents/src/runtime/agent-runtime.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/agents/src/runtime/agent-runtime.ts)\n- [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)\n- [packages/@n8n/agents/src/sdk/agent.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/agents/src/sdk/agent.ts)\n- [packages/@n8n/agents/src/runtime/message-list.ts](https://github.com/n8n-io/n8n/blob/main/packages/@n8n/agents/src/runtime/message-list.ts)\n \n\n# AI Agent 运行时\n\n## 概述\n\nAI Agent 运行时（Agent Runtime）是 n8n 平台中负责执行 AI 代理的核心组件系统。该运行时负责管理代理的生命周期、消息处理、工具调用以及与外部系统（如 MCP 服务器）的集成。运行时架构设计遵循模块化原则，将核心逻辑与具体实现解耦，使得系统具备良好的可扩展性和可维护性。\n\n运行时系统的核心职责包括：\n\n- **消息管理**：维护对话历史，处理用户输入与模型输出的流转\n- **工具解析**：解析并执行 MCP（Model Context Protocol）工具调用\n- **状态管理**：跟踪代理执行状态，处理错误恢复\n- **上下文维护**：管理代理的长期记忆和会话状态\n\n## 核心组件架构\n\nAI Agent 运行时由多个协同工作的组件构成，每个组件承担特定的职责。以下是主要组件及其功能：\n\n```mermaid\ngraph TD\n A[Agent SDK] --> B[AgentRuntime]\n B --> C[MessageList]\n B --> D[MCPToolResolver]\n D --> E[MCP Servers]\n B --> F[AI Workflow Builder]\n F --> G[PromptBuilder]\n G --> H[工具定义]\n G --> I[示例生成]\n```\n\n### AgentRuntime（代理运行时引擎）\n\n`AgentRuntime` 是整个运行时的核心引擎，负责协调各个组件的工作。它处理代理的初始化、执行循环和结果返回。\n\n主要功能包括：\n\n- 初始化运行时环境\n- 执行主循环，处理用户消息\n- 调用工具并处理返回结果\n- 管理会话状态和错误处理\n\n### MessageList（消息列表）\n\n`MessageList` 组件负责管理对话消息的历史记录。它维护一个有序的消息队列，支持消息的添加、检索和上下文管理。\n\n核心功能：\n\n- 存储对话历史\n- 支持消息角色区分（用户、助手、系统）\n- 提供上下文窗口管理\n- 支持消息格式转换\n\n### MCPToolResolver（工具解析器）\n\n`MCPToolResolver` 负责解析和执行 MCP 协议定义的工具调用。它充当 n8n 运行时与外部 MCP 服务器之间的桥梁。\n\n主要职责：\n\n- 发现可用的 MCP 工具\n- 验证工具参数\n- 执行工具调用\n- 处理工具返回结果\n\n## 消息处理流程\n\n运行时采用事件驱动的消息处理模式，确保每条消息都能得到正确处理并返回相应的响应。\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Runtime as AgentRuntime\n participant Messages as MessageList\n participant Tools as MCPToolResolver\n participant LLM as AI 模型\n \n User->>Runtime: 发送消息\n Runtime->>Messages: 添加用户消息\n Runtime->>LLM: 发送完整上下文\n LLM->>Runtime: 返回响应/工具调用\n alt 工具调用\n Runtime->>Tools: 解析工具请求\n Tools->>Tools: 执行 MCP 工具\n Tools-->>Runtime: 返回结果\n Runtime->>LLM: 发送工具结果\n LLM->>Runtime: 生成最终响应\n end\n Runtime->>Messages: 添加助手消息\n Runtime-->>User: 返回响应\n```\n\n## 工具系统集成\n\n### AI Tools 生成\n\nn8n 的 AI Tools 系统负责将 n8n 节点转换为 AI 模型可调用的工具。这一过程在 `packages/cli/src/tool-generation/ai-tools.ts` 中实现。\n\n工具描述生成流程：\n\n```typescript\n// 工具描述自动生成逻辑\nconst descriptionType: INodeProperties = {\n displayName: 'Tool Description',\n name: 'descriptionType',\n type: 'options',\n options: [\n { name: 'Set Automatically', value: 'auto' },\n { name: 'Set Manually', value: 'manual' },\n ],\n default: 'auto',\n};\n```\n\n### 工具属性处理\n\n运行时支持两种工具描述设置模式：\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| 自动设置（auto） | 基于 resource 和 operation 参数自动推断描述 | 标准 n8n 节点 |\n| 手动设置（manual） | 用户提供自定义工具描述 | 复杂或特殊用途工具 |\n\n当节点包含 `resource` 和 `operation` 属性时，运行时可以自动生成语义化的工具描述，使 LLM 能够更准确地理解和调用工具。\n\n## Prompt 构建系统\n\nAI Workflow Builder 使用 `PromptBuilder` 组件构建发送给 LLM 的提示词。该构建器采用流式 API 设计，支持灵活的提示词组装。\n\n### PromptBuilder 核心特性\n\n```mermaid\ngraph LR\n A[section] --> B[sectionIf]\n A --> C[examples]\n A --> D[examplesIf]\n B --> E[build]\n C --> E\n D --> E\n```\n\n主要方法：\n\n| 方法 | 说明 | 用途 |\n|------|------|------|\n| `section()` | 添加静态内容区块 | 基础提示词组装 |\n| `sectionIf()` | 条件性添加区块 | 动态内容控制 |\n| `examples()` | 添加少样本示例 | Few-shot 学习 |\n| `examplesIf()` | 条件性添加示例 | 条件化示例注入 |\n| `merge()` | 合并多个构建器 | 提示词复用 |\n| `build()` | 生成最终提示词 | 输出结果 |\n\n### 示例格式化\n\n`PromptBuilder` 支持多种输出格式：\n\n```typescript\n// Markdown 格式\nconst markdownOutput = `## Examples\\n${examplesContent}`;\n\n// XML 格式\nconst xmlOutput = `\\n${examplesContent}\\n`;\n```\n\n构建器会根据配置自动选择合适的格式化方式，确保与不同 LLM API 的兼容性。\n\n## Web Fetch 工具\n\n运行时不直接提供网络获取功能，而是通过 `web-fetch.tool.ts` 实现网页内容提取。该工具将获取的网页转换为 LLM 可处理的结构化文本。\n\n处理流程：\n\n1. 发送 HTTP 请求获取页面内容\n2. 提取可读文本和标题\n3. 处理内容截断和错误情况\n4. 返回结构化结果\n\n返回格式示例：\n\n```xml\n\nhttps://example.com\n页面标题\n\n提取的正文内容...\n\n\n```\n\n## MCP 浏览器集成\n\nn8n 提供了 MCP（Model Context Protocol）浏览器工具，用于在开发环境中测试 MCP 服务器功能。该工具支持多种 AI 客户端配置，包括 Claude Desktop、Cursor、Windsurf 等。\n\n### 开发环境配置\n\n```bash\n# 启动 MCP 服务器\nnpx @n8n/mcp-browser --transport http --port 3100\n```\n\n### 客户端配置示例\n\n```json\n{\n \"mcpServers\": {\n \"n8n-browser\": {\n \"url\": \"http://localhost:3100/mcp\"\n }\n }\n}\n```\n\n## 错误处理机制\n\n运行时实现了完善的错误处理机制，确保代理在遇到异常情况时能够优雅地降级或恢复：\n\n- **验证错误**：通过 Zod 进行输入参数验证\n- **工具执行错误**：捕获并记录工具调用异常\n- **网络错误**：处理 MCP 服务器连接问题\n- **上下文溢出**：管理令牌使用量，避免超出限制\n\n```typescript\n// 验证错误处理示例\nif (error instanceof z.ZodError) {\n const validationError = new ValidationError('Invalid URL input', {\n extra: { errors: error.errors },\n });\n reporter.error(validationError);\n}\n```\n\n## 数据流总结\n\n```mermaid\ngraph TD\n subgraph 输入层\n A[用户消息] --> B[MessageList]\n end\n \n subgraph 处理层\n B --> C[PromptBuilder]\n C --> D[AI 模型]\n D --> E[响应/工具调用]\n end\n \n subgraph 执行层\n E --> F{MCPToolResolver}\n F --> G[MCP 工具]\n G --> H[外部服务]\n end\n \n subgraph 输出层\n E --> I[格式化响应]\n I --> J[返回用户]\n end\n```\n\n## 相关配置\n\n运行时的行为可通过多种方式配置：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| 上下文窗口 | 单次请求的最大消息数 | 依赖模型限制 |\n| 工具超时 | 单个工具调用的最大执行时间 | 30秒 |\n| 重试次数 | 工具调用失败时的重试次数 | 3 |\n| 日志级别 | 运行时的日志详细程度 | info |\n\n## 扩展指南\n\n### 添加新的工具解析器\n\n要扩展工具系统，需要实现 `ToolResolver` 接口：\n\n```typescript\ninterface ToolResolver {\n resolve(toolCall: ToolCall): Promise;\n getAvailableTools(): ToolDefinition[];\n validateParams(params: unknown): boolean;\n}\n```\n\n### 集成新的 MCP 服务器\n\n1. 在 MCP 配置中注册服务器端点\n2. 实现服务器端的工具定义\n3. 配置 `MCPToolResolver` 连接参数\n\n## 总结\n\nAI Agent 运行时是 n8n 平台智能化能力的核心支撑。通过模块化的组件设计，系统实现了高效的消息处理、灵活的提示词构建和完善的工具调用机制。开发者可以通过扩展现有组件或集成新的 MCP 服务器来增强运行时功能，以满足各种复杂的 AI 工作流需求。\n\n---\n\n\n\n## LangChain 节点集成\n\n### 相关页面\n\n相关主题：[AI Agent 运行时](#page-agents-runtime)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# LangChain 节点集成\n\n## 概述\n\nLangChain 节点集成是 n8n 工作流自动化平台中用于构建 AI 驱动工作流的**核心组件体系**。该集成通过提供标准化的节点、工具和提示构建系统，使开发者能够在 n8n 工作流中无缝调用 LangChain 的语言模型、代理（Agent）和工具链能力。\n\nLangChain 节点集成的主要功能包括：\n\n- **语言模型（LLM）节点**：支持 OpenAI、Anthropic 等多种语言模型的调用\n- **代理（Agent）节点**：基于 LangChain 构建的 AI 代理，支持多种推理策略\n- **工具（Tools）节点**：提供 Web 抓取、代码执行等工具扩展\n- **提示构建系统**：基于 `PromptBuilder` 的类型安全、fluent API\n\n## 架构设计\n\n### 整体架构\n\nLangChain 节点集成采用分层架构设计，各组件之间通过标准接口进行通信：\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n A[编辑器 UI] --> B[节点配置面板]\n B --> C[代码编辑器]\n end\n \n subgraph \"节点层\"\n D[LLM 节点] --> E[代理节点]\n E --> F[工具节点]\n F --> G[PromptBuilder]\n end\n \n subgraph \"集成层\"\n H[LangChain Core] --> I[模型适配器]\n I --> J[工具适配器]\n end\n \n subgraph \"外部服务\"\n K[OpenAI API] --> I\n L[Anthropic API] --> I\n M[外部工具] --> J\n end\n \n style A fill:#e1f5fe\n style D fill:#fff3e0\n style H fill:#e8f5e9\n```\n\n### PromptBuilder 核心组件\n\n`PromptBuilder` 是 LangChain 节点集成中的提示构建核心类，提供类型安全的流式 API：\n\n| 特性 | 说明 |\n|------|------|\n| 流式 API | 支持方法链式调用 |\n| 条件部分 | `sectionIf()` 支持动态内容 |\n| 延迟求值 | 工厂函数仅在构建时执行 |\n| 输出格式 | 支持 XML 标签和 Markdown 标题 |\n| LangChain 集成 | 支持 message blocks 和 cache_control |\n\n## 提示构建系统\n\n### PromptBuilder 类接口\n\n`PromptBuilder` 类位于 `packages/@n8n/ai-workflow-builder.ee/src/prompts/builder/prompt-builder.ts`，提供以下核心方法：\n\n```typescript\nclass PromptBuilder {\n private readonly sections: SectionEntry[];\n private readonly format: SectionFormat;\n private readonly separator: string;\n\n constructor(options: PromptBuilderOptions = {});\n \n // 添加固定部分\n section(name: string, content: ContentOrFactory, options?: SectionOptions): this;\n \n // 添加条件部分\n sectionIf(condition: unknown, name: string, content: ContentOrFactory, options?: SectionOptions): this;\n \n // 添加示例\n examples(name: string, data: unknown[], formatter: ExampleFormatter): this;\n examplesIf(condition: unknown, name: string, data: unknown[], formatter: ExampleFormatter): this;\n \n // 合并多个 PromptBuilder\n merge(other: PromptBuilder): this;\n \n // 构建最终提示字符串\n build(): string;\n}\n```\n\n资料来源：[prompt-builder.ts:48-90]()\n\n### 使用示例\n\n```typescript\nconst systemPrompt = prompt()\n .section('ROLE', 'You are an assistant')\n .sectionIf(hasContext, 'CONTEXT', () => buildContext())\n .examples('EXAMPLES', data, (ex) => `${ex.input} → ${ex.output}`)\n .build();\n```\n\n上述代码通过 fluent API 构建了一个包含角色定义、上下文信息和示例的提示词，最终通过 `build()` 方法生成字符串输出。\n\n## 工具节点系统\n\n### WebFetch 工具\n\n`WebFetch` 工具是 AI workflow builder 中用于获取网页内容的核心工具，位置在 `packages/@n8n/ai-workflow-builder.ee/src/tools/web-fetch.tool.ts`。其工作流程如下：\n\n```mermaid\ngraph TD\n A[输入 URL] --> B[验证 URL 格式]\n B --> C{验证通过?}\n C -->|否| D[返回 ValidationError]\n C -->|是| E[发起 HTTP 请求]\n E --> F[提取可读内容]\n F --> G[构建响应 XML]\n G --> H[记录安全状态]\n H --> I[返回 SuccessResponse]\n \n style D fill:#ffcdd2\n style I fill:#c8e6c9\n```\n\n### 响应格式\n\nWebFetch 工具返回的响应采用 XML 结构，包含以下元素：\n\n| 元素 | 说明 |\n|------|------|\n| `` | 原始请求 URL |\n| `` | 最终重定向后的 URL（可选） |\n| `` | 网页标题 |\n| `<content>` | 提取的内容 |\n| `<note>` | 截断说明（当内容被截断时） |\n\n```xml\n<web_fetch_result>\n <url>https://example.com</url>\n <title>Example Domain\n \n [提取的内容]\n \n\n```\n\n资料来源：[web-fetch.tool.ts:26-43]()\n\n## 节点指南系统\n\n### 指南注册机制\n\nn8n 的 AI workflow builder 通过指南系统（Guides）为不同类型的节点提供上下文相关的帮助信息：\n\n```mermaid\ngraph LR\n A[用户操作] --> B{匹配节点类型}\n B -->|Set 节点| C[赋值结构与类型指南]\n B -->|IF 节点| D[过滤条件与操作符指南]\n B -->|HTTP Request| E[URL、Header、Body、认证指南]\n B -->|Tool 节点| F[$fromAI 表达式指南]\n```\n\n### 指南配置结构\n\n每个节点指南的定义包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `patterns` | `string[]` | 匹配节点类型的模式 |\n| `condition` | `(ctx) => boolean` | 可选：额外的上下文条件 |\n| `content` | `string` | 指南内容 |\n\n```typescript\nexport const MY_NODE_GUIDE: NodeTypeGuide = {\n patterns: ['n8n-nodes-base.myNode'],\n condition: (ctx) => true,\n content: `Your guide content here...`,\n};\n```\n\n资料来源：[README.md (prompts)](packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md)\n\n## 前端编辑器集成\n\n### 代码编辑器组件\n\nn8n 前端使用 CodeMirror 6 实现代码编辑器，位于 `packages/frontend/editor-ui/src/features/shared/editors/composables/useCodeEditor.ts`：\n\n```typescript\nconst editor = ref();\nconst hasFocus = ref(false);\nconst hasChanges = ref(false);\nconst autocompleteStatus = ref<'pending' | 'active' | null>(null);\n```\n\n编辑器支持的语言包括多种代码语言，并提供语法高亮、自动完成等功能。\n\n### AI Builder 界面文本\n\n前端国际化文件 `packages/frontend/@n8n/design-system/src/locale/lang/en.ts` 包含 AI Builder 相关的界面文本：\n\n| 文本键 | 说明 |\n|--------|------|\n| `assistantChat.builder.name` | AI Builder 界面名称 |\n| `assistantChat.builder.generatingFinalWorkflow` | 生成最终工作流时的提示 |\n| `assistantChat.builder.configuredNodes` | 已配置节点 |\n| `assistantChat.rating.thumbsUp` | 有帮助 |\n| `assistantChat.rating.thumbsDown` | 没有帮助 |\n| `assistantChat.rating.feedbackPlaceholder` | 反馈占位符 |\n\n## 多代理提示系统\n\n### 代理类型\n\n提示系统支持多种专业化代理：\n\n| 代理 | 功能 |\n|------|------|\n| **Supervisor** | 将用户请求路由到合适的专业代理 |\n| **Discovery** | 识别相关 n8n 节点并分类技术 |\n| **Builder** | 创建工作流结构并配置节点参数 |\n| **Responder** | 生成面向用户的响应 |\n\n所有代理提示都使用 `PromptBuilder` 进行统一组合。\n\n### 链式提示\n\n除了代理提示外，系统还包含用于特定 LLM 链式操作的提示：\n\n| 链 | 功能 |\n|----|------|\n| **Categorization** | 分析用户提示以识别工作流技术 |\n| **Compact** | 压缩对话以节省上下文 |\n\n## 安全性与状态管理\n\n### 安全状态追踪\n\nWebFetch 工具实现了安全状态追踪机制：\n\n```typescript\nconst stateUpdates: Record = {\n ...security.getStateUpdates(),\n fetchedUrlContent: [\n {\n url,\n status: 'success' as const,\n title: extracted.title,\n content: extracted.content,\n },\n ],\n};\n```\n\n安全系统记录每次抓取请求，并在返回响应时附带安全状态更新，确保工作流执行的可追溯性。\n\n## 最佳实践\n\n### 提示构建\n\n1. **使用条件部分**：对于可选内容，使用 `sectionIf()` 避免不必要的延迟求值\n2. **链式调用**：利用流式 API 的可读性组织提示构建逻辑\n3. **示例格式化**：通过 `examples()` 方法添加少样本示例时，使用清晰的格式化函数\n\n### 工具使用\n\n1. **URL 验证**：WebFetch 工具会自动验证 URL 格式，无效输入将抛出 `ValidationError`\n2. **内容截断**：大型页面内容可能被截断，应检查 `truncated` 标志\n3. **错误处理**：工具返回的错误包含 Zod 验证详情，便于调试\n\n## 相关资源\n\n- 官方文档：[n8n AI Workflow Builder](https://docs.n8n.io/)\n- LangChain 官方文档：[LangChain.js](https://js.langchain.com/)\n- 源码仓库：[n8n-io/n8n](https://github.com/n8n-io/n8n)\n\n---\n\n\n\n## AI 工作流构建器\n\n### 相关页面\n\n相关主题：[AI Agent 运行时](#page-agents-runtime), [工作流 SDK 与构建器](#page-workflow-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [packages/testing/rules-engine/README.md](https://github.com/n8n-io/n8n/blob/main/packages/testing/rules-engine/README.md)\n \n\n# AI 工作流构建器\n\n## 概述\n\nAI 工作流构建器是 n8n 平台中一个基于大语言模型（LLM）的智能工作流创建系统。该系统通过多代理（Multi-Agent）架构，允许用户使用自然语言描述需求，自动生成 n8n 工作流代码。该模块位于 `packages/@n8n/ai-workflow-builder.ee` 包中，是 n8n 企业版的重要组成部分。\n\nAI 工作流构建器的主要特点包括：\n\n- **自然语言驱动**：用户通过自然语言描述工作流需求\n- **多代理协作**：多个专业代理协同工作，各司其职\n- **代码生成**：自动生成可执行的工作流代码（JavaScript/TypeScript）\n- **上下文感知**：能够理解当前工作流状态并进行多轮优化\n- **工具集成**：支持网络搜索、文档获取等辅助工具\n\n## 系统架构\n\n### 多代理架构\n\nAI 工作流构建器采用多代理架构设计，每个代理拥有特定的角色和职责：\n\n| 代理 | 用途 | 说明 |\n|------|------|------|\n| **Supervisor** | 主管代理 | 路由用户请求到合适的专业代理 |\n| **Discovery** | 发现代理 | 识别相关 n8n 节点并分类技术 |\n| **Builder** | 构建代理 | 创建工作流结构并配置节点参数 |\n| **Responder** | 响应代理 | 生成面向用户的响应 |\n\n资料来源：[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)\n\n```mermaid\ngraph TD\n A[用户请求] --> B[Supervisor 主管代理]\n B --> C[Discovery 发现代理]\n B --> D[Builder 构建代理]\n B --> E[Responder 响应代理]\n C --> F[节点搜索结果]\n D --> G[工作流代码]\n F --> D\n D --> H[工作流状态]\n H --> B\n G --> E\n E --> I[用户响应]\n```\n\n### 核心组件\n\n```\npackages/@n8n/ai-workflow-builder.ee/\n├── src/\n│ ├── code-builder/ # 代码构建器核心\n│ │ └── prompts/ # 代码生成提示词\n│ ├── agents/ # 多代理系统\n│ │ ├── planner.agent.ts # 规划代理\n│ │ └── ...\n│ ├── prompts/ # 提示词构建系统\n│ │ ├── builder/ # PromptBuilder 工具\n│ │ ├── chains/ # 链式提示词\n│ │ └── guides/ # 节点和参数指南\n│ ├── tools/ # 工具集\n│ │ ├── web-fetch.tool.ts # 网页抓取工具\n│ │ └── builder-tools.ts # 构建器专用工具\n│ └── workflow-state.ts # 工作流状态管理\n```\n\n## PromptBuilder 提示词构建器\n\n### 概述\n\nPromptBuilder 是一个类型安全的链式 API，用于组合 LLM 提示词。它支持条件化部分、延迟求值和 LangChain 集成。\n\n资料来源：[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)\n\n### 核心功能\n\n```typescript\nconst systemPrompt = prompt()\n .section('role', 'You are an assistant')\n .sectionIf(hasContext, 'context', () => buildContext())\n .examples('examples', data, (ex) => `${ex.input} → ${ex.output}`)\n .build();\n```\n\n| 方法 | 说明 |\n|------|------|\n| `section(name, content)` | 添加始终包含的部分 |\n| `sectionIf(condition, name, content)` | 根据条件添加部分 |\n| `examples(name, data, formatter)` | 添加少样本示例 |\n| `merge(other)` | 合并另一个 PromptBuilder |\n| `build()` | 构建最终的提示词字符串 |\n| `buildAsMessageBlocks()` | 构建为 LangChain 消息块 |\n\n### 格式化选项\n\nPromptBuilder 支持两种输出格式：\n\n| 格式 | 说明 | 示例 |\n|------|------|------|\n| `xml` | XML 标签格式（默认） | `...` |\n| `markdown` | Markdown 标题格式 | `## Role\\n...` |\n\n## 代码构建器\n\n### 系统提示词构建\n\n代码构建器通过 `buildCodeBuilderPrompt` 函数构建完整的系统提示词，该函数整合多个组件：\n\n```typescript\nexport function buildCodeBuilderPrompt(\n\tcurrentWorkflow?: WorkflowJSON,\n\thistoryContext?: HistoryContext,\n\toptions?: BuildCodeBuilderPromptOptions,\n): ChatPromptTemplate\n```\n\n资料来源：[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)\n\n### 提示词组成部分\n\n系统提示词由以下部分组成：\n\n```mermaid\ngraph LR\n A[buildCodeBuilderPrompt] --> B[ROLE 角色定义]\n A --> C[RESPONSE_STYLE 响应风格]\n A --> D[WORKFLOW_RULES 工作流规则]\n A --> E[WORKFLOW_PATTERNS 工作流模式]\n A --> F[EXPRESSION_REFERENCE 表达式参考]\n A --> G[ADDITIONAL_FUNCTIONS 附加函数]\n A --> H[MANDATORY_WORKFLOW_PROCESS 强制流程]\n```\n\n### 用户消息构建\n\n用户消息部分通过 `buildUserMessageParts` 函数构建，支持以下可选组件：\n\n| 组件 | 条件 | 说明 |\n|------|------|------|\n| 当前工作流 JSON | 始终存在 | 工作流的当前状态 |\n| 对话历史 | historyContext 存在 | 多轮对话上下文 |\n| 计划输出 | planOutput 存在 | 规划代理的输出结果 |\n| 预搜索结果 | preSearchResults 存在 | 预先获取的节点搜索结果 |\n\n```typescript\nfunction buildUserMessageParts(\n\tcurrentWorkflow?: WorkflowJSON,\n\thistoryContext?: HistoryContext,\n\toptions?: BuildCodeBuilderPromptOptions,\n): string[]\n```\n\n资料来源：[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)\n\n### XML 标签包装\n\n系统使用 XML 标签封装不同类型的信息，便于解析：\n\n| 标签 | 用途 |\n|------|------|\n| `...` | 代理角色定义 |\n| `...` | 响应风格指导 |\n| `...` | 工作流生成规则 |\n| `...` | 工作流文件内容 |\n| `...` | 已批准的计划 |\n| `...` | 节点搜索结果 |\n| `...` | 用户请求 |\n| `...` | 网页抓取结果 |\n\n## 工具系统\n\n### 网页抓取工具\n\n`WebFetchTool` 允许 AI 代理获取网页内容以辅助决策：\n\n```mermaid\nsequenceDiagram\n 代理->>WebFetchTool: fetch(url)\n WebFetchTool->>URL: 发起 HTTP 请求\n URL-->>WebFetchTool: 返回 HTML 内容\n WebFetchTool->>WebFetchTool: extractReadableContent()\n WebFetchTool->>安全检查: recordFetch()\n WebFetchTool-->>代理: 返回结构化结果\n```\n\n资料来源：[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)\n\n### 工具响应格式\n\n工具执行完成后返回结构化的响应，包含状态更新信息：\n\n```typescript\ninterface ToolResponse {\n\tstatus: 'success' | 'error';\n\turl?: string;\n\tfinalUrl?: string;\n\ttruncated?: boolean;\n}\n\nconst stateUpdates: Record = {\n\t...security.getStateUpdates(),\n\tfetchedUrlContent: [{\n\t\turl,\n\t\tstatus: 'success' as const,\n\t\ttitle: extracted.title,\n\t\tcontent: extracted.content,\n\t}],\n};\n```\n\n### 安全状态追踪\n\n网页抓取工具集成了安全状态追踪机制，记录所有抓取操作并生成相应的状态更新：\n\n- `security.recordFetch()` - 记录抓取操作\n- `security.getStateUpdates()` - 获取状态更新\n\n## 节点指南系统\n\n### 指南注册表\n\nn8n 为常见节点提供专门的指南，帮助 AI 代理正确理解和配置节点：\n\n| 指南 | 节点模式 | 用途 |\n|------|----------|------|\n| Set Node | `n8n-nodes-base.set` | 赋值结构与类型 |\n| IF Node | `n8n-nodes-base.if` | 过滤条件与运算符 |\n| Switch Node | `n8n-nodes-base.switch` | 规则和路由 |\n| HTTP Request | `n8n-nodes-base.httpRequest` | URL、头部、请求体、认证 |\n| Tool Nodes | `*Tool` | $fromAI 表达式 |\n| Resource Locator | `*` | __rl 结构与模式 |\n| System Message | `*` | AI 节点消息分离 |\n| Text Fields | `*` | 表达式输入框 |\n\n资料来源：[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)\n\n### 条件化指南\n\n某些指南仅在特定上下文中适用，使用 `condition` 属性控制：\n\n```typescript\nexport const RESOURCE_LOCATOR_GUIDE: NodeTypeGuide = {\n\tpatterns: ['*'], // 匹配所有节点\n\tcondition: (ctx) => ctx.hasResourceLocatorParams === true,\n\tcontent: `...`,\n};\n```\n\n## LangChain 集成\n\n### 消息块构建\n\nPromptBuilder 支持构建 LangChain 兼容的消息块，带有缓存控制支持：\n\n```typescript\nreturn ChatPromptTemplate.fromMessages([\n\t['system', [{\n\t\ttype: 'text',\n\t\ttext: systemMessage,\n\t\tcache_control: { type: 'ephemeral' }\n\t}]],\n\t['user', userMessageTemplate],\n]);\n```\n\n### 缓存策略\n\n系统使用 LangChain 的 `cache_control` 机制进行提示词缓存优化：\n\n- `ephemeral` - 临时缓存，仅在当前请求周期内有效\n- 适用于频繁使用但频繁变化的内容\n\n## 工作流状态管理\n\n工作流状态由 `workflow-state.ts` 管理，跟踪工作流的当前配置和历史变更。状态信息在多代理协作中流转，确保每个代理都能访问一致的工作流上下文。\n\n## 代码节点编辑器补全\n\n### 输入方法补全\n\nAI 工作流构建器为 `$input` 对象提供智能补全支持：\n\n| 方法 | 模式 | 说明 |\n|------|------|------|\n| `first()` | `$input.first().` | 获取第一个输入项 |\n| `last()` | `$input.last().` | 获取最后一个输入项 |\n| `item` | `$input.item.` | 获取当前项 |\n| `all()[index]` | `$input.all()[index].` | 获取指定索引项 |\n\n补全选项包括 `.json` 和 `.binary` 两种数据类型访问方式。\n\n资料来源：[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)\n\n## 规则引擎\n\n### 架构规则\n\nAI 工作流构建器的测试框架使用规则引擎进行架构验证：\n\n| 规则 | 严重性 | 说明 |\n|------|--------|------|\n| `boundary-protection` | error | 防止页面间直接导入 |\n| `scope-lockdown` | error | 强制页面对象的显式架构意图 |\n\n资料来源：[packages/testing/rules-engine/README.md](https://github.com/n8n-io/n8n/blob/main/packages/testing/rules-engine/README.md)\n\n## 最佳实践\n\n### 提示词构建\n\n1. **使用条件化部分**：通过 `sectionIf()` 按需包含内容，减少不必要的上下文\n2. **延迟求值**：使用工厂函数避免不必要的计算\n3. **适当格式化**：XML 格式便于程序解析，Markdown 格式便于调试\n4. **缓存控制**：对频繁使用的系统提示词部分使用缓存标记\n\n### 代理协作\n\n1. **职责分离**：每个代理应专注于特定任务\n2. **状态传递**：通过标准化的工作流状态对象在各代理间传递信息\n3. **错误处理**：工具执行应包含完整的错误处理和状态回滚机制\n\n## 相关链接\n\n- [n8n 官方文档](https://docs.n8n.io/)\n- [n8n GitHub 仓库](https://github.com/n8n-io/n8n)\n- [AI 工作流构建器源码](https://github.com/n8n-io/n8n/tree/main/packages/@n8n/ai-workflow-builder.ee)\n\n---\n\n\n\n## 数据库实体与数据管理\n\n### 相关页面\n\n相关主题：[工作流执行引擎](#page-execution-engine), [系统架构概览](#page-architecture)\n\n根据提供的上下文，我没有找到查询中要求的相关数据库实体文件（如 `workflow-entity.ts`、`execution-entity.ts`、`credentials-entity.ts`、`workflow.repository.ts` 等）。\n\n提供的上下文主要包含以下内容：\n\n- **前端国际化文件**：`packages/frontend/@n8n/design-system/src/locale/lang/en.ts`\n- **前端组件测试**：`packages/frontend/editor-ui/src/app/components/MainHeader/MainHeader.test.ts`\n- **AI工作流构建器**：`packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts`、`web-fetch.tool.ts`、`prompt-builder.ts`\n- **SSO SAML认证**：各种XSD schema文件\n- **测试框架文档**：`packages/testing/janitor/README.md`\n- **节点开发CLI**：`packages/@n8n/node-cli/README.md`\n- **评估框架**：`packages/@n8n/ai-workflow-builder.ee/evaluations/README.md`\n- **UI组件文档**：`packages/frontend/@n8n/design-system/src/components/N8nSwitch/component-switch.md`\n\n---\n\n如果您能提供数据库实体相关的源文件（如 `packages/@n8n/db/src/entities/*.ts`），我可以为您生成关于\"数据库实体与数据管理\"的完整技术文档。\n\n或者，如果您希望我基于当前上下文中实际存在的文件生成文档，我可以撰写以下主题：\n\n1. **n8n前端国际化系统**\n2. **AI工作流构建器提示词系统**\n3. **Playwright测试框架架构**\n4. **n8n节点CLI开发工具**\n\n请告知您希望处理哪个方向。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：n8n-io/n8n\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:193215554 | https://github.com/n8n-io/n8n | README/documentation is current enough for a first validation pass.\n\n## 2. 运行坑 · 运行可能依赖外部服务\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。\n- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。\n- 建议检查：确认是否有离线 demo、mock 数据或可替代服务。\n- 防护动作：外部服务依赖未明确时，不把本地安装成功等同于能力可用。\n- 证据：packet_text.keyword_scan | github_repo:193215554 | https://github.com/n8n-io/n8n | matched external service / cloud / webhook / database keyword\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:193215554 | https://github.com/n8n-io/n8n | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:193215554 | https://github.com/n8n-io/n8n | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：n8n-io/n8n\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:193215554 | https://github.com/n8n-io/n8n | README/documentation is current enough for a first validation pass.\n\n## 2. 运行坑 · 运行可能依赖外部服务\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。\n- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。\n- 建议检查：确认是否有离线 demo、mock 数据或可替代服务。\n- 防护动作：外部服务依赖未明确时，不把本地安装成功等同于能力可用。\n- 证据：packet_text.keyword_scan | github_repo:193215554 | https://github.com/n8n-io/n8n | matched external service / cloud / webhook / database keyword\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:193215554 | https://github.com/n8n-io/n8n | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:193215554 | https://github.com/n8n-io/n8n | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:193215554 | https://github.com/n8n-io/n8n | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# n8n - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 n8n 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：n8n 平台介绍。围绕“n8n 平台介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构概览。围绕“系统架构概览”模拟一次用户任务，不展示安装或运行结果。\n3. page-package-structure：包结构与模块组织。围绕“包结构与模块组织”模拟一次用户任务，不展示安装或运行结果。\n4. page-workflow-sdk：工作流 SDK 与构建器。围绕“工作流 SDK 与构建器”模拟一次用户任务，不展示安装或运行结果。\n5. page-execution-engine：工作流执行引擎。围绕“工作流执行引擎”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“n8n 平台介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-package-structure\n输入：用户提供的“包结构与模块组织”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-workflow-sdk\n输入：用户提供的“工作流 SDK 与构建器”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-execution-engine\n输入：用户提供的“工作流执行引擎”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“n8n 平台介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构概览”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-package-structure：Step 3 必须围绕“包结构与模块组织”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-workflow-sdk：Step 4 必须围绕“工作流 SDK 与构建器”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-execution-engine：Step 5 必须围绕“工作流执行引擎”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/n8n-io/n8n\n- https://github.com/n8n-io/n8n#readme\n- .claude/plugins/n8n/skills/community-pr-review/SKILL.md\n- .claude/plugins/n8n/skills/content-design/SKILL.md\n- .claude/plugins/n8n/skills/conventions/SKILL.md\n- .claude/plugins/n8n/skills/create-community-node-lint-rule/SKILL.md\n- .claude/plugins/n8n/skills/create-issue/SKILL.md\n- .claude/plugins/n8n/skills/create-pr/SKILL.md\n- .claude/plugins/n8n/skills/create-skill/SKILL.md\n- .claude/plugins/n8n/skills/design-system/SKILL.md\n- .claude/plugins/n8n/skills/linear-issue/SKILL.md\n- .claude/plugins/n8n/skills/loom-transcript/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 n8n 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：n8n-io/n8n\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx n8n\n```\n\n来源：https://github.com/n8n-io/n8n#readme\n\n## 来源\n\n- repo: https://github.com/n8n-io/n8n\n- docs: https://github.com/n8n-io/n8n#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_11dd99ed2a0d4948a9bb68d21f67a3f8"
}