物联网中的 Node-RED（9·上）：AI 协作与多工程拆分方案 · 背景、核心概念与总体架构
本篇是《AI + Node-RED 协作开发与多工程拆分统一管理方案》拆分后的第 1 篇（共 5 篇）。原文是一份完整、可复刻的工作手册，本系列不压缩，按主题拆成 5 篇连续发出：
- （上）背景、核心概念与总体架构 ← 本篇
- （中）第一阶段：Flow 拆分与 AI 协作
- （下壹）第二阶段：多工程拆分（分组 / 目录 / settings.js / 注册表 / 配置节点 / 脚本改造）
- （下贰）第二阶段：统一面板升级、风险清单与实施计划
- （终）协作边界、与传统方式对比、FAQ 与检查清单
原文标题：AI + Node-RED 协作开发与多工程拆分统一管理方案
版本：V1.0（整合版）｜ 适用场景：本地单人开发 + AI 辅助编程 ｜ 状态：可复刻工作手册
文档定位：本方案将「Flow 按 Tab 拆分 + AI 安全协作」（第一阶段·单实例）与「多工程隔离 + 统一面板管理」（第二阶段·多实例）两阶段方法合并为一份通用手册。前半部分是地基，后半部分是演进扩展，第一阶段定义的三条铁律在两个阶段均继续有效。
使用方式：本文去掉了所有项目特有细节（具体业务域、设备型号、端口、Tab 名），只保留可复用的「架构 + 工具 + 流程 + 风险」。读者按自己项目的实际业务域、端口、节点数填空即可复刻。文中示例值（如端口1891-1898、节点数约 500+）仅为示意，落地时以你的环境为准。
〇、这份文档能帮你做什么
如果你在用 Node-RED 做物联网 / 数据采集 / 设备接入类开发，并且开始借助 AI（如 Copilot、WorkBuddy 等）辅助写流逻辑，本文提供一套已被验证可行的协作 + 工程化工作模式：
- 让 AI 安全、低成本地改 Node-RED 流：把巨型
flows.json拆成按 Tab 的小 YAML，AI 只读写相关小文件，token 省、diff 清、不乱动运行时。 - 让多业务域隔离、互不污染：当一个项目里 Tab 越来越多、彼此并不一起工作时，按业务域拆成多个独立 Node-RED 实例，各自端口、各自配置、各自部署。
- 让一切按钮化、可一键复现：用一个统一的 Web 面板管理所有工程（启动检测、正向热部署、反向回写），别人拿到这份手册 + 脚本即可照做。
本文不包含具体业务逻辑，只给「方法论 + 工具骨架 + 操作清单」。复制本方案后，把
<业务域>、<端口段>、<Tab 名>等占位替换为你自己的内容即可。
一、背景与痛点
1.1 单体 flows.json 的问题（第一阶段）
Node-RED 默认把所有流存进一个 flows.json。当项目成长到一定规模，这个文件会变成巨型单体文件：
| 指标 | 示例数值（以实际项目为准） |
|---|---|
| 文件大小 | ~600KB+ |
| 总行数 | ~10000 行 |
| Tab（标签页）数 | 十几个到几十个 |
| 总节点数 | 数百到上千 |
| 配置节点（MQTT Broker / 数据库 等） | 十几个 |
AI 协作时的痛点：
- 每次改一个节点逻辑，都要读写整个上万行 JSON，Token 消耗巨大、上下文易被撑爆；
- AI diff 不直观，难以定位变更范围；
- Git diff 混乱——改 A Tab 和改 B Tab 落在同一个文件，冲突频发。
1.2 单一实例的局限（第二阶段）
当 Tab 数继续增长，且这些 Tab 并非一起工作，而是天然按业务域分成若干组时，把所有 Tab 堆在一个 Node-RED 运行时里会造成：
- 上下文混杂、AI 读写范围大、Token 浪费；
- 单一端口、单一实例，无法隔离调试；
- 一个 Tab 出错可能影响其他无关业务；
- 反向同步时若连错实例有清库风险（第一阶段已埋雷，第二阶段必须根治）。
1.3 目标形态
两层演进，一套理念：
- 第一阶段：把工作流按 Tab 拆成多个独立 YAML 小文件，AI 只改 YAML，由脚本/面板热部署回 Node-RED。
- 第二阶段：把按业务域分组的 Tab 进一步拆成多个独立 Node-RED 工程（实例），各自端口、各自配置；用一个统一按钮化面板选择性启动某几个、各自部署、各自反向回写。
二、核心概念
2.1 工程（Project）
| 概念 | 定义 |
|---|---|
| 工程（Project） | 一个独立的 Node-RED 实例 = 独立的 userDir + settings.js + flows.json + 独立端口。本文中「工程」≈「子项目」≈「一个 Node-RED 实例」。 |
| 全局工程文档 | 项目根 doc/ 目录下的统一规范文档（本文即其中之一），跨工程通用。 |
| 分项目文档 | 各工程目录内（或 doc/<工程名>/ 下）的文档，只描述该工程业务逻辑。 |
文档分级：根目录 doc = 全局规范；各分项目 = 对应业务文档。两者通过索引互相引用，不混写。
2.2 三条铁律（贯穿两阶段，绝不妥协）
- Tab → YAML 拆分：运行时只认
flows.json，但人和 AI 只维护src/tabs/*.yaml，二者通过脚本/面板互转。 - AI 绝不直接改
flows.json：AI 的修改只落在 YAML 小文件；向运行时部署由脚本/面板/用户执行。 - UI 改完必须反向同步：在 Node-RED 编辑器里手动改并 Deploy 后，必须把改动回写到 YAML，否则下次热部署会被本地 YAML 覆盖。
三、总体架构
3.1 第一阶段：单实例架构
┌─────────────────────────────────────────────────────────────┐
│ Node-RED Editor (Web UI) │
│ http://127.0.0.1:<主端口> │
│ 用户手动编辑 → Deploy 部署 → flows.json 更新 │
└────────────────────────┬────────────────────────────────────┘
│ 用户 UI 编辑完后手动执行
▼
┌──────────────────┐
│ split_flows.js │ 拆分 flows.json → src/
│ (自研拆分工具) │ 按 Tab/Subflow/Config 分 YAML
└────────┬─────────┘
│
▼
┌──────────────────┐
│ src/ 目录 │ ← AI 只读写这里的 200-400 行小文件
│ ├── tabs/ │
│ ├── subflows/ │
│ └── config-nodes/│
└────────┬─────────┘
│ AI 修改 YAML 后执行
▼
┌──────────────────┐
│ sync_flows.js │ 读取 YAML → 组装数组
│ (自研合并工具) │ → POST /flows (Admin API v1)
└────────┬─────────┘
│ HTTP POST (flat array)
▼
┌──────────────────┐
│ Node-RED Runtime │ 热重载，新逻辑立即生效
└──────────────────┘
3.2 第二阶段：多工程架构
┌─────────────── 统一面板 (端口 <面板端口>, 例 1889) ───────────────┐
│ 第一层：工程列表 + 状态探活 + 启动命令 │
│ 第二层：进入某工程 → 该工程内 热部署/反向同步 │
└───────────┬───────────┬───────────┬───────────┬────────────────┘
│ │ │ │
┌─────────────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
工程① <端口1> │ │ 工程② │ │ 工程③ │ │ 工程④ │ │ 工程… │ （各独立 Node-RED 实例）
(业务域 A) │ │(业务域B)│ │(业务域C)│ │(业务域D)│ │ │
src/tabs/ 仅本工程 │ │ │ │ │ │ │ │ │
settings.js(uiPort) │ │ │ │ │ │ │ │ │
flows.json 独立 │ │ │ │ │ │ │ │ │
└─────────────────┘ └────────┘ └────────┘ └────────┘ └────────┘
多工程下，每个工程就是第一阶段里「一个被拆出来的子集」，只是各自有了独立端口与运行时，互不干扰。
浙公网安备 33010602011771号