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

v0.2 微服务总体规格

本文是 HWLAB v0.2 服务矩阵、稳定外部服务和 HWPOD 快速闭环边界的总览。单项服务 API、测试规格和实现状态以对应 docs/reference/spec-*.md 为准。

docs/reference/spec-*.md 是微服务、稳定外部服务、短连接 CLI 和系统能力的权威出处；代码开发和测试代码编写必须先对齐对应 spec，再修改实现或测试。

职责划分

hwlab-v02 是独立 runtime namespace，公网只暴露 19666/19667。浏览器进入 hwlab-cloud-web，应用 API 收敛到 hwlab-cloud-api，执行调度接入 AgentRun v0.1，HWPOD 快速闭环由 Code Agent workspace 内的 hwpod-cli、hwpod-ctl、hwpod-compiler-cli 和 host/edge 侧 hwpod-node 完成。

• hwlab-cloud-api 是 v0.2 应用层 authority：用户身份、admin/user、Code Agent session owner、OpenFGA relation、工具能力、HWPOD node-ops 转发和 trace/result 都在这里收口。
• hwlab-cloud-web 是用户入口和同源 API proxy，不拥有业务 authority。
• hwlab-edge-proxy 是公网 API/FRP 边界，不做业务权限。
• hwlab-gateway 只保留为底层 transport 诊断和历史硬件通道，不作为 HWPOD 产品主概念。
• hwlab-agent-skills 是 skills bundle 的 health/list 可见服务，不承载每次 Code Agent 对话的运行时依赖。
• hwpod-node 不部署为 G14 runtime Service；它运行在 PC host、AI 网关、调试器边缘设备或实验室控制盒上，通过 hwpod-node-ops 接收基础操作。
• hwpod-cli、hwpod-ctl 和 hwpod-compiler-cli 是 Code Agent workspace 内短连接工具，不进入 runtime service inventory、artifact catalog 或 GitOps desired state。
• hwlab-agent-mgr、hwlab-agent-worker、repo-owned codex-stdio supervisor、router、tunnel、模拟器和旧硬件执行服务不在 v0.2 runtime service matrix 中，不再生成 Deployment、Job template、Service、artifact 或 GitOps desired state。

主要链路

浏览器和 API：

browser
-> hwlab-cloud-web
-> hwlab-edge-proxy
-> hwlab-cloud-api
-> Postgres / OpenFGA / AgentRun / provider bridge

HWPOD 快速闭环：

Code Agent workspace
-> hwpod-cli or hwpod-ctl
-> hwpod-compiler-cli
-> hwlab-cloud-api /v1/hwpod-node-ops
-> hwpod-node
-> target device / workspace / debug probe / io probe

Code Agent provider：

hwlab-cloud-api
-> AgentRun v0.1
-> codex-api profile or deepseek profile
-> upstream provider

CI/CD：

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

API 接口说明

接口类别	入口	权威规格
浏览器工作台	http://74.48.78.17:19666/	spec-v02-hwlab-cloud-web.md
API/live 公网入口	http://74.48.78.17:19667/health/live 和同源 API	spec-v02-hwlab-edge-proxy.md、spec-v02-hwlab-cloud-api.md
用户、session、授权	/auth/*、/v1/admin/*、/v1/agent/chat*	spec-user-access.md、spec-v02-openfga-authorization.md
HWPOD 快速闭环	/v1/hwpod-node-ops、hwpod-cli、hwpod-ctl	spec-hwpod-harness.md
Gateway transport 诊断	cloud-api /v1/gateway/poll、/v1/gateway/result、gateway /status	spec-v02-hwlab-gateway.md
Code Agent provider	deepseek 和 codex-api provider profile	spec-v02-deepseek-proxy.md、spec-v02-codex-api-forwarder.md
Code Agent AgentRun 调度	hwlab-cloud-api 会话 owner/auth/trace -> AgentRun v0.1 dispatch	agentrun-code-agent-dispatch.md、spec-v02-hwlab-agent-skills.md
短连接 CLI	G14:/root/hwlab-v02 内直接运行 hwlab-cli client ...	spec-v02-hwlab-cli.md
Durable runtime store	Postgres TCP 5432 and cloud-api DB readiness	spec-v02-postgres.md
公网 FRP	master frps + hwlab-v02-frpc TCP 19666/19667	spec-v02-frpc.md
CI/CD 控制	render、Tekton、GitOps、Argo、runtime health	spec-v02-cicd.md

服务总表

对象	类型	v0.2 处理	细节出处
hwlab-cloud-api	HWLAB 自研常驻服务	保留并核心化	spec-v02-hwlab-cloud-api.md、spec-user-access.md、spec-hwpod-harness.md
hwlab-cloud-web	HWLAB 自研常驻 web/proxy wrapper	保留	spec-v02-hwlab-cloud-web.md、cloud-workbench.md
hwlab-edge-proxy	HWLAB 自研常驻服务	保留	spec-v02-hwlab-edge-proxy.md
hwlab-gateway	HWLAB 自研 transport	保留为底层 transport 诊断和兼容硬件通道，不作为 HWPOD 产品主概念	spec-v02-hwlab-gateway.md、gateway-outbound-demo.md
hwlab-agent-skills	HWLAB 自研 bundle/health wrapper	保留	spec-v02-hwlab-agent-skills.md
AgentRun v0.1 runner	共享 Agent 执行基础设施	外部基础设施接入，不进 HWLAB service/artifact matrix	agentrun-code-agent-dispatch.md
HWPOD workspace tools	短连接 CLI/skill	hwpod-cli、hwpod-ctl、hwpod-compiler-cli 放在 Code Agent workspace 内快速迭代	spec-hwpod-harness.md
hwpod-node	host/edge executor	运行在 PC host、AI 网关或调试器边缘设备；不进入 G14 runtime service inventory	spec-hwpod-harness.md
v0.2 Observability Monitoring	应用侧监控声明	保留为业务接入能力，不进 runtime service inventory	spec-v02-observability-monitoring.md
hwlab-codex-api-responses-forwarder	HWLAB 自研 sidecar	保留	spec-v02-codex-api-forwarder.md
hwlab-deepseek-responses-bridge / hwlab-deepseek-proxy	HWLAB 自研 bridge + Moon Bridge 外部依赖	保留	spec-v02-deepseek-proxy.md
Moon Bridge	外部稳定服务	保留	spec-v02-deepseek-proxy.md
frpc / frps	外部稳定服务	保留	spec-v02-frpc.md
Postgres	外部稳定服务	保留	spec-v02-postgres.md
OpenFGA	外部稳定服务 / 内部授权 PDP	新增并保留，ClusterIP-only	spec-v02-openfga-authorization.md
Argo CD / Tekton / BuildKit / registry	外部稳定服务	保留	spec-v02-cicd.md、g14-gitops-cicd.md
Codex CLI	外部工具/runtime	保留	code-agent-chat-readiness.md
Keil / pyOCD / UART 工具	外部或主机侧工具	由 HWPOD spec 和 node-ops 绑定使用	spec-hwpod-harness.md

裁撤集合

以下对象不再保留单服务 spec、GitOps desired state、artifact catalog、Tekton build task 或长期测试入口：

hwlab-router
hwlab-tunnel-client
hwlab-gateway-simu
hwlab-box-simu
hwlab-patch-panel
hwlab-agent-mgr
hwlab-agent-worker
旧硬件执行服务和旧本地设备 CLI

发现旧测试、旧预检、旧脚本或旧文档再次把这些对象作为 v0.2 目标行为时，直接删除旧断言并按本文服务矩阵收敛。

测试规格

T1

阅读 docs/reference/spec-v02-services.md，然后用 CLI 手动测试以下内容：列出 deploy/deploy.json、deploy/deploy.schema.json、deploy/artifact-catalog.dev.json 和 deploy/gitops/g14/runtime-v02，确认 runtime service set 只包含 hwlab-cloud-api、hwlab-cloud-web、hwlab-gateway、hwlab-edge-proxy 和 hwlab-agent-skills。

T2

阅读 docs/reference/spec-v02-services.md，然后用 CLI 手动测试以下内容：确认 hwpod-cli、hwpod-ctl、hwpod-compiler-cli 和 hwpod-node 不被渲染为 G14 Deployment、Service、Tekton build task 或 artifact service；它们属于 workspace/host 侧 HWPOD harness。

T3

阅读 docs/reference/spec-v02-services.md，然后用 CLI 手动测试以下内容：检查 docs/reference/spec-*.md 与 AGENTS.md 规格索引，确认裁撤集合没有单服务 spec 入口。

规格的实现情况

规格项	状态	说明
v0.2 总体依赖方向	已实现/持续约束	本文定义浏览器、API、HWPOD、provider 和 CI/CD 链路。
保留服务均有 spec	已实现	本文服务总表列出当前保留服务和 spec 文件。
稳定外部服务纳入 spec	已实现	Postgres、Codex API forwarder/hyueapi、DeepSeek/Moon Bridge、FRP 已独立成文或交叉引用权威规格。
HWPOD 快速闭环边界	已实现/持续约束	workspace-local tools、API node-ops 转发和 host/edge node 边界见 spec-hwpod-harness.md。
裁撤集合不进 runtime	已实现/持续约束	render、artifact catalog、Tekton build service set 和 cloud-api runtime env 不再包含裁撤对象。