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：

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

HWPOD 快速闭环：

```text
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：

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

CI/CD：

```text
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](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-edge-proxy.md)、[spec-v02-hwlab-cloud-api.md](spec-v02-hwlab-cloud-api.md) |
| 用户、session、授权 | `/auth/*`、`/v1/admin/*`、`/v1/agent/chat*` | [spec-user-access.md](spec-user-access.md)、[spec-v02-openfga-authorization.md](spec-v02-openfga-authorization.md) |
| HWPOD 快速闭环 | `/v1/hwpod-node-ops`、`hwpod-cli`、`hwpod-ctl` | [spec-hwpod-harness.md](spec-hwpod-harness.md) |
| Gateway transport 诊断 | `cloud-api /v1/gateway/poll`、`/v1/gateway/result`、gateway `/status` | [spec-v02-hwlab-gateway.md](spec-v02-hwlab-gateway.md) |
| Code Agent provider | `deepseek` 和 `codex-api` provider profile | [spec-v02-deepseek-proxy.md](spec-v02-deepseek-proxy.md)、[spec-v02-codex-api-forwarder.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](agentrun-code-agent-dispatch.md)、[spec-v02-hwlab-agent-skills.md](spec-v02-hwlab-agent-skills.md) |
| 短连接 CLI | `G14:/root/hwlab-v02` 内直接运行 `hwlab-cli client ...` | [spec-v02-hwlab-cli.md](spec-v02-hwlab-cli.md) |
| Durable runtime store | Postgres TCP `5432` and cloud-api DB readiness | [spec-v02-postgres.md](spec-v02-postgres.md) |
| 公网 FRP | master `frps` + `hwlab-v02-frpc` TCP `19666/19667` | [spec-v02-frpc.md](spec-v02-frpc.md) |
| CI/CD 控制 | render、Tekton、GitOps、Argo、runtime health | [spec-v02-cicd.md](spec-v02-cicd.md) |

## 服务总表

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

## 裁撤集合

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

```text
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 不再包含裁撤对象。 |