面向代理的文档
人类和 AI 代理都会阅读 n8n 文档。两类用户对文档的需求大体相同,但代理要有效解析和浏览文档,也有一些特定需求。
本页介绍 n8n 文档所说的「面向代理」意味着什么,以及它为何重要。这些准则适用于文档贡献者,也适合所有想了解 n8n 文档方法的用户。
为什么这对 n8n 文档很重要
有两类相互重叠的受众会通过代理而非浏览器使用 n8n 文档:
- 用户向 AI 代理提问,而不是自己搜索。 越来越多的文档流量来自 AI 助手和搜索代理:它们检索页面来回答问题,而不是由用户通过网站导航直接打开页面。
- 用户借助编码代理使用 n8n 进行构建。 越来越多的人使用 AI 编码工具编写工作流、节点或集成。这些工具会直接检索 n8n 文档,以当前、准确的信息为依据,而不是依赖过时的训练数据。
「面向代理」意味着什么
该标准分为四个层面。
机器可读的交付方式
代理需要一种无需渲染完整网页即可获取内容的方式。n8n 文档提供以下几种途径:
- Markdown: 每个页面都提供整洁的 Markdown,而不仅是渲染后的 HTML。
- llms.txt:
llms.txt和llms-full.txt列出了所有已发布页面,供支持该格式的代理使用。 - MCP server: MCP server 会将文档直接提供给 MCP 客户端。请参阅连接 n8n 文档 MCP server。
- AI 搜索: 由 AI 驱动的搜索(Kapa.ai)直接根据文档、博客和社区论坛回答问题。
- Context7: Context7 会索引 n8n 文档,让编辑器内的编码代理能够在用户构建时检索最新文档。
全站一致性
- 术语: n8n 文档始终使用同一个术语表示同一个概念,从而减少人类用户和代理的困惑。请参阅术语和命名。
- 稳定的 URL: 页面重命名时 URL 保持稳定;只要 URL 发生变化,就会设置重定向。
- 功能可用性: 取决于 n8n 版本或套餐的事实会放在其适用范围内:适用于整页或整个章节时使用提示,顺带提及时写在行内,适用于表格某一行时写在对应单元格中。这样,即使代理只检索到页面片段,也能看到正确的上下文。请参阅功能可用性。
- 审核流程: 新页面和修改内容在发布前,会在 n8n 文档的公开 GitHub 仓库中由人工审核者和 AI 审核工具 cubic共同审核一致性和技术准确性。
结构和导航
- 页面长度: n8n 文档将内容拆分为主题明确、长度适中的页面,便于 agent 完整检索,不会被截断。搜索和文档助手会根据
##/###标题对内容分块,每次检索一个章节。过短的页面或章节会与不相关的相邻内容合并。将同一主题过度拆分到多个小页面会显著降低回答质量。请参阅页面长度和粒度。 - 独立完整的章节: 每个章节都能独立理解,不依赖「如上所述」之类的上下文。Agents 可能只检索页面中的一个片段或章节,有时甚至只有标题,而非完整内容。请参阅确保每个章节独立完整。
- 答案优先的开头: 每个页面都在 H1 之后用一句通俗易懂的话直接给出答案。AI 助手和搜索界面往往只将这一行显示为引用,因此具体明确的开头可以提高引用率和回答准确度。请参阅用一句话直接给出答案。
- 交叉链接: 页面会明确链接到先决条件、后续步骤和相关主题,让 agent 能够沿着路径浏览,而无需猜测 URL。相互链接的页面还会形成主题集群,AI 搜索会将其视为内容深度的信号,其引用率远高于孤立页面。请参阅链接到相关页面、先决条件和后续步骤。
内容和示例
- 文本优先于图像: 操作说明应采用易于解析的文本,而不是放在图像中。Agents 和屏幕阅读器只能获得图像的 alt text 和文件路径,而看不到图像本身。屏幕截图只能确认读者已经从页面文字中了解到的内容,绝不能单独承载信息。请参阅图像。
- 完整示例: 对于包含代码、表达式或配置界面的功能,n8n 文档会尽量提供完整示例。示例既要覆盖常见情况,也要涵盖容易出错的情况,因为代理会直接复制示例,无法推断未展示的内容。请参阅为每项功能提供完整示例。
- 选项卡内容: 选项卡内容应保持精简,因为用户一次只会看到一个选项卡,而代理会读取所有选项卡。请参阅选项卡内容。
与风格指南的关系
本页解释这些要求背后的原因。贡献指南介绍贡献流程,风格指南则列出了要遵循的具体规则。其中多项规则——包括页面长度、章节独立性、内部链接、功能可用性、图像和选项卡内容——正是为了让文档同时适合代理和人类阅读。如果你要贡献内容,请直接遵循风格指南;如果想了解某项规则背后的原因,或判断是否值得新增一项规则,再回到本页参考。
仍在演进的领域
并非每项准则都有定论。n8n 文档会持续测试和研究怎样才能让文档更适合代理,并开发新系统来满足这些标准。面向代理的文档实践发展迅速,本页也会随着实践成熟而不断更新。
相关资源
不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。