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
需求规格模板	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 执行。
• 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、日志、托盘和更新能力，同时通过主动出站协议领取云端命令。
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 结果和错误语义。

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、客户端

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 中观察。