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