# NodeStudio

**Repository Path**: cai-jingchuang/node-studio

## Basic Information

- **Project Name**: NodeStudio
- **Description**: WPF 节点图编辑器框架 —— 用节点可视化你的逻辑
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-07-31
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NodeStudio

[![.NET 8](https://img.shields.io/badge/.NET-8.0-512BD4?logo=dotnet)](https://dotnet.microsoft.com/)
[![Platform](https://img.shields.io/badge/Platform-Windows-0078D6?logo=windows)](https://www.microsoft.com/windows)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)

**WPF 节点图编辑器框架 —— 用节点可视化你的逻辑**

NodeStudio 帮助你在 .NET 桌面应用中快速构建节点式交互体验：拖一拖节点、连一连线、点一下运行，一个可视化流程就活了。无论是数据流水线、逻辑编排，还是面向最终用户的"低代码"工具，NodeStudio 都为你准备好了画布、引擎与编辑器。

## NodeStudio 能做的

- 🧩 **所见即所得的编辑**：拖拽创建节点、拉线连接、框选、复制粘贴、重命名删除，一切直觉操作
- 🔀 **真并行执行**：内置 DAG 执行引擎，自动追踪依赖、就绪节点并行运行、失败节点不影响下游
- 📦 **子图与模块化**：把一组节点打包成"节点块"，双击即可进入内部继续编辑——复杂流程也能拆得清清楚楚
- ▶️ **一键运行，放心操作**：全局运行/暂停/连续运行，运行中画布自动进入只读保护（仍可选中与查看），不怕误操作；右键任意节点「运行」可单节点执行——不重置输入（已连接端口取上游上次输出值，未连接端口取手动值），调试单个节点不用跑整图
- 🎛️ **选中即编辑**：单击节点，右侧属性面板立即呈现可调参数，改完即生效；选中节点时相关连线自动高亮
- 📋 **多选复制粘贴**：框选/多选后 Ctrl+C 复制、Ctrl+V 或右键粘贴——单个粘贴到鼠标位置，多选按原位置整体平移并恢复相互连线；Delete 删除选中（一次确认）
- 💾 **随存随取**：一键保存/加载完整图——节点、连线、参数、子图结构全部保留；格式带版本号，旧文件兼容、过新文件友好提示
- 🧩 **自定义类型与属性持久化**：注册自定义端口类型；节点复杂属性（含第三方不可序列化类型）分层序列化，属性多态（基类声明、泛型列表混装派生类）自动按 `$type` 还原为派生实例，`[NotSerialized]` 标记不保存
- 🌙 **一致的深色风格**：编辑器、弹窗、菜单、面板统一深色主题，专注不刺眼

## 快速开始

```bash
# 构建
dotnet build NodeStudio.sln

# 运行演示（图形界面）
dotnet run --project TestWpf

# 运行功能测试
dotnet run --project TestConsole
```

在 TestWpf 演示中：从左侧工具箱拖入节点 → 连线 → 点 ▶ 运行 → 从"文件"菜单导出/导入你的图。

## 内置节点

引擎自带六个开箱即用的流程/运算/同步节点，无需任何代码即可搭建条件分支、数值计算、时序控制与跨块同步流程。

**object 通配连接规则**：内置节点（延时、数据入队/出队等）使用 object 通配端口实现任意类型透传。为杜绝"运行后才发现类型不对"，object 通配输出连接到具体类型输入时有以下约束：

- 连接时若输出端口**当前值无法转换**到目标输入类型（如 string "abc" → int），**拒绝连接**并给出原因；
- 输出值为 null 时允许连接（"先搭图后运行"的工作流），但运行后上游仍传入 null 或不匹配的值时，**下游节点运行失败并给出明确报错**（内置节点已内置该检查；自定义节点可用 `GetValueStrict()` 严格读取，或用 `GetValue()` 容错读取后自行判断与报错）；
- 数值语义兼容的值自动转换（int 经 object 输出读入 double/int 端口正常工作）。

### 节点块

把一组节点打包成可复用模块——外部看是一个节点，双击即可进入内部编辑器继续编辑，复杂流程拆成清晰的层次结构。

**结构与块端口**

块内部是一张独立的子图；块与外部交换数据靠「块输入 / 块输出」两个特殊节点（进入块内部编辑器后可见）：

```
外部图：   [上游] ──→ (块.数值A)            [下游] ←── (块.结果)
                        │                    ↑
内部子图：      [块输入]→ 数值A        块输出 ←[内部计算]──┘
                         └────→ [内部节点] ────┘
```

- **添加端口**：在「块输入 / 块输出」节点上右键「新增输入 / 新增输出」即可给块加端口（**添加时选定类型**，强类型避免 object 装箱）；端口名在块内唯一，添加后不可改类型，可重命名
- **数据流向**：外部连到块输入端口的值 → 内部「块输入」节点 → 流入内部节点；内部节点的结果连到「块输出」节点 → 执行结束时回写块的外部输出端口
- 块级「运行」控制端口是**块级控制信号**：不出现在内部图中、不可删除、也不占用内部端口命名

**运行语义**

- 块作为**一个节点**参与外层调度：外层连到块输入的连线全部就绪后，块才开始执行内部图；内部图每轮执行前重置内部节点
- **「运行」开关**（bool 端口）：连接后为 `false` 时整块跳过（标记"未运行"），下游照常——与所有节点的通用「运行」端口是同一个端口（见「扩展开发」）
- **循环执行**：内部编辑器右上角配置「循环执行 / 起始 / 结束 / 步长」后，内部图按区间重复执行（每轮完整执行一次，轮间重置）；计算出的循环轮数 ≤ 0 时内部图一次都不执行
- **失败语义**：内部任一节点失败 → 块标记失败（错误信息列出内部失败节点），但**不阻断外部下游**（与普通节点一致）
- **取消传播**：整图取消时内部图同步响应（内部节点标记"未运行"）
- 块也自带通用「运行状态」输出端口（0/1/2）——接条件节点即可按**块的成败**分支；输出端口在每轮开始时清空，块未执行时下游读到 0

**编辑与复用**

- **双击进入 / 面包屑返回**：进入块内部后画布只显示该块的子图，外层运行中允许进入查看（内部只读）
- **嵌套**：块内可以再放块（块中块），层级不限；运行锁与全局运行模型对内层一致生效
- **复制粘贴 / 克隆**：块的内部图（节点 + 连线）整体深克隆，粘贴后内容完整恢复
- **序列化**：块端口定义与内部子图一起保存/恢复（JSON），旧格式兼容

**代码方式创建块**（模型层完整可用，编辑器创建的块同构）：

```csharp
var block = new NodeBlock { Name = "处理块" };
block.AddInput<int>("数值A").AddOutput<int>("结果");

var inner = new MultiplyNode { Name = "内部乘法" };
block.InnerGraph.AddNode(inner);
block.InnerGraph.Connect(block.GetInputProxyNode("数值A"), "值", inner, "数值A"); // 块输入 → 内部
block.InnerGraph.Connect(inner, "结果", block.GetOutputProxyNode("结果"), "值");   // 内部 → 块输出

graph.AddNode(block);
graph.Connect(source, "结果", block, "数值A"); // 外部与块端口按名连接
```

### 条件节点

按用户设定的条件表达式决定运行哪条后续路线，每个条件对应一个输出端口：

- 添加多个条件（自定义名称 + 表达式），表达式为真时该路线激活；多条同时满足时并行运行
- 典型用法：条件节点输出（bool）连接到目标节点的「运行」端口（节点块/任意节点均可），由条件决定谁执行
- **表达式引擎**内置：引用输入端口值 `[输入1]`，支持四则/幂运算、比较（`>` `>=` `<` `<=` `==` `!=`）、逻辑（`&&` `||` `!`，短路求值）与常用数学函数（`abs sqrt sin cos tan pow min max log` 等），以及常量 `pi`、`e`
- **对象路径引用**：输入是对象/对象列表时，用 `{input}`、`{input[0]}`（列表首元素）、`{input.Area}`（属性）、`{input[0].Area}`（链式）参与比较与运算——属性是否存在、索引是否越界在运行期报错（该条件视为不满足并显示错误）
- **实时校验**：在属性面板输入表达式时即时检查括号、函数名、`[输入名]`/`{对象路径}` 格式与输入名是否存在、整体是否为判断语句；非法表达式对应的路线不生效且不阻断其他路线

> 条件节点的输出端口是 bool 类型，只能连接到 bool 输入（如节点块的「运行」端口），从类型上杜绝了误连到数值端口。

#### 按上游节点的运行结果分支（成功走一条、失败走另一条）

每个节点都自带「运行状态」int 输出端口（引擎在节点执行完成后写入），把它接到条件节点，就能按**上游是否运行成功**决定后续走哪条路线：

| 运行状态值 | 含义 |
|---|---|
| `0` | 未运行（被禁用、「运行」开关关闭、取消未执行） |
| `1` | 运行成功 |
| `2` | 运行失败 |

连线方式：

```
X 节点.运行状态  →  条件节点.状态          （条件节点输入端口用 [状态] 引用）
条件节点：条件“成功” = [状态] == 1
          条件“失败” = [状态] == 2
条件节点.成功    →  A 节点.运行            （X 成功时才执行 A）
条件节点.失败    →  B 节点.运行            （X 失败时才执行 B）
```

- 连上「运行状态」即建立了依赖：条件节点会**等 X 执行完**（状态已写入）才运行，因此读到的一定是本次结果；
- 一条「运行状态」可以同时接多个条件节点；条件表达式也可写 `[状态] > 0`（已运行，不论成败）、`[状态] != 2` 等；
- 「运行状态」是 int，**不能直接连「运行」端口**（bool），必须经条件节点中转——这也是类型系统的刻意约束。

### 计算节点

按用户设定的表达式计算输入并输出结果，每个计算对应一个输出端口：

- 添加多个计算（自定义名称 + 表达式 + 输出类型：int/long/float/double/decimal/bool/string），表达式如 `[输入1] + cos([输入2]) * 1`
- **数值表达式引擎**内置：四则/幂运算、数学函数（`abs sqrt sin cos tan pow min max log` 等）、常量 `pi`/`e`
- **对象路径引用**：输入是对象/对象列表时，用 `{input}`、`{input[0]}`（列表首元素）、`{input.Area}`（属性）、`{input[0].Area}`（链式）参与运算——如 `{input.Area} * 2`、`{input[0].Area} + 1`；属性是否存在、索引是否越界在运行期报错；也可用于拼接（`"标签:" + {input.Name}`，按 ToString 格式化）
- **字符串拼接**：`+` 号任一侧为字符串字面量（双引号包裹，如 `"hello"`）或 string 类型输入端口时执行拼接——`"hello" + [a]`（a=1 → `hello1`）、`[a] + "hello"`（→ `1hello`）；数值按 "G" 格式转字符串；拼接表达式只能配 string 输出类型（数值表达式配 string 输出仍按 "G" 格式化——原有行为）
- **输出类型在添加时选定、之后锁定**；结果自动转换到输出类型，无法转换（如 NaN → int）时节点运行失败并给出明确错误
- 动态输入端口（**添加时可选类型**：object/short/int/float/double/bool/string，默认 object；表达式用 `[名称]` 引用数值、`{名称.属性}`/`{名称[索引]}` 引用对象，两种语法可混用），实时校验表达式格式与输入名是否存在（`- * /` 等运算与函数参数不支持字符串，静态提示）
- **面板直读端口值**：属性面板的输入端口行与「输出值」区显示最近一次运行的值（含内置"运行状态"），无需悬停端口看 ToolTip

> 计算节点的输出端口按选定类型（如 int/double），只能连接类型兼容的输入。

### 延时节点

把输入值延时指定毫秒后原样输出（响应取消），用于流程中模拟耗时工具、控制时序：

- 输入/输出为 **object 通配**——任意类型的数据流中间都可以插入延时节点做时序控制
- 延时毫秒在属性面板设置（0 表示不延时）；图取消/暂停可中断延时

### 数据入队 / 数据出队节点

生产者-消费者数据流（详见下文「全局数据队列」章节）：数据入队把值放入指定名称的全局队列（逐条缓冲不覆盖）；数据出队从队列取走一条数据输出（无数据时可等待，可配超时），等待期间同块其他分支照常并行。

## 内置样式（可复用的控件样式库）

自定义节点控件时可以直接复用框架的深色控件样式——`App.xaml` 已全局合并样式资源，在你的 XAML 中通过 `StaticResource` 直接引用即可，无需重复定义：

| 样式 | 控件类型 | 说明 |
|------|----------|------|
| `DialogTextBoxStyle` | TextBox | 深色输入框，聚焦时蓝色边框 |
| `DarkCheckBoxStyle` | CheckBox | 深色复选框，勾选时蓝色填充 + 白色对勾，悬停高亮 |
| `DialogButtonStyle` | Button | 深色普通按钮 |
| `DialogPrimaryButtonStyle` | Button | 深色主按钮（高亮，用于确定类操作） |
| `IconButtonStyle` | Button | 图标按钮（编辑器操作栏同款） |
| `DialogCloseButtonStyle` | Button | 弹窗关闭按钮 |
| `DialogMessageTextStyle` | TextBlock | 弹窗消息文本样式 |
| `DarkContextMenuStyle` | ContextMenu | 深色右键菜单 |
| `DarkMenuItemStyle` | MenuItem | 深色菜单项（悬停高亮） |

在自定义节点控件中直接使用：

```xml
<!-- MyNodeControl.xaml -->
<ctrl:NodeBaseControl x:Class="MyApp.MyNodeControl"
                      xmlns:ctrl="clr-namespace:NodeStudio.Controls.Views;assembly=NodeStudio.Controls">
    <StackPanel>
        <TextBox Text="{Binding Value}" Style="{StaticResource DialogTextBoxStyle}"/>
        <CheckBox Content="启用" IsChecked="{Binding Enabled}" Style="{StaticResource DarkCheckBoxStyle}"/>
        <Button Content="执行" Command="{Binding RunCommand}" Style="{StaticResource DialogButtonStyle}"/>
    </StackPanel>
</ctrl:NodeBaseControl>
```

> 样式资源定义在 `NodeStudio.Controls/Views/Styles.xaml`（含节点状态色/文案转换器），随包分发；编辑器画布、节点、端口、弹窗、菜单与属性面板本身也统一使用这套深色样式。

## 技术栈

- .NET 8 / WPF（Windows）
- [Nodify](https://github.com/miroiu/nodify) 节点画布
- MVVM（CommunityToolkit.Mvvm）
- 标准 JSON 序列化，无第三方配置依赖

## 设计理念

- **面向节点，不碰引擎**：你编写节点 ViewModel，端口、连线、执行由框架接管
- **数据流可见**：每个节点的运行状态与错误信息一目了然，调试与演示同样轻松

## 自定义类型与属性序列化

框架为"自定义类型端口"与"节点属性持久化"提供完整的分层支持。

### 自定义端口类型

允许宿主注册任意数据类型，节点块等"可动态增删端口"的节点在新增端口时即可选择：

```csharp
PortTypeRegistry.Register("payload", typeof(MyPayload)); // 应用启动时注册一次
```

注册后，节点块的块输入/块输出右键"新增输出/新增输入"菜单出现 `payload` 类型；端口为真实 CLR 类型，序列化按类型全名保存/恢复。

### 节点属性分层序列化

节点公共可写属性自动随图保存/恢复，按优先级分三层：

| 层 | 机制 | 适用 |
|---|---|---|
| 自动 | 任意属性尝试 System.Text.Json | 简单值 + 可序列化的自定义复杂类型 |
| 注册表 | `PropertySerializerRegistry.Register(type, encode, decode)` | 第三方不可序列化类型（只读/无无参构造等） |
| 节点级 | 实现 `ISerializableNode`（`SaveState`/`LoadState`） | 完全接管节点状态，格式自定义 |

```csharp
// 第 2 层：为不可 JSON 序列化的第三方类型注册编解码
PropertySerializerRegistry.Register(
    typeof(LegacyConfig),
    encode: cfg => new Dictionary<string, object?> { ["Url"] = ((LegacyConfig)cfg).Url },
    decode: dto => new LegacyConfig((string)dto["Url"]));

// 第 3 层：节点级完全接管
public class MyNode : NodeBase, ISerializableNode
{
    public string? SaveState() => ...;
    public void LoadState(string? state) => ...;
}
```

### 属性多态序列化（派生类与泛型列表）

属性声明为基类/接口、运行时保存派生实例——包括最常见的"`List<T>` 泛型列表混装多种派生类"——序列化自动写入 `$type` 类型标识，导入时还原为**原派生类**，派生类特有属性完整保留（嵌套递归、词典值、端口手动值同样支持；不打标时与旧版一致，旧图文件兼容读取）：

```csharp
public abstract class Shape { public string Label { get; set; } = ""; }
public class CircleShape : Shape { public double Radius { get; set; } }
public class RectShape : Shape { public double Width { get; set; } public double Height { get; set; } }

public class MyNode : NodeBase
{
    public Shape? Main { get; set; }                  // 单值多态
    public List<Shape> Shapes { get; set; } = new();  // 列表混装多种派生类
}
```

序列化后列表元素逐个携带类型标识，导入即还原为 `CircleShape`/`RectShape` 原派生实例：

```json
"Shapes": [
  { "$type": "MyApp.CircleShape", "Radius": 2.5, "Label": "主圆" },
  { "$type": "MyApp.RectShape", "Width": 3, "Height": 4, "Label": "横幅" }
]
```

> 限制：集合容器类型不保真（`IList<T>` 等接口声明还原为 `List<T>`，元素类型完整保真）；含 `$type` 的嵌套对象需可无参构造；属性图循环引用不支持。

### 不序列化的属性

需要排除的属性（运行时缓存、敏感数据、自行持久化）加特性即可：

```csharp
[NotSerialized] public string Password { get; set; }   // 不随图保存/恢复
public int Timeout { get; set; }                        // 正常保存
```

### 执行会话资源释放

节点创建的 IDisposable 资源（流、连接、位图）若需"随本轮图执行结束释放"，注册到执行会话即可：

```csharp
protected override Task ExecuteAsync()
{
    var stream = new FileStream(...);
    Scope?.Track(stream);   // 图执行结束（含失败/取消）后框架统一 Dispose
    _output.SetValue(stream);
    return Task.CompletedTask;
}
```

每轮执行独立会话；块内部图为独立会话；未 Track 的对象不受影响。

### 全局数据队列（生产者-消费者）

生产端持续生产数据、消费端逐条处理（如"生产块不断产出任务，消费块逐条执行"）时，用全局数据队列——内置「数据入队」「数据出队」节点（工具箱「流程」分类）：

```
生产块内：工具完成 → 数据入队"任务"（结果值进入队列缓冲，可连续生产多条）
消费块内：数据出队"任务" → 下游处理（每次取走一条；无数据时挂起等待）
生产/消费块无连线 → 并行运行，靠队列衔接
```

- 队列 = 名称（唯一）+ FIFO 缓冲；入队**不覆盖**、逐条排队，数据不会丢
- 出队**取走一条**（多消费者竞争时一条数据只给一个消费者）；取出值经 object 输出端口传给下游
- 出队无数据时等待时间可配（毫秒）：**-1 = 一直等待（默认）**，0 = 不等待，>0 = 最多等指定毫秒，超时报错"无数据取出，等待超时"；图取消时出队响应取消（标记"未运行"）
- 出队节点的队列名用**下拉选择**（候选自动包含所有层级的数据入队节点，防取出不存在的队列）
- 队列数据**跨轮保留**（不随图执行结束清空）；需要清空用 `DataQueueStore.Clear(name)` / `ClearAll()` 编程 API
- 注意：数据入队/出队是**运行期同步原语**（引入跨块外部状态），调试时优先检查队列名一致性与等待超时

## 扩展开发：创建你的第一个节点

按下面三步，一个自定义节点就能出现在工具箱、画布、属性面板与序列化中。

### 1. 定义节点（引擎层）

继承 `NodeBase`，用 `[Node]` 特性声明分类与工具箱显示名，构造中声明端口，执行时读写数据。
业务属性用 `SetProperty`（NodeBase 自带变更通知）——UI 可直接绑定，属性变化自动刷新：

```csharp
[Node("基础", "常量")]  // (分类, 工具箱显示名)
public class ConstantNode : NodeBase
{
    private readonly NodeOutput<int> _output;

    private int _value = 1;
    /// <summary>可编辑属性——自动被序列化保存/恢复；SetProperty 变更通知，可直接绑定 {Binding Subject.Value}</summary>
    public int Value { get => _value; set => SetProperty(ref _value, value); }

    public ConstantNode()
    {
        _output = AddOutput<int>("结果");  // 链式声明输出端口
    }

    protected override Task ExecuteAsync()
    {
        _output.SetValue(Value);           // 执行时把值写到输出端口
        return Task.CompletedTask;
    }

    public override INode Clone()          // 复制粘贴/剪贴板需要
    {
        var c = new ConstantNode { Value = Value };
        Comp.CopyTo(c.Comp);               // 复制端口结构
        return c;
    }
}
```

- 输入端口：`AddInput<int>("数值A")`，执行时 `input.GetValue()` 读取（已连接取上游值，未连接取手动值）
- **每个节点自带「运行」bool 输入端口**（默认 true）：连接到条件节点输出或手动设为 false，该节点即跳过执行（标记"未运行"，下游照常）——条件分支后无需再用节点块包装
- **每个节点自带「运行状态」int 输出端口**（引擎执行后写入：0=未运行、1=成功、2=失败）：接条件节点即可按"上游是否运行成功"分支（详见上文「按上游节点的运行结果分支」）。注意它与「运行」输入一样会出现在端口列表最前，按索引取端口的老代码建议改为按名取
- 更多参考：`TestConsole/TestNodes.cs` 中的 `MultiplyNode`（双输入）、`DelayNode`（异步 + 取消）、`FaultNode`（失败示例）

**方式二：组合 + 源生成器**——不继承 `NodeBase`，直接实现 `INode`，用特性字段声明端口，样板代码编译期自动生成：

```csharp
[Node("基础", "加法")]
public partial class AddNode : INode   // 组合方式必须 partial
{
    [NodeInput("数值A")] private NodeInput<int> _a = null!;
    [NodeInput("数值B")] private NodeInput<int> _b = null!;
    [NodeOutput("和")]   private NodeOutput<int> _sum = null!;

    public int Offset { get; set; }    // 普通属性照常自动序列化

    // 业务逻辑自己写（生成器不生成 ExecuteAsync 与 Clone）
    public Task ExecuteAsync(CancellationToken cancellationToken = default)
    {
        _sum.SetValue(_a.GetValue() + _b.GetValue() + Offset);
        return Task.CompletedTask;
    }

    public INode Clone()
    {
        var c = new AddNode { Offset = Offset };
        Comp.CopyTo(c.Comp);
        return c;
    }
}
```

生成器自动补齐：`Comp` 字段、构造器（调 `InitNode()` 接线端口）、`INode` 的全部状态/端口委托成员。注意：`[NodeInput]`/`[NodeOutput]` **只对字段生效**（标在属性上不触发生成）；通过 NuGet 引用时自动生效，同解决方案项目引用需额外加 `OutputItemType="Analyzer"` 的分析器引用。详见 NodeStudio README「组合源生成器」。

### 2. 创建节点 ViewModel（推荐）

ViewModel 包装节点实例，只做命令与交互相关职责——**节点属性无需在 ViewModel 重复转发**：
节点属性用 `SetProperty`（见第 1 步）后，操作控件 XAML 直接绑定 `{Binding Subject.Value}`（`Subject` 即节点实例，属性变化自动刷新 UI）：

```csharp
[NodeViewModel(typeof(ConstantNode))]   // 标注映射：拖拽/导入时框架自动发现，无需手动注册
public class ConstantNodeViewModel : NodeViewModel
{
    // 新建节点
    public ConstantNodeViewModel(string name)
    {
        Subject = new ConstantNode { Name = name };
        Init();
    }

    // 包装已有实例（图反序列化恢复时使用）
    public ConstantNodeViewModel(ConstantNode node)
    {
        Subject = node;
        Init();
    }

    // 业务属性不在这里转发——操作控件直接 {Binding Subject.Value}；
    // ViewModel 用来放命令、下拉候选等交互逻辑（旧转发模式仍然可用）
}
```

**反序列化完成钩子**：图导入时节点属性/端口全部还原后，框架调用 ViewModel 的 `OnDeserialized()`——需要"还原后初始化"（重算派生字段、同步外部资源等）重写它即可；重写 `Init()` 做不到这件事，它在构造时、属性还原**之前**调用：

```csharp
public override void OnDeserialized()
{
    var node = (ConstantNode)Subject;   // 保存的属性/端口手动值已全部还原（块内部子图随递归各自触发）
    // ... 自定义初始化；异常会被框架吞掉，不影响导入
}
```

### 3. 操作控件

想让节点被选中时在右侧属性面板显示可编辑界面，继承 `NodeBaseControl`，用 XAML 搭界面（自动带标题、描述与运行状态三行布局）：

```xml
<!-- ConstantNodeControl.xaml -->
<ctrl:NodeBaseControl x:Class="MyApp.ConstantNodeControl"
                      xmlns:ctrl="clr-namespace:NodeStudio.Controls.Views;assembly=NodeStudio.Controls">
    <TextBox Text="{Binding Value, UpdateSourceTrigger=PropertyChanged}"/>
</ctrl:NodeBaseControl>
```

```csharp
public class ConstantNodeControl : NodeBaseControl
{
    public ConstantNodeControl(ConstantNodeViewModel node) : base(node) => InitializeComponent();
}

// ViewModel 中返回操作控件：
public override Control GetControl() => new ConstantNodeControl(this);
```

### 4. ViewModel 注册（通常零注册——特性自动发现）

第 2 步示例中的 `[NodeViewModel(typeof(ConstantNode))]` 标注完成后，**无需任何注册代码**：拖拽创建、复制粘贴、JSON 导入时，框架发现节点没有内置分支且未注册工厂，会自动扫描已加载程序集找到该映射，并以"包装传入节点实例"的方式创建 ViewModel（属性面板与参数不丢失）。

仅两种情况需要显式调用：

```csharp
// ① 插件宿主：插件程序集是延迟加载的，加载完成后一键注册
NodeViewModelFactory.RegisterFromAssemblies(pluginAssembly);
// 或不传参：扫描当前已加载的全部程序集
NodeViewModelFactory.RegisterFromAssemblies();

// ② 特殊场景（依赖注入、非标准构造函数等）：lambda 显式注册，优先级最高
NodeViewModelFactory.RegisterVmFactory<ConstantNode>(node => new ConstantNodeViewModel((ConstantNode)node));
```

> 优先级：`RegisterVmFactory` 显式注册 > `[NodeViewModel]` 自动发现（已注册的映射不会被扫描覆盖）> 内置节点硬编码分支 > `GenericNodeViewModel`（无操作界面）。

> 完成以上步骤后，程序集自动扫描会把它加入工具箱——无需额外注册。

## 代码驱动：自定义你的界面

图编辑器只是框架的默认界面——**整套引擎与 ViewModel 都可以用代码驱动**，你完全可以只取所需（如把节点图嵌在自己的窗口里、用按钮/菜单代替画布操作，甚至不引用编辑器控件、只跑引擎）。

### 1. 纯引擎（仅引用 NodeStudio，无任何 UI）

搭图、连线、设值、运行、取结果：

```csharp
using NodeStudio.Core;
using NodeStudio.Nodes;

var graph = new NodeGraph();

// 1) 创建节点并配置（以内置计算/条件节点为例；自定义节点同样用构造函数 + 属性）
var calc = new CalculationNode { Name = "加10" };
calc.AddInputPort("数值A", typeof(int));
calc.AddCalc("结果", "[数值A] + 10", typeof(int));

var cond = new ConditionNode { Name = "是否达标" };
cond.AddInputPort("状态");
cond.AddCondition("通过", "[状态] >= 10");

var consumer = new DelayNode { Name = "达标后执行", DelayMs = 100 };

// 2) 加入图并连线（按节点 + 端口名；内置「运行」/「运行状态」端口也是普通端口）
graph.AddNode(calc);
graph.AddNode(cond);
graph.AddNode(consumer);
graph.Connect(calc, "运行状态", cond, "状态");        // int：0=未运行 1=成功 2=失败
graph.Connect(cond, "通过", consumer, NodeBase.RunPortName); // bool：控制下游是否执行

// 3) 设置节点参数与输入值（未连接端口的"手动值"）
calc.Inputs.First(i => i.Name == "数值A").SetValue(5);
consumer.State = NodeState.Enabled;                  // 启用/禁用节点

// 4) 运行（并行 DAG 调度）与停止
using var cts = new CancellationTokenSource();
var runTask = graph.ExecuteAsync(cts.Token);
// ……需要中途停止时：cts.Cancel();（已启动节点响应取消，未启动节点不再启动）
var result = await runTask;

// 5) 读取结果（图级 + 节点级 + 端口值）
Console.WriteLine(result.IsAllSuccess ? "全部成功" : $"失败节点：{string.Join(",", result.FailedNodeNames)}");
Console.WriteLine($"计算输出 = {calc.Outputs.First(o => o.Name == "结果").GetValue()}");
Console.WriteLine($"条件节点状态 = {cond.RunStatus}（NotRun/Success/Failed）");
```

- **顺序执行**：`await graph.ExecuteSequentialAsync(cts.Token)`（按拓扑序逐个运行，便于调试）；
- **单节点运行**：`await graph.ExecuteNodeAsync(node, cts.Token)`（不重置输入，语义见右键「运行」）；
- **按 Id 获取节点**：`graph.GetNode(nodeId)`；
- **输出值变化事件**：`node.Outputs.First(o => o.Name == "结果").ValueChanged += (s, e) => 刷新你的界面(...);`（每次 `SetValue` 触发——自定义 UI 的数据源）；
- **全局队列编程 API**：`DataQueueStore.Enqueue/DequeueAsync/Count/Clear/ClearAll`（与数据入队/出队节点共用）；
- 停止语义：`cts.Cancel()` 后引擎不再启动新节点，正在等待的节点响应取消（标记"未运行"），`ExecuteAsync` 正常返回当轮 `GraphResult`。

### 2. 编辑器协同（引用 NodeStudio.Controls，界面中嵌入 NodeEditer）

`EditorViewModel` 是编辑器的 ViewModel——命令、集合与选择状态都可以从代码驱动：

```csharp
var editor = new EditorViewModel();

// 1) 添加节点（CreateFromNode 由节点实例创建对应 ViewModel）并按名连线（链式调用）
var sourceVm = NodeViewModelFactory.CreateFromNode(new ConstantNode { Name = "常量", Value = 5 });
var calcVm = NodeViewModelFactory.CreateFromNode(new CalculationNode { Name = "计算1" });
calcVm.AddCalc("结果", "[数值A] * 2", typeof(int));
editor.AddNode(sourceVm);
editor.AddNode(calcVm);
editor.Connect(sourceVm, "结果", calcVm, "数值A");

// 2) 运行 / 暂停（取消本轮）/ 连续运行 / 停止连续运行（命令由 CommunityToolkit 生成）
await editor.ExecuteCommand.ExecuteAsync(null);   // 运行一轮（异步）
editor.PauseCommand.Execute(null);                // 运行中取消本轮
editor.LoopRunCommand.Execute(null);              // 连续运行
editor.StopLoopRunCommand.Execute(null);          // 停止连续运行（当前轮结束后退出）

// 3) 获取节点、读写参数（Subject 即节点实例，可强类型操作）
var nodeVm = editor.Nodes.First(n => n.Title == "计算1");
var calc = (CalculationNode)nodeVm.Subject;
calc.SetCalcExpression("结果", "[数值A] * 3");     // 修改参数（属性面板与表达式校验同步）
nodeVm.Update();                                   // 刷新画布与面板显示（含端口值）

// 4) 读取运行后的输出值 / 运行状态
var value = calc.Outputs.First(o => o.Name == "结果").GetValue();
var status = nodeVm.Subject.RunStatus;             // NotRun / Success / Failed

// 5) 序列化与恢复（JSON，含节点参数/连线/块内部子图）
var json = NodeStudio.Controls.Serialization.GraphSerializer.Serialize(editor);
var restored = NodeStudio.Controls.Serialization.GraphSerializer.Deserialize(json);
```

- **选择与批量操作**：`editor.SelectedNodes`（多选集合）、`CopySelectedNodes()` / `PasteClipboard(位置)`、`DeleteSelectedNodesCommand`（一次性确认删除）；
- **块内编辑器**：`NodeBlockViewModel.InnerEditor` 与外层是同一套 `EditorViewModel` API（`Root` 指向全局根）；
- **嵌入窗口**：`<ns:NodeEditer DataContext="{Binding Editor}" PanelRatio="0.4"/>`（`PanelRatio` 设置右侧操作面板默认占宽，拖动分隔条仍可微调）；
- 与编辑器运行互斥：命令的 `CanExecute` 已处理运行锁与编辑锁（如运行中禁止粘贴/删除），自定义按钮绑定命令即可获得同样的保护。

> 数据持久化（`GraphSerializer`）位于 NodeStudio.Controls 包并基于 `EditorViewModel` 承载数据——纯引擎场景如需存档，可自行以 JSON 记录节点配置与连线，或引入 Controls 用编辑器 ViewModel 承载。

## 许可证

[MIT](LICENSE.txt)