用途
Nathan 开发标准用于在 Nathan 项目内进行开发时提供统一的规范与模式。Nathan 是一个 n8n 与 Jira 结合的智能体自动化系统。当需要创建或修改 n8n 工作流 JSON 文件、为 Nathan 的 helpers 或 templating 模块编写 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": "Validate Secret", "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('\n') 对应 .join('\n') .replaceAll('\n', ' ') 对应 .replaceAll('\n', ' ')
Python 标准
详细模式见 references/python-patterns.md。
模块结构：
nathan/ helpers/ # 共享工具（工作流注册表等） workflows/ # 每个类别的 n8n 工作流 JSON + registry.yaml templating/ # YAML 转 JSON 模板引擎 scripts/ # 独立可运行脚本
代码风格：必需导入模式如下，要求类型提示，使用 T | None 而非 Optional[T]：
from future import annotations from typing import Any from pathlib import Path import logging
logger = logging.getLogger(name)
async def trigger_workflow(url: str, params: dict[str, Any]) -> dict[str, Any]: ...
注册表模式（registry.yaml）：
version: "1.0.0" description: "Registry description"
commands: command_name: endpoint: /webhook/endpoint-path method: POST required_params: - param1 optional_params: - param2 description: What this command does example: param1: "value"
规格驱动开发
使用 agent-os 命令进行功能开发：
/shape-spec - 初始化并塑造规格 /write-spec - 编写详细规格文档 /create-tasks - 从规格生成任务列表 /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，按工作流类别存放
适用场景与限制
该技能适用于在 Nathan 项目内进行 n8n 工作流、Python 模块、webhook 契约与注册表配置的开发。资料未提供该技能的收费、价格、平台支持范围或效果数据，这些信息暂未提供。