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

# v0.2 hwlab-cli 短连接 Client 规格

`hwlab-cli` 是 v0.2 固定开发目录里的短连接业务 client。它用于让 Codex 和人工在 `G14:/root/hwlab-v02` 直接调用与 Cloud Web 相同的 HTTP API，完成除视觉展示以外的真实业务交互和 E2E 排障。

`hwlab-cli` 不属于常驻服务，不发布镜像，不创建 Kubernetes Service、Deployment、CronJob 或 suspended Job template，不进入 GitOps desired state，不作为 CI/CD artifact 构建对象。CLI 变更默认直接在 `G14:/root/hwlab-v02` 固定 repo 修改、提交并推送 `origin/v0.2`；不创建 worktree，不走 PR，不启动或等待 CI/CD。

## 在系统中的职责划分

- 提供 WEB 等价的非视觉业务入口：登录鉴权、session 恢复、Device Pod 看板、Code Agent 对话、trace/result 轮询、logout 和工作台 live summary。
- 只走 Cloud Web 同源 API surface；默认 base URL 是 `http://74.48.78.17:19666`，也可通过 `--base-url` 或 `HWLAB_CLIENT_BASE_URL` 指向其他 Cloud Web 入口。
- 不直连 Postgres、Kubernetes Service、Secret、device-pod 内部 Service、gateway RPC 或本地 fixture；需要鉴权的请求使用 `/auth/*` 返回的 cookie 或显式 `--cookie`。
- 输出默认是 JSON；任何失败都要有 `ok:false`、`action`、`status`、HTTP 状态、route 和可定位错误，不允许无 stdout 成功。
- 旧 `hwlab-cli cicd`、fixture MVP gate 和 CLI 镜像/Job 口径属于废弃路径；开发中遇到这些旧门禁、旧测试或旧预检时直接删除，不再维护兼容。

## 内部架构

- `tools/hwlab-cli/bin/hwlab-cli.ts` 是唯一可执行入口，使用 Bun 运行。
- `tools/src/hwlab-cli-lib.ts` 承载参数解析、cookie jar、HTTP 请求、轮询和 JSON 输出。
- `tools/hwlab-cli/bin/hwlab-cli.mjs` 只允许作为兼容 shim 调用 Bun TS 入口；新功能不得继续写入 `.mjs` 旧库。
- CLI session cookie 默认写入 `.state/hwlab-cli/session.json`；状态只保存 base URL、cookie、actor 摘要和过期时间，不保存 password 或 Secret 原文。
- 所有 `client` 子命令都是短连接；长耗时 Code Agent 只提交 async request 并短轮询 result/trace，单次命令必须有 timeout 和中间状态输出。

## API 接口说明

| CLI 接口 | WEB 等价 API | 说明 |
| --- | --- | --- |
| `hwlab-cli client auth login` | `POST /auth/login` | 使用账号密码登录 Cloud Web，同步保存 cookie。 |
| `hwlab-cli client auth session` | `GET /auth/session` | 恢复当前 actor/session。 |
| `hwlab-cli client auth logout` | `POST /auth/logout` | 撤销 server session 并清理本地 cookie。 |
| `hwlab-cli client device-pods list` | `GET /v1/device-pods` | 对应右侧 Device Pod 列表。 |
| `hwlab-cli client device-pods status POD` | `GET /v1/device-pods/{pod}/status` | 对应 Device Pod summary/status。 |
| `hwlab-cli client device-pods events POD` | `GET /v1/device-pods/{pod}/events` | 对应纯文本事件流。 |
| `hwlab-cli client device-pods probe POD` | `/debug-probe/chip-id`、`/io-probe/uart/1`、`/tail` | 对应 Target/Debug/IO 摘要。 |
| `hwlab-cli client agent send` | `POST /v1/agent/chat` + `GET /result/{trace}` | 以 short connection 提交 Code Agent 消息并轮询结果。 |
| `hwlab-cli client agent trace TRACE` | `GET /v1/agent/chat/trace/{trace}` | 回放 trace。 |
| `hwlab-cli client agent cancel TRACE` | `POST /v1/agent/chat/cancel` | 取消当前 Code Agent 请求。 |
| `hwlab-cli client workbench summary` | `/health/live`、`/v1`、`/v1/live-builds`、`/v1/device-pods*` | 汇总 Cloud Workbench 非视觉功能面。 |

`client` 之外的历史命令不作为 v0.2 验收入口。保留旧命令时只能返回废弃说明或转向 `client`，不得把 fixture 或 dry-run 结果当作 WEB 功能通过证据。

## 测试规格

## T1

阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：运行 `node scripts/run-bun.mjs tools/hwlab-cli/bin/hwlab-cli.ts client auth login --base-url http://74.48.78.17:19666 --username admin --password-env HWLAB_PASSWORD`，确认返回 JSON、HTTP 200、保存 cookie，输出不包含 password 或 Secret 原文。

## T2

阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：运行 `client auth session`、`client device-pods list`、`client device-pods status device-pod-71-freq` 和 `client workbench summary --pod-id device-pod-71-freq`，确认全部走 `19666` Cloud Web 同源 API，未登录时返回认证 blocker，登录后返回真实 Device Pod payload，不读取本地 fixture。

## T3

阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：运行 `client agent send --message "你好" --provider-profile deepseek --timeout-ms 120000`，确认响应包含 accepted/result/trace 信息；若后端失败，输出必须包含 traceId、resultUrl 或 runnerTrace 摘要，不能无输出或只给旧 gate blocker。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| 固定 repo 短连接 client | 目标状态 | `hwlab-cli` 只在 `G14:/root/hwlab-v02` 直接运行。 |
| WEB 等价 API client | 目标状态 | `client` 子命令覆盖 Cloud Web 非视觉业务面。 |
| 本地 cookie session | 目标状态 | `.state/hwlab-cli/session.json` 只保存 cookie/session 摘要。 |
| 镜像/Service/Job template | 已废弃 | 相关 deploy、GitOps、artifact 和 Tekton 口径必须删除。 |
| PR/CI/CD/worktree 流程 | 已废弃 | CLI 变更不走常驻服务发布流程。 |