pikasTech-unidesk/.agents/skills/unidesk-hwpod-ops/SKILL.md

name, description

name	description
unidesk-hwpod-ops	UniDesk HWLAB HWPOD 节点运维技能，覆盖 Windows 单文件 Python 图形节点 `hwlab-node.py` 的发现、安装、界面/托盘、连接、更新、日志、诊断、nodeId、工作区、HWPOD 节点操作、 MDTODO 来源和旧 Bun 运行器漂移。用户提到 hwpod-node、hwlab-node、Python 图形节点、 HWPOD 节点上下线、D601/G14-WSL 硬件节点、工作区绑定或 HWLAB Web MDTODO 读取时使用。

UniDesk HWPOD 运维

• 本 skill 中的 MDTODO 仅表示遗留工作区来源与旧 Web 验收面；恢复相关任务前按 $unidesk-tasktree 迁移，不得新增文件式任务。

• 运维对象：

  • 默认对象：当前 HWLAB v0.3 Python 图形节点；
  • 历史调查：旧 $hwpod-ops 中的 TypeScript/Bun serve|connect；
  • 禁止事项：旧运行器不得作为新节点完成态。

P0 边界

• 当前 HWLAB 固定运行面由 UniDesk config/hwlab-node-lanes.yaml 选择：
  • 先运行 cicd status 和 source-workspace status；
  • 不得复用旧 G14/v0.2 地址。
• Python 图形节点的来源：
  • 权威源码是选中 HWLAB 源工作区的 tools/hwlab-node.py；
  • 发布版本由选中入口的 /v1/hwlab-node/update 给出；
  • 发布文件和 SHA 由 /v1/hwlab-node/download/hwlab-node.py 与更新元数据共同确定。
• 平台资源真相：
  • 节点、工作区、HWPOD 资源、MDTODO 来源、端点和 Secret 必须进入权威 YAML/配置引用；
  • ~/.hwlab/config.json 只属于桌面应用配置。
• Secret 规则：
  • 只通过 YAML sourceRef/targetKey 和受控入口下发；
  • 状态、日志和 issue 只披露是否存在、指纹和脱敏摘要。
• Windows 节点使用主动出站 WebSocket；不要为用户电脑增加入站端口或直连地址兜底。
• Windows Python 图形节点启动规则：
  • 优先使用目标 Windows 交互用户可见的原生 python.exe；
  • 不得用 WSL Python、SSH 辅助程序自带解释器、Bun 运行器或非交互 Windows 服务替代；
  • 解释器路径/版本必须进入节点配置和状态证据。
• HWPOD 节点部署必须采用 YAML-first + 仓库自带 CLI：
  • 只支持权威 YAML 已声明且 trans 路由可解析、可访问的节点；
  • CLI 可以在内部使用 trans 作为传输层；
  • 操作者不得用手写 trans/PowerShell/cmd 完成安装、更新、配置或自启动；
  • 受控 CLI 缺失时先实现 CLI，不把手工部署当临时完成态。
• 调查可只读访问现场；发生以下变更时加载对应 skill：
  • 安装、注册、更新、停止旧运行器或修改 MDTODO 来源：$unidesk-daddev；
  • L2/L3 部署或发布：同时加载 $unidesk-cicd；
  • L1 native API、worker、Web 和 Windows desktop node 的启动、恢复与回归不加载、 不依赖 $unidesk-cicd 或 Kubernetes；
  • YAML 变更：同时加载 $unidesk-ymalops。
• 远端操作走 $unidesk-trans。普通 trans 保持短连接；图形进程不得作为透传子进程长挂。
• Python 节点可用性：
  • 必须具备工作区允许列表/规范化；
  • 必须具备注册认证和能力对齐；
  • 缺失任一项时，不得把“WebSocket 已连接”报告为 HWPOD/MDTODO 可用。

只读调查

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 <<'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

• 状态分类：

  • desktop-ready：Python/tkinter 和交互式 Windows 会话可用。
  • process-ready：只有一个预期的 Python 图形进程存活，不存在冲突的 Bun 执行权威。
  • registered：云端注册表已确认预期 nodeId。
  • workspace-ready：node.inventory 和有界工作区读取指向 YAML 选中的根目录。
  • mdtodo-ready：项目管理来源通过公共 HWPOD 工作区操作完成保存、探测和重建索引。

• 当前应用合同、更新流程和已知缺口：

  • 读 references/python-ui-node.md。

• 新增节点、绑定工作区或验收 HWLAB Web MDTODO：

  • 读 references/workspace-mdtodo.md。

变更流程

• 观察运行上下文：
  • 选中的 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、地址、工作区和重连/更新设置不得硬编码进生成的辅助代码。
• Windows UART backend 由 HWPOD spec 的 YAML 字段选择：
  • serial-monitor 是默认 backend；
  • 目标机已有 pyserial 且 serial-monitor server 不可用时，可对该 spec 显式声明 backend: pyserial，不得改成全局隐式回退；
  • compiler 必须把同一 backend 对称传入 open、read、write、close 四类 plan；
  • pyserial 节点在四步操作之间持有同一串口连接，回归结束必须执行 close。
• 证明节点状态：
  • 单一执行权威；
  • 预期版本/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 选择命令验收。

停止条件

• 选中的通道/源权威不清晰或过期时，在变更前停止。
• 部署前停止条件：
  • 目标未进入权威 YAML；
  • 没有可解析且可达的 trans 路由；
  • 仓库自带规划/状态/应用 CLI 缺失。
• 现有进程控制相同 nodeId/资源时，在启动第二个运行器前停止。
• 工作区未实施包含性约束或来源可能逃逸声明根目录时，在 MDTODO 写入/重建索引前停止。
• 必须区分以下阻塞项：
  • 节点不匹配和认证失败；
  • 工作区缺失和能力不匹配；
  • 旧运行器漂移；
  • 来源投影失败。
• 不得只凭进程健康关闭 HWPOD issue；必须使用用户原始的 HWLAB Web/CaseRun/MDTODO 入口。

参考文档

• Python 图形节点合同、本地文件、更新端点和漂移：
  • references/python-ui-node.md。
• 节点接入、工作区绑定和 MDTODO 验收：references/workspace-mdtodo.md。