# NodeGraphEditor

**Repository Path**: zdll/node-graph-editor

## Basic Information

- **Project Name**: NodeGraphEditor
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-30
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NodeGraphEngine

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![.NET](https://img.shields.io/badge/.NET-10.0-512BD4)](https://dotnet.microsoft.com/)
<!-- 发布到 GitHub 后，可把下面的占位替换为仓库 CI 徽章：
[![CI](https://github.com/<owner>/<repo>/actions/workflows/ci.yml/badge.svg)](https://github.com/<owner>/<repo>/actions/workflows/ci.yml) -->

面向工控环境的 .NET 10 节点图（蓝图）执行引擎，执行模型参照 ComfyUI 最新架构：**数据流驱动的有向无环图（DAG）+ 拓扑排序显式调度**。节点只有数据引脚、没有执行引脚，从输出节点（汇点）反向拉取祖先闭包，入度归零即就绪，就绪集并行派发——纯数据流，无副作用执行引脚。

核心库 UI 无关，同一引擎支撑 Blazor WebAssembly Client 编辑器（配 ASP.NET Core 服务端）与控制台宿主。编辑器采用**服务端引擎 · 单机 B/S** 架构：`NodeGraphEditor.Client` 是唯一 Client，包含全部 UI；`NodeGraphEditor.Server` 发布时一并托管 Client 静态资源、REST/SSE API 和引擎，无需 nginx。Client 只引用 `NodeGraphEngine.Contracts`，不下载或执行引擎代码。

## 特性

- **ComfyUI 式数据流调度**：三态节点生命周期（Success / Pending / Failure）、输出签名缓存（`SHA256(typeId + 配置 + 祖先签名递归)`，缓存即恢复，中断重跑从未算节点继续）、懒求值与条件分支（`ExecutionBlocker` 静默下游）。
- **工控级可靠性**：节点级超时、失败策略（FailFast / Isolate / Retry(n)）、事件订阅者异常隔离、运行循环兜底 + 心跳 + 可选自愈、滚动日志与崩溃落盘。
- **事件触发**：OnPlay / Manual / SocketMessage / RisingEdge / FallingEdge / CommEvent / Heartbeat，触发合并防抖 + 有界队列 + 丢弃计数；事件注入 busyGuard 防重入。
- **引擎原生挂起恢复**：`Flow.Timeout` / `Flow.Sequence` / `Flow.WaitAll` 的等待经 `PendingResult` 登记截止时刻，到点自动重触发（`TimerResume`），无轮询。
- **统一脚本节点**：全系统单一 `Script.Node` 类型，实例设置声明引脚/依赖/事件源，编辑后编译（Roslyn）、运行期零编译；服务端真实 Roslyn 补全 + 本地静态库回退的代码提示。
- **通信通道**：SocketClient / SocketServer / ModbusTcp（全功能码 01/02/03/04/05/06/15/16）/ S7（S7netplus）/ EipScanner / EipAdapter，连接参数随图持久化，服务端图内常驻 + 宿主级共享通道。
- **三级变量**：Global（可掉电保持）/ Flow（单次运行）/ Local（子图/循环帧）。
- **权限认证**：登录会话、8 项权限键、admin/engineer/operator 角色与单用户权限覆盖（服务端强制校验，客户端仅 UX 门控）。
- **数据库**：SqlSugar（Sqlite / PostgreSQL / MySql / SqlServer），权限与运行历史持久化，切换只改配置。
- **插件化**：`[NodePlugin]` 声明式注册（Source Generator 生成强类型 TypeId 与静态元数据）、插件 DLL 热重载（影子复制 + collectible ALC）。

## 项目结构

唯一解决方案 `NodeGraphEngine.slnx` 只包含 6 个项目：

| 项目 | 说明 |
| --- | --- |
| `NodeGraphEngine.Contracts` | 插件契约与协议 DTO 层（net10.0，零依赖） |
| `NodeGraphEngine.Generators` | 增量 Source Generator：节点自动注册 + 静态元数据 |
| `NodeGraphEngine.Core` | 引擎核心：图模型、数据流调度器、输出缓存、通信通道、脚本节点、插件热重载 |
| `NodeGraphEngine.Core.Tests` | MSTest 自动化测试（210 用例） |
| `NodeGraphEditor.Client` | Blazor WebAssembly 唯一 Client（画布基于 Z.Blazor.Diagrams） |
| `NodeGraphEditor.Server` | 唯一可部署宿主：托管 Client 静态资源、REST/SSE API、引擎、权限与数据库 |

辅助项目（不在解决方案，单独 `dotnet run --project`）：`NodeGraphEngine.Smoke`（冒烟验证）、`NodeGraphEngine.Demo`（示例）、`NodeGraphSoakRunner`（7×24h 长稳/压测）、`NodeGraphEngine.StationSim`（机械手扫码工作站模拟器）。

## 快速开始

要求：.NET 10 SDK（无 MAUI/workload 依赖——Client 是纯浏览器端）。

```powershell
dotnet run --project NodeGraphEditor.Server -c Release -- --urls http://127.0.0.1:5099
```

浏览器打开 <http://127.0.0.1:5099> 即进入编辑器。默认账号 `admin / admin123`（登录页有提示，部署后务必改密）。示例图在服务端 `samples/` 目录，`/api/v1/graph/list` 可加载。

完整验证流程（每次修改代码后执行）：

```powershell
dotnet restore NodeGraphEngine.slnx
dotnet build NodeGraphEngine.slnx -c Release --no-restore
dotnet test NodeGraphEngine.slnx -c Release --no-build
```

## 执行模型（ComfyUI 式数据流调度）

- **阻塞计数调度**：从输出节点（`IsOutputNode` 汇点）反向拉取祖先闭包，入度归零即就绪，就绪集并行派发（`MaxConcurrency` 可配）；循环依赖显式报错。
- **三态节点生命周期**：`Success / Pending / Failure`；懒求值补边与异步让出统一走 Pending 重排；挂起节点到点自动恢复（`TimerResume`）。
- **输出缓存**：运行期按 `(nodeId, pin)` 缓存，共享上游只算一次；跨运行签名缓存键 = `SHA256(typeId + 配置 + 祖先签名递归)`，改任一上游自动失效。
- **信号连线**（ngjson v4）：不参与调度依赖的通用信号反馈通道（橙色边，允许自环）。
- **触发限定调度**：事件源触发只调度「命中节点 + 下游闭包汇点 + 常驻汇点」，无关节点不派发、UI 不闪烁。

## 内置节点

Literal、Math、Convert、Compare、Branch（ConditionalSelect/If/Switch）、Loop（ForLoop/While）、String、Fieldbus（Modbus Read/Write、S7 Read/Write）、Event（EdgeTrigger）、Comm、Network（HttpGet/HttpPost/HttpRequest、SocketReceive/SocketSend/ReplyClient）、Variable（Global/Flow/Local）、Flow（Start/Pass/Timeout/Sequence/WaitAll）、SubGraph、Image（Image.Source）、Script.Node（统一脚本节点）。完整清单以编辑器节点目录（`/api/v1/graph/catalog`）为准。

## 通信通道（Comm Channels）

连接参数集中在 `GraphDocument.CommChannels` 随图持久化；服务端图内通道随权威图加载即建连/监听（常驻，不随引擎启停断开），宿主级通道经 `appsettings.json` 的 `CommChannels` 节在进程启动时建连。通道类型：`SocketClient` / `SocketServer` / `ModbusTcp` / `S7` / `EipScanner` / `EipAdapter`。Modbus 地址前缀：`4xxxx` 保持寄存器 / `3xxxx` 输入寄存器 / `1xxxx` 离散输入 / `0xxxx` 线圈；EipScanner 另支持 AB 标签 `TagRead`/`TagWrite`。

## 变量系统（三级）

- **Global 全局**：跨运行保留，可经 `RetainedVariablesPath` 掉电保持
- **Flow 临时**：单次触发运行内有效，运行开始自动清空
- **Local 局部**：子图/循环帧作用域

## 文档

- `docs/CustomNodeSpec.md`：自定义节点开发规范（契约/义务/插件热重载/完整示例）
- `docs/RobotStationSpec.md`：机械手扫码工作站示例图与模拟器规格
- `docs/ROADMAP.md`：架构评审结论与演进路线

## 部署

- **单机 B/S（推荐）**：发布并运行 `NodeGraphEditor.Server`，同时提供 Client 静态资源、REST/SSE API 与引擎执行，浏览器和 API 保持同源，无需 nginx。部署配置固化在 `deploy/`（Windows 服务安装脚本 + systemd unit + 防火墙放行）。
- **服务化**：同一份服务端代码两端运行——Windows 注册为服务（服务名 `NodeGraphEngineServer`）、Linux 由 systemd 托管。
- **工控部署注意**：SocketServer/EdgeTrigger 需放行对应 TCP 端口；EIP 用 TCP/UDP 44818 与 UDP 2222，Modbus TCP 默认 502；插件热重载在单文件发布/裁剪场景受限，请用非单文件发布。

## 工程约定

- 统一编译与分析器设置位于 `Directory.Build.props`（`TreatWarningsAsErrors=true`，警告即错误）；格式与代码风格规则位于 `.editorconfig`。
- **每次修改必须执行完整测试流程**（编译 + 全部测试，不止编译通过）。
- 每次修改核心模型或执行语义时，应在 `NodeGraphEngine.Core.Tests` 增加或更新测试。
- 序列化格式自数据流重写后已变更，**旧 exec-pin 时代的 .ngjson 文件不兼容**。
- 详细开发约定见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 开源协议

本项目以 **MIT 协议**开源，详见 [LICENSE](LICENSE)。仓库内包含 Apache-2.0 许可的移植代码（ModbusLib 移植层、EtherNet/IP 协议栈移植层）与第三方依赖，其归属与许可义务详见 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。