排错

遇到问题时先不要急着改代码。按这个顺序定位：安装能不能编译、宿主有没有启动、通道有没有打开、协议有没有回包、点表有没有值、界面有没有正确绑定。

先做三步快速判断

channel.DataReceived += (_, e) =>
{
    Console.WriteLine(Convert.ToHexString(e.Data.Span));
};

现象	最可能原因	处理
`dotnet` 命令不存在	没装 .NET SDK，或 PATH 未刷新	安装 .NET 8 SDK，重新打开终端
找不到 Zeus 预览包	没加 `--prerelease`	`dotnet add package Zeus.Communications --prerelease`
找不到 `AddVirtualChannel`	没引用 `Zeus.Communications`	安装或引用通信包
找不到 `AttachZeus`	没引用 UI 适配器	WinForms 引 `Zeus.Presentation.WinForms`，WPF 引 `Zeus.Presentation.Wpf`
WinForms / WPF 包还原失败	目标框架不是 Windows 桌面	改成 `net8.0-windows`

现象	最可能原因	处理
`找不到名为 xxx 的通道`	`Channels.Get` 的名称和注册名称不一致	看异常里列出的已注册通道名
`通道名称已存在`	注册了两个同名通道	改名，例如 `meterBus`、`plcBus`
`当前为 Created，无法写入`	还没调用 `StartAsync`	先启动宿主
关闭程序后端口仍被占用	宿主没释放	使用 `await using`，或让 `AttachZeus` 管理窗口生命周期

现象	最可能原因	处理
一直超时	从站地址、波特率、RTU/TCP 类型不对	先用 `ModbusSlaveResponder` 验证主站逻辑
`非法数据地址`	地址偏移或数量不对	检查 40001 是否要写成地址 0
CRC 失败	串口参数不一致或线路干扰	核对 9600/8N1/校验位，缩短线缆测试
事务号不匹配	同一 TCP 通道并发多路请求	串行请求，或为不同任务拆通道
读到的值比例不对	少了比例换算	在点表中使用 `scale` 或 `raw => raw * 0.1`

现象	最可能原因	处理
找不到配置文件	工作目录不对，或文件没复制到输出目录	看异常中的绝对路径，设置 `CopyToOutputDirectory`
`channel 未在 channels 中声明`	设备引用了不存在的通道	先声明通道，再声明设备
改了 COM 口但没生效	通道配置不热更新	重启程序
改了采集间隔但没生效	JSON 语法错误或没有监视文件	看日志，确认 `watch: true`

现象	最可能原因	处理
控件跨线程异常	直接在 `DataReceived` 中改 UI	使用 `BindTo` / `BindState` / `AttachZeus`
界面状态不刷新	没绑定状态，或绑定发生太晚	在构造函数里调用 `BindState`
关闭窗口后仍在采集	宿主没跟窗口生命周期绑定	使用 `this.AttachZeus(...)`
点击发送失败	通道还没打开	看状态 Label 是否为 `Open`

请准备这些信息再继续查：