41 KiB

Raw Blame History

Windows Node Host 与 WPF 重构方案

状态：阶段 0–7 已落地，进入阶段 8 发布准备日期：2026-08-31 适用范围：windows-node/Zcbot.WindowsNode 及其测试、打包与运行文档

1. 背景

当前 Windows Node 已完成托盘常驻、节点注册、WebSocket 连接、任务持久化与恢复、Adapter 发现与执行、Workspace 管理、专业软件配置、受管 runtime 安装、本机任务查看、数据目录迁移和 ANSYS 真机验收。它已经从一个简单的内网托盘 MVP 演进为专业软件任务的稳定宿主。

当前实现仍是单个 .NET 10 WinForms WinExe，后台协议与执行能力总体边界正确，但 UI 和 Host 内部职责开始集中：

ConfigurationForm.cs 约 1300 行，布局、状态、软件管理、任务展示、数据迁移和 ANSYS 验收混在同一窗口类中。
TrayApplicationContext.cs 同时管理托盘、窗口、注册、连接、重连、迁移和安全退出。
NodeConnectionLoop.cs 同时承担 WebSocket 会话、心跳、消息解析、任务编排、恢复、取消与终态回报。
JobInboxStore.cs 同时承担协议接单、磁盘持久化、状态流转、恢复扫描和 UI 展示读取。
SoftwareRuntimeManager.cs 以大体量静态类同时承担软件定义、位置存储、探测、环境注入和 runtime 安装。
注册、下载和上传分别管理 HTTP 客户端，网络错误分类、重试和认证注入缺少统一边界。
现有 Windows Node 测试中有较多源码字符串断言，能够保护若干安全约束，但难以验证真实状态转换和异步生命周期。

本次重构同时处理两个问题：

将 WinForms 主窗口迁移为 WPF，使用 XAML、数据绑定和 MVVM 组织界面。
将 Node Host 重构为可测试、可组合、与 UI 无关的长期宿主架构。

本次不是服务端协议重写，也不是 Adapter 架构替换。

2. 目标

2.1 用户与运维目标

保持现有节点身份、数据目录、任务、Workspace 和 runtime 原位兼容。
保持解压发布包后直接运行的部署方式。
保持同一 EXE 的托盘、enroll 和 run --headless 三种入口。
提升 125%、150% 和 200% DPI 下的布局稳定性。
让节点状态、软件状态、任务状态和长时间操作在界面中保持一致。
让新增专业软件主要落在 Adapter 和软件定义，不再扩张单个巨型窗口。
在出现连接、传输、Worker 或恢复故障时提供可定位但不泄露 Token 的本机诊断。

2.2 工程目标

建立唯一 Composition Root，GUI 与 headless 共用同一套 Host 组装。
将 UI、应用编排、领域状态、协议传输和基础设施分层。
以明确的 Host 生命周期替代托盘类直接管理连接任务。
以明确的 Job 状态机约束接单、下载、执行、上传、取消和恢复。
统一 HTTP、WebSocket、认证、错误分类和传输重试边界。
统一 Adapter 目录发现、合同加载、软件 probe 和进程监督边界。
对纯逻辑和关键异步流程增加 .NET 行为测试，减少脆弱的源码字符串测试。
每个实施阶段都可构建、可打包、可验收和可回退。

3. 非目标

以下事项不随本轮重构进入实现：

不改服务端 HTTP/WebSocket URL、消息类型、字段语义或认证方式。
不改 node.json、jobs/、workspaces/、runtimes/ 的对外文件布局。
不清理、重置或隐式迁移已有节点数据。
不改 Adapter 的 adapter.json + contract + worker + job directory 协议。
不引入 Python GUI、Electron、WebView 或 WinUI 3。
不安装 Windows Service，不拆 Service/DesktopRunner 双进程。
不增加自动更新平台、插件市场或在线 Adapter 覆盖。
不增加多 Job 并行或 per-capability slot；继续保持整机单执行槽。
不把 Adapter probe、软件语义或具体软件分支移入通用 Host。
不在框架迁移时同时进行大规模视觉重设计。

4. 必须保持的兼容契约

契约	重构后要求
可执行文件	仍为 `Zcbot.WindowsNode.exe`
GUI 启动	无参数启动托盘；未注册时显示主窗口，已注册时后台连接
CLI	`enroll` 参数、输出标签和退出码不变
Headless	`run --headless` 不初始化 WPF、窗口或托盘
单实例	继续使用 `Local\\Zcbot.WindowsNode` Mutex
节点身份	继续读取现有 DPAPI `LocalMachine` 加密 Token
注册表	数据根目录、软件位置和当前账号 Run 项键名不变
数据目录	默认值、环境变量优先级和旧 `%ProgramData%` 兼容不变
Job	已落盘任务可由新版继续恢复、取消、上传和回报终态
Workspace	`current`、`rollback` 和 head Job 语义不变
Adapter	继续从 EXE 同级 `adapters/*/adapter.json` 发现
发布	完整包和独立 Adapter 包的目录结构不变
服务端	无 DB migration、无 API 变化、无部署联动要求

任何需要改变以上契约的实现发现都必须暂停，单独形成兼容设计，不得借重构直接修改。

5. 总体架构

flowchart TD
    Entry["Program / Composition Root"]
    Tray["TrayHost"]
    Wpf["WPF Views"]
    VM["ViewModels"]
    App["Application Services"]
    Host["NodeHost"]
    Session["NodeSession"]
    Jobs["JobCoordinator"]
    Transfers["TransferClient"]
    Adapters["AdapterCatalog / AdapterExecutor"]
    Persistence["Config / Job / Workspace Repositories"]
    Runtime["SoftwareRuntimeService"]
    Server["zcbot HTTP / WebSocket"]
    Workers["Python or EXE Workers"]
    Disk["Existing data root"]

    Entry --> Tray
    Entry --> Host
    Tray --> Wpf
    Wpf --> VM
    VM --> App
    Tray --> App
    App --> Host
    Host --> Session
    Host --> Jobs
    Jobs --> Transfers
    Jobs --> Adapters
    Jobs --> Persistence
    App --> Runtime
    Session --> Server
    Transfers --> Server
    Adapters --> Workers
    Persistence --> Disk
    Runtime --> Disk

5.1 分层规则

Presentation

包含 WPF View、ViewModel、托盘和对话框适配器。

可以引用 Application。
不直接引用 ClientWebSocket、HttpClient、Registry、文件系统或进程。
XAML code-behind 只处理纯 View 行为，例如 PasswordBox 取值、窗口拖动和焦点。
不在 MainWindow.xaml.cs 中编排节点业务。

Application

包含用户操作和宿主生命周期的用例编排。

注册、重连、清除身份、迁移数据目录、安全退出。
软件位置变更、runtime 安装和固定验收。
组合领域结果为不可变 UI Snapshot。
不依赖 WPF 或 WinForms 类型。

Host / Domain

包含节点会话、Job 状态机、单槽执行、恢复和 Adapter 抽象。

不感知托盘、窗口、按钮或对话框。
不通过任意字符串隐式改变 Job 状态。
关键状态转换经过统一校验和持久化。

Infrastructure

包含 HTTP、WebSocket、JSON、DPAPI、Registry、文件、进程和软件探测实现。

向上提供明确的小接口或服务，不把 Win32/IO 类型扩散到 ViewModel。
原子写、路径约束、日志脱敏和进程树终止在此集中实现。

6. 目标项目结构

第一轮保持单一 Zcbot.WindowsNode.csproj，先形成目录和命名空间边界，避免同时承担程序集拆分、internal 可见性和发布路径变化。完成后再依据依赖图决定是否拆出测试友好的 Core 项目。

Zcbot.WindowsNode/
├── Program.cs
├── App.xaml
├── App.xaml.cs
│
├── Bootstrap/
│   ├── NodeCompositionRoot.cs
│   ├── NodeCommandLine.cs
│   └── SingleInstanceGuard.cs
│
├── Application/
│   ├── NodeApplicationController.cs
│   ├── NodeApplicationSnapshot.cs
│   ├── NodeShutdownDecision.cs
│   ├── DiagnosticService.cs
│   ├── JobMonitorService.cs
│   ├── SoftwareManagementService.cs
│   └── AnsysAcceptanceService.cs
│
├── Host/
│   ├── NodeHost.cs
│   ├── NodeHostSnapshot.cs
│   ├── NodeSession.cs
│   ├── NodeSessionState.cs
│   └── NodeEvent.cs
│
├── Protocol/
│   ├── NodeProtocolClient.cs
│   ├── NodeProtocolCodec.cs
│   ├── ServerMessage.cs
│   ├── NodeMessage.cs
│   └── NodeProtocolException.cs
│
├── Jobs/
│   ├── JobCoordinator.cs
│   ├── JobExecutionGate.cs
│   ├── JobStateMachine.cs
│   ├── JobRepository.cs
│   ├── JobRecoveryService.cs
│   └── JobSnapshot.cs
│
├── Transfers/
│   ├── NodeHttpClient.cs
│   ├── JobInputTransfer.cs
│   ├── JobOutputTransfer.cs
│   └── TransferRetryPolicy.cs
│
├── Adapters/
│   ├── AdapterCatalog.cs
│   ├── AdapterDescriptor.cs
│   ├── AdapterContractLoader.cs
│   ├── AdapterExecutionService.cs
│   └── ProcessSupervisor.cs
│
├── Workspaces/
│   ├── WorkspaceRepository.cs
│   └── WorkspacePromotionService.cs
│
├── Runtime/
│   ├── SoftwareCatalog.cs
│   ├── SoftwareLocationService.cs
│   ├── SoftwareProbeService.cs
│   └── ManagedRuntimeInstaller.cs
│
├── Persistence/
│   ├── NodeConfigStore.cs
│   ├── NodeDataRootService.cs
│   ├── AtomicFile.cs
│   ├── PathGuard.cs
│   └── RotatingNodeLog.cs
│
├── Presentation/
│   ├── Tray/
│   ├── ViewModels/
│   ├── Views/
│   ├── Commands/
│   ├── Converters/
│   └── Themes/
│
└── Compatibility/
    └── persisted model readers retained only where required

目录是目标职责图，不要求通过一次机械移动完成；重构期间优先保证逻辑边界，最后再统一物理目录。

7. Host 核心设计

7.1 Composition Root

NodeCompositionRoot 是唯一对象组装入口：

解析一次数据根目录并生成 NodePaths。
创建唯一 NodeConfigStore、JobRepository、WorkspaceRepository 和 AdapterCatalog。
按当前节点配置创建共享 NodeHttpClient 和 NodeProtocolClient。
创建 JobCoordinator、NodeSession 和 NodeHost。
GUI 与 headless 只决定 Presentation 和生命周期宿主，不各自复制 Host 构造逻辑。

不引入通用依赖注入容器；当前规模使用显式构造函数组装更便于审计、打包和故障定位。

7.2 NodeHost 生命周期

NodeHost 对外只暴露少量稳定操作：

Task RunAsync(CancellationToken cancellationToken);
Task ReconnectAsync(CancellationToken cancellationToken);
Task<NodeShutdownResult> StopAsync(NodeShutdownMode mode, CancellationToken cancellationToken);
NodeHostSnapshot Current { get; }
event EventHandler<NodeHostSnapshot>? SnapshotChanged;

生命周期约束：

RunAsync 是结构化并发根，拥有会话、恢复、Job 和传输子任务。
所有子任务都可追溯到 Host CancellationToken，不允许 fire-and-forget Worker 管线。
重连先停止接收 offer，再等待本地任务和上传到达安全点，之后替换会话。
正常退出与取消任务退出使用同一 StopAsync，GUI 和 headless 不复制收尾逻辑。
StopAsync 幂等；重复点击退出或系统注销不会启动第二条取消链。
Snapshot 是不可变值，UI 只消费 Snapshot，不读取 Host 内部集合。

7.3 WebSocket 会话拆分

从 NodeConnectionLoop 提取：

NodeSession：连接、hello、心跳、接收循环和退避重连。
NodeProtocolCodec：JSON 消息的严格解析、类型分发和序列化。
NodeProtocolClient：并发安全发送和 WebSocket 关闭语义。
JobCoordinator：处理 offer、cancel 和导出等业务消息。

要求：

一个会话只拥有一个接收循环。
所有发送通过同一发送锁，避免并发 SendAsync。
认证拒绝、握手 HTTP 错误、网络中断和协议错误继续保持不同状态。
未知消息按现有兼容策略处理，不得把解析异常误报为身份失效。
心跳携带的能力、health、slot 和合同摘要来自同一个原子 Snapshot。

7.4 Job 状态机

新增 JobStateMachine 作为内部唯一状态转换入口，覆盖：

offered
  -> accepted
  -> downloading
  -> ready
  -> software_running
  -> promoting_workspace
  -> uploading_preview / uploading_output
  -> succeeded

任意可取消阶段 -> cancelling -> cancelled
任意执行阶段   -> failed
进程重启       -> recovered according to persisted markers

具体落盘字符串和 JSON 字段保持现状；状态机首先包裹现有格式，不强制迁移历史文件。

要求：

offer 仍然先持久化并 flush/原子替换，再回复 accept。
Job ID、lease ID 和 request digest 一致性校验保持不变。
终态不可逆；重复终态消息必须幂等。
单执行槽由本机 JobExecutionGate 再次强制，不只依赖云端 slot。
Workspace promotion、预览上传和显式导出分别建模，不能因上传重试重复执行专业软件。
进程重启恢复只依赖已落盘事实，不依赖 UI 内存状态。

7.5 Job 持久化拆分

将 JobInboxStore 拆为三个职责：

JobRepository：原子读写 Job、marker 和 terminal。
JobRecoveryService：启动扫描和恢复决策。
JobMonitorService：面向 UI 生成只读展示 Snapshot。

统一 AtomicFile：

同目录临时文件。
写入、flush、关闭后原子替换。
原文件存在时保持当前替换语义。
不用跨卷 rename。
临时文件命名不与 Worker 协议文件冲突。

统一 PathGuard：

所有 Job、Workspace、Adapter 和 runtime 派生路径必须归一化后验证仍位于预期根目录。
不把请求内文件名直接拼入本机路径。
保持合同内输出 ID 与实际文件 manifest 的现有校验。

7.6 传输层

创建每个已加载节点配置唯一的 NodeHttpClient：

统一 BaseAddress、Bearer Token、User-Agent、默认超时和错误摘要。
输入下载和输出上传复用连接池。
大文件继续流式传输，不整体读入内存。
重试只覆盖可安全重放的阶段，上传继续依赖服务端幂等校验。
认证失败不进入普通网络重试。
日志不记录 Authorization Header、Node Token、注册码或签名 URL 查询串。

JobInputTransfer 与 JobOutputTransfer 只负责传输；是否重试、何时回报终态由 JobCoordinator 决定。

7.7 Adapter 与进程监督

将当前 Adapter 发现和执行拆为：

AdapterCatalog：启动时一次发现、合同加载和描述符缓存。
AdapterContractLoader：manifest、合同路径、Schema 和 SHA-256 校验。
AdapterExecutionService：准备 Job 目录并调用固定 Adapter。
ProcessSupervisor：启动、标准流采集、超时、取消、完整进程树终止和退出确认。

安全边界保持：

Worker 入口必须来自已安装 manifest，不来自任务请求。
入口归一化后必须位于对应 Adapter 目录。
Python 解释器必须来自固定受管 runtime 解析。
请求不能注入命令行、环境变量、工作目录或本机路径。
进程退出后才读取 terminal；取消后必须等待完整进程树退出。
Host 不解析 Origin、ANSYS、Blender 业务语义。

7.8 Workspace

WorkspaceRepository 负责现有 metadata 和目录读取，WorkspacePromotionService 负责：

校验 source head。
在临时目录准备下一版。
成功后更新 rollback 和 current。
失败时保持旧 current 可继续使用。
只保留一份 rollback。

重构不得增加按 Job 永久保存工程副本，也不得在 Node 间搬迁 Workspace。

7.9 软件与 runtime 管理

将 SoftwareRuntimeManager 拆为：

SoftwareCatalog：固定的软件和 runtime 定义。
SoftwareLocationService：注册表配置、自动检测和版本来源。
SoftwareProbeService：通过 Adapter probe 汇总最终 health。
ManagedRuntimeInstaller：固定 requirements、临时目录安装、验证和原子替换。

要求：

软件卡继续按 runtime_id 归并多个 capability。
环境变量优先级和现有兼容名称不变。
runtime 有活动任务时继续拒绝替换。
安装命令、镜像地址和 requirements 不接受任务请求控制。
Origin 软件位置识别与 COM 健康继续分离。
ANSYS 执行门和固定验收继续由 Adapter/验收脚本给出事实结果。

8. WPF Presentation 设计

8.1 框架选择

继续使用 C# 和 .NET 10。
项目启用 WPF。
暂时保留 WinForms 引用，仅复用成熟的 NotifyIcon。
不引入第三方 MVVM 或主题框架；先使用小型 ObservableObject、RelayCommand、AsyncCommand 和资源字典。
首版使用浅色主题，颜色、字体、间距和控件状态全部抽为资源。

8.2 View 与 ViewModel

MainWindow
├── OverviewView / OverviewViewModel
├── SoftwareView / SoftwareViewModel
│   ├── SoftwareCardViewModel[]
│   └── AnsysAcceptanceViewModel
├── JobsView / JobsViewModel
└── SettingsView / SettingsViewModel

ViewModel 只接收 Application Service 和不可变 Snapshot；不直接 new Adapter Registry、Job Store 或路径对象。

8.3 状态绑定

以下状态由 Snapshot 或专用 ViewModel 字段统一驱动：

节点连接状态、颜色、说明和操作可用性。
注册卡是否显示。
软件位置、runtime、probe 和 capability 状态。
runtime 安装、验收和数据迁移进度。
Job 列表、选中项、详情和刷新状态。
退出期间全局操作禁用。

不允许同一状态同时由多个页面各自推断。

8.4 托盘与窗口生命周期

TrayHost 只处理：

创建和释放 NotifyIcon。
将 Host Snapshot 映射为图标、悬浮文本和菜单摘要。
打开、隐藏和激活 WPF 主窗口。
收集退出选择并调用 NodeApplicationController.StopAsync。

活动任务退出的三种选择、二次确认和等待提示保持现有语义。业务取消与进程收尾不在 TrayHost 内实现。

8.5 可访问性与 DPI

使用设备无关布局，不写依赖当前字体像素测量的固定页面宽度。
关键页面在 760×560 最小窗口和 100%–200% DPI 下可访问。
长路径、长错误和任务标题允许换行、截断并提供完整详情。
设置合理的 Tab 顺序、AccessKey、默认按钮和取消行为。
不仅使用颜色表达在线、警告和失败状态。
长时间操作必须有文本状态、进度反馈和可用时的取消入口。

9. 诊断与可观测性

在不引入远程日志平台的前提下，增加受控本机 Host 日志：

路径位于现有 data root 的 logs/。
使用 ASCII 级别标签：[INFO]、[WARN]、[ERR]。
单文件有明确大小上限并只保留有限轮转文件。
记录会话阶段、Job ID、capability、Adapter 版本、Worker PID、传输阶段和 HRESULT/异常类型。
不记录 Node Token、注册码、Authorization Header、完整签名 URL 或用户输入文件内容。
“复制诊断信息”继续输出可粘贴摘要，不默认复制完整日志。

NodeHostSnapshot 至少包含：

当前节点状态和状态变化时间。
当前会话 ID 或本地连接代次，不包含凭据。
活动 Job、当前阶段和开始时间。
待恢复/待上传数量。
Adapter 数量、能力摘要和最近 probe 时间。
data root 和版本信息。

10. 测试策略

10.1 Characterization 测试

重构前固定当前行为：

CLI 参数、stdout/stderr 标签和退出码。
未注册、在线、身份失效和普通断线状态差异。
offer 先落盘后 accept。
重复 Job digest 校验。
终态与上传重试幂等。
Workspace promotion 与 rollback。
活动任务退出的等待和取消路径。
数据目录迁移的停止、复制、校验和切换顺序。

10.2 .NET 单元测试

新增 Zcbot.WindowsNode.Tests，优先测试：

JobStateMachine 合法和非法转换。
NodeHost 启停、重复停止和重连屏障。
NodeProtocolCodec 消息分类及错误处理。
JobRecoveryService 对各持久化阶段的恢复决策。
TransferRetryPolicy 对认证、网络、服务端和取消错误的分类。
AdapterContractLoader 的路径、manifest、版本与合同校验。
ViewModel Snapshot 映射、Command 可用性和异步失败恢复。

测试使用临时目录和可控的 HTTP handler/协议替身；不连接 .env 中的数据库或生产服务。

10.3 集成测试

本地假 WebSocket 服务完成 hello、心跳、offer、cancel 和重连。
固定测试 Worker 验证启动、超时、取消和进程树回收。
临时 data root 验证重启恢复、原子写和 Workspace promotion。
framework-dependent 与 self-contained 两种发布包完成启动烟测。
发布包验证 Adapter、合同、验收资产和 requirements 完整。

10.4 UI 验收

未注册首次启动。
已注册后台启动和托盘显示。
托盘双击、窗口隐藏和恢复。
注册、重连、清身份和复制诊断。
软件自动检测、手选、清除和 runtime 安装。
ANSYS 固定验收、取消、通过报告和执行门。
本机任务刷新、选中详情和重启后恢复。
活动任务等待退出、取消退出和返回。
100%、125%、150%、200% DPI。

10.5 现有 Python 源码测试调整

保留适合静态审计的测试：

项目目标框架和发布参数。
不暴露任意执行原语。
Adapter 与合同是否完整打包。
Token 不以明文模型字段或日志字段出现。
独立 Adapter 包不依赖重建 Node。

将控件名称、WinForms 布局字符串、按钮宽度等断言替换为 .NET 行为测试或 WPF 结构测试，避免测试阻止内部文件拆分。

11. 实施阶段

阶段 0：基线与保护网

固化功能、协议、持久化和发布包基线。
增加关键生命周期 Characterization 测试。
记录真机 DPI 与托盘行为。
不改变生产行为。

完成门槛：现有 build、专项测试、打包和启动烟测全部通过。

阶段 1：Composition Root 与应用控制器

引入唯一 NodeCompositionRoot。
从托盘类提取注册、连接、重连、迁移和退出编排。
GUI 与 headless 共用 Host 构造路径。
WinForms 界面保持不变。

完成门槛：现有界面和 CLI 行为完全等价。

阶段 2：Job 持久化与状态机

提取 JobRepository、JobStateMachine 和 JobRecoveryService。
集中原子文件和路径约束。
保持现有落盘格式，验证新版能恢复旧 Job。
增加状态机和恢复测试。

完成门槛：旧 Job 样本可恢复，终态与 Workspace 不回退。

阶段 3：会话、协议与传输

拆分 NodeSession、NodeProtocolCodec 和 NodeProtocolClient。
引入共享 NodeHttpClient。
统一错误分类、认证注入和安全重试。
由 JobCoordinator 接管消息业务编排。

完成门槛：假服务端重连、offer、cancel、上传重试和身份拒绝测试通过。

阶段 4：Adapter、进程与 runtime

提取 AdapterCatalog、AdapterExecutionService 和 ProcessSupervisor。
拆分软件位置、probe 和 runtime 安装。
统一活动任务执行门和取消收尾。
不改 Adapter 文件或合同。

完成门槛：Origin、ANSYS、Blender 现有 probe、执行、取消和打包测试通过。

阶段 5：WPF Shell 与托盘

启用 WPF，建立 App、MainWindow、资源字典和 ViewModel 基础设施。
保留 WinForms NotifyIcon。
完成无参数 GUI、CLI 和 headless 启动分流。
先建立空页面与完整生命周期，不删除旧窗口。

完成门槛：单实例、后台启动、显示/隐藏和安全退出通过。

阶段 6：逐页迁移

按以下顺序迁移：

节点概览与首次注册。
运行设置与数据目录迁移。
专业软件卡和 runtime 管理。
ANSYS 固定验收。
本机任务列表和详情。

完成门槛：每一页迁移后均完成行为等价检查，不等待最后一次性验收。

阶段 7：移除 WinForms 主窗口与加固

删除 ConfigurationForm 和旧 TrayApplicationContext。
保留 NotifyIcon 所需的最小 WinForms 依赖。
清理重复状态、静态 Service Locator 和临时兼容代码。
完成本机结构化日志与诊断摘要。
完成全量专项测试和发布包真机烟测。

完成门槛：源码中没有第二套可达 UI 或重复 Host 生命周期。

阶段 8：文档与发布准备

架构落地后把稳定决策同步到根 DESIGN.md。
如运行方式、诊断路径或部署步骤有变化，同步 RUN.md 和 windows-node/README.md。
阶段性成果更新 PROGRESS.md。
WPF 稳定前不提升版本号，不创建已发布 Changelog 版本。
准备上线时再通过独立 release commit 更新版本和用户版 Changelog。

12. 建议提交拆分

每个提交只包含一个可验证的逻辑变化：

test(windows-node): characterize host lifecycle
refactor(windows-node): add shared composition root
refactor(windows-node): extract job state and persistence
refactor(windows-node): separate session and protocol handling
refactor(windows-node): unify job transfers
refactor(windows-node): extract adapter process supervision
refactor(windows-node): split software runtime services
feat(windows-node): add wpf shell and tray host
feat(windows-node): migrate overview and settings views
feat(windows-node): migrate software and acceptance views
feat(windows-node): migrate local job monitor
refactor(windows-node): remove legacy winforms window
test(windows-node): cover wpf and host integration
docs(windows-node): document host and wpf architecture

实施中可根据实际依赖合并相邻提交，但不得将 Host 重构、UI 视觉调整和发布版本提升混入同一提交。

13. 风险与控制

风险	控制措施
重连时重复启动任务	Host 统一拥有会话代次和单槽执行门
退出后残留 Worker	所有进程归 `ProcessSupervisor`，停止时等待完整树退出
上传重试导致重复执行	执行终态与传输状态分离，传输只重放幂等上传
后台线程更新 WPF 集合	Snapshot 在 Dispatcher 上映射到 ObservableCollection
新版无法恢复旧 Job	不改落盘字段，使用历史样本做恢复测试
数据迁移期间重新接单	Controller 先停调度并等待安全屏障，再执行迁移
runtime 安装覆盖活动环境	本机执行门检查活动 Job，临时安装验证后原子替换
Token 泄露到日志或 UI	集中认证客户端、脱敏器和诊断字段 allowlist
WPF 与 WinForms 类型冲突	WinForms 仅限 Tray 命名空间并使用完整类型名
重构范围失控	非目标列表和阶段完成门槛作为 review gate

14. 回退策略

整个改动在独立功能分支完成，WPF 稳定前不让线上用户接触。
每个阶段保持可构建，Host 抽取阶段继续由旧 WinForms UI 驱动。
WPF 迁移期间旧窗口可作为开发对照，但最终合并前必须只有一套可达 UI。
发布前保留上一版完整 Node 程序包；回退只替换程序目录，不修改 data root。
因持久化格式保持兼容，回退旧 EXE 后仍能读取原有身份、Job 和 Workspace。
若实施中确需新增持久化字段，必须做到旧版本忽略、新版本可缺省，且在本方案中补充独立兼容说明。

15. 完成定义

满足以下条件才视为重构完成：

WinForms ConfigurationForm 已移除，主界面全部使用 WPF。
WinForms 仅用于 NotifyIcon 或已明确记录的必要互操作。
GUI 和 headless 从同一个 Composition Root 获得 Node Host。
NodeConnectionLoop 的会话、协议和 Job 编排职责已拆分。
JobInboxStore 的持久化、恢复、状态机和 UI 展示职责已拆分。
SoftwareRuntimeManager 的定义、位置、probe 和安装职责已拆分。
关键 Host 生命周期和 Job 状态转换有真实 .NET 行为测试。
旧节点身份、历史 Job 和 Workspace 在新版测试样本中可继续使用。
Origin、ANSYS、Blender Adapter 无需修改即可运行。
framework-dependent 与 self-contained 发布包均通过构建和启动烟测。
真机托盘、DPI、runtime 安装、任务执行、取消、上传和安全退出验收通过。
DESIGN.md、RUN.md、PROGRESS.md 和 Windows Node README 已按实际落地范围同步。

16. 首个实施切片

建议第一个开发切片只做以下内容：

增加 Host 生命周期 Characterization 测试。
引入 NodeCompositionRoot，消除 GUI 与 headless 的重复构造路径。
提取 NodeApplicationController，从托盘类移出注册、重连、迁移和退出编排。
让现有 WinForms UI 继续驱动新的 Controller。
完成 build、专项测试、打包和启动烟测。

该切片不启用 WPF、不移动 Job 格式、不改 Adapter，也不改变用户可见界面。它先建立后续 Host 重构和 WPF 迁移共同依赖的稳定边界，风险最低、验证价值最高。

16.1 实施记录（2026-08-31）

首个切片已完成：新增 Zcbot.WindowsNode.Tests 与 Host 生命周期行为测试；引入唯一 NodeCompositionRoot 和 UI 无关的 NodeApplicationController；GUI 与 run --headless 已共用组装入口；注册、重连、清除身份、迁移和安全退出编排已从托盘类移入 Controller。现有 WinForms 主窗口、协议、Job/Workspace 落盘格式、Adapter 和发布目录均保持不变。

验证已覆盖未注册启动、重连收尾屏障、幂等停止、取消退出、迁移失败重启和清身份收尾；.NET 测试、既有 Windows Node 源码专项测试、solution build、framework-dependent 打包及 GUI/headless 启动烟测通过。下一切片进入阶段 2，提取 Job 持久化、状态机与恢复决策。

16.2 阶段 2 实施记录（2026-08-31）

Job 持久化、状态和恢复边界已提取：JobRepository 直接负责既有 request/state/terminal/marker 目录的读取与原子写，JobStateMachine 约束正常单向转换并以显式 Recovery 模式兼容重启后的输入复验和历史成功任务续传，JobRecoveryService 将落盘事实分类为续执行、续上传、重放终态和无需动作。AtomicFile 与 PathGuard 集中保持同目录临时文件、flush 后替换和 Job 派生路径不越界；JobInboxStore 暂时保留 offer 校验、旧调用薄入口和 UI 展示读取，后续由协议与 JobMonitorService 切片继续收窄。

新增测试覆盖完整状态图、非法回退、终态不可重开、恢复例外、旧 request/state 样本无迁移读取、终态幂等、offer 先持久化及 digest/lease 重放、Workspace promotion/rollback、原子替换和路径穿越拒绝。40 项 .NET 行为测试、25 项既有源码专项、格式检查、Release 发布包及 headless 启动烟测通过；下一切片进入阶段 3，会话、协议与传输拆分。

16.3 阶段 3 实施记录（2026-08-31）

会话、协议和 Job 编排已从原连接循环分离：NodeSession 负责连接、hello、心跳、单接收循环与退避重连，NodeProtocolCodec 保持既有消息信封并允许未知消息按原策略忽略，NodeProtocolClient 集中处理文本分片、1 MiB 上限、身份关闭语义和发送锁；JobCoordinator 接管 offer、cancel、export、恢复回报及本地执行流水线，新的 NodeConnectionLoop 只组合并收尾两者。

输入下载和输出上传现共用每份已加载配置唯一的 NodeHttpClient，统一 BaseAddress、Bearer、Node ID 与 User-Agent；lease/digest 保持逐请求 Header，避免共享 Header 竞争。TransferRetryPolicy 将认证、瞬时、永久和取消错误分开，只有无请求体的 GET 下载执行有界自动重试，输出上传继续依赖既有服务端幂等确认与落盘恢复，不会因传输重试重新执行专业软件。新增假 WebSocket/HTTP handler 测试覆盖信封兼容、未知消息、分片接收、并发发送、4003 身份拒绝、断线重连、认证不重试和瞬时下载重试；57 项 .NET 行为测试、25 项源码专项、格式与 diff 检查、Release 发布包及隔离数据目录 headless 烟测通过。下一切片进入阶段 4，拆分 Adapter、进程监督与 runtime。

16.4 阶段 4 实施记录（2026-08-31）

Adapter 发现、合同、执行和进程边界已拆分：AdapterCatalog 以线程安全 Lazy 在启动期一次发现并缓存已安装描述符，AdapterContractLoader 负责 manifest 白名单、版本/runtime、相对路径边界、合同 capability、Workspace 输出、JSON Schema、入口扩展名和 SHA-256；AdapterExecutionService 保留既有 Job 目录协议、终态读取、Workspace promotion/restore 和错误码，所有 capability 共享 JobExecutionGate，不再只依赖云端 slot。ProcessSupervisor 统一固定进程启动、受限标准流采集、取消、完整进程树终止和 30 秒退出确认；对不存在 Job 的取消不再创建遗留 CTS。

软件与 runtime 已拆为 SoftwareCatalog、SoftwareLocationService、SoftwareProbeService 和 ManagedRuntimeInstaller。Origin/ANSYS/Blender 固定定义、兼容环境变量、注册表与标准目录检测顺序保持不变，probe 保持 30 秒缓存并可在 runtime 更新后显式失效；安装器仍只接受内置 requirements 和固定 Python 3.12 发现方式，在临时目录验证后原子替换并保留失败 rollback，同时在入口机械拒绝活动执行。新增行为测试覆盖已打包 Adapter 合同加载、跨 capability 单槽、等待取消、软件目录定义和 probe 缓存失效；62 项 .NET 行为测试、122 项 Origin/ANSYS/Blender/合同/Node 专项、格式与 diff 检查、Release 发布包及隔离数据目录 headless 烟测通过。下一切片进入阶段 5，建立 WPF Shell、ViewModel 基础设施及 NotifyIcon 互操作。

16.5 阶段 5 实施记录（2026-08-31）

GUI 入口已切换为 WPF Application 消息循环，新增 MainWindow、Light 资源字典、ObservableObject、同步/异步 Command 和 MainWindowViewModel。主窗口提供节点状态总览、隐藏到托盘、安全退出及经典配置入口；关闭窗口只隐藏，不终止后台节点。新的 TrayHost 通过显式 WinForms 类型别名管理 NotifyIcon，把 Controller 状态切回 WPF Dispatcher，延续托盘双击、重连、三选一活动任务退出和取消二次确认。尚未迁移的注册、专业软件、验收、本机任务和数据目录功能仍由按需创建的 ConfigurationForm 承担，阶段 8 完成前保持可达。

CLI 参数分支仍在创建任何 WPF 对象前执行，run --headless、单实例互斥体、Composition Root 和 Controller 生命周期保持原语义。新增 ViewModel 状态映射、命令转发、异步命令防重入与异常报告测试；66 项 .NET 行为测试、188 项 Origin/ANSYS/Blender/合同/Node 专项、格式与 diff 检查、framework-dependent Release 包、隔离 GUI 消息循环及 headless 返回码烟测通过。下一切片进入阶段 6，迁移节点概览、注册与运行设置页面。

16.6 阶段 6 第一切片实施记录（2026-08-31）

节点概览、首次注册和运行设置基础能力已迁入 WPF。MainWindowViewModel 现在持有页面导航、身份摘要、注册字段、操作反馈及 Command 可用状态，通过事件边界复用 Controller 的注册、重连和清身份流程；一次性注册码由 PasswordBox 同步到 ViewModel，注册成功或身份状态刷新后立即清空。清身份继续二次确认，注册继续使用 EnrollOptions 的 URL、名称和注册码校验。登录自启动经 IStartupRegistration 接口调用当前账号 Run 项，权限或 IO 失败会保留原开关状态并展示错误。运行设置展示实际 data root，迁移按钮暂时进入经典配置，以继续使用已有活动任务检查、固定磁盘校验、复制摘要和重启流程。

专业软件、runtime、ANSYS 验收、本机任务和数据目录迁移尚未迁入 WPF，因此本记录不把阶段 6 标为整体完成。新增测试覆盖 WPF 页面导航、身份映射、注册参数转发、自启动成功与失败回滚，源码契约确认 WPF 不直接依赖 Controller；69 项 .NET 行为测试、189 项 Origin/ANSYS/Blender/合同/Node 专项、格式与 diff 检查、framework-dependent Release 包及隔离 GUI/headless 烟测通过。下一切片迁移专业软件卡与 runtime 管理。

16.7 阶段 6 第二切片实施记录（2026-08-31）

专业软件卡和 runtime 管理已迁入 WPF。新的 SoftwareManagementService 组合 SoftwareCatalog、SoftwareLocationService、Adapter probe 和 ManagedRuntimeInstaller，向 Presentation 只暴露不可变快照与受控操作；SoftwarePageViewModel 在用户进入页面后异步刷新 Origin、ANSYS、Blender 卡片，支持选择严格匹配的 EXE/安装根目录、清除账号级配置后恢复自动检测、安装或更新隔离 runtime，以及显式取消安装。文件和目录对话框、安装确认仍封装在 Tray WinForms 互操作层，WPF ViewModel 不读取注册表、不创建进程，也不接触任意命令。

软件快照直接读取 AdapterCatalog.HasActiveExecution，全机任一 Job 执行时均禁用 runtime 安装；即使 UI 快照过期，安装器入口仍会二次拒绝活动执行。安装继续固定 Python 3.12、内置 requirements 和镜像配置，在临时目录验证后原子切换，取消时终止完整安装进程树，失败保持原 runtime。新增测试覆盖软件卡刷新、位置保存与清除、安装确认/结果、活动任务禁用和取消收尾；73 项 .NET 行为测试、190 项 Origin/ANSYS/Blender/合同/Node 专项、格式与 diff 检查、framework-dependent Release 包及隔离 GUI/headless 烟测通过，未执行真实安装或启动专业软件。下一切片迁移 ANSYS 固定验收。

16.8 WPF UI 打磨记录（2026-08-31）

在不改变页面命令和 Host 生命周期的前提下，Light 主题补齐集中颜色、表面、边框、状态和间距 token，并用 WPF ControlTemplate 统一按钮与侧栏导航的圆角、悬停、按下、禁用和键盘焦点状态。侧栏使用单选视觉的 ToggleButton 显示当前页，页头增加实时节点状态徽标，概览卡增加同源状态色带，软件卡增加位置可用性徽标和安装忙碌进度；操作区改用 WrapPanel，在 760 px 最小窗口下可自动换行。操作结果改为独立提示条，仅在有消息时占位，减少与底部常驻说明的竞争。

新增 UI 结构契约覆盖导航选中绑定、状态 tone、响应式操作区、忙碌反馈和主题资源，既有 ViewModel 测试补充状态色与提示可见性；73 项 .NET 行为测试、191 项 Origin/ANSYS/Blender/合同/Node/UI 专项、格式与 diff 检查、framework-dependent Release 包及隔离 GUI/headless 烟测通过。纯视觉改动未改变 CLI、托盘、注册、runtime 安装或持久化契约。

16.9 阶段 6 第三切片实施记录（2026-08-31）

按主导航可用性优先，将本机任务迁移提前到 ANSYS 固定验收之前。JobMonitorService 从 JobInboxStore 接管面向 UI 的只读快照生成，继续合并 request、state、terminal、cloud-terminal 和 upload-complete 落盘事实，不改变既有 Job 目录或恢复协议。新的 JobPageViewModel 负责状态中文映射、执行时长、摘要、选中详情与按 Job ID 保持选择；WPF 页面以只读表格展示最近 50 条记录，进入页面立即刷新，并在窗口可见且任务页激活时每秒刷新。侧栏“本机任务”不再打开经典配置。

新增测试覆盖快照刷新、状态格式、读取失败、刷新后选择保持，以及真实 WPF 资源加载后的四页互斥可见性和标题绑定；94 项 .NET 行为测试、28 项 Windows Node 源码专项、格式与 diff 检查通过。阶段 6 尚余 ANSYS 固定验收和数据目录完整迁移，完成后再删除经典任务页及其 WinForms 定时器，避免迁移期间影响现有回退入口。

16.10 阶段 6 完成记录（2026-08-31）

ANSYS 固定验收和数据目录完整迁移已进入 WPF。AnsysAcceptanceService 固定绑定已打包的 ansys.mechanical.static_structural@v2 验收入口，ViewModel 提供报告目录选择、长时进度、显式停止、通过报告校验和机器级执行门；执行门仍要求本次报告 passed=true、用户确认许可证已释放，并在权限不足时保持关闭。DataRootPageViewModel 通过 DataRootManagementService 检查环境变量托管与未完成任务，目标规范化和二次确认后只调用 Controller 的迁移编排，继续保持停连、复制、逐文件 SHA-256 校验、成功后保存新根目录与失败重连回滚。

16.11 阶段 7 完成记录（2026-08-31）

诊断摘要提取为 DiagnosticService 并由 WPF 概览页复制，内容继续排除 Node Token。删除 ConfigurationForm 和旧 TrayApplicationContext，托盘菜单不再暴露经典配置入口；WinForms 仅保留 NotifyIcon、固定文件/目录选择、确认框和剪贴板互操作。Presentation 不直接持有 Controller，不解析 Job JSON，不访问注册表，也不创建 Worker；117 项 .NET 行为测试、28 项 Windows Node 源码专项、格式与 diff 检查通过。下一步进入阶段 8 发布准备与目标机 DPI/GUI 烟测。

41 KiB Raw Blame History Unescape Escape