docs: add v02 service specs

docs/reference/spec-device-pod.md

@@ -13,6 +13,12 @@ device-pod-cli or cloud-web
 -> Keil / pyOCD / UART / target
 ```
 
+## 在系统中的职责划分
+
+`device-pod` 是云端可授权、可租约保护、可审计的逻辑设备能力单元。`hwlab-cloud-api` 是用户身份、grant、lease、profile authority 和用户态 REST API 的入口；`hwlab-device-pod` 是内部执行服务；`hwlab-gateway` 只承载 transport；`device-host-cli` 只在硬件 host 侧执行 Keil、pyOCD、UART 和 workspace 操作。
+
+普通用户、浏览器和 Code Agent session 不直接持有 gateway route、host workspace route、Kubernetes Service 直连能力或 profile 修改权。
+
 ## 设计目标
 
 - 用最少组件把 `device-pod-cli` 从“本地 profile + RPC/gateway 调用”迁到“1:1 REST 请求”。
@@ -74,6 +80,12 @@ code agent 本地文件只能作为非权威 hint/cache，最多包含：
 
 正式 profile 必须由 `cloud-api` 从 DB 读取；`hwlab-device-pod` 不接受浏览器、code agent 或 CLI 上传的 profile 作为执行依据。若 `hwlab-device-pod` 需要 profile snapshot，应只接受 `cloud-api` 内部服务凭据转发的 snapshot，或通过内部服务凭据向 `cloud-api` 拉取。该凭据不得挂载进 code agent session Pod。
 
+## 内部架构
+
+正式 device-pod 由 profile registry、job lifecycle、freshness/blocker、bounded output、gateway/device-host adapter 和 lease integration 组成。第一阶段只有一个 `hwlab-device-pod` Deployment 管理多个 `devicePodId`；profile authority 和 user grant 在 cloud-api/Postgres 中，device-pod 服务只接受 cloud-api 内部调用。
+
+当前 v02 部署中的 `hwlab-device-pod` 微服务实现情况见 [spec-v02-hwlab-device-pod-service.md](spec-v02-hwlab-device-pod-service.md)。
+
 ## Profile Shape
 
 `device_pods.profile_json` 至少表达以下 server-side 字段：
@@ -135,6 +147,8 @@ CREATE TABLE IF NOT EXISTS device_pods (
 
 ## REST API
 
+## API 接口说明
+
 用户态 API 只经过 `cloud-api` 暴露：
 
 ```text
@@ -226,3 +240,28 @@ manages: many devicePodId
 - `hwlab-device-pod` 一个实例可以列出并执行多个 `devicePodId` 的状态/job。
 - fake fallback 只能标记为 fake/source，不得作为正式 device-pod DEV-LIVE 证据。
 - 强副作用 job 必须有 reason，并在物理互斥需要时获取 `device_leases`。
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-device-pod.md，然后用 cli 手动测试以下内容：普通用户无 grant 时访问 `/v1/device-pods` 不得看到任何 device pod；获得 grant 后能看到对应 devicePodId 和脱敏 profileHash，不能看到 gatewaySessionId、hostWorkspaceRoot 或 probe UID 等敏感路由字段。
+
+## T2
+
+阅读 docs/reference/spec-device-pod.md，然后用 cli 手动测试以下内容：尝试通过本地 `.device-pod/*.json` 修改 gateway route 或 workspace route，正式 cloud-api/device-pod 路径必须忽略该本地文件并继续使用服务端 profile authority。
+
+## T3
+
+阅读 docs/reference/spec-device-pod.md，然后用 cli 手动测试以下内容：提交一个强副作用 job，例如 download/reset，缺少 reason 或 lease 时必须被拒绝；获得 lease 后响应必须包含 devicePodId、profileHash、traceId、operationId、freshness、blocker 和 bounded output metadata。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| 逻辑 device-pod 模型 | 已实现为规格 | 四要素、profile shape 和 Kubernetes 口径已定义。 |
+| profile server authority | 未完全实现 | 当前 v02 device-pod 服务未读取正式 DB profile。 |
+| 用户 grant + lease | 未完全实现 | 与 spec-user-access 配套，仍待完整实现。 |
+| REST/job API | 未完全实现 | 当前只读/fake device-pod payload 已部署，正式 job lifecycle 未完成。 |
+| 禁止 fake 作为 DEV-LIVE | 已实现/持续约束 | 规格和服务 payload 要求显式标记 fake/source。 |
+

docs/reference/spec-user-access.md

@@ -4,6 +4,12 @@
 
 本规格与 [spec-device-pod.md](spec-device-pod.md) 配套：用户和权限规格定义谁可以看见、创建和使用 device pod；device-pod 规格定义 profile authority、REST/job 和硬件执行边界。
 
+## 在系统中的职责划分
+
+用户和权限管理不是独立微服务，权威实现收敛在 `hwlab-cloud-api`：它负责登录、session、角色、device pod grant、device lease 和 code agent session owner 校验。`hwlab-cloud-web` 只提供浏览器 UI 和同源代理；`hwlab-device-pod` 只执行设备语义；`hwlab-agent-mgr`、`hwlab-agent-worker` 和 Code Agent runtime 只能消费已经由 cloud-api 判断过的 actor/session/device 权限。
+
+Postgres 是该规格的数据持久化边界。Kubernetes namespace、ServiceAccount、Service 直连和 gateway route 都不能替代用户权限模型；普通用户不获得 kubeconfig、内部 Service 直连能力或长期 Secret。
+
 ## 规格目标
 
 - 只保留两类角色：`admin` 和 `user`。
@@ -251,6 +257,25 @@ code agent turn
 
 code agent prompt、runner 或 worker 不得直接绕过 cloud-api 调用 device pod Service。device pod 服务只信任来自 cloud-api 的内部调用，不做最终用户权限判断。
 
+## 内部架构
+
+`hwlab-cloud-api` 内部应按 auth/session、authorization、agent session owner、device-pod grant、device lease 和 admin API 模块分层。所有模块共享同一 Postgres runtime store 和 migration ledger，避免拆出早期 `hwlab-user-api` 造成跨服务一致性成本。
+
+`user_sessions` 存浏览器 session token hash；`agent_sessions.owner_user_id` 绑定 Code Agent session；`device_pods` 存 profile authority；`device_pod_grants` 表示用户对 device pod 的完整使用权；`device_leases` 只表达物理设备互斥，不表达权限。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `POST /auth/login` | 校验本地账号并写入 `user_sessions` token hash。 |
+| `GET /auth/session` | 从 cookie 恢复 actor、role 和 session 状态。 |
+| `POST /auth/logout` | 设置 `revoked_at`，撤销当前 browser session。 |
+| `POST /v1/admin/users` | admin 创建用户，响应不得返回 `password_hash` 或 token。 |
+| `POST /v1/admin/device-pods`、`PUT /v1/admin/device-pods/{devicePodId}` | admin 管理 device pod profile authority。 |
+| `POST /v1/admin/device-pod-grants`、`DELETE /v1/admin/device-pod-grants/{devicePodId}/{userId}` | admin 授权或撤销普通用户使用 device pod。 |
+| `GET /v1/device-pods` 和 device-pod 操作 API | 按 actor role 和 grant 过滤可见/可用 device pod。 |
+| `POST /v1/agent/chat` 及 result/trace/cancel | 必须校验 `agent_sessions.owner_user_id`；admin 可跨用户查看和取消。 |
+
 ## 微服务设计
 
 v0.2 不新增独立用户管理微服务。用户管理、登录、session、device pod grant 和 code agent owner 校验全部放在 `hwlab-cloud-api` 内，理由是：
@@ -283,3 +308,28 @@ Kubernetes 只做运行时隔离和资源兜底，不承载 HWLAB 用户权限
 - 第一轮不引入 Keycloak、Dex、oauth2-proxy、OpenFGA、Capsule、vCluster、Kyverno 或 service mesh；需要正式外部身份源或集群 admission 兜底时再单独设计。
 
 当前态、差距和迁移步骤见 [../plan/v02-multi-user-migration.md](../plan/v02-multi-user-migration.md)。
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-user-access.md，然后用 cli 手动测试以下内容：创建或确认 bootstrap admin，登录后访问 `/auth/session`，确认响应包含 actor、role 和 active session，不包含 password hash、session token 原文或 Secret 值。
+
+## T2
+
+阅读 docs/reference/spec-user-access.md，然后用 cli 手动测试以下内容：用 admin 创建普通用户和 device pod grant，再用普通用户列出 `/v1/device-pods`，确认只能看到被授权 device pod；撤销授权后同一用户不能再看到或使用该 device pod。
+
+## T3
+
+阅读 docs/reference/spec-user-access.md，然后用 cli 手动测试以下内容：普通用户创建 Code Agent session 后，只能读取、继续和取消自己的 trace/result；另一个普通用户访问该 session 必须失败，admin 可以跨用户查看或取消。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| admin/user 两角色模型 | 未完全实现 | 表结构和链路已定义，完整 cloud-api auth/authorization 仍待收敛。 |
+| `users`、`user_sessions`、grant/lease 表 | 未完全实现 | 推荐迁移已定义，需实现 migration 和 runtime store。 |
+| Code Agent owner 绑定 | 未完全实现 | `agent_sessions` 已存在，owner 字段和鉴权链路仍需落地。 |
+| device pod 授权模型 | 未完全实现 | grant 语义已定义；当前 device-pod 仍主要是 fake/只读 payload。 |
+| 不用 Kubernetes 表达用户权限 | 已实现/持续约束 | 规格明确禁止普通用户持有 kubeconfig 或直连 Service 权限。 |
+

docs/reference/spec-v02-cicd.md

@@ -4,6 +4,24 @@
 
 实施跟踪见 [pikasTech/HWLAB#530](https://github.com/pikasTech/HWLAB/issues/530)，阶段计划见 [../plan/hwlab-v02-namespace-cicd.md](../plan/hwlab-v02-namespace-cicd.md)。本文只记录稳定规格、边界和判定标准；不要把一次性执行记录、排障流水账或临时证据写入本文。
 
+## 在系统中的职责划分
+
+`v0.2` CI/CD 是 G14 上的加法 lane：source branch、GitOps branch、runtime namespace、artifact catalog、Argo Application、Tekton Pipeline 和 FRP 入口均独立于 DEV/PROD。它共享 G14 k3s、Tekton controller、Argo CD controller、本地 registry 和构建工具，但不能复用 DEV/PROD runtime path、namespace、Application 或公网端口作为 v02 发布证据。
+
+## 内部架构
+
+CI/CD 内部由 branch poller、PipelineRun、component planner、BuildKit publish、GitOps promotion、Argo sync 和公网验收构成。source branch 只保存源码和人写配置；`v0.2-gitops` branch 保存 catalog 和 rendered runtime desired state；live runtime 是最终通过证据。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `scripts/g14-gitops-render.mjs --lane v02` | v02 GitOps render 入口，负责 namespace、runtime path、catalog 和 endpoint 固定。 |
+| Tekton `hwlab-v02-ci-image-publish` | 构建 affected images、复用 unchanged digest，并 promotion 到 `v0.2-gitops`。 |
+| Argo `argocd/hwlab-g14-v02` | 从 `v0.2-gitops:deploy/gitops/g14/runtime-v02` 同步到 `hwlab-v02`。 |
+| `http://74.48.78.17:19666/` | v02 Cloud Web 公网入口。 |
+| `http://74.48.78.17:19667/health/live` | v02 API/live 公网验收入口。 |
+
 ## 规格目标
 
 - `v0.2` 固定作为 G14 上的新增 CI/CD lane，不改写现有 `G14` DEV/PROD lane。
@@ -146,6 +164,35 @@
 
 GitOps branch 已更新、source branch render 通过、PipelineRun 名称存在或 `G14` DEV/PROD health 正常，都不能单独代表 `v0.2` CI/CD 通过。
 
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：确认 `origin/v0.2` 最新 commit 对应的 PipelineRun 完成，promotion 只写入 `v0.2-gitops`，且 source branch 没有跟踪 `deploy/artifact-catalog.v02.json` 或 `deploy/gitops/g14/runtime-v02/**` 生成物。
+
+## T2
+
+阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：查询 Argo `hwlab-g14-v02`，确认 source branch/path 为 `v0.2-gitops:deploy/gitops/g14/runtime-v02`，destination namespace 为 `hwlab-v02`，sync revision 与目标 GitOps revision 对齐。
+
+## T3
+
+阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：访问 `http://74.48.78.17:19666/` 和 `http://74.48.78.17:19667/health/live`，确认公网入口、payload environment、revision 和 runtime identity 都指向 v02，不把 DEV/PROD health 当作 v02 证据。
+
+## T4
+
+阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：涉及 Code Agent 时使用短连接 submit/result/trace 轮询，确认 `status=completed` 且 assistant reply 非空；不得只用 `/health/live` 中 `codeAgent=ready` 证明 provider 鉴权通过。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| v02 独立 source/GitOps/runtime lane | 已实现 | `v0.2`、`v0.2-gitops`、`hwlab-v02` 和 `runtime-v02` 已固定。 |
+| Tekton poller/pipeline/promotion | 已实现 | 通过 `hwlab-v02-*` 对象和 GitOps promotion 管理。 |
+| Argo v02 Application | 已实现 | `hwlab-g14-v02` 指向 v02 GitOps path 和 namespace。 |
+| FRP `19666/19667` 入口 | 已实现 | 由 `hwlab-v02-frpc` 与 master frps allowlist 共同提供。 |
+| SecretRef 独立与 provider 验收 | 已实现/持续约束 | SecretRef 已独立；验收必须做真实短连接聊天。 |
+| 自动 registry GC | 未实现 | 初期不启用自动 GC，后续需 lane/profile 保护集。 |
+
 ## 平行 lane 运维边界
 
 后续新增 `v0.x` 或其他平行 runtime lane 时，优先复用本节的判定顺序和排障边界，避免把一次性补丁沉淀成新的宽泛门禁。本节只保留可复用的运维边界；具体执行记录、排障流水和一次性证据应放在 issue、PR 或 `docs/plan/` 中。

docs/reference/spec-v02-codex-api-forwarder.md

@@ -0,0 +1,51 @@
+# v0.2 Codex API Forwarder 稳定外部通道规格
+
+`hwlab-codex-api-forwarder` 是 `hwlab-cloud-api` Pod 内的本地 sidecar，监听 `127.0.0.1:49280/responses`，为 Code Agent `codex-api` provider profile 提供到 hyueapi Responses upstream 的直连 HTTP 转发通道。它没有独立 Kubernetes Service，但属于 v02 稳定外部 provider 通道的一部分。
+
+## 在系统中的职责划分
+
+- 为 `hwlab-cloud-api` 中的 `codex-api` profile 提供 OpenAI Responses 兼容上游，不经过 `hwlab-deepseek-proxy`。
+- 保证 `hyueapi.com` / `.hyueapi.com` 保留在 `NO_PROXY` / `no_proxy` 中，避免被 G14 proxy 或其他 egress 配置劫持。
+- 只在同 Pod loopback 暴露，不向 ClusterIP、公网、浏览器或普通用户开放。
+- 使用同一个 Code Agent provider SecretRef 注入鉴权材料，但自身不记录或打印 Secret 值。
+
+## 内部架构
+
+- `cmd/hwlab-codex-api-responses-forwarder/main.mjs` 启动 HTTP proxy。
+- listen host 默认 `127.0.0.1`，端口默认 `49280`。
+- upstream 默认 `https://hyueapi.com`，可由 `HWLAB_CODE_AGENT_CODEX_API_UPSTREAM_BASE_URL` 覆盖。
+- forwarder 会过滤 hop-by-hop headers、限制请求体大小，并按 upstream base path 规范化 `/v1/responses`、`/v1/models` 等路径。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /health`、`GET /health/live`、`GET /health/liveliness` | 本地 forwarder 存活检查，返回 upstream host 和 required NO_PROXY entries。 |
+| `GET /health/readiness` | 本地 readiness，不证明 upstream provider 鉴权可用。 |
+| `POST /v1/responses` | Codex API profile 的 Responses 请求代理入口。 |
+| `GET /v1/models` | 按 upstream base path 代理模型列表请求。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-codex-api-forwarder.md，然后用 cli 手动测试以下内容：在 `hwlab-cloud-api` Pod 内访问 `127.0.0.1:49280/health/live`，确认 `upstream.host` 为 hyueapi 域名，且 `NO_PROXY` / `no_proxy` 包含 `hyueapi.com` 和 `.hyueapi.com`。
+
+## T2
+
+阅读 docs/reference/spec-v02-codex-api-forwarder.md，然后用 cli 手动测试以下内容：通过 `hwlab-cloud-api /v1/agent/chat` 指定 `codex-api` provider profile 做短连接聊天，只有 result completed 且 assistant reply 非空才算 provider 通道通过。
+
+## T3
+
+阅读 docs/reference/spec-v02-codex-api-forwarder.md，然后用 cli 手动测试以下内容：确认该 forwarder 没有独立 Kubernetes Service，也没有公网端口；所有调用都应来自同 Pod `hwlab-cloud-api`。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| loopback Responses forwarder | 已实现 | `hwlab-cloud-api` Pod sidecar 监听 `127.0.0.1:49280`。 |
+| hyueapi direct NO_PROXY | 已实现/持续约束 | forwarder 启动时合并 required NO_PROXY entries。 |
+| health/readiness | 已实现 | health 返回 upstream 和 no_proxy 信息。 |
+| provider auth 真实验收 | 已实现/持续约束 | 必须通过 `/v1/agent/chat` 短连接 result 判定。 |
+| 独立 Service/公网暴露 | 不采用 | 只能由同 Pod loopback 调用。 |
+

docs/reference/spec-v02-deepseek-proxy.md

@@ -0,0 +1,50 @@
+# v0.2 DeepSeek/Moon Bridge 稳定外部服务规格
+
+`hwlab-deepseek-proxy` 是 v02 Code Agent `deepseek` provider profile 的内部模型桥，Service 端口 `4000`。它由 repo-owned Responses bridge 容器和稳定外部 `moonbridge` 容器组成。
+
+## 在系统中的职责划分
+
+- 为 `hwlab-cloud-api` 提供 OpenAI Responses 兼容入口 `/v1/responses`，内部转到 Moon Bridge，再转 DeepSeek upstream。
+- 只服务 Code Agent provider profile，不向浏览器或普通用户直接暴露。
+- 读取 `hwlab-v02-code-agent-provider/openai-api-key` 作为 `DEEPSEEK_API_KEY` 渲染 Moon Bridge config；Secret 更新后必须滚动本 Deployment。
+
+## 内部架构
+
+- `ConfigMap/hwlab-deepseek-proxy-config` 提供 `render-config.sh`，initContainer 把 `DEEPSEEK_API_KEY` 写入 `/config/config.yml`。
+- `responses-bridge` 容器运行 `cmd/hwlab-deepseek-responses-bridge/main.mjs`，监听 `4000`，处理 `/health`、`/health/readiness`、`/v1/models` 和 `/v1/responses`。
+- `moonbridge` 容器监听 `4001`，读取渲染后的 config，负责 DeepSeek provider 调用和模型列表。
+- bridge 会解压 zstd body，并过滤 Responses tools 中 Moon Bridge 不支持的 tool type。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /health`、`GET /health/live`、`GET /health/liveliness` | bridge 进程存活。 |
+| `GET /health/readiness` | 探测 Moon Bridge `/health/readiness` 或 `/v1/models`，失败返回 degraded。 |
+| `GET /v1/models` | 返回 Codex/Responses 可消费的模型列表。 |
+| `POST /v1/responses` | `hwlab-cloud-api` deepseek profile 的模型调用入口。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-deepseek-proxy.md，然后用 cli 手动测试以下内容：访问 `hwlab-deepseek-proxy:4000/health/readiness` 和 `/v1/models`，确认 ready 或明确 degraded 原因。
+
+## T2
+
+阅读 docs/reference/spec-v02-deepseek-proxy.md，然后用 cli 手动测试以下内容：通过 `hwlab-cloud-api /v1/agent/chat` 指定或默认 deepseek profile 做短连接聊天，确认 result completed 且 reply 非空。
+
+## T3
+
+阅读 docs/reference/spec-v02-deepseek-proxy.md，然后用 cli 手动测试以下内容：Secret 变更后必须滚动 `hwlab-cloud-api` 和 `hwlab-deepseek-proxy`，验证只输出 SecretRef、bytes 和 hash，不输出值。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| Responses bridge | 已实现 | `/v1/responses`、`/v1/models` 和 readiness 已实现。 |
+| Moon Bridge sidecar | 已实现 | 外部稳定镜像在同 Pod 运行。 |
+| Secret 渲染边界 | 已实现 | initContainer 渲染 config；需 rollout 才生效。 |
+| provider auth 真实验收 | 已实现 | 通过 cloud-api 短连接聊天判定。 |
+| 多 provider 动态切换 UI | 未完全实现 | cloud-api 支持 profile，完整用户级策略仍待产品化。 |
+

docs/reference/spec-v02-frpc.md

@@ -0,0 +1,49 @@
+# v0.2 FRP 公网入口规格
+
+`hwlab-v02-frpc` 是 v02 的 FRP client Deployment，连接 master server 上稳定外部 `frps`，把 `hwlab-v02` 内部服务发布为 `19666/19667`。
+
+## 在系统中的职责划分
+
+- 将 `hwlab-cloud-web:8080` 暴露为 `http://74.48.78.17:19666/`。
+- 将 `hwlab-edge-proxy:6667` 暴露为 `http://74.48.78.17:19667/`。
+- 只承载 v02 公网入口，不复用或改义 DEV `17666/17667`、PROD `18666/18667`。
+- master `frps` allowPorts 是外部稳定服务配置；缺失时修 master-side frps，不改 v02 Service 或 DEV/PROD GitOps。
+
+## 内部架构
+
+- `ConfigMap/hwlab-v02-frpc-config` 保存 `frpc.toml`，包含两个 TCP proxy：`hwlab-v02-cloud-web` 和 `hwlab-v02-edge-proxy`。
+- `Deployment/hwlab-v02-frpc` 使用外部镜像 `fatedier/frpc:v0.68.1`，只挂载 config，不保存 Secret。
+- master `frps` 监听 `74.48.78.17:7000`，必须允许 remotePort `19666` 和 `19667`。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| TCP `74.48.78.17:19666` | FRP 转发到 `hwlab-cloud-web.hwlab-v02.svc.cluster.local:8080`。 |
+| TCP `74.48.78.17:19667` | FRP 转发到 `hwlab-edge-proxy.hwlab-v02.svc.cluster.local:6667`。 |
+| frpc logs | 判断 `login to server success`、`start proxy success` 或 `port not allowed`。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-frpc.md，然后用 cli 手动测试以下内容：访问 `http://74.48.78.17:19666/` 和 `http://74.48.78.17:19667/health/live`，确认分别到 v02 cloud-web 和 v02 cloud-api。
+
+## T2
+
+阅读 docs/reference/spec-v02-frpc.md，然后用 cli 手动测试以下内容：读取 `hwlab-v02-frpc` logs，确认没有 `port not allowed`；若出现该错误，只修 master frps allowlist 并重启 frps。
+
+## T3
+
+阅读 docs/reference/spec-v02-frpc.md，然后用 cli 手动测试以下内容：修复或验证 v02 FRP 后，同时验证 DEV `17666/17667` 仍可用，不能把 DEV/PROD 入口当成 v02 证据。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| v02 web/API 端口 | 已实现 | `19666/19667` 在 frpc config 中固定。 |
+| 外部 frpc 镜像 | 已实现 | 使用 `fatedier/frpc:v0.68.1`。 |
+| master frps allowlist 依赖 | 已实现/外部维护 | 由 master-side frps 配置控制。 |
+| HTTP health endpoint | 不适用 | frpc 本身不提供 HWLAB HTTP health。 |
+| 自动 frps 配置 GitOps | 未实现 | master frps 仍是边缘运维对象。 |
+

docs/reference/spec-v02-hwlab-agent-mgr.md

@@ -0,0 +1,47 @@
+# v0.2 hwlab-agent-mgr 服务规格
+
+`hwlab-agent-mgr` 是 agent runtime 管理服务，运行在 `hwlab-v02` namespace，内部端口 `7410`。当前实现是本地状态目录驱动的 runtime skeleton，不是 `hwlab-cloud-api` Code Agent 对话的主执行路径。
+
+## 在系统中的职责划分
+
+- 管理 agent session 生命周期模型：create、start、trace、finish、cleanup。
+- 生成 workspace volume、worker session、trace event 和 evidence record 的结构化状态。
+- 与 `hwlab-agent-worker`、`hwlab-agent-skills` 共同定义未来 session-scoped worker 执行边界。
+- 不直接暴露给普通用户；用户态 Code Agent 请求必须先进入 `hwlab-cloud-api`。
+
+## 内部架构
+
+- `cmd/hwlab-agent-mgr/main.mjs` 同时提供 CLI 和健康 HTTP server。
+- `internal/agent/runtime.mjs` 负责文件系统状态、session lifecycle、trace/evidence 和 cleanup。
+- `internal/agent/index.mjs` 定义 serviceId、session status 和 skills manifest 结构。
+- `HWLAB_AGENT_RUNTIME_STATE_DIR` 可隔离状态目录；默认 `.state/agent-runtime` 只用于本地/测试状态。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /health`、`GET /health/live` | HTTP server 模式下返回 manager health、skills 注入状态和 build metadata。 |
+| `GET /`、`GET /help` | 返回 CLI/服务用法。 |
+| `node cmd/hwlab-agent-mgr/main.mjs health` | 本地 JSON health。 |
+| `create/status/trace/evidence/cleanup` | 本地 session lifecycle CLI；必须传 `--agent-session-id`，create 还需 `--project-id`。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-hwlab-agent-mgr.md，然后用 cli 手动测试以下内容：访问 v02 ClusterIP 或 pod 内 `/health/live`，确认 `serviceId=hwlab-agent-mgr`，并记录 skills missing/ready 状态。
+
+## T2
+
+阅读 docs/reference/spec-v02-hwlab-agent-mgr.md，然后用 cli 手动测试以下内容：在隔离 `--state-dir` 下执行 create、status、trace、evidence、cleanup，确认每步输出 JSON 且生命周期顺序稳定。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| HTTP health server | 已实现 | `server` 模式提供 `/health/live`。 |
+| 本地 session lifecycle CLI | 已实现 | create/status/trace/evidence/cleanup 可用。 |
+| skills commit/version readiness | 已实现 | health 会报告缺失字段；不静默 fallback。 |
+| 调度真实 worker Job | 未完全实现 | 当前是 skeleton，本身不负责创建 Kubernetes worker Job。 |
+| 接入 cloud-api 用户会话 | 未完全实现 | 当前 Code Agent 对话主要由 cloud-api 内部 Codex stdio manager 承担。 |
+

docs/reference/spec-v02-hwlab-agent-skills.md

@@ -0,0 +1,43 @@
+# v0.2 hwlab-agent-skills 服务规格
+
+`hwlab-agent-skills` 是 v02 agent 技能包的部署可见服务，运行在 `hwlab-v02` namespace，内部端口 `7430`。它用于暴露 skills bundle 的构建/health 元数据，不应成为 `hwlab-cloud-api` 每次 Code Agent 对话的运行时必依赖；Code Agent 实际读取的是镜像内 `/app/skills`。
+
+## 在系统中的职责划分
+
+- 证明当前 lane 中 skills bundle 随 source commit 发布，并为 live-build inventory 和 M4/M5 agent-loop 验收提供 health metadata。
+- 与 `hwlab-agent-mgr` 和 `hwlab-agent-worker` 的 skills commit/version readiness 对齐。
+- 不保存用户数据，不保存 Secret，不执行用户代码。
+
+## 内部架构
+
+- artifact runtime 以 health-only server 方式运行，暴露 `/health` 和 `/health/live`。
+- 镜像包含 `skills/` 目录，构建身份来自 `HWLAB_COMMIT_ID`、`HWLAB_IMAGE`、`HWLAB_IMAGE_TAG`。
+- `HWLAB_SKILLS_COMMIT_ID` 由 GitOps render 注入；`HWLAB_SKILLS_VERSION` 是 skills manifest readiness 需要的稳定字段。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /health`、`GET /health/live` | 返回 service identity、revision、image/build metadata 和 skills 相关 env。 |
+| `GET /help` | 返回 health-only runtime 的可用 route。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-hwlab-agent-skills.md，然后用 cli 手动测试以下内容：访问 `hwlab-agent-skills:7430/health/live`，确认 `serviceId=hwlab-agent-skills`、revision 与 v02 source commit 对齐。
+
+## T2
+
+阅读 docs/reference/spec-v02-hwlab-agent-skills.md，然后用 cli 手动测试以下内容：检查 Deployment env，确认 `HWLAB_SKILLS_COMMIT_ID` 存在；若 `HWLAB_SKILLS_VERSION` 缺失，必须在验收结果中标记未完全实现。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| health-only 服务 | 已实现 | Deployment/Service 存在，端口 7430。 |
+| skills bundle 随镜像发布 | 已实现 | Dockerfile 复制 `skills/` 到 `/app/skills`。 |
+| `HWLAB_SKILLS_COMMIT_ID` | 已实现 | v02 render 已注入 source commit。 |
+| `HWLAB_SKILLS_VERSION` | 未完全实现 | 当前 render 未稳定注入 version，manager/worker readiness 仍可能报告缺失。 |
+| 作为 Code Agent 运行时依赖 | 不采用 | Code Agent 读取镜像内 skills，不应每轮依赖该服务。 |
+

docs/reference/spec-v02-hwlab-agent-worker.md

@@ -0,0 +1,44 @@
+# v0.2 hwlab-agent-worker 服务规格
+
+`hwlab-agent-worker` 是 session-scoped 执行模板，在 `hwlab-v02` 中以 suspended Job template `hwlab-agent-worker-template` 存在。它不是长驻 HTTP 服务。
+
+## 在系统中的职责划分
+
+- 在未来由 manager 或调度器实例化为单次 worker Job，执行一个 agent session 的受控工作。
+- 负责写入 worker trace、evidence、workspace dry-run 结果，并在完成后退出。
+- 不保存长期用户状态，不直接处理浏览器或公网请求。
+
+## 内部架构
+
+- `cmd/hwlab-agent-worker/main.mjs` 提供 CLI 命令 `health` 和 `dry-run/smoke`。
+- `internal/agent/runtime.mjs` 提供 `runLocalWorkerDryRun`，读取 manager 创建的本地 session 状态并写入 evidence。
+- Job template 通过 env 注入 `HWLAB_AGENT_SESSION_ID`、`HWLAB_SKILL_COMMIT_ID` 和 `HWLAB_SKILL_VERSION`。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `node cmd/hwlab-agent-worker/main.mjs health` | 返回 worker health、runtime mode 和 skills 注入状态。 |
+| `node cmd/hwlab-agent-worker/main.mjs dry-run --agent-session-id ID` | 执行本地 dry-run worker 流程，写入 trace/evidence。 |
+| Kubernetes Job template | `hwlab-agent-worker-template` 默认 `suspend: true`，只能由受控调度实例化。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-hwlab-agent-worker.md，然后用 cli 手动测试以下内容：从 Job template dry-run 或本地 CLI 执行 `health`，确认输出 JSON，且缺少 skill commit/version 时明确 degraded 或 blocked。
+
+## T2
+
+阅读 docs/reference/spec-v02-hwlab-agent-worker.md，然后用 cli 手动测试以下内容：先用 agent-mgr 创建 session，再执行 worker `dry-run`，确认 trace 和 evidence 均写入同一 isolated state-dir。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| CLI health/dry-run | 已实现 | worker 以 JSON 输出。 |
+| suspended Job template | 已实现 | runtime-v02 中存在 `hwlab-agent-worker-template`。 |
+| session-scoped evidence 写入 | 已实现 | 本地 dry-run 覆盖 trace/evidence。 |
+| 长驻 HTTP API | 不适用 | worker 不是长驻服务。 |
+| 生产调度与真实执行 | 未完全实现 | 当前仍是 skeleton/dry-run 模式。 |
+

docs/reference/spec-v02-hwlab-cli.md

@@ -0,0 +1,47 @@
+# v0.2 hwlab-cli 服务规格
+
+`hwlab-cli` 是 v02 的受控操作 CLI 镜像和 suspended Job template。它不是长驻业务服务；默认通过手动 Job 或本地 repo CLI 执行 JSON 命令。
+
+## 在系统中的职责划分
+
+- 提供 HWLAB 操作和验收的 CLI 合同，包括 health、project list、M3 status/io 和 MVP e2e 计划。
+- 明确删除 legacy `hwlab-cli cicd` 路径，CI/CD 只能走 G14 Tekton/GitOps。
+- 与 `hwlab-cloud-api` 交互时必须通过 `HWLAB_CLI_ENDPOINT` 指向 `19667` 或内部 API base，不直连 gateway/patch/simu 服务。
+
+## 内部架构
+
+- `tools/hwlab-cli/bin/hwlab-cli.mjs` 是唯一 CLI bin 入口。
+- `tools/hwlab-cli/lib/cli.mjs` 负责参数解析、JSON 输出、legacy cicd 拒绝、M3 Skill CLI 转发和 MVP e2e dry-run plan。
+- `hwlab-cli-template` 是 `suspend: true` 的 Kubernetes Job template，运行时通过 env 注入 endpoint、commit 和 image metadata。
+
+## API 接口说明
+
+| CLI 接口 | 说明 |
+| --- | --- |
+| `hwlab-cli health` | 输出 MVP gate 摘要和 blocker。 |
+| `hwlab-cli project list` | 输出项目/topology 摘要。 |
+| `hwlab-cli m3 status --api-base-url URL` | 通过 Skill CLI 调用 HWLAB API `/v1/m3/status`。 |
+| `hwlab-cli m3 io --action ... --api-base-url URL` | 通过 Skill CLI 调用 `/v1/m3/io`；写操作必须显式 approval。 |
+| `hwlab-cli test e2e --env dev --mvp --dry-run` | 输出 MVP e2e dry-run plan。 |
+| `hwlab-cli cicd ...` | 必须返回 `legacy-cicd-removed`。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-hwlab-cli.md，然后用 cli 手动测试以下内容：运行 `hwlab-cli health`、`project list` 和 `test e2e --env dev --mvp --dry-run`，确认全部输出 JSON 且不执行 live DEV/PROD 修改。
+
+## T2
+
+阅读 docs/reference/spec-v02-hwlab-cli.md，然后用 cli 手动测试以下内容：运行 `hwlab-cli cicd status`，确认返回 `legacy-cicd-removed`，并给出 G14 Tekton/GitOps 替代入口。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| CLI JSON 输出 | 已实现 | `lib/cli.mjs` 默认 JSON。 |
+| M3 Skill CLI 转发 | 已实现 | 使用 repo-owned Skill CLI 调 HWLAB API。 |
+| legacy cicd 删除 | 已实现 | `cicd` 子命令返回明确错误。 |
+| v02 Job template | 已实现 | `hwlab-cli-template` 存在且 `suspend: true`。 |
+| live e2e 执行 | 未完全实现 | 当前 live path 在 blocker 或未实现时拒绝执行。 |
+

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

@@ -0,0 +1,61 @@
+# 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、Code Agent 对话、trace/result 轮询、gateway outbound registry、M3 IO 控制、device-pod 只读代理和 live build inventory。
+- 是 `hwlab-cloud-web`、Code Agent session、device-pod 用户态操作和 gateway outbound poll 的唯一应用层收口点。
+- 读取 `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.mjs` 负责启动 HTTP server、解析端口和 Code Agent timeout。
+- `internal/cloud/server.mjs` 负责 HTTP route、REST/RPC bridge、health、live-builds、device-pod proxy、gateway poll/result 和 Code Agent chat。
+- `internal/db/runtime-store.mjs` 和 `internal/cloud/db-contract.mjs` 负责 Postgres runtime store 与 readiness 分层。
+- `internal/cloud/code-agent-*.mjs` 负责 Codex stdio session、trace store、result cache、provider profile 和取消/轮询。
+- 同 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...` | 代理到 `hwlab-device-pod`；上游不可用时当前会返回 fake fallback，并必须标明来源。 |
+| `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/agent/chat`、`GET /v1/agent/chat/result/{traceId}`、`GET /v1/agent/chat/trace/{traceId}`、`POST /v1/agent/chat/cancel` | Code Agent 短连接提交、轮询、trace 和取消。 |
+
+用户、权限、device-pod 管理 API 的最终规格见 [spec-user-access.md](spec-user-access.md) 和 [spec-device-pod.md](spec-device-pod.md)；当前实现尚未完整落地 admin/user 表和授权链路。
+
+## 测试规格
+
+## 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 通过。
+
+## T3
+
+阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：访问 `/v1/device-pods` 和一个 device-pod status route，确认响应标明来自 `hwlab-device-pod` 或明确 fake fallback，不得把 fake fallback 写成真实硬件 DEV-LIVE。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| health/readiness | 已实现 | `/health/live` 汇总 DB、runtime、Code Agent 和 blocker。 |
+| Code Agent 短连接 submit/result/trace/cancel | 已实现 | repo-owned Codex stdio 和 provider profile 已接入。 |
+| Postgres durable runtime | 已实现 | 通过 v02 独立 DB SecretRef 和 migration ledger 判定。 |
+| gateway outbound poll/result | 已实现 | 支持 gateway 主动轮询和 `hardware.invoke.shell` 分发。 |
+| device-pod 正式权限/profile/job | 未完全实现 | 当前主要是只读 proxy/fake fallback；正式规格见 device-pod specs。 |
+| v0.2 admin/user 权限模型 | 未完全实现 | 表结构和 API 规格已定义，完整应用层鉴权仍待实现。 |
+

docs/reference/spec-v02-hwlab-cloud-web.md

@@ -0,0 +1,52 @@
+# v0.2 hwlab-cloud-web 服务规格
+
+`hwlab-cloud-web` 是 `v0.2` 浏览器工作台，运行在 `hwlab-v02` namespace，内部端口 `8080`，公网经 FRP 暴露为 `http://74.48.78.17:19666/`。
+
+## 在系统中的职责划分
+
+- 向用户提供 Cloud Workbench、Code Agent 对话、live status、device-pod 右侧面板、trace 展示和帮助内容。
+- 只消费 `hwlab-cloud-api`，不直接访问 Postgres、gateway、device-pod Service、FRP、Kubernetes 或 provider Secret。
+- 为浏览器提供同源代理，避免前端直接跨域调用内部 ClusterIP。
+
+## 内部架构
+
+- `web/hwlab-cloud-web/app.mjs` 是浏览器端主应用，组织 Workbench 状态、Code Agent 会话缓存、trace 轮询和 device-pod 面板。
+- `internal/dev-entrypoint/http.mjs` 提供静态服务、health 和 HTTP proxy 基础能力。
+- `internal/dev-entrypoint/cloud-web-routes.mjs` 定义可代理到 cloud-api 的同源 API route 和认证边界。
+- `web/hwlab-cloud-web/auth.mjs` 管理工作台登录态；真正的用户权限 authority 仍应收敛到 cloud-api。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /` | Cloud Workbench 首屏。 |
+| `GET /health`、`GET /health/live` | 返回 cloud-web 自身 health 和 build metadata。 |
+| `GET /help` | 返回可用 route 摘要。 |
+| `GET /v1`、`GET /v1/...` | 同源代理到 `hwlab-cloud-api`；公开的 Code Agent result/trace 轮询按 route policy 处理。 |
+| `POST /v1/agent/chat`、`POST /v1/agent/chat/cancel` | 同源代理到 cloud-api 的 Code Agent 入口。 |
+| `POST /v1/m3/io`、`POST /json-rpc` | 同源代理到受控 API；不能绕过 cloud-api 直连硬件服务。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：访问 `http://74.48.78.17:19666/` 和 `/health/live`，确认页面和 health 均来自 v02 cloud-web，而不是 DEV/PROD 端口。
+
+## T2
+
+阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：从同源 `19666` 提交 Code Agent 短连接请求并轮询 result，确认请求经 cloud-web proxy 到 `hwlab-cloud-api`，且 trace 可回放。
+
+## T3
+
+阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：打开 Workbench device-pod 面板，确认 status/freshness/blocker 显示来自 `/v1/device-pods`，fake 数据必须在 UI 或 payload 中可追溯。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| Workbench 首屏 | 已实现 | 当前页面直接进入工作台，不是 landing page。 |
+| cloud-api 同源代理 | 已实现 | 受 route policy 控制。 |
+| Code Agent UI/trace/result | 已实现 | 支持 provider profile、timeout、trace 轮询和取消。 |
+| device-pod 面板 | 未完全实现 | 当前主要消费 fake/只读 device-pod payload。 |
+| 完整多用户 admin/user UI | 未完全实现 | 登录态存在，权限 authority 仍需按 spec-user-access 收敛到 cloud-api。 |
+

docs/reference/spec-v02-hwlab-device-pod-service.md

@@ -0,0 +1,49 @@
+# v0.2 hwlab-device-pod 服务规格
+
+本文描述 v02 中 `hwlab-device-pod` 微服务的部署和接口实现。逻辑 device-pod、profile authority、grant 和 job 模型的权威规格见 [spec-device-pod.md](spec-device-pod.md)。
+
+## 在系统中的职责划分
+
+- 承接 `cloud-api -> hwlab-device-pod -> gateway/device-host-cli` 的设备业务服务位置。
+- 当前阶段只为 Cloud Workbench 右侧面板提供 fake/只读 device-pod 数据，不能作为真实硬件 DEV-LIVE 证据。
+- 普通用户和 Code Agent 不应直接调用该 Service；正式路径必须经过 `hwlab-cloud-api` 鉴权、grant 和 lease。
+
+## 内部架构
+
+- `cmd/hwlab-device-pod/main.mjs` 提供 HTTP server，端口默认 `7601`。
+- `internal/device-pod/fake-data.mjs` 构造 list、status、events、chip-id、UART status/tail 等 fake payload。
+- `HWLAB_DEVICE_POD_ID` 可指定默认 devicePodId；当前不读取正式 `device_pods.profile_json`。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /health`、`GET /health/live` | 返回 `contractVersion=device-pod-fake-v1` 和 fake 服务说明。 |
+| `GET /v1/device-pods` | 返回 device-pod 列表。 |
+| `GET /v1/device-pods/{devicePodId}/status` | 返回 fake status/freshness/profileHash。 |
+| `GET /v1/device-pods/{devicePodId}/events` | 返回 bounded fake event lines。 |
+| `GET /v1/device-pods/{devicePodId}/debug-probe/chip-id` | 返回 fake chip-id。 |
+| `GET /v1/device-pods/{devicePodId}/io-probe/uart/1`、`.../tail` | 返回 fake UART status/tail。 |
+
+正式 `POST /jobs`、job output/cancel 和 admin profile/grant API 尚未在该服务实现，应以 [spec-device-pod.md](spec-device-pod.md) 为目标。
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-hwlab-device-pod-service.md，然后用 cli 手动测试以下内容：访问 `/health/live` 和 `/v1/device-pods`，确认响应包含 `contractVersion=device-pod-fake-v1`，并明确 fake/source 信息。
+
+## T2
+
+阅读 docs/reference/spec-v02-hwlab-device-pod-service.md，然后用 cli 手动测试以下内容：通过 `hwlab-cloud-api /v1/device-pods` 访问同一数据，确认 cloud-api proxy 标明 upstream 或 fake fallback 状态。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| health 和只读 fake REST | 已实现 | 支持 Workbench 右侧面板迁移。 |
+| bounded events/tail | 已实现 | fake 数据有限长输出。 |
+| 正式 profile authority | 未实现 | 尚未读取 cloud-api DB profile。 |
+| job lifecycle | 未实现 | `POST /jobs` 等正式 API 尚未实现。 |
+| gateway/device-host-cli adapter | 未实现 | 当前不连接真实硬件。 |
+

docs/reference/spec-v02-hwlab-edge-proxy.md

@@ -0,0 +1,44 @@
+# v0.2 hwlab-edge-proxy 服务规格
+
+`hwlab-edge-proxy` 是 v02 API 公网入口的内部 edge proxy，运行在 `hwlab-v02` namespace，内部端口 `6667`。FRP `19667` 转发到该服务。
+
+## 在系统中的职责划分
+
+- 接收 FRP 转入的 API/health 请求，并代理到 `hwlab-cloud-api:6667`。
+- `/health/live` 必须透传 cloud-api live health，因此公网 API readiness 以 cloud-api 为准。
+- 不实现业务 API，不读取 Secret，不替代 cloud-api 权限和 runtime readiness。
+
+## 内部架构
+
+- `cmd/hwlab-edge-proxy/main.mjs` 启动 HTTP server。
+- `internal/dev-entrypoint/http.mjs` 的 `proxyHttpRequest` 负责 streaming proxy、timeout 和错误 payload。
+- `HWLAB_EDGE_UPSTREAM` 指向 v02 `hwlab-cloud-api` ClusterIP；`HWLAB_EDGE_PROXY_TIMEOUT_MS` 控制长 Code Agent 请求代理窗口。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /health/live` | 代理到 upstream `/health/live`，代表公网 API live readiness。 |
+| `GET /health`、`GET /edge/health` | 返回 edge-proxy 自身 health 和 upstream 配置。 |
+| `GET /status`、`GET /routes` | 返回代理路由表。 |
+| 其他路径 | 透明代理到 `hwlab-cloud-api`。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-hwlab-edge-proxy.md，然后用 cli 手动测试以下内容：访问 `http://74.48.78.17:19667/health/live`，确认响应是 cloud-api payload 且 `environment=v02`。
+
+## T2
+
+阅读 docs/reference/spec-v02-hwlab-edge-proxy.md，然后用 cli 手动测试以下内容：访问 edge-proxy `/status` 或 `/routes`，确认 upstream 指向 `hwlab-cloud-api.hwlab-v02.svc.cluster.local:6667`。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| API edge proxy | 已实现 | 其他路径透明代理 cloud-api。 |
+| live health 透传 | 已实现 | `/health/live` 代理 upstream。 |
+| 长请求 timeout | 已实现 | 默认支持 Code Agent 长窗口。 |
+| 业务权限/鉴权 | 不在本服务 | 由 cloud-api 承担。 |
+

docs/reference/spec-v02-hwlab-gateway.md

@@ -0,0 +1,46 @@
+# v0.2 hwlab-gateway 服务规格
+
+`hwlab-gateway` 是 v02 的真实硬件/host transport 边界服务，内部端口 `7001`。它用于 gateway 主动出站 demo 和受控 shell dispatch，不是普通用户或前端可直连的硬件 API。
+
+## 在系统中的职责划分
+
+- 向 `hwlab-cloud-api` 注册 gateway session、resource 和 capability。
+- 通过主动轮询 `/v1/gateway/poll` 获取 cloud-api 分发的 `hardware.invoke.shell` 请求，并把结果回传 `/v1/gateway/result`。
+- 只做 transport 和 bounded command execution，不理解用户权限、device-pod grant 或业务授权。
+
+## 内部架构
+
+- `cmd/hwlab-gateway/main.mjs` 维护 gateway state、outbound poll loop、inflight request map 和 command execution。
+- `internal/cloud/gateway-demo-registry.mjs` 在 cloud-api 内保存 gateway session、队列和 pending result。
+- command execution 默认关闭；只有显式 `HWLAB_GATEWAY_CMD_EXEC_ENABLED=1` 或 demo open 时才执行 shell。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /health/live` | 返回 gateway health、gatewayId、gatewaySessionId 和 outboundConnected。 |
+| `GET /status` | 返回 session、registry、outbound poll 和 inflight 摘要。 |
+| `GET /capabilities` | 返回 resource/capability 列表。 |
+| `POST cloud-api /v1/gateway/poll` | gateway 主动向 cloud-api 取任务。 |
+| `POST cloud-api /v1/gateway/result` | gateway 回传 JSON-RPC response。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-hwlab-gateway.md，然后用 cli 手动测试以下内容：访问 gateway `/health/live` 和 `/status`，确认 gatewaySessionId、resourceId、capability 列表存在，且 command execution 状态清晰。
+
+## T2
+
+阅读 docs/reference/spec-v02-hwlab-gateway.md，然后用 cli 手动测试以下内容：通过 cloud-api `/v1/gateway/sessions` 观察 gateway online/stale 状态；不要直接从前端或普通用户请求 gateway shell。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| health/status/capabilities | 已实现 | gateway service 提供只读观测。 |
+| outbound poll/result | 已实现 | 与 cloud-api registry 对接。 |
+| bounded shell execution | 已实现 | 受 env 开关、timeout 和 output limit 约束。 |
+| device-pod grant/lease | 不在本服务 | 由 cloud-api/device-pod 负责。 |
+| 生产级 gateway 多租户隔离 | 未完全实现 | 当前是 demo/transport skeleton。 |
+

docs/reference/spec-v02-postgres.md

@@ -0,0 +1,45 @@
+# v0.2 Postgres 稳定外部服务规格
+
+`hwlab-v02-postgres` 是 v02 独立 Postgres StatefulSet，使用外部稳定镜像 `postgres:16-alpine` 的本地 registry 版本，内部端口 `5432`。
+
+## 在系统中的职责划分
+
+- 为 `hwlab-cloud-api` 提供 v02 独立 durable runtime store、migration ledger、agent/gateway/evidence 等持久化表。
+- 与 `hwlab-dev`/`hwlab-prod` 数据隔离；v02 使用独立 namespace、Service、PVC、database/user 和 SecretRef。
+- 不向公网开放，不由普通用户或 Code Agent 直连。
+
+## 内部架构
+
+- `StatefulSet/hwlab-v02-postgres` 挂载 `data` PVC 到 `/var/lib/postgresql/data`。
+- `ConfigMap/hwlab-v02-postgres-init` 提供初始化 SQL 和 `hwlab_schema_migrations` ledger。
+- `Secret/hwlab-v02-postgres` 提供 `POSTGRES_PASSWORD`；`Secret/hwlab-cloud-api-v02-db` 提供 cloud-api 使用的 `database-url`。
+- `Service/hwlab-v02-postgres` 提供 ClusterIP DNS。
+
+## API 接口说明
+
+| 接口 | 说明 |
+| --- | --- |
+| TCP `hwlab-v02-postgres.hwlab-v02.svc.cluster.local:5432` | Postgres wire protocol，仅内部服务使用。 |
+| `POSTGRES_DB=hwlab_v02`、`POSTGRES_USER=hwlab_v02` | v02 独立数据库身份。 |
+| `hwlab-cloud-api /health/live` DB readiness | 对外展示 DB env、schema、auth、readiness 和 migration ledger，不打印 Secret。 |
+
+## 测试规格
+
+## T1
+
+阅读 docs/reference/spec-v02-postgres.md，然后用 cli 手动测试以下内容：查询 StatefulSet、Service、PVC 和 SecretRef 名称，确认全部在 `hwlab-v02` namespace，且不输出 Secret 值。
+
+## T2
+
+阅读 docs/reference/spec-v02-postgres.md，然后用 cli 手动测试以下内容：访问 `hwlab-cloud-api /health/live`，确认 DB readiness ready、runtime adapter 为 Postgres、migration ledger 存在。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| 独立 StatefulSet/PVC | 已实现 | `hwlab-v02-postgres` 在 v02 namespace。 |
+| 初始化 schema/migration ledger | 已实现 | ConfigMap 包含 `0001_cloud_core_skeleton`。 |
+| cloud-api DB SecretRef | 已实现 | `hwlab-cloud-api-v02-db/database-url`。 |
+| 自动备份/恢复 | 未实现 | 当前 spec 未定义备份服务。 |
+| 多副本 HA | 未实现 | 当前为单副本 StatefulSet。 |
+

docs/reference/spec-v02-services.md

@@ -1,27 +1,31 @@
 # v0.2 微服务总体规格
 
-本文是 HWLAB `v0.2` 微服务总体规格。它只定义组件取舍、依赖方向、语言迁移边界和裁撤口径；单个服务的 API、表结构、profile、权限、CI/CD 和 provider 细节应交叉引用对应规格，不在本文重复展开。
+本文是 HWLAB `v0.2` 微服务总体规格和服务规格索引。它定义组件取舍、依赖方向、语言迁移边界、裁撤口径和单服务 spec 入口；单个服务的 API、测试规格和实现状态以对应 `docs/reference/spec-*.md` 为准。
+
+`docs/reference/spec-*.md` 是微服务、稳定外部服务、CLI/Job 模板和系统能力的权威出处；代码开发和测试代码编写必须先对齐对应 spec，再修改实现或测试。
 
 细节权威出处：
 
 - 用户、权限、session 归属和 device pod grant：见 [spec-user-access.md](spec-user-access.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 profile、DeepSeek bridge、Codex loopback forwarder 和真实聊天验收：见 [code-agent-chat-readiness.md](code-agent-chat-readiness.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)。
-- 当前 gateway 主动出站 demo 仍可作为 transport 背景，正式 device pod 路径以 [spec-device-pod.md](spec-device-pod.md) 为准。
+- 保留服务、稳定外部服务和 CLI/Job 模板的单服务 spec：见本文“服务总表”。
 
-## 总体边界
+## 在系统中的职责划分
 
-- `hwlab-cloud-api` 是 v0.2 应用层 authority：用户身份、`admin/user`、code agent session owner、device pod grant、profile authority 和用户态 REST 都在这里判定。
+`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、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 是外部稳定服务。
+- 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 裁撤；不再为这些裁撤对象保留单独规格文档。
 - CLI、一次性脚本、render/publish/smoke helper、vendored 前端库和稳定外部服务不纳入 Bun + TypeScript 迁移范围；HWLAB 自研前端浏览器代码纳入 TypeScript 化范围，因为低频 UI 分支的语法错误也必须在发布前拦截。
 
-## 依赖关系
+## 内部架构
 
 v0.2 的主要请求链路按以下方向收敛：
 
@@ -68,35 +72,53 @@ origin/v0.2
 
 这些链路只表达总体依赖方向。接口、鉴权、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) |
+| 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) |
+| Agent runtime skeleton | manager HTTP/CLI、worker Job template、skills health | [spec-v02-hwlab-agent-mgr.md](spec-v02-hwlab-agent-mgr.md)、[spec-v02-hwlab-agent-worker.md](spec-v02-hwlab-agent-worker.md)、[spec-v02-hwlab-agent-skills.md](spec-v02-hwlab-agent-skills.md) |
+| CLI/Job 操作 | `hwlab-cli` suspended Job template 和 repo CLI | [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 自研常驻服务 | 上游是 web、edge、CLI 和 agent 工具；下游是 Postgres、provider 通道、device-pod 和 agent runtime | 保留并核心化 | 是，P0 | [spec-user-access.md](spec-user-access.md)、[spec-device-pod.md](spec-device-pod.md)、[code-agent-chat-readiness.md](code-agent-chat-readiness.md) |
-| `hwlab-cloud-web` runtime wrapper | HWLAB 自研常驻 web/proxy wrapper | 上游是浏览器；下游只代理 `cloud-api` | 保留 | 是，P0 | [spec-user-access.md](spec-user-access.md)、[cloud-workbench.md](cloud-workbench.md) |
-| `hwlab-edge-proxy` | HWLAB 自研常驻服务 | 上游是公网/FRP API 入口；下游是 `cloud-api` | 保留 | 是，P0 | [spec-v02-cicd.md](spec-v02-cicd.md)、[dev-runtime-boundary.md](dev-runtime-boundary.md) |
-| `hwlab-device-pod` | HWLAB 自研常驻服务 | 上游只能是 `cloud-api` 内部调用；下游是 `gateway` 和 host 侧设备工具 | 保留并增强 | 是，P0 | [spec-device-pod.md](spec-device-pod.md) |
-| `hwlab-agent-mgr` | HWLAB 自研常驻服务 | 属于 code agent session 管理面；不得与 `cloud-api` owner authority 冲突 | 保留，但职责需收敛 | 是，P1 | [spec-user-access.md](spec-user-access.md)、[code-agent-chat-readiness.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](code-agent-chat-readiness.md)、[g14-gitops-cicd.md](g14-gitops-cicd.md) |
-| `hwlab-deepseek-responses-bridge` | HWLAB 自研常驻 sidecar | 上游是 `deepseek` profile；下游是 Moon Bridge | 保留 | 是，P1 | [code-agent-chat-readiness.md](code-agent-chat-readiness.md)、[g14-gitops-cicd.md](g14-gitops-cicd.md) |
-| `hwlab-agent-worker` | HWLAB 自研 Job/执行入口 | 由 agent session 生命周期触发，不作为常驻 Deployment | 保留，非第一波 | 建议迁，P2 | [code-agent-chat-readiness.md](code-agent-chat-readiness.md)、[spec-user-access.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](code-agent-chat-readiness.md) |
-| `hwlab-gateway` | HWLAB 自研用户端/硬件 transport | 上游由 `device-pod` 或受控 cloud 调用；下游是用户端硬件资源 | 保留 | 暂不迁 | [spec-device-pod.md](spec-device-pod.md)、[gateway-outbound-demo.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](spec-v02-cicd.md) |
-| `device-pod-cli` | CLI 工具 | 用户或 agent 工具入口；正式模式只请求 `cloud-api` REST | 保留并改 REST 调用 | 否 | [spec-device-pod.md](spec-device-pod.md) |
-| render/publish/smoke scripts | 一次性脚本 | 支撑 CI/CD、验证和开发流程，不常驻 | 保留现状 | 否 | [spec-v02-cicd.md](spec-v02-cicd.md)、[g14-gitops-cicd.md](g14-gitops-cicd.md) |
-| browser-side Cloud Web JS | HWLAB 自研前端浏览器代码 | 运行在浏览器；通过 web/proxy 调 `cloud-api` | 保留并 TS 化 | 是，P0 | [cloud-workbench.md](cloud-workbench.md) |
-| Moon Bridge | 外部稳定服务 | `deepseek` bridge 的下游转换层 | 保留 | 否 | [code-agent-chat-readiness.md](code-agent-chat-readiness.md)、[g14-gitops-cicd.md](g14-gitops-cicd.md) |
-| `frpc` / `frps` | 外部稳定服务 | 公网入口和反向隧道 | 保留 | 否 | [spec-v02-cicd.md](spec-v02-cicd.md) |
-| Postgres | 外部稳定服务 | `cloud-api` 的持久化数据底座 | 保留 | 否 | [spec-user-access.md](spec-user-access.md)、[spec-v02-cicd.md](spec-v02-cicd.md) |
-| Argo CD / Tekton / BuildKit / registry | 外部稳定服务 | v0.2 CI/CD 和 GitOps 控制面 | 保留 | 否 | [spec-v02-cicd.md](spec-v02-cicd.md)、[g14-gitops-cicd.md](g14-gitops-cicd.md) |
-| Codex CLI | 外部工具/runtime | `cloud-api` code agent runtime 调用的外部 agent 工具 | 保留 | 否 | [code-agent-chat-readiness.md](code-agent-chat-readiness.md) |
-| Keil / pyOCD / UART 工具 | 外部或主机侧工具 | 由 `device-host-cli` 和 gateway 间接调用 | 保留 | 否 | [spec-device-pod.md](spec-device-pod.md) |
+| 对象 | 类型 | 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-agent-mgr` | HWLAB 自研常驻服务 | 保留，但职责需收敛 | 是，P1 | [spec-v02-hwlab-agent-mgr.md](spec-v02-hwlab-agent-mgr.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) |
+| `hwlab-agent-worker` | HWLAB 自研 Job/执行入口 | 保留，非第一波 | 建议迁，P2 | [spec-v02-hwlab-agent-worker.md](spec-v02-hwlab-agent-worker.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) |
+| `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` | CLI/Job 工具 | 保留灵活 | 否 | [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) |
+| 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) |
 
 ## 语言迁移边界
 
@@ -152,3 +174,33 @@ hwlab-patch-panel
 ```
 
 裁撤集合不再新增单服务 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；裁撤对象即使 runtime 暂存，也不能作为新开发权威入口。
+
+## 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 已独立成文或交叉引用权威规格。 |
+| `simu`、接线盘、router、tunnel-client 裁撤 | 已实现 | 本文记录裁撤口径，不建立对应单服务 spec。 |
+| Bun + TypeScript 迁移边界 | 已实现 | 本文区分第一阶段、后续、暂不迁移和裁撤集合。 |
+| spec 作为开发和测试权威 | 已实现 | AGENTS.md 规格区提供顶级索引。 |
+