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 课题
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0101 硬件池
规格治理索引	规格治理

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

2. 目的和范围

2.1 目的

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

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

2.2 范围内

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

2.3 范围外

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

3. 术语表

术语	定义
AI 网关	靠近真实硬件的节点侧执行能力，包含 PC 客户端、硬件网关盒子或等价 HWPOD node。
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 命令不会遮蔽节点是否仍在心跳、是否仍能处理短状态查询。

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 后才暴露失败。

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 端口可达、进程在线或命令已发出等中间状态当作硬件动作成功。