pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010104-ai-gateway.md

# PJ2026-010104 AI网关

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。

## 正文

## PJ2026-010104 AI网关需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010104 |
| 短名 | AI网关 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e; draft-2026-07-10-g14-wsl-python-hwpod-node; draft-2026-07-13-p0-cloud-console; draft-2026-07-19-native-python-provider |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 AI 网关的稳定使命、范围、术语、系统边界、内部分工和原子需求。

## 2. 目的和范围

### 2.1 目的

AI网关负责靠近真实硬件执行受控动作并回传原始硬件事实，使 HWPOD 服务能够触达 PC 侧工具、debug probe、board-comm、ioProbe、UART、CANopen、电压、电流和频率等设备能力。

本课题的目标状态是：节点先完成只读连通与身份确认，再按声明能力执行写操作，并在失败时返回可区分的节点、协议、板侧处理或安全恢复错误。

在 Web CaseRun 场景中，PC 侧单文件 Python UI node 可以作为 HWPOD node 的一种实现形态。它提供本地连接状态、日志观察、托盘和更新等 operator 体验，但硬件事实、operation result 归属、租约和云端可见状态仍以 HWPOD 服务协议为准。

### 2.2 范围内

- HWPOD node / AI 网关进程、心跳、能力上报、健康和可用性。
- PC 客户端形态、硬件网关盒子形态和靠近设备的 adapter 执行。
- 无 Docker 的 Windows/Linux 原生 Python Provider 形态和 `trans` 透传。
- debug probe 下载、reset、UART、board-comm JSON-RPC、CANopen SDO、ioProbe、电压、电流和频率适配器。
- 只读诊断、写操作前置身份确认、安全态恢复和恢复失败分类。
- 原始硬件事实回传，包括板内 echo、板外采样、协议响应、适配器日志摘要和错误语义。
- Web CaseRun 所需的 workspace、Keil build、download、reset、UART、capability 上报、日志摘要和云端诊断回传。

### 2.3 范围外

- HWPOD spec 字段、资源身份和能力声明归 [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)。
- CLI/API 命令形态和结构化输出归 [PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md)。
- 服务端 registry、租约、路由和结果归属归 [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md)。
- CaseRun 评价、aggregate 和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| AI 网关 | 靠近真实硬件的节点侧执行能力，包含 PC 客户端、硬件网关盒子或等价 HWPOD node。 |
| Python UI node | 单文件 Python PC 客户端形态的 HWPOD node，面向本地 operator 提供简洁 GUI、日志、托盘和更新能力，同时通过主动出站协议领取云端命令。 |
| Windows Python Provider | 直接运行在 Windows 用户会话中的 Python 图形 Provider，只主动连接云端并在本机执行 `trans` 请求，不依赖 Docker、WSL 内运行器或入站 SSH 服务。 |
| Linux Python Provider | 直接运行在 Linux host 上的 Python headless Provider，只主动连接云端并在本机执行 `trans` 请求，不依赖 Docker、Node 或入站 SSH 服务。 |
| adapter | 网关侧执行某类硬件动作的适配器，例如 debug probe、UART、board-comm、ioProbe 或 CANopen。 |
| board-comm | 通过板侧通信协议访问目标固件接口的能力，可包含 JSON-RPC over TCP 等形态。 |
| CANopen SDO | 通过 CANopen Service Data Object 读写设备对象字典的协议动作。 |
| 主动出站 | 网关从用户 PC 或本地环境主动连接云端 HWPOD 服务领取命令，云端不需要入站访问用户网络。 |
| in-flight 请求 | 网关已领取并在后台执行、尚未完成回传的长命令或硬件动作。 |
| gateway_busy | 网关达到并发上限或暂时无法领取新操作时返回的结构化忙碌状态。 |
| 安全恢复 | 在写操作前后把真实设备恢复到可继续使用状态的 reset、重新连接或清理输出能力。 |
| 原始硬件事实 | 由节点直接观测或执行得到的协议响应、板外读数、probe 结果和错误语义。 |
| 接入 readiness | 节点从下载到 HWPOD 可用的分阶段状态，不以单一进程或连接信号替代。 |

## 4. 系统边界和接口

本规格把 AI网关作为硬件池的节点侧执行层看待；本章只描述输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | HWPOD服务、HWPOD工具、Agent编排、HarnessRL、平台管理员。 |
| 外部输入 | 服务端路由请求、HWPOD spec 摘要、租约上下文、adapter 参数、workspace 路径、probe UID、通信端点、超时和网关命令执行策略。 |
| 受控资源 | HWPOD node、主动出站连接、in-flight 请求、adapter、debug probe、UART、board-comm 连接、ioProbe、CANopen 通道、电压/电流/频率通道和节点日志摘要。 |
| 外部输出 | 心跳、能力上报、健康状态、in-flight 摘要、adapter 结果、原始硬件事实、恢复结果、`gateway_busy` 和错误分类。 |
| 用户接口 | HWPOD node 协议、网关执行 API、节点侧工具适配器、board-comm/ioProbe 原始接口。 |
| 系统边界 | AI网关负责真实硬件动作执行和原始事实生产；不拥有服务端资源真相、用户权限、客户端体验或 Harness 评价语义。 |

## 5. 内部分工与规格索引

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-01010401 | 节点健康 | 本规格 6.1 | 心跳、能力、健康、可用性和节点运行形态 | HWPOD服务、平台运行面 | 工具、客户端、Agent编排 |
| PJ2026-01010402 | 适配执行 | 本规格 6.2 | debug、UART、board-comm、ioProbe、CANopen、电压、电流和频率适配器 | HWPOD标准、节点健康 | HWPOD服务、HarnessRL |
| PJ2026-01010403 | 安全恢复 | 本规格 6.3 | 只读诊断、写前身份确认、reset 和恢复失败分类 | HWPOD标准、适配执行 | Agent编排、CaseRun |
| PJ2026-01010404 | 原始事实 | 本规格 6.4 | 协议响应、板外读数、adapter 摘要和错误语义回传 | 适配执行、安全恢复 | HarnessRL、客户端 |
| PJ2026-01010405 | Windows节点 | 本规格 6.7 | 纯 Windows Python 图形运行形态、用户 YAML 和 `trans` 执行 | 节点健康、平台连接能力 | HWPOD工具、客户端、平台运维 |
| PJ2026-01010406 | Linux节点 | 本规格 6.8 | Linux Python headless 运行形态、systemd、用户 YAML 和 `trans` 执行 | 节点健康、平台连接能力 | HWPOD工具、客户端、平台运维 |

### 5.1 Windows Python Provider 目标架构

```mermaid
flowchart LR
  T[trans 客户端] --> C[UniDesk backend-core]
  C --> W[Provider WebSocket 与 TCP 数据通道]
  W --> P[Windows Python Provider]
  P --> E[PowerShell、cmd 与原生进程]
  P --> Y[用户 provider.yaml]
  Y --> S[credentialFile]
  P --> U[Tkinter 面板与 Win32 托盘]
  P --> R[用户登录自启动]
```

### 5.2 Windows Python Provider 数据流

```mermaid
flowchart TD
  A[用户 YAML 与凭据文件] --> B[启动校验]
  B --> C[主动注册与心跳]
  D[trans 请求] --> E[既有 host.ssh.tcp-pool]
  E --> F[Windows 路径归一化]
  F --> G[本机子进程]
  G --> H[stdout、stderr 与 exitCode]
  H --> E
```

### 5.3 Windows Python Provider 关键时序

```mermaid
sequenceDiagram
  participant U as trans 用户
  participant C as backend-core
  participant P as Windows Python Provider
  participant W as Windows 子进程
  P->>C: register 与 heartbeat
  U->>C: trans G14-win:win/... 请求
  C->>P: host_ssh_open
  P->>W: 启动 PowerShell、cmd 或原生进程
  W-->>P: stdout、stderr 与 exitCode
  P-->>C: 流式数据与关闭状态
  C-->>U: 原命令结果
```

## 6. 原子需求

### 6.1 HWPOD-GW-REQ-001 节点健康

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-GW-REQ-001 | 节点健康 | PJ2026-01010401 节点健康 | [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md)、[平台运维](PJ2026-0106-platform-ops.md) |

AI网关应上报节点心跳、能力、健康、可用性和运行形态，使 HWPOD 服务能判断某个资源是否可以被路由到真实执行节点。

节点健康必须覆盖 adapter 可用性，而不只是进程在线。debug probe、board-comm 端点、ioProbe、CANopen 通道或恢复能力不可用时，应以能力级状态暴露给服务端。

AI网关默认采用主动出站连接模式：用户 PC、本地 gateway 或硬件盒子主动连接云端 HWPOD 服务并领取命令，云端不要求入站访问用户网络。网关注册和会话状态应暴露当前 in-flight 数量、并发上限和主要执行摘要，使一个长 Keil、下载或 Windows 命令不会遮蔽节点是否仍在心跳、是否仍能处理短状态查询。

Python UI node 作为 PC 客户端形态时，必须上报与 Web CaseRun 相关的实际能力，而不只是进程版本。能力摘要至少应覆盖 workspace 操作、apply-patch、Keil build、download/reset、UART read/write、diagnostics、日志回传和更新状态；缺失能力必须以 capability mismatch 暴露给 HWPOD 服务、HarnessRL 和客户端。

### 6.2 HWPOD-GW-REQ-002 适配器执行

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-GW-REQ-002 | 适配执行 | PJ2026-01010402 适配执行 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)、[PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) |

AI网关应按 HWPOD spec 声明执行 debug、download、reset、UART、board-comm、ioProbe、CANopen SDO、电压、电流和频率等适配器动作。

适配器执行必须先确认目标身份和声明能力。对于真实频率源链路，网关应能把控制侧写入、板侧读回和外部电流/频率观测区分为不同事实来源。

长时间执行的适配动作应作为网关内 in-flight 请求后台推进，poll loop 仍继续处理心跳、job-status、日志读取、取消和诊断请求。达到并发上限时，网关应返回结构化 `gateway_busy`，不得把请求静默排队到云端 dispatch timeout 后才暴露失败。

Web CaseRun 需要的 workspace patch、Keil build、download、UART 和诊断动作都应返回结构化 adapter result。节点侧本地黑框、GUI 文本框或托盘提示不能成为唯一错误载体；异常、stdout/stderr 摘要、日志路径、returnCode、probe mismatch、serial-monitor 状态和可恢复建议必须进入云端可查询的 operation result 或节点诊断摘要。

### 6.3 HWPOD-GW-REQ-003 安全恢复

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-GW-REQ-003 | 安全恢复 | PJ2026-01010403 安全恢复 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

AI网关应在写操作前后提供只读诊断、身份确认、reset 和安全恢复能力，使真实硬件不会在目标不明或恢复入口缺失时被继续写入。

安全恢复必须绑定明确 debug probe、设备和 reset 能力。无法确认 probe 属于目标设备、恢复能力不可用或恢复结果不可判定时，网关应返回受控失败并停止后续写操作。

### 6.4 HWPOD-GW-REQ-004 原始硬件事实回传

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-GW-REQ-004 | 原始事实 | PJ2026-01010404 原始事实 | [HarnessRL](PJ2026-0103-harness-rl.md)、[PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md) |

AI网关应回传原始硬件事实，使板内协议响应、板外 ioProbe 读数、adapter 摘要、连接失败、协议失败和板侧处理失败能被 HWPOD 工具与 HarnessRL 一致消费。

原始硬件事实必须区分板内 echo、板外真实读数和节点适配器状态。网关不能把 TCP 端口可达、进程在线或命令已发出等中间状态当作硬件动作成功。

Python UI node 本地日志应与云端诊断保持可关联。节点在处理 CaseRun 操作时应保留 requestId、runId 或等价 correlation 摘要，并把可脱敏的关键错误上报给 HWPOD 服务，使 Cloud Web、web-probe 和 issue evidence 能看到同一失败原因，而不是只能在 Windows 控制台或本地 GUI 中观察。

### 6.5 HWPOD-GW-REQ-005 Windows Python 图形节点受控部署

- 主责模块：
  - PJ2026-01010401 节点健康；
  - PJ2026-01010402 适配器执行。
- 关联模块：
  - [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md)；
  - [PJ2026-010404 Project Management](PJ2026-010404-project-management.md)。
- 部署入口：
  - 必须使用 UniDesk YAML-first 受控 CLI；
  - 只支持 owning YAML 已声明且 `trans` 路由可解析、可访问的节点；
  - CLI 可以在内部使用 `trans` 作为传输层；
  - 操作者不得用手写 PowerShell、cmd 或远端脚本形成部署真相。
- Windows 运行时：
  - 必须使用 owning YAML 声明的交互用户；
  - 必须优先使用该用户 Windows 会话内的原生 `python.exe`；
  - WSL Python、SSH 辅助解释器、Bun 运行器和非交互 Windows 服务不得作为完成态；
  - GUI 和托盘必须属于同一交互登录会话。
- 节点身份与认证：
  - nodeId 必须全局唯一；
  - 节点凭据只通过 YAML `sourceRef`/`sourceKey` 和目标 credentialFile 下发；
  - WebSocket 握手必须携带节点凭据；
  - UI、日志、CLI 和 issue 只披露凭据是否存在及指纹。
- 工作区策略：
  - owning YAML 必须声明允许的 Windows 工作区根；
  - 节点必须执行规范路径包含性检查；
  - 节点必须拒绝根目录之外的绝对路径、`..`、符号链接/联接点逃逸和跨根操作；
  - `node.inventory` 必须返回脱敏的允许根与实际能力摘要。
- 启动与单活：
  - 登录自启动策略由 owning YAML 声明；
  - 受控 CLI 必须区分“已安装”“界面可见”“已注册”；
  - 相同 nodeId 或 HWPOD 资源出现第二运行器时必须阻塞；
  - 旧 Bun 运行器只能作为漂移证据，不得参与完成态。
- 配置归属：
  - nodeId、入口、pythonPath、运行目录、允许根、更新策略和启动策略以 owning YAML 为准；
  - `%USERPROFILE%\.hwlab\config.json` 仅是 CLI 渲染的桌面副本；
  - 规格不保存具体路径、地址、token、重连次数或时间参数。

### 6.6 HWPOD-GW-REQ-006 Python 节点接入元数据与 Readiness

- 主责模块：
  - PJ2026-01010401 节点健康。
- 关联模块：
  - [HWPOD服务](PJ2026-010103-hwpod-service.md)；
  - [云端控制台](PJ2026-010405-cloud-console.md)。
- 发布元数据：
  - 服务端应公开 Python 单文件的版本、文件名、大小、SHA-256、发布说明和下载 URL；
  - 客户端只能展示和消费这些元数据，不在前端硬编码版本或文件指纹。
- 接入阶段：
  - readiness 必须分别表达 `downloaded`、`installed`、`desktop-visible`、`registered`、`workspace-ready` 和 `hwpod-ready`；
  - WebSocket connected 只证明主动出站会话成立，不等于 workspace 或 HWPOD ready；
  - 每个未完成阶段应返回结构化 blocker 和下一步受控入口。
- 安全边界：
  - 网页不得生成、显示或传递节点 Secret 值；
  - 节点身份、凭据、工作区根、解释器和启动策略继续由 owning YAML 与受控 CLI 拥有；
  - 不得为接入便利新增用户 PC 入站端口、直连地址或匿名注册兜底。

### 6.7 HWPOD-GW-REQ-007 纯 Windows Python Provider

- 主责模块：
  - PJ2026-01010405 Windows节点。
- 关联模块：
  - [HWPOD工具](PJ2026-010102-hwpod-tools.md)；
  - [YAML运维](PJ2026-010603-yaml-first-ops.md)；
  - [平台运维](PJ2026-0106-platform-ops.md)。
- 运行形态：
  - provider 必须作为 Windows 用户会话中的 Python 单进程运行；
  - 不得要求 Docker、WSL 内运行器、入站 SSH 服务或复杂启动参数；
  - 启动命令不得接收配置覆盖参数或环境变量；
  - 启动时必须从固定用户目录读取唯一 `provider.yaml`。
  - Provider 必须使用 Tkinter 提供小型控制面板，并使用 Win32 API 提供托盘，不依赖浏览器或额外 GUI 服务；
  - 托盘必须使用 Provider 自有图标，并通过颜色区分未连接、连接中、已连接和重连状态；
  - 存在活跃 `trans` 会话时，托盘图标必须叠加小扳手动效，会话全部结束后恢复静态状态图标；
  - 关闭控制面板必须隐藏到托盘，托盘必须支持重新打开、连接或断开以及完全退出；
  - 托盘菜单动作必须从 Win32 菜单返回值可靠投递到 Tk 主线程，选择退出后必须停止连接、移除托盘并结束进程；
  - `autoStart: true` 必须通过当前用户 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` 在用户登录后用 `pythonw.exe` 启动；
  - 面板必须允许切换自动启动，并把结果写回同一用户 YAML。
- 配置真相：
  - 用户 YAML 至少声明 provider id、云端 WebSocket 地址和 `credentialFile`；
  - `autoStart`、名称和数据通道地址可以省略，数据通道由 WebSocket 地址确定；
  - 未知字段、缺失字段、非 Windows 平台和不可读凭据必须在连接前明确失败；
  - 凭据值只从 YAML 引用的文件读取，日志只披露 presence 和 fingerprint。
- 本地可见性：
  - 面板必须展示 provider id、当前版本、服务器、连接状态、TCP pool 状态、升级状态和简单滚动日志；
  - 必须提供连接、断开、打开配置目录和打开日志目录入口；
  - 文件日志固定写入用户目录并轮转，控制面板不得因为日志增长持续扩张内存；
  - 文件日志必须按本机自然日轮转并保留有限天数，不得把全部历史持续堆积到单一文件；
  - `trans` 会话日志必须记录实际 shell、cwd 和脱敏后的真实执行命令，不能只记录命令哈希；
  - 常见 PowerShell 与 `cmd` 透传必须从内部 bootstrap 中提取用户命令，
    内部包装器不得占据主命令字段；
  - stdin 脚本无法在启动时完整还原时必须显示稳定的 stdin 脚本标识，
    不得把内部读取器冒充用户命令；
  - token、password、Authorization、API key 和等价敏感参数必须在写入文件日志或面板前脱敏；
  - 同一 Windows 用户会话只允许运行一个实例。
- 升级管理：
  - Provider 必须在启动后自动检查升级，并按用户 YAML 声明的间隔持续监测；
  - 面板必须提供手动检查和手动升级按钮，托盘必须提供等价的检查和升级入口；
  - 可选的空闲自动升级只能在没有活跃 `trans` 会话时应用，检查失败不得中断 Provider 连接或现有会话；
  - 升级元数据必须至少包含版本、Python 文件下载地址、字节数和 SHA-256；
  - 默认升级源必须是 Windows 客户端无需 Git 凭据即可访问的独立 Apps L1 HTTPS 固定路径；
  - Apps L1 必须直接读取权威 Provider 组件目录，不得维护第二份发布脚本，
    其固定端口、状态目录、发布路径和公网 origin 必须由 owning YAML 声明并由项目 CLI 管理；
  - 下载地址必须满足用户 YAML 的 host allowlist，文件必须通过字节数、SHA-256、Python 语法和 Provider 标识校验；
  - 应用升级前必须备份当前脚本，使用同目录临时文件原子替换并记录升级状态；
  - 重启必须在旧进程释放单实例互斥量后发生，不得并行运行两个 Provider；
  - 更新源、频道、检查间隔和空闲自动应用策略必须由同一个用户 YAML 拥有，省略时使用稳定频道的安全默认值。
  - 升级下载使用直连或系统代理必须由同一个用户 YAML 声明，默认直连不得继承未知桌面代理。
- `trans` 合同：
  - provider 必须复用既有 `host.ssh` 与 `host.ssh.tcp-pool` 协议；
  - Windows Provider 必须保持 32 条主动出站 warm data channel，并持续上报 desired、ready、claimed、connecting、total 和最近错误；
  - 必须支持 Windows route 的 PowerShell、cmd、原生 argv、stdin、stdout、stderr、cwd 和 exitCode；
  - `/mnt/<drive>` 形式的桥接路径必须在 provider 内归一化为同机 Windows 路径；
  - provider id 可以与同机 WSL provider 并存，例如 `G14-win` 与 `G14-WSL`；
  - 未实现的 Docker、升级、微服务代理和其他能力不得注册，并应返回结构化 unsupported 错误。
- 快速部署入口：
  - Apps L1 必须同时提供面向人的 Windows 安装工具页和面向 Agent 的稳定 JSON 安装合同；
  - 安装页、JSON 合同、PowerShell installer、Provider 发布件和升级 manifest 必须统一使用 owning YAML 声明的 `apps.hwpod.com` canonical origin，不维护第二安装域名；
  - 页面只采集非敏感配置字段，不得采集、回显或传输 Provider token；
  - JSON 合同必须公开先决条件、固定用户路径、短 YAML 字段、PowerShell 单行命令模板、发布端点和成功判据；
  - PowerShell installer 必须只依赖 Windows 自带 PowerShell 和 Provider 所需的 Python，不得要求 Node.js；
  - PowerShell installer 启动命令不得携带 provider id、server、credential、自动启动或其他配置参数，所有选项只从固定用户 `provider.yaml` 读取；
  - PowerShell installer 必须在 Windows 本机校验 `provider.yaml` 和凭据文件，校验 Provider 发布件并启动 Windows Python 进程；
  - Apps L1 必须发布零参数的纯 CMD installer，
    脚本只读取固定用户目录中的配置，不接受配置覆盖参数；
  - Windows 7、Windows 10 和 Windows 11 必须使用同一条 CMD 命令和同一个 CMD 脚本；
  - CMD installer 必须先探测系统 Python 与 Tkinter，
    版本和能力满足目标平台时必须复用现有运行时；
  - 系统运行时不满足时，CMD installer 必须在固定用户目录安装 Provider 专属私有 Python，
    不得修改系统 PATH、文件关联或全局 Python launcher；
  - 已有私有 Python 通过版本、Tkinter 和依赖校验时必须直接复用，
    不得重复下载、覆盖或安装；
  - 用户 YAML 必须允许用 `pythonRuntime` 选择 `auto`、`system` 或 `private`：
    - `auto` 依次尝试系统、已有私有和按需安装私有运行时；
    - `system` 只接受合适的系统 Python，缺失时必须报错并提示选择 `private`；
    - `private` 只复用或安装 Provider 专属 Python，不扫描系统 Python；
    - 明确选择 `system` 或 `private` 后禁止回退到另一类运行时；
  - CMD installer 必须显示有界的阶段、下载和安装进度，
    长时间操作不得表现为无输出黑框；
  - 每个实质下载必须至少每秒显示当前速度、已耗时秒数和预计剩余秒数，
    已知总大小时同时显示字节进度和百分比；
  - installer 必须通过有界连通性与延迟探测在官方源和大陆镜像之间自动选择，
    显示选中来源，并在下载或完整性校验失败时自动回退到下一个可用来源；
  - CMD installer 失败必须输出稳定错误码、失败阶段和恢复提示，
    不得只返回原生命令退出码；
  - installer 从正在运行的 Provider 会话内触发时，
    必须通过独立于旧 Provider 命令树的 Windows 原生交接进程完成重启，
    禁止先终止承载当前安装命令的旧进程再尝试启动新进程；
  - Windows 7 的私有运行时使用仍受官方支持的 Python 3.8 系列，
    Windows 10/11 的私有运行时使用 Python 3.11 系列；
  - Provider 源码和依赖必须同时支持 Python 3.8 与 Python 3.11，
    不得只让安装脚本完成下载后再在解释器启动阶段失败；
  - Human 页面必须使用标签页展示 PowerShell 安装和通用 CMD 安装，
    CMD 入口同时提供同源脚本下载；
  - 页面、安装合同和 installer 必须由 Apps owning YAML 声明固定路径和 L1 HTTPS origin，并复用同一 Apps native lifecycle。
- 验收：
  - 在同机 WSL provider 仍在线时启动 Windows provider；
  - 从原 `trans` 入口分别验证 `cmd`、PowerShell、只读文件操作和 stdin；
  - 云端节点状态必须显示 Windows runtime、Python 版本、`host.ssh` 能力和新 provider id；
  - Windows 桌面必须可见控制面板和托盘，关闭窗口后进程保持在线并可从托盘恢复；
  - `autoStart: true` 时必须验证当前用户登录启动项存在；
  - 必须验证启动后自动检查、手动检查、手动升级、版本变化、进程重启、TCP pool 恢复和升级备份；
  - 必须覆盖 32 路并发短命令、混合 stdout/stderr/exitCode、stdin、PowerShell、cmd、文件读写、上传下载校验、单大文件与并发小请求隔离、断连恢复和持续多轮零泄漏；
  - 并发结束后 TCP pool 必须恢复 `ready=desired`、`claimed=0`，不得出现数据尾部丢失、错误串线、假成功或永久通道损失；
  - 快速部署页必须从 owning YAML 固定 HTTPS origin 完成桌面和移动端 DOM、命令生成、复制或下载、Agent JSON 合同及浏览器错误验收；
  - 停止 Windows provider 后，同机 WSL provider 不受影响。

### 6.8 HWPOD-GW-REQ-008 Linux 原生 Python Provider

- 主责模块：
  - PJ2026-01010406 Linux节点。
- 关联模块：
  - [HWPOD工具](PJ2026-010102-hwpod-tools.md)；
  - [YAML运维](PJ2026-010603-yaml-first-ops.md)；
  - [平台运维](PJ2026-0106-platform-ops.md)。
- 共享实现：
  - Windows 与 Linux 必须发布同一个 Python Provider 文件；
  - WebSocket、TCP 数据池、会话、更新、日志、配置和凭据逻辑必须共用同一核心；
  - 平台差异只允许位于命令执行、生命周期、单实例、自动启动和本地交互层；
  - 禁止复制 Linux 专用 Provider 主体或引入 Docker、Node、WSL 和入站 SSH。
- Linux 运行形态：
  - Provider 必须作为 Linux host 原生 Python headless 进程运行；
  - 启动命令不得接收配置覆盖参数或环境变量；
  - 启动时必须从固定用户目录读取唯一 `~/.unidesk/provider.yaml`；
  - `autoStart: true` 必须注册为 systemd system service，并以配置所属用户运行；
  - systemd unit 必须使用前台进程、自动重启和有界停止，不得使用 daemonize、nohup 常驻或容器兜底；
  - 前台手动启动必须支持 `SIGINT` 与 `SIGTERM`，并在退出前关闭控制连接、数据通道和活跃子进程；
  - 同一 Linux 用户只允许运行一个实例。
- Linux `trans` 合同：
  - Provider 必须复用既有 `host.ssh` 与 `host.ssh.tcp-pool` 协议；
  - POSIX route 必须支持 Bash/argv、stdin、stdout、stderr、cwd、exitCode 和文件传输；
  - Linux 命令必须由登录 Bash 执行，并记录脱敏后的实际命令与 cwd；
  - 平台标签必须明确披露 Linux、headless、Python 版本、数据池状态和原生 attach mode；
  - 数据通道数量必须与 Windows 使用同一用户 YAML 合同，传输并发由调用端 owning YAML 控制。
- 分发与升级：
  - Apps L1 必须提供 Linux Bash 一行安装命令、同源脚本下载和 Agent JSON 合同；
  - Bash installer 必须零参数运行，只读取固定用户 YAML 和 `credentialFile`；
  - installer 必须校验 Python、PyYAML、发布字节数、SHA-256、语法和 Provider 标识；
  - `pythonRuntime` 的 `auto`、`system` 和 `private` 在 Linux 必须保持严格语义，明确选择后不得跨类型回退；
  - installer 必须原子安装 Provider 文件、生成 systemd unit、启动服务并输出结构化终态；
  - Linux 必须复用同一升级 manifest、下载 allowlist、空闲升级和备份合同；
  - systemd 运行时应用升级后必须由同一进程重启或 systemd 恢复，不得形成双实例。
- YAML-first 受控部署：
  - 平台运维必须在 Apps owning YAML 中声明目标 Provider ID、bootstrap route、用户目录、Secret `sourceRef`、systemd unit 和验收参数；
  - 受控 CLI 必须完成配置与凭据下发、安装提交、状态查询和验收；
  - Secret 只披露 presence 与 fingerprint，不得进入命令参数、日志、TaskTree 或 issue；
  - 长安装和压测必须 submit-and-poll，禁止让普通 `trans` 长连接承担整个生命周期。
- 验收：
  - 必须从 apps.hwpod.com 的 Linux 一行命令完成原生安装；
  - 必须从原 `trans` 入口验证 Bash、argv、stdin、cwd、stdout/stderr/exitCode、上传、下载和哈希；
  - 必须执行 YAML 声明的多轮并发短命令、大文件双向传输、并发隔离、断连恢复和池恢复压测；
  - 压测结束后 TCP pool 必须恢复 `ready=desired`、`claimed=0`，不得出现串线、假成功、数据损坏、进程泄漏或永久通道损失；
  - Apps 页面必须完成桌面与移动端平台切换、YAML 生成、命令复制、脚本下载和 Agent JSON 合同验收。