v0.2 hwlab-device-pod 服务规格

本文描述 v02 中 hwlab-device-pod 微服务的部署和接口实现。逻辑 device-pod、profile authority、grant 和 job 模型的权威规格见 spec-device-pod.md。

在系统中的职责划分

承接 cloud-api -> hwlab-device-pod -> gateway/device-host-cli 的内部执行服务位置。
当前阶段只暴露 device-pod executor 边界；用户、profile、grant、lease 和 job authority 都在 hwlab-cloud-api，不能由该 Service 伪造或兜底。
普通用户和 Code Agent 不应直接调用该 Service；正式路径必须经过 hwlab-cloud-api 鉴权、grant 和 lease。

内部架构

cmd/hwlab-device-pod/main.ts 提供 HTTP server，端口默认 7601。
cmd/hwlab-device-pod/main.ts 返回 contractVersion=device-pod-executor-v1，并声明 authority=hwlab-cloud-api、fake=false。
internal/device-pod/fake-data.mjs 只保留为 legacy 前端/smoke fixture，不是 hwlab-device-pod 服务运行契约。
HWLAB_DEVICE_POD_ID 可指定默认 executor devicePodId；正式 profile 仍由 hwlab-cloud-api 的 device_pods.profile_json 管理。

API 接口说明

接口	说明
`GET /health`、`GET /health/live`	返回 `contractVersion=device-pod-executor-v1`、`authority=hwlab-cloud-api` 和 `fake=false`。
`GET /v1/device-pods`	返回 executor boundary 摘要，不表达用户可见 device pod authority。
`GET /v1/device-pods/{devicePodId}/status`	返回 blocked executor status；真实 profile/status 以 cloud-api `/v1/device-pods/{devicePodId}/status` 为准。
`GET /v1/device-pods/{devicePodId}/events`	返回 bounded executor boundary event，不伪造硬件事件。
`POST /v1/device-pods/{devicePodId}/jobs`	只接受 `hwlab-cloud-api` 内部调用；当前无 gateway/device-host-cli 连接时返回 `gateway_dispatch_unavailable`。

用户态 POST /jobs、job output/cancel 和 admin profile/grant API 由 hwlab-cloud-api 实现，应以 spec-device-pod.md 为目标。

测试规格

T1

阅读 docs/reference/spec-v02-hwlab-device-pod-service.md，然后用 cli 手动测试以下内容：访问 /health/live 和 /v1/device-pods，确认响应包含 contractVersion=device-pod-executor-v1、authority=hwlab-cloud-api 和 fake=false。

T2

阅读 docs/reference/spec-v02-hwlab-device-pod-service.md，然后用 cli 手动测试以下内容：通过 hwlab-cloud-api /v1/device-pods 访问 device pod authority，确认未登录返回认证错误，登录后只返回 actor 可见 device pod。

规格的实现情况

规格项	状态	说明
health 和 executor boundary REST	已实现	服务声明内部 executor、cloud-api authority 和非 fake 来源。
bounded events/status	已实现	只返回 executor boundary/blocker，不伪造硬件事件。
正式 profile authority	已在 cloud-api 实现	`hwlab-device-pod` 不读取或覆盖 `device_pods.profile_json`。
job lifecycle	部分实现	用户态 job 由 cloud-api 创建和持久化；executor 侧当前只保留内部 job 边界。
gateway/device-host-cli adapter	部分实现	cloud-api 已能向 gateway registry 分发；无在线 gateway 时返回 blocker。

3.3 KiB Raw Blame History