pikasTech-HWLAB/docs/reference/spec-v02-hwlab-cloud-api.md

v0.2 hwlab-cloud-api 服务规格

hwlab-cloud-api 是 v0.2 应用层核心服务，运行在 hwlab-v02 namespace，内部端口 6667，公网经 hwlab-edge-proxy 和 FRP 暴露为 http://74.48.78.17:19667。

在系统中的职责划分

• 承担 runtime health、DB readiness、用户/session 权限、Code Agent 对话、trace/result 轮询、gateway outbound registry、M3 IO 控制、device-pod authority/job 和 live build inventory。
• 是 hwlab-cloud-web、Code Agent session、device-pod 用户态操作和 gateway outbound poll 的唯一应用层收口点；普通用户不直接访问内部 hwlab-device-pod Service。
• 读取 hwlab-cloud-api-v02-db/database-url、hwlab-v02-code-agent-provider/openai-api-key 和 hwlab-v02-code-agent-codex-auth/auth.json 等 v02 独立 SecretRef；文档和日志只允许记录 SecretRef 名称、key、字节数或哈希指纹，不记录值。

内部架构

• cmd/hwlab-cloud-api/main.ts 负责启动 HTTP server、解析端口和 Code Agent timeout。
• internal/cloud/server.ts 负责 HTTP route、REST/RPC bridge、health、live-builds、device-pod authority、gateway poll/result 和 Code Agent chat。
• internal/cloud/access-control.ts 负责 /auth/*、admin/user、device pod profile/grant、device job lifecycle 和 Code Agent owner binding。
• internal/cloud/access-control.ts 也是账号 workspace authority：account_workspaces 记录同一账号的 Workbench 当前 workspace、selected conversation/session、active trace、provider profile 和 revision。
• internal/db/runtime-store.ts 和 internal/cloud/db-contract.ts 负责 Postgres runtime store 与 readiness 分层。
• internal/cloud/code-agent-*.ts 负责 Codex stdio session、trace store、result cache、provider profile 和取消/轮询。
• AgentRun v0.1 接入只使用标准 threadId 路径：POST /v1/agent/chat 收到的 conversationId/sessionId/threadId 必须写入 AgentRun command payload.threadId 和 SessionRef.threadId；协议字段、trace、result 和 conversation facts 都以该字段为唯一 thread identity。
• AgentRun run 级 events 写回 HWLAB trace 时必须按当前 commandId 归属过滤；同一 run 的旧 command 尾部事件不能混入后续 command trace。取消、失败或 blocked 轮次如果已有 assistant/tool 可读上下文，必须以脱敏、限长的 partial context 写入 conversation facts，供后续 inspect/--from-trace 和同一 thread 的下一轮使用。
• 传给 AgentRun runner Job 的 transientEnv 是短期运行上下文，数量不设固定 8 项上限；新增项必须仍满足最小必要、脱敏和 Secret 值不打印原则。
• 同 Pod sidecar hwlab-codex-api-forwarder 监听 127.0.0.1:49280/responses，用于 codex-api profile 直连 hyueapi，并保持 hyueapi 在 NO_PROXY 中。
• hwlab-code-agent-workspace PVC 挂载到 /workspace/hwlab，用于长会话 workspace；它是 cloud-api 运行资源，不是独立用户入口。

API 接口说明

接口	说明
GET /health、GET /health/live	返回 service identity、environment、revision、DB/runtime/Code Agent readiness 和 blocker。
GET /live	轻量 live 标记。
GET /v1	REST adapter 索引、RPC 方法、runtime readiness 和 device-pod/M3 能力摘要。
POST /rpc、POST /json-rpc	JSON-RPC 入口，支持 system、adapter、gateway、hardware、audit、evidence 和 M3 方法。
POST /v1/rpc/{method}	REST 到 JSON-RPC 的桥接入口。
GET /v1/device-pods...	经 cloud-api 鉴权后读取服务端 profile/grant/job authority；probe GET 会创建只读 device job 并经 hwlab-device-pod executor/gateway 执行或返回同源 blocker，不会回退到 fake device pod 数据。
GET /auth/session、POST /auth/login、POST /auth/logout	v0.2 本地用户 session 入口。
GET /v1/auth/session、GET /v1/users/me、GET /v1/access/status、GET /v1/setup/status	v0.2 用户/session/setup 的 REST 状态和兼容入口；响应不得暴露 password hash、session token 原文或 Secret 值。
POST /v1/admin/users、POST/PUT /v1/admin/device-pods、POST/DELETE /v1/admin/device-pod-grants...	admin 管理用户、device pod profile 和 grant 的入口。
GET/PATCH /v1/workbench/workspace、POST /v1/workbench/workspace/{id}/reset、GET /events	账号级共享 workspace authority；所有读写按 ownerUserId 隔离，写入使用 revision 防冲突，active trace 用于阻止同账号并发 Code Agent turn。
GET /v1/m3/status、POST /v1/m3/io	M3 只读/受控 IO 入口；写操作必须有明确 approval。
GET /v1/diagnostics/gate、GET /v1/live-builds	诊断和 live build inventory。
GET /v1/gateway/sessions、POST /v1/gateway/poll、POST /v1/gateway/result	gateway 主动出站注册、取任务和回传结果。
POST /v1/internal/device-pod/gateway-dispatch	仅接受 hwlab-device-pod 内部服务凭据，用于把 executor job dispatch 到 gateway poll/result；普通用户和 Code Agent 不可调用。
POST /v1/agent/chat、POST /v1/agent/chat/steer、GET /v1/agent/chat/result/{traceId}、GET /v1/agent/chat/trace/{traceId}、POST /v1/agent/chat/cancel	Code Agent 短连接提交、运行中 steer、轮询、trace 和取消。

用户、权限、device-pod 管理 API 的最终规格见 spec-user-access.md 和 spec-device-pod.md。

测试规格

T1

阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：访问 http://74.48.78.17:19667/health/live，确认 environment=v02、ready=true、DB runtime 为 Postgres，且响应不包含 Secret 值。

T2

阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：使用短连接 POST /v1/agent/chat 提交一次对话，再轮询 /v1/agent/chat/result/{traceId}，只有 status=completed 且 assistant reply 非空才算 Code Agent 通过；对运行中请求使用 POST /v1/agent/chat/steer 时，响应必须包含 target trace、steerTraceId、AgentRun runId/targetCommandId/steerCommandId 和继续观察原 trace 的 result/trace URL。

T2.1

阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：在同一 conversationId/sessionId/threadId 中先发起一轮会产生可见 assistant/tool 进展的 Code Agent 请求并取消，再发送“回答一下刚才调查结果”这类后续消息；第二轮必须继续使用同一个标准 threadId，且 trace/result 不能混入上一 command 的尾部事件。

T3

阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：未登录访问 /v1/device-pods 必须返回认证错误；登录后访问 device-pod list/status 时必须显示 contractVersion=device-pod-authority-v1 和 fake=false 来源，不得出现 fake fallback。

规格的实现情况

规格项	状态	说明
health/readiness	已实现	/health/live 汇总 DB、runtime、Code Agent 和 blocker。
Code Agent 短连接 submit/steer/result/trace/cancel	已实现	repo-owned Codex stdio、运行中 steer 和 provider profile 已接入。
Postgres durable runtime	已实现	通过 v02 独立 DB SecretRef 和 migration ledger 判定。
gateway outbound poll/result	已实现	支持 gateway 主动轮询和 hardware.invoke.shell 分发。
device-pod 正式权限/profile/job	部分实现	profile/grant/list/status/job 持久化在 cloud-api；用户态 probe GET 已收敛为只读 job；已提供内部 gateway dispatch route 供 hwlab-device-pod executor 下发到 device-host-cli，无在线 gateway/device-host-cli 时返回 blocker。
v0.2 admin/user 权限模型	部分实现	/auth/*、admin user/device-pod/grant API 和 Code Agent owner binding 已接入；生产 bootstrap 依赖 SecretRef。
账号共享 workspace authority	已实现	account_workspaces 持久化同账号 Web/CLI 共享 workspace，支持 revision 冲突、账号隔离、active trace 并发保护和 reset。