n8n-conventions

n8n 快速参考

📚 完整文档：

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

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

关键规则（必须遵守）

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 schemas 进行验证

测试：

• Vitest（单元测试）、Playwright（E2E）
• 模拟外部依赖
• 在 package 目录中运行：pushd packages/cli && pnpm test

数据库：

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

命令：

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

主要 package

Package	用途
packages/cli	后端 API
packages/frontend/editor-ui	Vue 3 前端
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