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 入口。
- Web/CLI 路径一致性优先于继续 Web 修复。Cloud Web 暴露 Code Agent、AgentRun、continuation、trace/result 或 provider 问题后，必须先能用 `hwlab-cli client agent send/result/trace/inspect` 对同一 base URL、同一 `/v1/agent/chat`、同一 `conversationId/sessionId/threadId/retryOf` 复现或解释，再继续修 Web 状态机。
- 从 Web trace 回放 Code Agent 问题时，优先用 `client agent send --from-trace <traceId>` 读取 Cloud Web 的 `/v1/agent/chat/inspect`，自动带回原 `conversationId/sessionId/threadId` 并把 `retryOf` 指向来源 trace；只有 inspect 缺失时才手动传 `--conversation-id`、`--session-id`、`--thread-id` 和 `--retry-of`。CLI 输出必须包含 replay 来源、inspect 状态和 redacted continuation 摘要。
- 默认业务子命令不直连 Postgres、Kubernetes Service、Secret、device-pod 内部 Service、gateway RPC 或本地 fixture；需要鉴权的请求使用 `/auth/*` 返回的 cookie 或显式 `--cookie`。唯一例外是 `client gateway` 诊断族：它允许显式 `--api-base-url` 指向 Cloud API，用于短连接观测 gateway session、单次 shell invoke 和 transport 压测；该入口只验证底层传输稳定性，不替代 Web 用户流程授权，也不发布镜像或常驻服务。
- 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 runtime routes` 必须按当前运行 profile/lane 的数据生成 UniDesk `pod:` route；实现不得硬编码 `dev`、`v0.2`、`v0.3`、namespace 或 catalog path。新增版本只允许通过 `deploy.json.lanes[profile]` 声明 namespace、artifact catalog 和 service overrides，不为每个版本新增代码分支。
- 运行时不做内部证明型校验、旧健康诊断或重断言；CI/CD 只保留能证明代码可构建、语法正确和最小冒烟可用的校验。功能正确性通过 `hwlab-cli client` 短连接真实业务 E2E 暴露和修复。
- 专用子命令覆盖高频用户工作台；`client request METHOD /path` 覆盖 WEB 同源代理允许的其他非视觉 API。`client request` 只接受以 `/` 开头的 Cloud Web 相对路径，禁止绝对 URL，避免绕过 Cloud Web 直接打内部服务。
- `client gateway pressure` 是 device-pod/gateway 高频故障的真实业务传输压测入口；必须覆盖 small stdout、大 stdout、长单行 stdout、stderr flood、结构化 timeout 和超出 gateway inflight 上限的并发请求。所有场景必须返回 JSON、HTTP/route/traceId/requestId、字节数、truncated 标记、sha256 和 bounded preview；失败必须明确是 `http_*`、`stdout_not_truncated`、`stderr_not_truncated`、`timeout_not_observed`、`structured_gateway_busy` 等可定位原因，禁止无输出、长时间黑洞或只靠 shell pipe 截断。
- 输出默认是 JSON；任何失败都要有 `ok:false`、`action`、`status`、HTTP 状态、route 和可定位错误，不允许无 stdout 成功。可能返回大对象的 `client` 子命令默认返回紧凑摘要，避免高频排障输出爆炸；需要完整响应体时显式加 `--full`。
- `device-pod-cli`/`hwpod` 的 `job output` 默认也必须返回紧凑 JSON：保留 job/status/blocker/freshness/text/evidence 摘要，省略嵌套 gateway dispatch 和长命令；需要完整 payload 时显式加 `--full`。Code Agent 和人工不得用 `| head`、`grep` 或 shell 管道作为默认输出压缩方式，避免 stdout pipe、子进程信号转发或长输出造成 commandExecution 黑洞。
- Code Agent 交互必须默认暴露 `traceId`、`resultUrl`、终态和 assistant 回复文本摘要；不能要求用户先拉全量 trace 再手工查找回复。
- `client agent send` 是 Cloud Web Code Agent composer 的非视觉等价入口。它必须支持 `--from-trace`、`--conversation-id`、`--session-id`、`--thread-id` 和 `--retry-of`，并在输出中返回 redacted continuation 摘要，证明本次 CLI 请求是否覆盖 Web 的继续会话路径。
- AgentRun v0.1 短连接 runner 不保证历史 Web/Codex `threadId` 可在新 runner Job 内 resume；CLI 仍应把 Web 提交的 `threadId` 原样送到 Cloud Web API，以便验证 adapter 是否正确把它降级为 `requestedThreadId` 元数据，而不是让 runner 执行旧 thread resume。
- `client harness`、`client harness-ops` 和 `client harness-opt` 吸收 G14 harness-ops 的短连接业务能力：health、submit、result、trace、wait 和 audit。
- harness 系列命令只调用 Cloud Web/Code Agent 同源 API，不创建镜像、Job、常驻服务，也不执行 hot-sync、kubectl cp 或硬编码 namespace/pod 的运行面写路径。
- 旧 `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 gateway sessions` | `GET Cloud API /v1/gateway/sessions` | 显式 Cloud API 诊断入口，观察 gateway online/stale、inflight 和 capability；默认不带 Web cookie。 |
| `hwlab-cli client gateway invoke` | `POST Cloud API /v1/rpc/hardware.invoke.shell` | 显式 Cloud API 诊断入口，执行一次 bounded shell dispatch 并返回结构化 dispatch 摘要。 |
| `hwlab-cli client gateway pressure` | `POST Cloud API /v1/rpc/hardware.invoke.shell` | 显式 Cloud API 压测入口，真实验证大输出、长单行、stderr、timeout 和并发超容量不会造成黑洞。 |
| `hwlab-cli client agent send` | `GET /v1/agent/chat/inspect` + `POST /v1/agent/chat` + `GET /result/{trace}` | 以 short connection 提交 Code Agent 消息并轮询结果，默认输出 assistant 回复文本摘要；支持 `--from-trace` 自动复现 Web continuation，也支持手动 `--conversation-id`、`--session-id`、`--thread-id`、`--retry-of`。 |
| `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 harness submit` | `POST /v1/agent/chat` | G14 harness-ops 的短连接提交入口，默认 provider profile 为 `deepseek`，返回 trace/result URL；`harness-ops` 和 `harness-opt` 是同义别名。 |
| `hwlab-cli client harness wait/result/trace` | `GET /v1/agent/chat/result/{trace}`、`GET /trace/{trace}` | 轮询或读取一次 Code Agent 结果和 trace；单次 wait 最长 60 秒。 |
| `hwlab-cli client harness audit` | `GET /v1/agent/chat/trace/{trace}` 或本地 trace file | 只输出工具摩擦信号，辅助发现应补的主 CLI/device-pod 操作；不是运行时 gate。 |
| `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。

## T3.1

阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：对一个来自 Cloud Web 的失败 trace 运行 `client agent send --from-trace <traceId> --message "重试上一条" --provider-profile deepseek --no-wait`，确认 CLI 先访问 `/v1/agent/chat/inspect?traceId=<traceId>`，再提交 `/v1/agent/chat`，输出包含 `replay.source`、`continuation.replayedFromTrace`、`conversationId/sessionId/threadId/retryOf`，且不输出 cookie、token 或 secret 原文。

## 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 会被拒绝。

## T5

阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：运行 `client harness health`、`client harness submit --message "你好" --provider-profile deepseek --timeout-ms 120000`、`client harness wait <traceId>` 和 `client harness audit <traceId>`。确认它们全部是短连接 JSON 输出，不创建镜像、Job、CronJob、Deployment 或 hot-sync 写路径。

## T6

阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：运行 `hwpod job output --pod-id D601-F103-V2 <jobId> --api-base-url http://74.48.78.17:19667`，确认默认输出包含 `body.compacted=true`、状态、job 摘要和 bounded text，且不包含嵌套 `dispatch.command`；再加 `--full` 确认完整 payload 可按需展开。通过 `client harness submit` 让 Code Agent 执行同一 `hwpod job output`，确认 trace 中 commandExecution 可以完成，不需要 `| head`。

## T7

阅读 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 gateway pressure --api-base-url http://74.48.78.17:19667 --gateway-session-id gws_D601_F103 --large-bytes 131072 --parallel 8 --request-timeout-ms 60000 --timeout-scenario-ms 1000 --no-auth --full`。确认 small stdout、大 stdout、长单行 stdout、stderr flood、timeout 和并发超容量全部返回结构化 JSON；大输出应显示 `stdoutBytes` 或 `stderrBytes`、`stdoutTruncated` 或 `stderrTruncated`、sha256 和 preview，超出 `maxInflightRequests` 的请求必须显示 `structured_gateway_busy`，不能出现无输出或卡死。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| 固定 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。 |
| G14 harness-ops 短连接能力 | 目标状态 | `client harness` / `client harness-ops` / `client harness-opt` 覆盖 submit/result/trace/wait/audit，只作为业务 API client。 |
| Gateway transport 压测 | 已实现 | `client gateway pressure` 只作为显式短连接诊断入口，覆盖大输出、timeout 和并发超容量的结构化返回。 |
| Device Pod job output 紧凑输出 | 已实现 | `hwpod job output` 默认省略嵌套 dispatch，`--full` 才展开完整 payload，防止 Code Agent 通过 shell pipe 压输出。 |
| 本地 cookie session | 目标状态 | `.state/hwlab-cli/session.json` 只保存 cookie/session 摘要。 |
| 镜像/Service/Job template | 已废弃 | 相关 deploy、GitOps、artifact 和 Tekton 口径必须删除。 |
| PR/CI/CD/worktree 流程 | 已废弃 | CLI 变更不走常驻服务发布流程。 |