n8n 工作流技能（Python / JavaScript + 工作流 JSON）

面向 自托管或任意 n8n 实例：不假设具体集成；用占位符表示环境与凭证名称。

何时应用本技能

• 项目内日常编写（优先读本技能）：编写、改写或审查 n8n 相关 的 Code 节点（Python / JavaScript）、工作流 JSON 时；须按 references/n8n-daily-authoring.md 落盘（工作流文件夹 + 按节点拆分文件 + 节点关系与分支说明.md），除非用户 明确 只要聊天内代码、不要写入磁盘。
• 编写、合并或审查 workflow JSON（导出片段、完整工作流、或节点 parameters 的 JSON 形态）。
• 需要 同时 产出 可运行代码 与 可合并进 n8n 的 JSON（见下文「双轨交付」）。
• 需要 标明上下游（edges 或等价表）；日常说明文档见 n8n-daily-authoring.md。
• 要求 规范化、简洁、清晰、代码量尽量少（不以删注释为代价），尽量逐行中文注释（见 references/commenting-standard.md）、安全检查。
• 用户 本地未运行 n8n：本地测试策略见 references/local-testing.md。
• 用户提出 工作流备份反推：须同时拿到 备份 .json 路径 与 输出目录路径（见 workflow-backup-reverse-engineering.md「前置条件」）；缺一则 提醒补齐并暂停，不得擅自执行反推或写入磁盘。

日常编写：工作流文件夹 + 按节点文件 + 说明 MD（方法）

当用户 未 处于「仅反推备份」场景、而是在 日常写 n8n 代码或 JSON 时，必须遵守 references/n8n-daily-authoring.md 全文。摘要：

• 在 项目根或用户指定目录 下创建 {功能简述}_n8n_workflow（或用户约定名）。
• 文件夹内：每个 Code 节点 → 单独 .py/.js；需单独保存的节点 → 单独 .json；文件名用 01_1.2_节点名 等形式体现 顺序与分支层级（与说明文档一致）。
• 同一文件夹 内 节点关系与分支说明.md：节点清单表（上下游）；每条分支 用 一段话 写透从上游到下游的逻辑；所有阈值与数值 在文中 写全具体数字与单位，不得仅写「见代码」。
• 反推 的产出结构（工作流分支逻辑与优化建议.md + code/ + code_optimized/）不因本节而改变；二者不要混用目录约定。

禁止在文档中粘贴未脱敏的 Webhook URL、Token。

工作流备份 JSON → 分支段落 + 优化建议 + code/ + code_optimized/（方法）

当用户 已同时提供（1）备份 JSON 文件路径、（2）输出目录路径，并要求反推时，必须按 references/workflow-backup-reverse-engineering.md 全文执行；若任一路径缺失，不得解析或落盘，只提醒用户补全后再运行。摘要：一个 工作流分支逻辑与优化建议.md（每条端到端分支 = 单标题 + 单一段落详细逻辑）；code/（Code 节点从 JSON 原样 抽出）；code_optimized/（与 code/ 同名一一对应，等价精简 + 注释规则见 code-optimized-export.md）。不默认再生成 00-workflow-overview.md、branches-index.md、nodes/*.md 等；残留旧结构应删除或覆盖。

双轨交付（强制）

凡涉及 Code 节点或可执行逻辑，代理在交付时必须 一并给出，缺一不可：

1. 代码轨：完整 Python 或 JavaScript（与节点 parameters.language 一致）；遵守 references/code-node-python.md 或 references/code-node-javascript.md。
2. JSON 轨：与上述代码对应的 工作流片段（nodes + edges，schema 见 references/workflow-json-fragment.md），或用户要求的 完整可导入 JSON 中的相关节点对象；Code 节点的 pythonCode / jsCode 字段须与代码轨 内容一致（注意 JSON 字符串转义）。

若用户只要其中一种，仍须在回复中 明确说明 另一种为省略项；默认 两者都交。日常编写若落盘，代码与 JSON 须写入 工作流文件夹 内对应文件（见 n8n-daily-authoring.md）。

代理必须遵守的执行顺序

1. 判定场景：日常编写（默认读 n8n-daily-authoring.md）还是 仅 反推备份（读 workflow-backup-reverse-engineering.md）；反推缺路径则 停止。
2. 日常落盘时：确认或约定 输出根目录 与 工作流文件夹名；确定 节点层级编号 与 节点关系与分支说明.md 结构，再写各节点文件，保证 文件名编号 ↔ MD 表 ↔ 代码 一致。
3. 确认语言与执行模式：Python 还是 JavaScript；Run once for all items 还是 Run once for each item。不得混用 _items 与 $input.all() 等约定而不加说明。参见对应 reference 文件。
4. 先拓扑后 JSON 后代码（或代码与 JSON 同步迭代）：输出 edges（或 from→to 表 + note），再输出 nodes JSON，再输出或嵌入 带完整注释的代码。
5. 注释（强制）：严格遵循 references/commenting-standard.md——以 尽量每一行都有中文语义注释 为默认目标（块标题 + 行级说明）；循环、分支、返回处不得出现大段「零注释」代码。
6. JSON 的可读性：标准 JSON 不允许 // 注释；使用 meta、edges[].note、meta.fieldNotes（对象：键路径 → 中文说明）或在代码块外附 「参数说明」 Markdown 逐字段解释（见 references/workflow-json-fragment.md）。
7. 审查与瘦身：对照 references/review-checklist.md；删未使用 import/变量；不删必要注释；异常与日志不泄露密钥。
8. 合并完整导出时：节点 name 唯一；connections 与 name 一致；typeVersion 与用户实例一致；提醒 Import + 试跑 烟测。

片段与完整工作流

见 references/workflow-json-fragment.md。占位符：{{PLACEHOLDER}}。

分册参考

输出语言

• 对用户说明、代码内注释、JSON 配套说明：中文（除非用户要求英文）。
• 节点 type、官方 JSON 键名：英文，与 n8n 导出一致。