# zcbot Windows Node

内网 MVP 的 Windows 执行节点，目标运行环境为 Windows 11 Enterprise + .NET 10 SDK 10.0.303。仓库根目录 `global.json` 固定 SDK patch；客户端只使用 .NET Windows Desktop Framework，不依赖第三方 NuGet 包。

当前实现托盘状态角标、配置与本机任务窗口、注册、DPAPI/ACL 配置保存、WebSocket `hello`/心跳和退避重连。Node Host 以语言无关的 job 目录协议负责持久化、下载、恢复、取消和上传，并从 EXE 同级 `adapters/*/adapter.json` 发现能力；每个 adapter 目录必须自带 manifest 指向的合同，Node 不读取共享合同目录。Host 只按该合同的 JSON Schema 通用校验请求，软件探测、语义校验和执行都由 Worker 完成。Worker 可为受管 Python 脚本或独立 EXE，manifest 独立声明每种软件的任务超时及可选 Workspace 状态。当前安装包带 Origin、ANSYS 和 `blender.scene.author@v3` Worker，但 Python 不是 Node 通用协议的一部分。本机任务列表只读取已派发到该 Node 的持久化目录；Origin OPJU 与 Blender `.blend` 工程保存在各自的 `workspaces/<workspace-id>/current`，只保留一份 `rollback`，完成时自动上传轻量预览，用户明确请求导出时才上传并发布所选正式产物。

在仓库根目录执行一条命令生成可分发 ZIP：

```bat
windows-node\package-windows-node.bat
```

产物位于 `windows-node\dist\zcbot-windows-node-<version>-win-x64.zip`，旁边同时生成 SHA-256 文件。默认不包含 .NET Runtime，目标机器需预装 .NET 10 Desktop Runtime；需要免安装 .NET 的离线包时执行 `package-windows-node.bat --self-contained`。打包脚本是纯 BAT，使用 .NET SDK 以及 Windows 自带的 `tar.exe`、`certutil.exe`。

固定 Origin Worker 通过统一的 `origin.plot@v2` / `series[]` 数据角色模型支持 `line`、`scatter`、`line_scatter`、`column`、`bar`、`grouped_column`、`y_error`、`contour`、`surface_3d`、`ternary` 和 `heatmap`，并支持毫米画布、轴范围/尺度/刻度排版、标题、图例及逐系列样式。adapter 0.6.0 提供 `multi_panel`：可组成 1–4 个二维 panel，在每个 panel 混合基础二维系列、绑定左右 Y 轴并添加对称 X/Y 误差列；adapter 0.7.0 增加 `box`、`histogram`、`stacked_column`、`bubble` 和 `band`，adapter 0.8.0 再增加 `area`、`stacked_area`、`polar`、`pie` 和 `stacked_bar`，adapter 1.2.0 增加适合 XRD/XPS/光谱比较的 `stacked_line`，adapter 1.3.0 增加用于多组原始观测分布比较的 `violin`。Worker 生成 OPJU、PNG、SVG、PDF、plot spec、provenance 与原子 `terminal.json`。热图输入必须是完整、等间距且坐标不重复的规则 XYZ 网格；累计堆叠系列必须逐行共享相同 X 值，错位谱线允许各系列使用不同 X 采样点。运行时独立于 zcbot 服务端 Python。发布目录包含统一安装入口；使用实际运行 Node 的专用 Windows 账号直接双击：

日常只更新 adapter 时运行 `package-origin-adapter.bat`，无需编译 Node。退出托盘 Node 后，整体替换安装目录中的 `adapters\origin.plot@v2\` 再启动即可；不要在任务执行期间覆盖文件。只有依赖清单变化才需要在对应软件卡中更新 runtime。

Origin adapter 1.1.0 起随包提供独立 CLI 真机 QA harness；1.3.0 的固定合成数据覆盖 annotations、2×2 Recipe、heatmap、surface_3d、stacked、stacked_line、violin 和 band，并验证 OPJU 重开、数据与数值 oracle、三种图件复导及 Origin 进程释放；该入口暂不接入 Node UI，运行命令和验收边界见根目录 `RUN.md`。

Windows Node 不再提供统一安装脚本。解压发布包后直接运行 `Zcbot.WindowsNode.exe`，在主窗口完成节点注册、登录后自动启动、应用位置配置和各软件 runtime 的独立安装。runtime 安装依次尝试 `py -3.12` 和 PATH 中的 `python.exe`，要求 Python 3.12；依赖默认通过清华 PyPI 镜像安装，需要改用官方源或院内镜像时，在启动 Node 前设置 `ZCBOT_PIP_INDEX_URL`。runtime 位于 `<data_root>\runtimes\<runtime_id>\Scripts\python.exe`。全新节点默认使用 `%LocalAppData%\Zcbot\WindowsNode`；已有 `%ProgramData%\Zcbot\WindowsNode` 的升级节点继续沿用原目录。

推荐在 Node 主窗口“专业软件”区域完成后续配置：Origin、ANSYS、Blender 各有独立软件卡，均可自动检测或手工选择受支持的位置，并单独“安装/更新运行环境”。安装动作只接受内置软件定义和随包发布的固定 requirements，不执行用户输入的命令；新环境先在同一数据根目录的临时目录构建，成功后再替换对应 runtime。手工路径保存在当前专用 Windows 账号下，Node 启动 Worker 时注入固定环境变量；“自动检测”可清除手工路径并回到环境变量、COM、卸载注册表、PATH 或标准目录发现。Origin 的手选程序用于确定安装位置和读取版本，实际执行仍以 COM probe 为准。

主窗口“运行设置”可把完整数据根目录迁移到其他本机固定磁盘。Node 会先停止接收任务，已有未完成任务时拒绝开始；随后把身份、任务、Workspace 和 runtime 复制到临时目录并逐文件校验，校验成功后才切换账号级配置并重启，旧目录不会自动删除。机器级 `ZCBOT_WINDOWS_NODE_DATA_DIR` 优先于 UI 设置；设置后 UI 只读，适合统一运维。软件卡始终把 runtime 安装到当前数据根目录，后续更新不会写回默认目录。

Blender adapter 1.0.0 面向 Blender 5.2 LTS，将受管 Scene Recipe 编译为静态三维场景。Recipe 可组合基础体、拉伸/旋转/扫掠、带壁厚直管、文字、父子层级、集合、受控修改器、材质和灯光，`rotary_kiln` 作为普通 generator 与其他对象共同构图；一次任务可按声明相机输出最多八张 PNG，并生成 `scene.blend`、场景清单、溯源和可选 GLB。启动命令固定包含 background、factory startup、禁止自动脚本和 Python 异常退出码；请求不接受 Python、命令行、路径、URL、插件或任意节点脚本。只更新该 adapter 时运行 `package-blender-adapter.bat`，退出托盘 Node 后移除旧 v1/v2 目录、放入 `adapters\blender.scene.author@v3\` 并重启；旧 Workspace 文件保留但不能由 v3 续作。若节点没有 `runtimes\blender`，在 Blender 软件卡中单独安装即可。

ANSYS adapter 0.2.0 已实现 Mechanical 2024 R2 / PyMechanical 0.11.3 的真实线性静力流程，可从 STEP/Parasolid/IGES 导入 Named Selection，应用固定材料/网格/支撑/力或压力，并导出 MECHDAT、汇总、结果表、结果图、solver log 和溯源。契约不接收 Python、APDL、Journal、工程文件或本机路径。Node 主窗口提供“复制诊断信息”和“ANSYS Mechanical 真机验收”卡片；验收使用内置 NIST FTC-11 STEP 并自动建立两个端面 Named Selection，用户只需选择报告目录。该入口不受执行门影响，但只有固定的取消与连续 20 次求解全部通过后，界面才允许写入机器级执行门。完成专用节点的许可证、取消、残留进程和许可证释放验收前，能力仍保持不可调度，具体步骤见根目录 `RUN.md`。

注册和运行必须使用同一专用 Windows 账号。MVP 由主窗口按需写入该账号的登录启动项，不以 Windows Service 在 Session 0 运行。

```powershell
dotnet build windows-node/Zcbot.WindowsNode/Zcbot.WindowsNode.csproj
windows-node/Zcbot.WindowsNode/bin/Debug/net10.0-windows/Zcbot.WindowsNode.exe enroll `
  --server http://zcbot.internal:8765 `
  --name win-origin-01 `
  --code ZCN-...
windows-node/Zcbot.WindowsNode/bin/Debug/net10.0-windows/Zcbot.WindowsNode.exe
```

直接双击 EXE 默认启动托盘 UI；红点表示未注册或身份失效，黄点表示正在连接，绿点表示在线。双击托盘图标打开窗口，可在“本机任务”中查看最近 50 条已接收任务及执行详情。每个任务的输出上传诊断日志保存在 `<data_root>\jobs\<job-id>\logs\node-output-upload.log`，记录阶段、产物文件名、重试次数和 Windows `HRESULT`，不记录 Node Token 或认证请求头；单文件达到 1 MiB 后轮转一份 `.1`。无界面运行使用：

```powershell
Zcbot.WindowsNode.exe run --headless
```

注册结果保存在 `<data_root>\node.json`，可恢复任务保存在同级 `jobs`，持久工程保存在同级 `workspaces/<workspace-id>`；它们不随程序包更新。Workspace 目录不按 user ID 分层，用户归属、home node、head Job 和容量由服务端数据库集中维护。Token 使用 DPAPI `LocalMachine` 加密，目录与文件 ACL 只保留注册时的运行账号和 `SYSTEM`。复制配置到另一台机器不能解密 Token；Windows 重装、运行账号变更或身份丢失时应由管理员禁用旧节点并重新注册。
