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 运维

• 运维对象：

  • 默认对象：当前 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 来源：$dad-dev；
  • 部署/发布：同时加载 $unidesk-cicd；
  • 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 '[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'

• 状态分类：

  • 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。

变更流程

1. 观察运行上下文：
   • 选中的 HWLAB 节点/通道；
   • 公共入口和 Python 发布元数据；
   • Windows 用户/会话；
   • 当前节点进程、任务/启动项、配置是否存在和旧运行器。
2. 节点身份、工作区根、资源绑定、认证、能力或 MDTODO 来源变化时，先更新权威规格。
3. 使用当前 CLI 帮助选定的仓库自带 hwlab nodes hwpod-node 规划/状态/应用命令族：
   • 变更前要求预检解析 YAML 节点配置；
   • 证明节点的 trans 路由可达；
   • 命令族不存在时先实现它。
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 正文或凭据。

停止条件

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

参考文档

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