别来无恙的 C# 上位机 AI 实战站

Appearance

操作员界面与维护诊断分层 ​

内容类型：UI / 诊断设计方法难度：进阶适合：实验室测试软件、设备控制平台、产线工装、长期运行上位机阅读时间：约 10 分钟

一套上位机软件经常同时面对两类人：

  • 操作员 / 测试人员：关心设备能不能用、当前在做什么、出了什么事、下一步怎么办；
  • 维护 / 调试人员：关心哪条命令失败、错误码是什么、协议返回了什么、线程和状态在哪一步异常。

把两类信息全部堆在一个界面上，软件会越来越像开发调试器；只保留“通信失败”这种一句话，又会让现场问题无法定位。

V10 的目标是：操作层简洁明确，诊断层证据完整。

1. 两层信息模型 ​

OperatorSummary ​

面向操作员，特点是：

  • 中文短句；
  • 先说结果；
  • 说明当前状态；
  • 告诉用户下一步能做什么；
  • 不要求理解协议、寄存器、异常类型和内部模块名。

例如：

text
设备连接失败，请检查网线和设备电源后重试。
text
示波器未准备完成，本次采集未开始。请确认设备状态后重新自检。

DiagnosticDetail ​

面向维护人员，保留：

  • SCPI / Modbus / 自定义协议原文；
  • TX/RX 原始数据；
  • 错误码、寄存器、状态字；
  • 设备错误队列；
  • 异常类型和堆栈；
  • request/session/通道信息；
  • 时间戳、超时和重试次数；
  • 关键状态机位置。

例如：

text
2026-08-25 14:31:22.184 [Scope] READ_RAW failed
Command=:WAV:DATA?
Session=scope-1
Timeout=3000ms
Error=-410 Query INTERRUPTED
State=StopWindow.RawRecovery

这两层不是互相替代，而是同一个事件的两种表达。

2. 一条异常应该怎样从底层走到界面 ​

推荐思路：

text
底层异常 / 设备返回
        ↓
DiagnosticDetail
        ↓
业务语义判断
        ↓
Event Consequence
        ↓
OperatorSummary
        ↓
界面状态 / 弹窗 / 状态栏 / 日志

中间必须先经过“业务语义判断”。

例如同样是磁盘空间低：

text
底层事实: D: 剩余 4.7 GB
业务分类: Advisory
操作员显示: 磁盘空间不足 5 GB，建议清理后继续。是否继续测试？
维护诊断: drive=D:\ free=4.7GB threshold=5GB check=PreStart

不要因为底层返回了 error，就自动把事件升级成 InterlockFault。

3. 操作员真正需要看到的 5 类信息 ​

3.1 设备身份 ​

操作员应该知道：

  • 这是哪台设备；
  • 当前连接的是哪个实例；
  • 是否在线；
  • 是否被占用；
  • 是否允许操作。

比“进程 PID 18240 已启动”更有价值的是：

text
高压电源 1    在线    可控制
示波器 1      在线    采集中
信号源 1      离线    重新连接

3.2 当前业务状态 ​

状态应使用操作语义：

text
待机
自检中
准备就绪
测试中
停止中
已完成
故障

不要直接把内部枚举、线程状态或通信状态原样暴露给操作员。

3.3 关键结果 ​

操作员需要看到：

  • 当前值；
  • 目标值；
  • 是否达标；
  • 当前步骤；
  • 剩余时间；
  • 结果是否有效。

不是所有原始采样、寄存器和协议字段都应该常驻主界面。

3.4 异常后果 ​

异常信息必须让人知道“现在还能不能继续”。

建议与事件后果一致：

类型操作员感知
Information状态提示，不打断
Advisory需要注意或确认，但可以继续
AlarmOnly明确报警并记录，流程继续
InterlockFault明确说明流程已停止/被阻断

详见 行为与告警语义。

3.5 下一步动作 ​

好提示不是：

text
CommunicationException

而是：

text
设备连接已中断，当前测试已暂停。
请检查设备连接后点击“重新连接”。

如果软件不能自动恢复，也要说清楚用户能做什么。

4. 主界面、详细信息和日志怎么分工 ​

建议三层：

text
主界面
→ 当前状态 + 关键数据 + 高频操作 + 重要异常

详细信息 / 维护页
→ 设备参数 + 连接详情 + 错误码 + 当前模式 + 诊断状态

日志 / 导出证据
→ 原始命令 + 原始响应 + 时间线 + 堆栈 + 完整上下文

主界面不是“信息越少越高级”，而是只放对当前操作决策有用的信息。

详细信息页也不是“把所有变量 dump 出来”，而是保留维护人员真正能用来定位问题的证据。

5. 中英文和设备原文怎么处理 ​

常见错误是：

text
设备通信失败 Communication failed

如果两句意思完全重复，操作员层只需要：

text
设备通信失败，请检查连接后重试。

而底层原文：

text
SocketException: Connection reset by peer

保留在 DiagnosticDetail 或日志中。

什么时候应该保留英文原文 ​

  • 设备厂商错误文本本身有诊断价值；
  • 错误码需要和手册对应；
  • SCPI / API 原文是定位依据；
  • 翻译可能丢失技术含义。

这时不是把英文塞进主弹窗，而是在“详细信息”中可查看。

6. 一条消息的推荐结构 ​

yaml
EventId: ScopeConnectionLost
Severity: AlarmOnly

OperatorSummary:
  Title: 示波器连接中断
  Message: 当前采集已停止，请检查网线和设备状态后重新连接。
  NextAction: 重新连接

DiagnosticDetail:
  Device: DHO900-1
  Endpoint: 192.168.1.20:5555
  Exception: SocketException
  RawMessage: Connection reset by peer
  WorkflowState: Acquiring
  Timestamp: 2026-08-25T14:31:22.184+08:00

不要求项目必须真的使用这个类或结构；它表达的是信息边界。

7. 什么时候要弹窗，什么时候只放状态栏 ​

适合弹窗 / 强提示 ​

  • 需要用户做决定；
  • 当前操作无法继续；
  • 危险操作需要确认；
  • 用户必须知道状态已经发生重大变化。

适合状态栏 / 非阻塞提示 ​

  • 自动恢复成功；
  • 信息性状态变化；
  • 不影响当前流程的提醒；
  • 高频但无需人工处理的状态。

不适合不停弹窗 ​

  • 设备轮询每秒失败一次；
  • 同一个故障持续存在；
  • 后台正在自动重连；
  • 已经有持续状态指示。

高频异常应该聚合和去重，否则操作员只能不停点“确定”。

8. 报警去重、节流和恢复提示 ​

长时间运行设备常见：同一个故障每个轮询周期都产生一条消息。

需要区分：

text
FaultEnter
FaultStillActive
FaultRecovered

操作员可能只需要：

text
14:31 示波器连接中断
14:31 自动重连中…
14:32 示波器连接已恢复

诊断日志仍然可以记录每次底层尝试。

不要为了“日志完整”让主界面每秒刷几十条重复错误。

9. 状态颜色不能代替文字 ​

工业界面不要只靠红/黄/绿：

text
● 在线
● 报警
● 故障

颜色用于加速识别，文字负责明确语义。

尤其要区分：

  • 离线；
  • 未配置；
  • 连接中；
  • 被占用；
  • 报警但可继续；
  • 故障已阻断。

它们不应该都只是“红色”。

10. 面向实验人员，不要暴露开发者概念 ​

主界面通常不需要显示：

  • PID；
  • 线程 ID；
  • 类名；
  • 方法名；
  • DLL 名；
  • 内部服务名；
  • “进程启动成功”；
  • “Task 状态 = RanToCompletion”。

除非这些内容对现场维护确实有价值，否则放到诊断页或日志。

对操作员更有用的是：

text
设备已连接
自检通过
测试进行中
数据保存正常
示波器离线
高压电源故障，测试已停止

11. AI 修改提示语时不要自动造抽象 ​

单个页面一句文案改错：

text
直接 MicroPatch

不要为了“一致性”马上创建新的 MessageFormatter、ErrorPresenter、ResourceManager 层。

只有同一类格式问题已经在两个以上入口重复出现，而且确实需要统一行为，才考虑抽取公共 Formatter / Mapping。

这能避免一个小文案修改变成半天重构。

12. Review 清单 ​

改操作员提示或诊断信息时检查：

  • 操作员是否知道发生了什么；
  • 是否知道流程当前还能不能继续；
  • 是否知道下一步能做什么；
  • 中文是否足够清晰；
  • DiagnosticDetail 是否保留底层证据；
  • 错误码、单位、时间戳是否可追踪；
  • 同一故障是否重复轰炸 UI；
  • 恢复后是否有明确状态；
  • AlarmOnly 是否被误实现成 Stop；
  • Information / Advisory 是否变成新的启动门禁；
  • 单点文案是否引入了不必要的新抽象。

13. 可直接复制的 Prompt ​

text
$host-computer-dev
请检查这次上位机提示/异常显示是否正确分层。

目标用户：
【操作员 / 测试人员 / 调试工程师 / 维护人员】

当前提示：
【填写】

实际底层证据：
【异常、错误码、协议原文、日志】

请分别给出：
1. OperatorSummary：简短中文，说明结果、当前后果和下一步动作；
2. DiagnosticDetail：保留定位问题需要的原始技术证据；
3. 这条事件属于 Information / Advisory / AlarmOnly / InterlockFault 哪一种；
4. 是否需要弹窗、状态栏、日志，还是组合展示；
5. 是否需要去重/节流/恢复提示。

如果只是单点文案问题，按 MicroPatch 修改，不要新建公共格式化架构。

下一步 ​

一句话原则 ​

操作员看“发生了什么、还能不能继续、下一步怎么办”；维护人员看“为什么发生、底层证据是什么”。两层都要有，但不要混在一起。

别来无恙 · C# 上位机 AI 实战站 · 从零到交付 · QQ 群：1016188499

内容用于工程学习与经验交流，设备结果与交付风险仍需人工确认。