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 需求规格模板
上级规格	PJ2026-0101 硬件池
规格治理索引	规格治理

本文采用 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标准。
• CLI/API 命令形态和结构化输出归 PJ2026-010102 HWPOD工具。
• 服务端 registry、租约、路由和结果归属归 PJ2026-010103 HWPOD服务。
• CaseRun 评价、aggregate 和训练反馈归 HarnessRL。

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 目标架构

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 数据流

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 关键时序

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服务、平台运维

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-010103 HWPOD服务

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标准、Agent编排

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

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

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

编号	短名	主责模块	关联模块
HWPOD-GW-REQ-004	原始事实	PJ2026-01010404 原始事实	HarnessRL、PJ2026-010102 HWPOD工具

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-010404 Project Management。
• 部署入口：
  • 必须使用 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服务；
  • 云端控制台。
• 发布元数据：
  • 服务端应公开 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工具；
  • YAML运维；
  • 平台运维。
• 运行形态：
  • 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工具；
  • YAML运维；
  • 平台运维。
• 共享实现：
  • 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 合同验收。