Merge pull request #1686 from pikasTech/feat/unidesk-hwpod-ops

feat: 新增 Python UI HWPOD 节点运维 skill

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

@@ -0,0 +1,133 @@
+---
+name: unidesk-hwpod-ops
+description: >-
+  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 可用。
+
+## 只读调查
+
+```bash
+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](references/python-ui-node.md)。
+- 新增节点、绑定工作区或验收 HWLAB Web MDTODO：
+  - 读 [references/workspace-mdtodo.md](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](references/python-ui-node.md)。
+- 节点接入、工作区绑定和 MDTODO 验收：[references/workspace-mdtodo.md](references/workspace-mdtodo.md)。

.agents/skills/unidesk-hwpod-ops/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "UniDesk HWPOD 运维"
+  short_description: "运维 Python UI HWPOD 节点、连接、工作区与 MDTODO"
+  default_prompt: "使用 $unidesk-hwpod-ops 调查并运维指定 HWLAB Python UI HWPOD 节点。"

.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md

@@ -0,0 +1,130 @@
+# Python 图形节点
+
+## 当前权威来源
+
+- HWLAB 源码：YAML 选中的 v0.3 源工作区内 `tools/hwlab-node.py`。
+- 应用形态：单文件 Python/tkinter 图形应用：
+  - 包含 Windows 托盘和自动重连；
+  - 包含日志轮转和自更新。
+- 本地状态：`%USERPROFILE%\.hwlab\config.json`、`state.json`、`logs\hwlab-node.log`、`update\`。
+- 默认公共入口：`https://hwlab.pikapython.com`。
+- 更新元数据：`GET /v1/hwlab-node/update?platform=windows&channel=stable&current=<version>`。
+- 发布文件：`GET /v1/hwlab-node/download/hwlab-node.py`；替换前校验元数据给出的 SHA。
+- 节点传输：主动出站连接 `wss://<origin>/v1/hwpod-node/ws`，完成注册和心跳。
+- 节点操作合同：`hwpod-node-ops-v1`。
+
+不要把版本号或 SHA 写入长期指令。每次操作从选中的运行面/源码重新读取。
+
+## 桌面配置
+
+- 当前应用配置：
+  - 暴露 `serverUrl`、`nodeId` 和 `autoConnect`；
+  - 暴露更新设置和日志设置；
+  - 有意不接受 CLI 参数或 `HWLAB_*` 环境变量。
+
+- Windows 原生解释器规则：
+
+  - 从拥有 `%USERPROFILE%\.hwlab` 和托盘的同一交互登录上下文解析 `python.exe`；
+  - 把选中的解释器路径写入权威节点配置/启动声明；
+  - 使用 `python --version`、`Get-Command python` 和 tkinter 导入作为发现证据；
+  - WSL `/usr/bin/python`、SSH 侧辅助解释器或隐藏服务账号不能作为运行时。
+
+- 平台声明拥有：
+
+  - 节点/通道和唯一 nodeId；
+  - HWPOD 资源与能力绑定；
+  - 允许的工作区根目录；
+  - WebSocket/认证 Secret 来源引用；
+  - 受管登录/启动策略；
+  - Windows 解释器路径/版本和交互用户；
+  - 项目管理 MDTODO 来源。
+- 本地配置边界：
+  - 只表达操作者偏好。
+
+## 状态证据
+
+### 状态采集命令
+
+```powershell
+$root = Join-Path $HOME ".hwlab"
+[ordered]@{
+  home = $HOME
+  configExists = Test-Path (Join-Path $root "config.json")
+  stateExists = Test-Path (Join-Path $root "state.json")
+  logExists = Test-Path (Join-Path $root "logs\hwlab-node.log")
+  interactiveShell = (Get-Process explorer -ErrorAction SilentlyContinue | Measure-Object).Count
+} | ConvertTo-Json -Compress
+```
+
+- 配置和运行证据规则：
+
+  - 只在需要时读取配置字段；
+  - 对未来可能出现的 Secret 字段脱敏；
+  - 注册/运行证据优先使用云端结果：
+    - `node.health` 和 `node.version`；
+    - `node.inventory` 和 `node.diagnostics`。
+
+## 受控部署
+
+- 部署入口：
+
+  - 必须属于 YAML-first UniDesk CLI 命令族；
+  - 不得由操作者手工拼接步骤；
+  - 命令族必须提供有界的规划、状态和显式确认应用动作；
+  - 命令族必须满足下列要求。
+
+- 命令族要求：
+  - 从权威 YAML/配置引用解析：
+    - 节点/通道和 Windows 路由；
+    - 交互用户、pythonPath 和运行目录；
+    - 文件/更新入口、nodeId 和 SecretRefs；
+    - 允许的工作区根和登录自启动策略；
+  - 拒绝没有可解析且可达 `trans` 路由的目标；
+  - 仅在 CLI 传输适配器内部使用 `trans`；
+  - 写入前校验下载文件的 SHA；
+  - 保证应用幂等，并报告：
+    - 写入文件指纹和配置指纹；
+    - 解释器版本和启动注册；
+    - 进程/注册表状态和脱敏阻塞项；
+  - 避免把图形应用作为短 SSH/trans 请求的子进程启动；
+  - 保持交互式 Windows 用户会话：
+    - 确保界面/托盘可见；
+    - 区分“已安装”和“界面可见且已注册”。
+
+- 命令族不存在时：
+
+  - 只允许只读发现；
+  - 人工下载只属于诊断；
+  - 远端 PowerShell 写文件只属于诊断；
+  - 临时计划任务和直接启动进程只属于诊断；
+  - 上述操作都不是部署证据。
+
+## 每次必须检查的缺口
+
+- 必须检查选中的源码/版本，不得假设最新发布文件已经解决以下事项：
+
+- 默认 nodeId 可能仍然绑定 D601。
+- 工作区操作可能接受请求提供的绝对路径，但没有配置允许列表或包含性检查。
+- 即使 cloud-api 支持 token，WebSocket 注册也可能仍然缺少节点凭据。
+- 实际能力可能落后于云端合同，尤其是 apply-patch、UART 写入/JSON-RPC、Keil 和结构化阻塞项。
+- 图形窗口关闭到托盘不等于登录持久化；非交互会话中的计划任务可能隐藏界面/托盘。
+- 另一个任务、启动项或运行目录中可能仍有旧 Bun 运行器活动。
+
+- 缺口处置：
+  - 每个缺口必须分别暴露；
+  - 不得增加本地兜底路径掩盖问题。
+
+## 旧运行器漂移
+
+- 旧运行器证据：
+
+  - `bun.exe tools\hwpod-node.ts connect`；
+  - 旧 IP/端口云端地址；
+  - `hwpod-node-runtime`；
+  - 旧计划任务名。
+
+- 停止旧运行器前：
+
+  - 比较 nodeId、云端地址、资源绑定和活动硬件任务；
+  - 可能中断硬件操作的变更必须有明确维护窗口；
+  - 变更必须遵循 `$dad-dev` 流程。

.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md

@@ -0,0 +1,84 @@
+# 工作区与 MDTODO
+
+## 必需声明
+
+- 新增节点/工作区规则：
+  - 只能通过权威 YAML/配置引用新增；
+  - 以下概念必须分离。
+- 桌面节点：
+  - HWLAB 节点/通道；
+  - 唯一 nodeId；
+  - Python 文件来源；
+  - Windows pythonPath/版本；
+  - 受管交互用户/启动策略。
+- HWPOD 资源：
+  - hwpodId/resourceId；
+  - nodeId；
+  - 能力；
+  - workspaceRootRef。
+- 工作区策略：
+  - 允许的 Windows 根目录；
+  - 包含性/规范化策略；
+  - 读写能力。
+- MDTODO 来源：
+  - sourceId 和 projectId；
+  - hwpodId 和 nodeId；
+  - workspaceRootRef 和 mdtodoRootRef。
+- 服务路由：
+  - 公共/服务节点操作配置引用；
+  - Secret 来源引用。
+
+Windows Python 图形节点的 `workspaceRootRef` 必须使用该进程可见的 Windows 路径。
+WSL `/mnt/<drive>/...` 路由可以证明同一批文件存在，但不是 Python 节点的路径权威。
+
+## 接入顺序
+
+1. 确认 Windows 路径存在、是目录并包含预期 MDTODO 根目录。
+2. 分配与 D601 和所有现有节点不同的 nodeId。
+3. 增加桌面节点、HWPOD 资源/工作区策略和 MDTODO 来源的 YAML 声明。
+4. 在节点配置中增加可解析的 `trans` Windows 路由，并通过受控 CLI 预检证明其可达。
+5. 确保 Python 节点对声明的工作区根实施规范路径包含性检查；拒绝：
+   - 根目录之外的绝对路径；
+   - `..`；
+   - 符号链接/联接点逃逸；
+   - 未声明根目录。
+6. 从 SecretRef 配置注册认证，不打印凭据。
+7. 使用仓库自带 YAML-first CLI：
+   - 安装已校验 SHA 的 Python 文件；
+   - 应用选中的交互式 Windows 登录自启动策略。
+8. 证明云端注册和预期能力。
+9. 对声明根目录运行 `node.inventory`，再对 MDTODO 根目录执行有界 `workspace.ls`/`workspace.cat`。
+10. 保存/探测/重建项目管理来源索引，并在 HWLAB Web 验证文件/任务。
+
+## MDTODO 验收
+
+1. 在 YAML 选中的入口打开 `/projects/mdtodo`。
+2. 用声明的 `hwpodId`、`nodeId`、工作区根和相对 MDTODO 根保存来源。
+3. 探测来源，并要求结构化就绪结果。
+4. 重建索引，记录文档/任务数量和指纹，不记录 Markdown 正文。
+5. 确认直接 `.md` 文件及其任务可见。
+6. 用户要求时，从一个任务启动 Workbench，并验证生成的任务/会话关联。
+
+- 等价入口规则：
+  - API 族是 `/v1/project-management/mdtodo/*`；
+  - 仓库存在 web-probe 命令时使用它们；
+  - 直接文件系统读取永远不能作为完成证据。
+
+## 失败分类
+
+| 错误族 | 含义 |
+| --- | --- |
+| node-offline | Python 进程不存在或 WebSocket 未注册 |
+| node-id-mismatch | 计划指向不同节点身份 |
+| node-auth | 凭据缺失或被拒绝 |
+| workspace-policy | 根目录缺失、不在允许列表或包含性校验失败 |
+| capability-mismatch | 节点无法执行请求的公共操作 |
+| workspace-op | 允许根目录内的有界操作失败 |
+| source-probe | 项目管理无法读取/解析来源 |
+| source-projection | 来源读取后重建索引或数据库投影失败 |
+| web-visibility | API 状态存在，但 HWLAB Web 未正确展示 |
+
+- 失败处理：
+  - 保留失败层的 requestId/traceId 和节点诊断；
+  - 修复权威层；
+  - 不得增加 SSH、直接文件系统、本地挂载或私有 API 兜底。