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。
• Pod 内透传执行不放进 hwlab-cli；需要进入正在工作的 Code Agent/Cloud API pod 时，hwlab-cli 只查询并输出 UniDesk 标准 route，实际透传由 UniDesk bun scripts/cli.ts ssh 'G14:k3s:hwlab-v02:pod:<pod>:<container>' ... 完成。pod: 是 route 语法，/ 只用于 pod 内文件系统路径。
• 专用子命令覆盖高频用户工作台；client request METHOD /path 覆盖 WEB 同源代理允许的其他非视觉 API。client request 只接受以 / 开头的 Cloud Web 相对路径，禁止绝对 URL，避免绕过 Cloud Web 直接打内部服务。
• 输出默认是 JSON；任何失败都要有 ok:false、action、status、HTTP 状态、route 和可定位错误，不允许无 stdout 成功。可能返回大对象的 client 子命令默认返回紧凑摘要，避免高频排障输出爆炸；需要完整响应体时显式加 --full。
• Code Agent 交互必须默认暴露 traceId、resultUrl、终态和 assistant 回复文本摘要；不能要求用户先拉全量 trace 再手工查找回复。
• 旧 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 runtime routes	GET /v1/live-builds	查询当前工作面 pod，并输出 UniDesk 标准 pod: route；不执行透传、不调用 kubectl、不内嵌 UniDesk。
hwlab-cli client agent send	POST /v1/agent/chat + GET /result/{trace}	以 short connection 提交 Code Agent 消息并轮询结果，默认输出 assistant 回复文本摘要。
hwlab-cli client agent trace TRACE	GET /v1/agent/chat/trace/{trace}	回放 trace，默认输出状态、事件摘要和 assistant stream 文本。
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 非视觉功能面。
hwlab-cli client rpc METHOD [--full]	POST /json-rpc	像 Web callRpc 一样自动生成 id、traceId 和 meta，覆盖 system.health、cloud.adapter.describe 等 JSON-RPC 非视觉能力。
hwlab-cli client request METHOD /path [--full]	Cloud Web 同源相对路径	覆盖 /v1/access/status、/v1/setup/status、/v1/diagnostics/gate、/v1/m3/status、/v1/m3/io 等低频或新增 WEB API；/json-rpc 优先使用 client rpc。

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 信息和 assistant 回复文本；若后端失败，输出必须包含 traceId、resultUrl 或 runnerTrace 摘要，不能无输出或只给旧 gate blocker。

T4

阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 G14:/root/hwlab-v02 用 cli 手动测试以下内容：运行 client request GET /v1/access/status、client request GET /v1/diagnostics/gate 和 client rpc system.health，确认它们全部走 19666 Cloud Web 同源 API，返回 JSON route/httpStatus/body，且 client request 传入绝对 URL 会被拒绝。

规格的实现情况

规格项	状态	说明
固定 repo 短连接 client	目标状态	hwlab-cli 只在 G14:/root/hwlab-v02 直接运行。
WEB 等价 API client	目标状态	client 子命令覆盖 Cloud Web 非视觉业务面。
JSON-RPC 同源 API	目标状态	client rpc 自动补齐 Web JSON-RPC envelope 的 meta 字段。
通用同源 API request	目标状态	client request 用于追平低频和新增 WEB API，禁止绝对 URL。
本地 cookie session	目标状态	.state/hwlab-cli/session.json 只保存 cookie/session 摘要。
镜像/Service/Job template	已废弃	相关 deploy、GitOps、artifact 和 Tekton 口径必须删除。
PR/CI/CD/worktree 流程	已废弃	CLI 变更不走常驻服务发布流程。