⚡

Nathan开发标准Skill nathan-standards

本技能文档详细定义了 Nathan 项目（一个基于 n8n 和 Jira 的代理自动化系统）的开发标准与最佳实践。内容涵盖 n8n 工作流设计规范、Python 代码编写模式、项目架构、Webhook 接口契约、工作流注册表配置以及规范驱动开发流程。适用于自动化流程开发、低代码平台集成、企业级工作流管理和 DevOps 自动化场景。关键词：n8n 工作流，Jira 自动化，Python 开发标准，Webhook 接口，低代码开发，DevOps 自动化，规范驱动开发，工作流注册表。

低代码开发 0 次安装 0 次浏览 更新于 2/28/2026

name: nathan-standards description: Nathan n8n-Jira 代理自动化系统的开发标准。涵盖 n8n 工作流、Python 模式和项目规范。 author: Joseph OBrien status: unpublished updated: ‘2025-12-23’ version: 1.0.1 tag: skill type: skill

Nathan 开发标准

在 Nathan 项目（一个 n8n-Jira 代理自动化系统）中进行开发的标准和模式。

何时使用

在以下情况时调用此技能：

  • 创建或修改 n8n 工作流 JSON 文件
  • 为 Nathan 助手或模板模块编写 Python 代码
  • 设计 Webhook 命令契约
  • 构建工作流注册表配置
  • 通过 agent-os 实现规范驱动的功能

项目架构

Nathan 遵循分层架构：

外部服务 (Jira) <-- n8n 工作流 <-- Python 代理服务
                             (凭据)      (Webhook 调用)

核心原则：n8n 拥有所有外部凭据。Python 服务使用共享密钥认证调用 n8n Webhook。

n8n 工作流标准

有关详细的工作流模式，请加载 references/n8n-workflow-patterns.md。

标准工作流结构

每个 Webhook 工作流必须遵循此模式：

Webhook --> 验证密钥 --> 操作 --> 响应 Webhook
               |                   |              |
               v                   v              v
           未授权响应 (401)    错误响应 (500)    成功响应 (200)

必需节点模式

{
  "id": "validate-secret",
  "name": "验证密钥",
  "type": "n8n-nodes-base.if",
  "typeVersion": 2,
  "parameters": {
    "conditions": {
      "conditions": [{
        "leftValue": "={{ $json.headers['x-n8n-secret'] }}",
        "rightValue": "={{ $env.N8N_WEBHOOK_SECRET }}",
        "operator": { "type": "string", "operation": "equals" }
      }]
    }
  }
}

响应格式

所有响应必须遵循此格式：

{ "success": true, "data": {...}, "status_code": 200, "error": null }
{ "success": false, "data": {}, "status_code": 500, "error": "message" }

JQL 表达式转义

在 JSON 中的 n8n 表达式内，请正确转义：

错误 正确
.map(x => "${x}") .map(x => '"' + x + '"')
`.join(’
')` `.join('\
')`
`.replaceAll(’
', ’ ')` `.replaceAll('\
', ’ ')`

Python 标准

有关详细模式，请加载 references/python-patterns.md。

模块结构

nathan/
  helpers/           # 共享工具（工作流注册表等）
  workflows/         # n8n 工作流 JSON + 每个类别的 registry.yaml
  templating/        # YAML 到 JSON 模板引擎
  scripts/           # 独立可运行脚本

代码风格

# 必需的导入模式
from __future__ import annotations
from typing import Any
from pathlib import Path
import logging

logger = logging.getLogger(__name__)

# 需要类型提示，使用 T | None 而不是 Optional[T]
async def trigger_workflow(url: str, params: dict[str, Any]) -> dict[str, Any]:
    ...

注册表模式

# registry.yaml
version: "1.0.0"
description: "注册表描述"

commands:
  command_name:
    endpoint: /webhook/endpoint-path
    method: POST
    required_params:
      - param1
    optional_params:
      - param2
    description: 此命令的作用
    example:
      param1: "value"

规范驱动开发

使用 agent-os 命令进行功能开发：

  1. /shape-spec - 初始化和塑造规范
  2. /write-spec - 编写详细规范文档
  3. /create-tasks - 根据规范生成任务列表
  4. /orchestrate-tasks - 委托给子代理

规范位于 agent-os/specs/[spec-name]/ 目录下，包含：

  • spec.md - 功能规范
  • tasks.md - 带复选框的实现任务
  • orchestration.yml - 子代理委托配置

快速参考

常用命令

uv sync                              # 安装依赖
uv run pytest                        # 运行测试
uv run pytest path/to/test.py -v     # 单个测试文件
uvx ruff check .                     # 代码检查
uvx ruff format .                    # 代码格式化
docker compose -f docker-compose.n8n.yml up -d  # 启动 n8n

环境变量

变量 用途
N8N_WEBHOOK_SECRET Webhook 认证的共享密钥
N8N_API_KEY n8n 公共 API 密钥
JIRA_DOMAIN Jira Cloud 域名
JIRA_EMAIL Jira 账户邮箱
JIRA_API_TOKEN Jira API 令牌

文件命名规范

类型 规范 示例
工作流 JSON kebab-case.json jira-get-ticket.json
Python 模块 snake_case.py n8n_workflow_registry.py
测试文件 test_*.py test_parser.py
注册表 registry.yaml 每个工作流类别