n8n-development

用途

n8n-development 技能为开发、测试和维护 n8n Webhook 工作流提供全面指导，重点在于与 Python 服务集成。它适用于以下场景：

构建新的 n8n Webhook 工作流
将 n8n 工作流与 Python 服务集成
为工作流集成编写测试
创建可复用的工作流模板
调试工作流执行问题
为 n8n 项目搭建开发环境
遵循异步模式和错误处理的最佳实践

主要能力

核心开发原则

采用测试驱动开发（TDD）：先写一个失败的测试来定义预期行为，再实现最小代码使测试通过，然后在保持测试通过的前提下重构。使用 uv run pytest 运行测试。

工作流开发流程

设计 Webhook 契约（请求/响应 Schema）
在 n8n 中实现并加入错误处理
导出 JSON 到 nathan/workflows/[category]/
添加到注册表（workflow_registry.yaml）
在 tests/workflows/[category]/ 编写集成测试
编写带使用示例的文档

模板开发

使用 ${VAR_NAME} 语法定义变量
通过模板 frontmatter 中的 Schema 添加验证
使用 CLI 测试渲染
在注释中编写带使用示例的文档

测试指南

测试结构应镜像 tests/ 目录中的源码，使用描述性命名（如 test_trigger_workflow_with_valid_parameters）。使用 pytest fixtures 进行共享设置，并 mock 外部依赖。目标测试覆盖率为 80% 以上。

验证与 Schema

对 API 请求/响应使用 Pydantic 模型，对数据库模型使用 SQLModel。在边界处（API 端点、CLI 参数）实施输入验证，并提供清晰、可操作的错误消息。

异步模式

所有 HTTP 调用使用 httpx，并妥善处理超时。始终对 HTTP 调用使用 try/except，对 HTTP 客户端使用 async with 上下文管理器。使用 asyncio.gather() 进行并行操作。

使用方式

常用命令

核心开发：

uv sync                                    # 安装依赖
uv run pytest                              # 运行测试
uv run pytest --cov=nathan --cov-report=term-missing  # 带覆盖率
uvx ruff check .                           # Lint
uvx ruff format .                          # 格式化

n8n 开发：

docker compose -f docker-compose.n8n.yml up -d  # 本地运行 n8n
uv run python -m nathan.scripts.n8n_workflow_registry --help  # 注册表 CLI
uv run python -m nathan.templating --help  # 模板 CLI

参考文档

在需要时加载以下参考文件：

常见模式：加载 references/common_patterns.md 获取工作流注册表、模板渲染和错误处理代码示例
代码审查：提交代码审查前加载 references/review_checklist.md
CLI 命令：加载 references/cli_commands.md 获取 n8n 命令行操作（导出、导入、执行工作流）
REST API：加载 references/rest_api.md 获取 n8n REST API 端点和 Python 客户端示例
工作流 JSON：加载 references/workflow_json_structure.md 以理解和构建 n8n 工作流 JSON 文件

提交规范

遵循 conventional commits 格式：

feat: 新功能
fix: 错误修复
docs: 文档变更
test: 测试新增/变更
refactor: 代码重构

进行原子提交（每次提交一个逻辑变更），提交前测试，并将文档更新与代码变更一起提交。

适用场景

需要构建可组合的 n8n Webhook 工作流时
需要将 n8n 工作流与 Python 服务集成时
需要为工作流集成编写测试时
需要创建可复用工作流模板时
需要调试工作流执行问题时
需要为 n8n 项目搭建开发环境时

限制

资料中未提供关于收费、价格、平台支持范围、具体效果或性能指标的信息。