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 管理。
HWLAB_CLOUD_API_INTERNAL_URL 配置后，executor 可用内部服务凭据回调 hwlab-cloud-api 的 gateway dispatch route，把已授权 job 下发到 gateway/device-host-cli；内部 job 和 dispatch 必须同时携带 x-hwlab-internal-service 与 HWLAB_DEVICE_POD_INTERNAL_TOKEN 对应的 x-hwlab-internal-token。未配置内部 token、profile route 缺失或 gateway 不在线时返回 blocker/拒绝执行。
hwlab-cloud-api 的用户态 device-pod job/probe 必须经 HWLAB_DEVICE_POD_URL 指向的 hwlab-device-pod executor；未配置 executor 时只创建 blocked job 并返回 device_pod_executor_unavailable，不得直接绕过 executor 调用 gateway/device-host-cli。

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`	只接受带内部 token 的 `hwlab-cloud-api` 调用；创建内部 executor job 并返回 job、freshness、output/cancel URL；有可用 profile route 和 `HWLAB_CLOUD_API_INTERNAL_URL` 时通过 cloud-api gateway dispatch 下发到 device-host-cli，否则返回 `gateway_dispatch_unavailable`。
`GET /v1/device-pods/{devicePodId}/jobs/{jobId}`、`GET /output`、`POST /cancel`	只接受带内部 token 的 `hwlab-cloud-api` 调用，用于查询内部 job、最大 12000 bytes 的 bounded output 和取消非终态 job；普通用户仍必须走 cloud-api 用户态 API。

用户态 POST /jobs、job output/cancel、admin profile/grant API 和正式 device-pod-cli REST 调用由 hwlab-cloud-api 实现，应以 spec-device-pod.md 为目标。hwlab-device-pod 不接受 CLI、浏览器或 Code Agent 直接上传 profile snapshot。

测试规格

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 鉴权、授权、lease 校验和持久化；executor 侧已提供内部 job create/get/output/cancel lifecycle，并能把 job dispatch 结果写回 bounded output。
gateway/device-host-cli adapter	部分实现	executor 已通过 cloud-api internal dispatch 接入 gateway poll/result 和 device-host-cli 命令映射；真实执行仍依赖 profile route、在线 gateway 和 host CLI。
device-pod-cli REST authority	已实现	`tools/device-pod-cli.ts` 默认只走 cloud-api REST，不读取 `.device-pod/*.json` 作为 profile authority；旧 `.mjs` 入口只负责启动 TypeScript CLI。

4.9 KiB Raw Blame History