pikasTech-HWLAB/docs/reference/spec-v02-services.md

v0.2 微服务总体规格

本文是 HWLAB v0.2 微服务总体规格。它只定义组件取舍、依赖方向、语言迁移边界和裁撤口径；单个服务的 API、表结构、profile、权限、CI/CD 和 provider 细节应交叉引用对应规格，不在本文重复展开。

细节权威出处：

• 用户、权限、session 归属和 device pod grant：见 spec-user-access.md。
• device pod profile authority、REST/job 和 gateway 执行边界：见 spec-device-pod.md。
• v0.2 branch、namespace、GitOps、FRP、SecretRef 和发布验收：见 spec-v02-cicd.md。
• Code Agent provider profile、DeepSeek bridge、Codex loopback forwarder 和真实聊天验收：见 code-agent-chat-readiness.md。
• G14 GitOps、Tekton、Argo CD、registry 和外部稳定中间件边界：见 g14-gitops-cicd.md。
• 当前 gateway 主动出站 demo 仍可作为 transport 背景，正式 device pod 路径以 spec-device-pod.md 为准。

总体边界

• hwlab-cloud-api 是 v0.2 应用层 authority：用户身份、admin/user、code agent session owner、device pod grant、profile authority 和用户态 REST 都在这里判定。
• hwlab-cloud-web 只作为用户入口和 API proxy，不拥有业务 authority；CLI 可以旁路 UI，但不能旁路 cloud-api 的授权。
• hwlab-device-pod 是正式设备业务承载点；用户态请求必须走 cloud-api -> hwlab-device-pod -> hwlab-gateway -> device-host-cli -> hardware。
• hwlab-gateway 是 transport，不理解用户权限、不保存 profile authority；用户端已经验证稳定，v0.2 第一阶段先不改造它。
• Code Agent provider 通道分为 codex-api loopback forwarder 和 deepseek bridge/Moon Bridge；自研 bridge/forwarder 属于 HWLAB 常驻服务，Moon Bridge 是外部稳定服务。
• hwlab-router、hwlab-tunnel-client、hwlab-gateway-simu、hwlab-box-simu、hwlab-patch-panel 在 v0.2 裁撤；不再为这些裁撤对象保留单独规格文档。
• CLI、一次性脚本、render/publish/smoke helper、vendored 前端库和稳定外部服务不纳入 Bun + TypeScript 迁移范围。

依赖关系

v0.2 的主要请求链路按以下方向收敛：

browser
-> hwlab-cloud-web
-> hwlab-edge-proxy
-> hwlab-cloud-api
-> Postgres

cloud-web or device-pod-cli or code agent tool
-> hwlab-cloud-api
-> hwlab-device-pod
-> hwlab-gateway
-> device-host-cli
-> Keil / pyOCD / UART / target

hwlab-cloud-api
-> codex-api profile
-> hwlab-codex-api-responses-forwarder
-> hyueapi upstream

hwlab-cloud-api
-> deepseek profile
-> hwlab-deepseek-responses-bridge
-> Moon Bridge
-> DeepSeek upstream

origin/v0.2
-> G14 Tekton / BuildKit / registry
-> v0.2-gitops
-> Argo CD
-> hwlab-v02 namespace
-> 19666 / 19667

这些链路只表达总体依赖方向。接口、鉴权、SecretRef、health、job、profile 和 provider 行为以对应规格文档为准。

服务总表

对象	类型	总体依赖关系	v0.2 处理	Bun + TS	细节出处
hwlab-cloud-api	HWLAB 自研常驻服务	上游是 web、edge、CLI 和 agent 工具；下游是 Postgres、provider 通道、device-pod 和 agent runtime	保留并核心化	是，P0	spec-user-access.md、spec-device-pod.md、code-agent-chat-readiness.md
hwlab-cloud-web runtime wrapper	HWLAB 自研常驻 web/proxy wrapper	上游是浏览器；下游只代理 cloud-api	保留	是，P0；浏览器端 JS 另阶段处理	spec-user-access.md、cloud-workbench.md
hwlab-edge-proxy	HWLAB 自研常驻服务	上游是公网/FRP API 入口；下游是 cloud-api	保留	是，P0	spec-v02-cicd.md、dev-runtime-boundary.md
hwlab-device-pod	HWLAB 自研常驻服务	上游只能是 cloud-api 内部调用；下游是 gateway 和 host 侧设备工具	保留并增强	是，P0	spec-device-pod.md
hwlab-agent-mgr	HWLAB 自研常驻服务	属于 code agent session 管理面；不得与 cloud-api owner authority 冲突	保留，但职责需收敛	是，P1	spec-user-access.md、code-agent-chat-readiness.md
hwlab-codex-api-responses-forwarder	HWLAB 自研常驻 sidecar	上游是 cloud-api Pod-local codex-api profile；下游是 hyueapi upstream	保留	是，P1	code-agent-chat-readiness.md、g14-gitops-cicd.md
hwlab-deepseek-responses-bridge	HWLAB 自研常驻 sidecar	上游是 deepseek profile；下游是 Moon Bridge	保留	是，P1	code-agent-chat-readiness.md、g14-gitops-cicd.md
hwlab-agent-worker	HWLAB 自研 Job/执行入口	由 agent session 生命周期触发，不作为常驻 Deployment	保留，非第一波	建议迁，P2	code-agent-chat-readiness.md、spec-user-access.md
hwlab-agent-skills wrapper	HWLAB 自研 bundle/health wrapper	为 agent runtime 提供 skill bundle identity；业务能力由 skill 自身定义	保留	仅常驻 wrapper 需要，P2	code-agent-chat-readiness.md
hwlab-gateway	HWLAB 自研用户端/硬件 transport	上游由 device-pod 或受控 cloud 调用；下游是用户端硬件资源	保留	暂不迁	spec-device-pod.md、gateway-outbound-demo.md
hwlab-router	HWLAB 自研路由占位服务	可被 edge-proxy、cloud-api 和 FRP 路径替代	裁撤	否	本文即裁撤权威，不保留单独 spec
hwlab-tunnel-client	HWLAB 自研 tunnel 状态占位服务	真实入口由 FRP/GitOps lane 表达	裁撤	否	本文即裁撤权威，不保留单独 spec
hwlab-gateway-simu	HWLAB 自研模拟服务	旧 M3 模拟链路组件	裁撤	否	本文即裁撤权威，不保留单独 spec
hwlab-box-simu	HWLAB 自研模拟服务	旧 M3 模拟链路组件	裁撤	否	本文即裁撤权威，不保留单独 spec
hwlab-patch-panel	HWLAB 自研接线盘服务	旧 M3 接线盘链路组件	裁撤	否	本文即裁撤权威，不保留单独 spec
hwlab-cli	CLI/Job 工具	人工或 CI 入口；最终请求仍应走 cloud-api	保留灵活	否	spec-v02-cicd.md
device-pod-cli	CLI 工具	用户或 agent 工具入口；正式模式只请求 cloud-api REST	保留并改 REST 调用	否	spec-device-pod.md
render/publish/smoke scripts	一次性脚本	支撑 CI/CD、验证和开发流程，不常驻	保留现状	否	spec-v02-cicd.md、g14-gitops-cicd.md
browser-side Cloud Web JS	前端浏览器代码	运行在浏览器；通过 web/proxy 调 cloud-api	暂不纳入第一阶段	暂不强制	cloud-workbench.md
Moon Bridge	外部稳定服务	deepseek bridge 的下游转换层	保留	否	code-agent-chat-readiness.md、g14-gitops-cicd.md
frpc / frps	外部稳定服务	公网入口和反向隧道	保留	否	spec-v02-cicd.md
Postgres	外部稳定服务	cloud-api 的持久化数据底座	保留	否	spec-user-access.md、spec-v02-cicd.md
Argo CD / Tekton / BuildKit / registry	外部稳定服务	v0.2 CI/CD 和 GitOps 控制面	保留	否	spec-v02-cicd.md、g14-gitops-cicd.md
Codex CLI	外部工具/runtime	cloud-api code agent runtime 调用的外部 agent 工具	保留	否	code-agent-chat-readiness.md
Keil / pyOCD / UART 工具	外部或主机侧工具	由 device-host-cli 和 gateway 间接调用	保留	否	spec-device-pod.md

语言迁移边界

v0.2 服务语言统一只约束 HWLAB 仓库内自研、会以 Deployment、sidecar 或长期进程运行的 JavaScript 服务代码。稳定外部服务、外部镜像、第三方二进制、CLI、一次性脚本、测试脚本、GitOps/render/publish helper 和 vendored 代码不纳入迁移范围。

迁移目标：

• 自研常驻服务入口使用 Bun + TypeScript。
• Bun 负责运行 .ts；发布前必须通过 TypeScript 类型检查，不能只依赖 Bun 运行时转译。
• 镜像构建和 CI 原语校验必须包含 tsc --noEmit 或等价 bun run typecheck。
• 每个 .ts 文件不超过 2000 行；超过必须先拆模块，再迁移或继续开发。
• 一个服务迁移完成后，不长期保留 .mjs 和 .ts 双入口兼容；runtime command、health check、artifact inventory 和 GitOps render 必须收敛到单一入口。

第一阶段迁移集合：

hwlab-cloud-api
hwlab-cloud-web runtime wrapper
hwlab-edge-proxy
hwlab-device-pod
hwlab-agent-mgr
hwlab-codex-api-responses-forwarder
hwlab-deepseek-responses-bridge

后续迁移集合：

hwlab-agent-worker
hwlab-agent-skills wrapper

暂不迁移集合：

hwlab-gateway
hwlab-cli
device-pod-cli
scripts and tools
browser-side Cloud Web JS
stable external services

裁撤集合：

hwlab-router
hwlab-tunnel-client
hwlab-gateway-simu
hwlab-box-simu
hwlab-patch-panel

裁撤集合不再新增单服务 spec。若历史文档仍提到这些服务作为 v0.2 必需依赖，应删除旧口径或交叉引用本文。