docs: 固化 Windows HWPOD 运维判定

记录 pyw 启动器、标准句柄隔离和 MDTODO 投影验收规则，并按结构化列表整理流程。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-07-10 13:36:22 +02:00
parent 44c9de4a25
commit eb12b0662b
1 changed files with 77 additions and 40 deletions
@@ -56,9 +56,28 @@ description: >-
 bun scripts/cli.ts cicd status --node NC01
 bun scripts/cli.ts hwlab nodes control-plane source-workspace status --node NC01 --lane v03

-trans <provider>:win ps '[ordered]@{home=$HOME; python=(python --version 2>&1 | Out-String).Trim(); config=(Test-Path (Join-Path $HOME ".hwlab\\config.json")); log=(Test-Path (Join-Path $HOME ".hwlab\\logs\\hwlab-node.log"))} | ConvertTo-Json -Compress'
-trans <provider>:win ps 'Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match "hwlab-node|hwpod-node" } | Select-Object ProcessId,Name,CommandLine | ConvertTo-Json -Compress'
-trans <provider>:win ps 'Get-ScheduledTask -ErrorAction SilentlyContinue | Where-Object { $_.TaskName -match "HWLAB|HWPOD" } | Select-Object TaskName,State | ConvertTo-Json -Compress'
+trans <provider>:win ps <<'POWERSHELL'
+[ordered]@{
+  home = $HOME
+  python = (python --version 2>&1 | Out-String).Trim()
+  config = Test-Path (Join-Path $HOME ".hwlab\\config.json")
+  log = Test-Path (Join-Path $HOME ".hwlab\\logs\\hwlab-node.log")
+} | ConvertTo-Json -Compress
+POWERSHELL
+
+trans <provider>:win ps <<'POWERSHELL'
+Get-CimInstance Win32_Process |
+  Where-Object { $_.CommandLine -match "hwlab-node|hwpod-node" } |
+  Select-Object ProcessId, Name, CommandLine |
+  ConvertTo-Json -Compress
+POWERSHELL
+
+trans <provider>:win ps <<'POWERSHELL'
+Get-ScheduledTask -ErrorAction SilentlyContinue |
+  Where-Object { $_.TaskName -match "HWLAB|HWPOD" } |
+  Select-Object TaskName, State |
+  ConvertTo-Json -Compress
+POWERSHELL
 ```

 - 状态分类：
@@ -76,43 +95,61 @@ trans <provider>:win ps 'Get-ScheduledTask -ErrorAction SilentlyContinue | Where

 ## 变更流程

-1. 观察运行上下文：
-   - 选中的 HWLAB 节点/通道；
-   - 公共入口和 Python 发布元数据；
-   - Windows 用户/会话；
-   - 当前节点进程、任务/启动项、配置是否存在和旧运行器。
-2. 节点身份、工作区根、资源绑定、认证、能力或 MDTODO 来源变化时，先更新权威规格。
-3. 使用当前 CLI 帮助选定的仓库自带 `hwlab nodes hwpod-node` 规划/状态/应用命令族：
-   - 变更前要求预检解析 YAML 节点配置；
-   - 证明节点的 `trans` 路由可达；
-   - 命令族不存在时先实现它。
-   - 云端认证与桌面部署分阶段执行：
-     - `--component cloud-auth` 先同步节点认证 Secret；
-     - HWLAB 发布完成后使用 `--component desktop` 部署桌面节点；
-     - `--component all` 只用于云端已引用该 Secret 的稳定运行面。
-4. 由受控 CLI 完成部署：
-   - 渲染并校验配置；
-   - 获取已发布 Python 文件并校验 SHA；
-   - 解析目标交互用户的 Windows `python.exe`；
-   - 安装文件并应用 YAML 声明的登录自启动策略；
-   - nodeId、地址、工作区和重连/更新设置不得硬编码进生成的辅助代码。
-5. 证明节点状态：
-   - 单一执行权威；
-   - 预期版本/nodeId 和注册；
-   - `node.health` 和 `node.inventory`；
-   - 有界工作区读取和结构化诊断。
-6. 通过 HWLAB Web 等价路径验收 MDTODO：
-   - 来源保存；
-   - 探测；
-   - 重建索引；
-   - 文件/任务可见；
-   - 直接 `trans cat` 只属于 P1 诊断。
-7. 记录证据：
-   - 源提交、文件 SHA 和 nodeId；
-   - 工作区指纹/路径摘要和注册状态；
-   - 操作 request/trace 标识；
-   - MDTODO 来源/重建索引结果；
-   - 默认不得记录 Markdown 正文或凭据。
+- 观察运行上下文：
+  - 选中的 HWLAB 节点/通道；
+  - 公共入口和 Python 发布元数据；
+  - Windows 用户/会话；
+  - 当前节点进程、任务/启动项、配置是否存在和旧运行器。
+- 节点身份、工作区根、资源绑定、认证、能力或 MDTODO 来源变化时：
+  - 先更新权威规格。
+- 使用当前 CLI 帮助选定的仓库自带 `hwlab nodes hwpod-node` 规划/状态/应用命令族：
+  - 变更前要求预检解析 YAML 节点配置；
+  - 证明节点的 `trans` 路由可达；
+  - 命令族不存在时先实现它。
+  - 云端认证与桌面部署分阶段执行：
+    - `--component cloud-auth` 先同步节点认证 Secret；
+    - HWLAB 发布完成后使用 `--component desktop` 部署桌面节点；
+    - `--component all` 只用于云端已引用该 Secret 的稳定运行面。
+- 由受控 CLI 完成部署：
+  - 渲染并校验配置；
+  - 获取已发布 Python 文件并校验 SHA；
+  - 解析目标交互用户的 Windows `python.exe`；
+  - 安装文件并应用 YAML 声明的登录自启动策略；
+  - nodeId、地址、工作区和重连/更新设置不得硬编码进生成的辅助代码。
+- 证明节点状态：
+  - 单一执行权威；
+  - 预期版本/nodeId 和注册；
+  - `node.health` 和 `node.inventory`；
+  - 有界工作区读取和结构化诊断。
+- 通过 HWLAB Web 等价路径验收 MDTODO：
+  - 来源保存；
+  - 探测；
+  - 重建索引；
+  - 文件/任务可见；
+  - 直接 `trans cat` 只属于 P1 诊断。
+- 记录证据：
+  - 源提交、文件 SHA 和 nodeId；
+  - 工作区指纹/路径摘要和注册状态；
+  - 操作 request/trace 标识；
+  - MDTODO 来源/重建索引结果；
+  - 默认不得记录 Markdown 正文或凭据。
+
+## Windows 运行态判定
+
+- 使用 Windows Store Python 启动图形节点时：
+  - `pyw.exe` 可能作为常驻启动器；
+  - 实际节点进程是其派生的 `pythonw*.exe`；
+  - 单实例状态只统计 `python*.exe` 解释器；
+  - 停止旧实例时同时清理启动器和解释器。
+- 通过 `trans` 启动图形节点时：
+  - 必须显式重定向标准输出和标准错误；
+  - 禁止让图形进程继承 PowerShell 或 trans 的管道句柄；
+  - `apply` 和 `status` 必须返回结构化终态后才算入口可用。
+- 验收 MDTODO 文件时：
+  - `workspace.ls` 证明目录原始文件可达；
+  - Project Management `reindex` 只投影可识别的 MDTODO 文档；
+  - Web 文件选择必须使用已进入投影的文件名；
+  - 原始目录存在但未进入投影的文件，不得用于 Web 选择命令验收。

 ## 停止条件