# 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 或未实现时拒绝执行。 |