n8n:conventions

n8n 快速参考

📚 完整文档：

• 通用： /AGENTS.md — 架构、命令、工作流
• 前端： /packages/frontend/AGENTS.md — CSS 变量、时序

需要快速回顾关键模式时，请使用此技能。

关键规则（必须遵守）

技术写作（注释、PR、问题、文档）：

• 使用 ASD-STE100 简明技术英语：句子简短，使用主动语态，每句话只包含一条指令

TypeScript：

• 禁止使用 any → 使用 unknown
• 优先使用 satisfies，而非 as（测试除外）
• 在 @n8n/api-types 中定义共享类型

错误处理：

import { UnexpectedError } from 'n8n-workflow';
throw new UnexpectedError('message', { extra: { context } });
// DON'T use deprecated ApplicationError

前端：

• 使用 Vue 3 Composition API（<script setup lang="ts">）
• 使用 CSS 变量（绝不硬编码 px）——请参阅 /packages/frontend/AGENTS.md
• 所有文本都通过 i18n（$t('key')）
• E2E 测试使用 data-testid（单个值，不含空格）

后端：

• Controller → Service → Repository
• 通过 @n8n/di 进行依赖注入
• 通过 @n8n/config 配置
• 使用 Zod schema 进行验证
• 分页参数：在 Controller 和 Service 中使用 offset + limit；仅在 Repository 中转换为 TypeORM 的 skip/take

测试：

• 使用 Vitest（单元测试）、Playwright（E2E）
• 模拟外部依赖
• 将文件系统测试放在由测试创建的临时目录中
• 在导入设置代码前设置 N8N_USER_FOLDER
• 跟踪由 mock 激活的分支，并隔离所有可到达的变更
• 在包目录中运行：pushd packages/cli && pnpm test

数据库：

• 仅使用 SQLite/PostgreSQL（应用数据库）
• 例外：数据库节点（MySQL Node 等）可以使用特定于数据库的功能

GitHub 工作流：

• 每个工作流都声明权限最小化的顶层 permissions: 块 （通常为 contents: read）；需要更多权限的任务在任务级别覆盖

命令：

pnpm build > build.log 2>&1  # Always redirect
pnpm typecheck               # Before commit
pnpm lint                    # Before commit

密钥：pnpm 命令行可能会被逐字记录（可选择启用开发指标）—— 请通过环境变量传递敏感值，绝不要将其直接写在命令行中。

关键包

包	用途
packages/cli	后端 API
packages/frontend/editor-ui	Vue 3 前端外壳
packages/modules/<name>/frontend	前端功能模块。指南：packages/@n8n/module-cli/frontend-module-guide.md
packages/@n8n/api-types	共享类型
packages/@n8n/db	TypeORM 实体
packages/workflow	核心接口

常见模式

Pinia Store：

import { STORES } from '@n8n/stores';
export const useMyStore = defineStore(STORES.MY_STORE, () => {
  const state = shallowRef([]);
  return { state };
});

Vue 组件：

<script setup lang="ts">
type Props = { title: string };
const props = defineProps<Props>();
</script>

Service：

import { Service } from '@n8n/di';
import { Config } from '@n8n/config';

@Service()
export class MyService {
  constructor(private readonly config: Config) {}
}

---

📖 需要更多详情？ 请阅读 /AGENTS.md 和 /packages/frontend/AGENTS.md