# 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 需求规格模板](../../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 执行。
- 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、日志、托盘和更新能力，同时通过主动出站协议领取云端命令。 |
| 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服务](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 中观察。
