v0.2 hwlab-gateway 服务规格

hwlab-gateway 是 v02 的真实硬件/host transport 边界服务，内部端口 7001。它用于 gateway 主动出站 demo 和受控 shell dispatch，不是普通用户或前端可直连的硬件 API。

在系统中的职责划分

向 hwlab-cloud-api 注册 gateway session、resource 和 capability。
通过主动轮询 /v1/gateway/poll 获取 cloud-api 分发的 hardware.invoke.shell 请求，并把结果回传 /v1/gateway/result。
只做 transport 和 bounded command execution，不理解用户权限、device-pod grant 或业务授权。

内部架构

cmd/hwlab-gateway/main.ts 维护 gateway state、outbound poll loop、inflight request map 和 command execution，运行入口必须使用 Bun。
internal/cloud/gateway-demo-registry.ts 在 cloud-api 内保存 gateway session、队列和 pending result。
command execution 默认关闭；只有显式 HWLAB_GATEWAY_CMD_EXEC_ENABLED=1 或 demo open 时才执行 shell。

API 接口说明

接口	说明
`GET /health/live`	返回 gateway health、gatewayId、gatewaySessionId 和 outboundConnected。
`GET /status`	返回 session、registry、outbound poll 和 inflight 摘要。
`GET /capabilities`	返回 resource/capability 列表。
`POST cloud-api /v1/gateway/poll`	gateway 主动向 cloud-api 取任务。
`POST cloud-api /v1/gateway/result`	gateway 回传 JSON-RPC response。

测试规格

T1

阅读 docs/reference/spec-v02-hwlab-gateway.md，然后用 cli 手动测试以下内容：访问 gateway /health/live 和 /status，确认 gatewaySessionId、resourceId、capability 列表存在，且 command execution 状态清晰。

T2

阅读 docs/reference/spec-v02-hwlab-gateway.md，然后用 cli 手动测试以下内容：通过 cloud-api /v1/gateway/sessions 观察 gateway online/stale 状态；不要直接从前端或普通用户请求 gateway shell。

规格的实现情况

规格项	状态	说明
health/status/capabilities	已实现	gateway service 提供只读观测。
outbound poll/result	已实现	与 cloud-api registry 对接。
bounded shell execution	已实现	受 env 开关、timeout 和 output limit 约束。
device-pod grant/lease	不在本服务	由 cloud-api/device-pod 负责。
生产级 gateway 多租户隔离	未完全实现	当前是 demo/transport skeleton。

2.4 KiB Raw Blame History