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

# v0.2 微服务总体规格

本文是 HWLAB `v0.2` 微服务总体规格和服务规格索引。它定义组件取舍、依赖方向、语言迁移边界、裁撤口径和单服务 spec 入口；单个服务的 API、测试规格和实现状态以对应 `docs/reference/spec-*.md` 为准。

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

细节权威出处：

- 用户、权限、session 归属和 device pod relation：见 [spec-user-access.md](spec-user-access.md)。
- OpenFGA 细粒度授权、Admin Access 管理页和同路径 CLI：见 [spec-v02-openfga-authorization.md](spec-v02-openfga-authorization.md)。
- device pod profile authority、REST/job 和 gateway 执行边界：见 [spec-device-pod.md](spec-device-pod.md)。
- `v0.2` branch、namespace、GitOps、FRP、SecretRef 和发布验收：见 [spec-v02-cicd.md](spec-v02-cicd.md)。
- Code Agent provider 真实聊天验收：见 [code-agent-chat-readiness.md](code-agent-chat-readiness.md)。
- G14 GitOps、Tekton、Argo CD、registry 和外部稳定中间件边界：见 [g14-gitops-cicd.md](g14-gitops-cicd.md)。
- 保留服务、稳定外部服务和短连接 CLI 的单项 spec：见本文“服务总表”。

## 在系统中的职责划分

`hwlab-v02` 是独立 runtime namespace，公网只暴露 `19666/19667`。浏览器进入 `hwlab-cloud-web`，API、agent、device 和 gateway 请求收敛到 `hwlab-cloud-api`，内部硬件与 agent 能力由专门服务承接，稳定外部服务只提供数据库、模型桥、provider 通道和 FRP 入口。

- `hwlab-cloud-api` 是 v0.2 应用层 authority：用户身份、`admin/user`、Code Agent session owner、OpenFGA relation、profile authority 和用户态 REST 都在这里判定。
- OpenFGA 是 `hwlab-v02` 内部稳定授权服务，只作为 cloud-api 的 PDP/relationship store；Keycloak、Cloud Web、CLI、AgentRun runner 和普通用户都不能直接调用 OpenFGA。
- `hwlab-cloud-web` 只作为用户入口和 API proxy，不拥有业务 authority；CLI 可以旁路 UI，但不能旁路 `cloud-api` 的授权。
- `hwlab-device-pod` 是正式设备业务承载点；用户态请求必须走 `cloud-api -> hwlab-device-pod -> hwlab-gateway -> device-host-cli -> hardware`。
- Code Agent session 归属、鉴权、trace 和用户态 API 收敛在 `hwlab-cloud-api`；执行调度接入 AgentRun v0.1 共享基础设施。`hwlab-agent-mgr`、`hwlab-agent-worker` 和 repo-owned codex-stdio supervisor 不是 v0.2 runtime service matrix，不再生成 Deployment、Job template、Service、artifact 或 GitOps desired state。
- `hwlab-gateway` 是 transport，不理解用户权限、不保存 profile authority；用户端已经验证稳定，v0.2 第一阶段先不改造它。
- Code Agent provider 通道分为 `codex-api` loopback forwarder 和 `deepseek` bridge/Moon Bridge；自研 bridge/forwarder 属于 HWLAB 常驻服务，Moon Bridge 和 hyueapi/DeepSeek upstream 是稳定外部依赖。
- `hwlab-router`、`hwlab-tunnel-client`、`hwlab-gateway-simu`、`hwlab-box-simu`、`hwlab-patch-panel` 在 v0.2 裁撤；不再为这些裁撤对象保留单独规格文档。
- `hwlab-cli` 是固定 repo 内短连接业务 client，不是镜像、常驻服务或 Job template；一次性脚本、render/publish/smoke helper、vendored 前端库和稳定外部服务不纳入 Bun + TypeScript 常驻服务迁移范围，短连接 CLI 自身按 [spec-v02-hwlab-cli.md](spec-v02-hwlab-cli.md) 使用 Bun + TypeScript。

## 内部架构

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

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

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

```text
hwlab-cloud-api
-> OpenFGA
-> Postgres
```

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

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

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

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

## 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-hwlab-cloud-api.md](spec-v02-hwlab-cloud-api.md) |
| OpenFGA 授权管理 | `/v1/admin/access*`、`hwlab-cli client access ...`、Cloud Web Access 页面 | [spec-v02-openfga-authorization.md](spec-v02-openfga-authorization.md) |
| Device Pod | `/v1/device-pods*`、正式 job/admin API | [spec-device-pod.md](spec-device-pod.md)、[spec-v02-hwlab-device-pod-service.md](spec-v02-hwlab-device-pod-service.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) |

服务级 HTTP、CLI、Job 或 TCP 接口以各服务 spec 为准。用户态入口只走 `19666/19667`，内部服务只通过 ClusterIP 或 Job 模板调用，稳定外部服务只暴露最小必要协议，不向普通用户开放 Kubernetes、Secret、Service 直连或 provider 凭据。

## 服务总表

| 对象 | 类型 | v0.2 处理 | Bun + TS | 细节出处 |
| --- | --- | --- | --- | --- |
| `hwlab-cloud-api` | HWLAB 自研常驻服务 | 保留并核心化 | 是，P0 | [spec-v02-hwlab-cloud-api.md](spec-v02-hwlab-cloud-api.md)、[spec-user-access.md](spec-user-access.md)、[spec-device-pod.md](spec-device-pod.md) |
| `hwlab-cloud-web` runtime wrapper | HWLAB 自研常驻 web/proxy wrapper | 保留 | 是，P0 | [spec-v02-hwlab-cloud-web.md](spec-v02-hwlab-cloud-web.md)、[cloud-workbench.md](cloud-workbench.md) |
| `hwlab-edge-proxy` | HWLAB 自研常驻服务 | 保留 | 是，P0 | [spec-v02-hwlab-edge-proxy.md](spec-v02-hwlab-edge-proxy.md) |
| `hwlab-device-pod` | HWLAB 自研常驻服务 | 保留并增强 | 是，P0 | [spec-v02-hwlab-device-pod-service.md](spec-v02-hwlab-device-pod-service.md)、[spec-device-pod.md](spec-device-pod.md) |
| `hwlab-codex-api-responses-forwarder` | HWLAB 自研常驻 sidecar | 保留 | 是，P1 | [spec-v02-codex-api-forwarder.md](spec-v02-codex-api-forwarder.md) |
| `hwlab-deepseek-responses-bridge` / `hwlab-deepseek-proxy` | HWLAB 自研 bridge + Moon Bridge 外部依赖 | 保留 | 是，P1 for bridge | [spec-v02-deepseek-proxy.md](spec-v02-deepseek-proxy.md) |
| AgentRun v0.1 runner | 共享 Agent 执行基础设施 | 作为外部基础设施接入，不进 HWLAB service/artifact matrix | 否 | [agentrun-code-agent-dispatch.md](agentrun-code-agent-dispatch.md) |
| `hwlab-agent-skills` wrapper | HWLAB 自研 bundle/health wrapper | 保留 | 仅常驻 wrapper 需要，P2 | [spec-v02-hwlab-agent-skills.md](spec-v02-hwlab-agent-skills.md) |
| `hwlab-gateway` | HWLAB 自研用户端/硬件 transport | 保留 | 暂不迁 | [spec-v02-hwlab-gateway.md](spec-v02-hwlab-gateway.md)、[gateway-outbound-demo.md](gateway-outbound-demo.md) |
| v0.2 Observability Monitoring | 应用侧监控声明 | 保留为业务接入能力，不进 runtime service inventory | 否 | [spec-v02-observability-monitoring.md](spec-v02-observability-monitoring.md) |
| `hwlab-router` | HWLAB 自研路由占位服务 | 裁撤 | 否 | 本文即裁撤权威，不保留单独 spec |
| `hwlab-tunnel-client` | HWLAB 自研 tunnel 状态占位服务 | 裁撤 | 否 | 本文即裁撤权威，不保留单独 spec |
| `hwlab-gateway-simu` | HWLAB 自研模拟服务 | 裁撤 | 否 | 本文即裁撤权威，不保留单独 spec |
| `hwlab-box-simu` | HWLAB 自研模拟服务 | 裁撤 | 否 | 本文即裁撤权威，不保留单独 spec |
| `hwlab-patch-panel` | HWLAB 自研接线盘服务 | 裁撤 | 否 | 本文即裁撤权威，不保留单独 spec |
| `hwlab-cli` | 固定 repo 短连接 client | 保留为 WEB 等价非视觉业务入口，不进 runtime service inventory | 是，CLI 自身 | [spec-v02-hwlab-cli.md](spec-v02-hwlab-cli.md) |
| `device-pod-cli` | CLI 工具 | 保留并改 REST 调用 | 否 | [spec-device-pod.md](spec-device-pod.md) |
| render/publish/smoke scripts | 一次性脚本 | 保留现状 | 否 | [spec-v02-cicd.md](spec-v02-cicd.md)、[g14-gitops-cicd.md](g14-gitops-cicd.md) |
| browser-side Cloud Web JS | HWLAB 自研前端浏览器代码 | 保留并 TS 化 | 是，P0 | [spec-v02-hwlab-cloud-web.md](spec-v02-hwlab-cloud-web.md)、[cloud-workbench.md](cloud-workbench.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 工具 | 外部或主机侧工具 | 保留 | 否 | [spec-device-pod.md](spec-device-pod.md) |

## 语言迁移边界

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

迁移目标：

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

第一阶段迁移集合：

```text
hwlab-cloud-api
hwlab-cloud-web runtime wrapper
hwlab-edge-proxy
hwlab-device-pod
hwlab-codex-api-responses-forwarder
hwlab-deepseek-responses-bridge
browser-side Cloud Web JS
```

后续迁移集合：

```text
hwlab-agent-skills wrapper
```

暂不迁移集合：

```text
hwlab-gateway
device-pod-cli
scripts and tools
stable external services
```

裁撤集合：

```text
hwlab-router
hwlab-tunnel-client
hwlab-gateway-simu
hwlab-box-simu
hwlab-patch-panel
hwlab-agent-mgr
hwlab-agent-worker
```

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

## 测试规格

## T1

阅读 docs/reference/spec-v02-services.md，然后用 cli 手动测试以下内容：列出 `docs/reference/spec-*.md`，确认 AGENTS.md 的“规格”部分索引了全部 spec，且没有 `hwlab-router`、`hwlab-tunnel-client`、`hwlab-gateway-simu`、`hwlab-box-simu` 或 `hwlab-patch-panel` 的单服务 spec 入口。

## T2

阅读 docs/reference/spec-v02-services.md，然后用 cli 手动测试以下内容：从 `deploy/gitops/g14/runtime-v02` 读取 Deployment、StatefulSet、Service 和 Job 模板，确认每个保留服务和稳定外部服务都有对应 spec；确认 `hwlab-router`、`hwlab-tunnel-client`、`hwlab-gateway-simu`、`hwlab-box-simu` 和 `hwlab-patch-panel` 不再出现在 v0.2 runtime desired state 或 v0.2 artifact catalog 中。

## T3

阅读 docs/reference/spec-v02-services.md，然后用 cli 手动测试以下内容：检查自研常驻服务和 browser-side Cloud Web JS 是否被列入 Bun + TypeScript 迁移集合，确认 CLI、一次性脚本、vendored 代码和稳定外部服务不被误纳入迁移范围。

## T4

阅读 docs/reference/spec-v02-services.md，然后用 cli 手动测试以下内容：逐个检查 `docs/reference/spec-*.md` 是否包含“在系统中的职责划分”“内部架构”“API 接口说明”“测试规格”“规格的实现情况”五个部分。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| v0.2 总体依赖方向 | 已实现 | 本文定义浏览器、API、device、provider 和 CI/CD 链路。 |
| 保留服务均有 spec | 已实现 | 本文服务总表列出当前保留服务和 spec 文件。 |
| 稳定外部服务纳入 spec | 已实现 | Postgres、Codex API forwarder/hyueapi、DeepSeek/Moon Bridge、FRP 已独立成文或交叉引用权威规格。 |
| OpenFGA 授权服务纳入 spec | 目标状态 | 需要按 [spec-v02-openfga-authorization.md](spec-v02-openfga-authorization.md) 完成 GitOps、cloud-api、WebUI 和 CLI。 |
| `simu`、接线盘、router、tunnel-client 裁撤 | 已实现 | 本文记录裁撤口径；v0.2 render、artifact catalog、Tekton build service set 和 cloud-api 运行时 env 不再包含裁撤对象。 |
| Bun + TypeScript 迁移边界 | 已实现 | 本文区分第一阶段、后续、暂不迁移和裁撤集合。 |
| spec 作为开发和测试权威 | 已实现 | AGENTS.md 规格区提供顶级索引。 |