# PJ2026-010402 HWLAB CLI

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。

## 正文

## PJ2026-010402 HWLAB CLI 需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010402 |
| 短名 | HWLAB CLI |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB CLI 的稳定使命、范围、术语、系统边界、内部分工和原子需求。

## 2. 目的和范围

### 2.1 目的

HWLAB CLI 负责提供 Cloud Web 的非视觉同源业务入口，使用户、管理员和自动化脚本能够用短连接命令完成认证、工作台恢复、Agent session、任务提交、trace/result、HWPOD/CaseRun 组合入口和管理能力的真实复验。

本课题的目标状态是：完整 HWLAB 内测和排障流程可以通过 CLI 从同一个运行端点跑通一遍；CLI 输出足够短、结构化、可继续查询，并且不绕过 Web/API 用户路径去直连内部服务、数据库、Kubernetes 或临时 fixture。

### 2.2 范围内

- 运行端点解析、lane/namespace 锁定、短连接行为和 fail-closed 语义。
- CLI API key 鉴权入口、Web session 诊断边界和凭据脱敏输出。
- `client auth`、`request`、`rpc`、`access`、`provider-profiles`、`workbench`、`agent`、`gateway`、`harness` 等同源业务命令的命令形态、输出和错误语义。
- 显式 Agent session 创建、选择、状态、send、result、trace、inspect、steer、cancel 和 composer policy 等非视觉入口。
- CaseRun 和 HWPOD 相关组合入口的身份、trace/result 和下一步命令提示；具体 HWPOD 语义和 CaseRun 评价由对应模块负责。
- JSON 输出、默认摘要、`--full`/`--raw` 渐进披露、错误分类和敏感值不输出。

### 2.3 范围外

- HWPOD spec、设备身份、租约、node health 和硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。
- HWPOD 工具的硬件动作语义归 [PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md)。
- AgentRun run、command、runner job、session continuation 和 provider profile runtime 归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
- CaseRun 定义、registry、评价、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。
- 用户、组织、API key、额度、usage 和权限真相归 [用户管理](PJ2026-0105-user-management.md)。
- 发布流水、GitOps、Secret 下发、FRP、Caddy 和 Prometheus 运维监控归 [平台运维](PJ2026-0106-platform-ops.md)。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| 同源 CLI | 通过 Cloud Web origin 和相对 API path 访问 HWLAB 的命令行入口，与浏览器使用同一业务路径和错误语义。 |
| 短连接命令 | 快速返回命令结果、查询标识或下一步命令的 CLI 调用，不用单个命令长期阻塞等待完整执行。 |
| 运行端点解析 | 根据运行 lane、namespace 或受控环境声明解析 Web/API endpoint，并在锁定状态下拒绝人工 URL 覆盖。 |
| 显式 Agent session | 用户明确创建或选择的 Code Agent session，是普通 `send` 的前置条件。 |
| Web renderer | Web trace 展示和 CLI `trace --render web` 共同使用的 trace row 转换语义。 |
| 组合入口 | 上层 CLI 只返回 ID、摘要和下一步命令，完整业务语义继续交给已有 HWPOD、Agent 或 CaseRun 入口。 |

## 4. 系统边界和接口

本规格把 HWLAB CLI 作为客户端方向下的命令行入口课题看待；本章只描述输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 硬件研发用户、平台管理员、自动化脚本、内测执行者和排障人员。 |
| 外部输入 | API key、运行端点选择、profile、请求 path、任务文本、sessionId、traceId、runId、caseId、HWPOD 选择和命令参数。 |
| 受控资源 | CLI 命令树、运行端点解析、同源 HTTP 调用、结构化输出、状态文件摘要、trace renderer 调用和下一步命令提示。 |
| 外部输出 | JSON 响应、HTTP route/status、sessionId、traceId、runId、commandId、错误分类、摘要 rows、脱敏凭据状态和可复制后续命令。 |
| 用户接口 | `hwlab-cli client ...`、`hwlab-cli case ...`、HWPOD 工具组合入口。 |
| 系统边界 | HWLAB CLI 负责命令入口、调用路径、输出和错误表达；不拥有账号、Agent、硬件、CaseRun 或发布事实。 |

## 5. 内部分工与规格索引

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-01040201 | 端点鉴权 | 本规格 6.1 | 运行端点解析、API key 鉴权入口、Web session 诊断边界和脱敏输出 | 用户管理、平台运维 | 全部 CLI 命令 |
| PJ2026-01040202 | 同源请求 | 本规格 6.2 | Cloud Web 相对 path、JSON-RPC、Admin Access、provider profile 和通用 request/rpc 命令 | API契约、用户管理 | Web 等价复验、自动化脚本 |
| PJ2026-01040203 | Agent会话 | 本规格 6.3 | 显式 session、send、composer、steer、cancel 和短连接提交语义 | Agent编排、用户管理 | Web 工作台、内测任务 |
| PJ2026-01040204 | Trace结果 | 本规格 6.4 | result/trace/inspect、Web renderer、sourceSeq 窗口和渐进披露 | Agent编排、Web工作台 | CaseRun、排障、阶段复现 |
| PJ2026-01040205 | 全流程复验 | 本规格 6.5 | 用 CLI 串起账号、工作台、Agent、HWPOD/CaseRun 和管理能力的非视觉复验组合 | 全部业务 L1 | 内测、灰度、用户反馈复现 |

## 6. 原子需求

### 6.1 CLIENT-CLI-REQ-001 端点与鉴权

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-CLI-REQ-001 | 端点鉴权 | PJ2026-01040201 端点鉴权 | [用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) |

HWLAB CLI 应根据运行 lane、namespace 或受控环境声明解析目标 Web/API endpoint，并在端点锁定时拒绝人工 URL 覆盖，使 CLI 复验不会误打旧 DEV、legacy 或内部服务路径。

CLI 鉴权入口只负责把用户提供的 API key 作为命令行调用凭据使用，并以脱敏方式输出 key presence、来源和 actor 摘要。API key 生命周期、用户身份和权限真相由用户管理负责；平台运维提供运行端点和公开入口支撑。

### 6.2 CLIENT-CLI-REQ-002 同源请求

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-CLI-REQ-002 | 同源请求 | PJ2026-01040202 同源请求 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

HWLAB CLI 应提供 Cloud Web 同源的 request、rpc、access、provider-profiles、workbench、gateway 和 harness 类命令，使非视觉复验能够访问与浏览器一致的业务 API、schema 和错误语义。

同源请求不得把绝对 URL、内部 ClusterIP、Postgres、Kubernetes Service、Secret 或临时 fixture 当作正式用户入口。确需 Cloud API 直连的 gateway/HWPOD 诊断必须明确显示其诊断属性，不能替代 Web 用户流程通过结论。

### 6.3 CLIENT-CLI-REQ-003 Agent 会话入口

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-CLI-REQ-003 | Agent会话 | PJ2026-01040203 Agent会话 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md) |

HWLAB CLI 应提供显式 Code Agent session 创建、选择、状态、send、composer、steer 和 cancel 入口，使用户能够按与 Web 工作台一致的 session 语义提交任务和干预运行中任务。

普通 `send` 必须绑定显式 session 或已显式选中的 session；session 缺失、failed、stale 或 canceled 时，CLI 应返回结构化 blocker 和下一步命令，不得自动创建、滚动或替换 session。AgentRun 执行生命周期和 provider profile runtime 事实仍由 Agent编排负责。

CLI 的 Agent 会话入口应以短连接资源操作为默认形态：创建、send、steer、cancel 快速返回 session、run、command、traceId 或下一步命令；完整模型 turn 通过 result/trace/status 轮询读取。CLI 不得为了“看起来像聊天”而长期阻塞等待 runner 完成，也不得在无 session 时用本地历史或默认 thread 静默续接。

### 6.4 CLIENT-CLI-REQ-004 Trace 与结果

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-CLI-REQ-004 | Trace结果 | PJ2026-01040204 Trace结果 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

HWLAB CLI 应提供 result、trace、inspect 和 Web renderer 等入口，使用户能通过 traceId 查看终态结果、实时 trace 摘要、session 上下文、steer 归属和必要工具行。

`trace --render web` 必须与 Web 工作台共享 trace row 语义，并支持默认摘要、sourceSeq 窗口、tail、tool summary 和完整展开。CLI 只呈现同一路径的 trace/result，不重新发明 final response、AgentRun events 过滤或 CaseRun aggregate 语义。

CLI 默认输出应低噪声且可继续操作：终端命令只显示状态、标识符、摘要和下一步命令，`--full` 或 `--raw` 才展开完整事件、原始 envelope 或长输出。trace/result 缺失、events capped、partial assistant、provider blocker 或 session 不可用都应结构化表达，不能把 stdout 尾部、transport close 或已有 assistant delta 当作 completed。

### 6.5 CLIENT-CLI-REQ-005 全流程 CLI 复验

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-CLI-REQ-005 | 全流程复验 | PJ2026-01040205 全流程复验 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[用户管理](PJ2026-0105-user-management.md) |

HWLAB CLI 应能串起一次完整非视觉业务复验：确认当前用户和额度边界、恢复账号工作台、显式创建 Agent session、提交嵌入式任务、读取 result/trace、通过 HWPOD 或 CaseRun 入口触达真实硬件能力，并把每一步的可查询标识返回给调用者。

全流程复验是客户端入口能力，不是新的业务事实源。硬件池负责 HWPOD 和设备事实，Agent编排负责 run/command/session，HarnessRL 负责 CaseRun 和评价关系，用户管理负责账号和权限；CLI 只负责把这些能力组合成一致、可脚本化、可排障的用户入口。

## 7. 过程控制

本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。