# PJ2026-0104 客户端

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |
| v0.3 | b5d8cee438a3bd66ca440a25bf5a16d9081d9efa | 2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 |
| v0.2 | b0cbe9b721b50e9fff4d350ee50ed2af03cf0405 | 2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 |
| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从迁移来源 pikasTech/HWLAB#1206 迁移到 UniDesk 项目管理目录。 |

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

## 正文

## PJ2026-0104 客户端需求规格

## 1. 文档控制

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

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

## 2. 目的和范围

### 2.1 目的

客户端负责 HWLAB 面向用户的统一入口，使 Web、HWLAB CLI 和 HTTP API 围绕同一任务模型、权限模型、资源模型、trace/result 模型和错误语义协同演进。

### 2.2 范围内

- Cloud Web 工作台、登录后工作流、任务创建、会话入口、trace/result 展示和用户可见资源入口。
- Cloud Web 通过 `/auth/session` 消费 canonical identity，并以业务 API 返回的 capability/blocker 展示授权状态。
- HWLAB CLI 的运行端点解析、API key 鉴权入口、同源 API 调用、短连接命令、结构化输出、错误语义和脚本可用性。
- 通过 HWLAB CLI 覆盖账号/额度、工作台、显式 Agent session、Agent 任务、trace/result、HWPOD/CaseRun 组合入口和必要管理入口的非视觉全流程复验。
- HTTP API 的同源 path、schema、错误语义、鉴权主体和多端一致性。

### 2.3 范围外

- 用户身份、API key、额度、usage、billing 和租户真相归 [用户管理](PJ2026-0105-user-management.md)。
- Agent run、session、workspace 和 result 指针事实归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
- HWPOD 资源、硬件事实和 probe 能力归 [硬件池](PJ2026-0101-hardware-pool.md)。
- CaseRun 评价、aggregate、replay 和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。
- FRP、Caddy、TLS、CI/CD、Secret 和发布健康归 [平台运维](PJ2026-0106-platform-ops.md)。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| Cloud Web | HWLAB 的 Web 用户入口，承载登录、工作台、任务、资源和管理页面。 |
| HWLAB CLI | HWLAB 命令行入口，用于脚本化访问 Web 同源 API、Agent、CaseRun、HWPOD、用户和管理能力。 |
| 同源 CLI | 与 Cloud Web 使用同一 Web origin、同一相对 API path 和同一用户身份语义的 HWLAB CLI 调用方式。 |
| API 契约 | HTTP API 和错误语义的稳定调用约定。 |
| 多客户端一致性 | 不同入口共享同一任务、权限、错误和结果语义。 |
| 短连接命令 | 发起后快速返回可查询 ID 或紧凑结果，再通过 status、trace、result 或 watch 继续观察的 CLI 命令。 |
| 前端身份消费 | Cloud Web 只调用 `/auth/session` 读取 canonical identity，并把后端返回的 capability/blocker 显示给用户；不保存、不派生、不输入其他身份凭据。 |

## 4. 系统边界和接口

本规格把客户端作为 HWLAB 的用户入口子系统看待；本章只描述该子系统的输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 硬件研发用户、自动化脚本使用者、平台管理员。 |
| 外部输入 | 用户凭据、API key、运行端点选择、任务请求、workspace/HWPOD 选择、Agent session 操作、CaseRun 操作和管理操作。 |
| 受控资源 | Web 页面、HWLAB CLI 命令、HTTP API、共享 trace renderer 和同源 API 调用契约。 |
| 外部输出 | 用户可见任务入口、资源入口、命令响应、HTTP 响应、错误语义、trace/result 摘要和结果展示。 |
| 用户接口 | Cloud Web、HWLAB CLI、HTTP API。 |
| 系统边界 | 客户端负责入口一致性和用户可见契约；不定义后端业务事实、硬件事实、评价语义、账本真相或发布机制。 |

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

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-010401 | Web工作台 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) | Cloud Web 用户工作流、会话输入、诊断反馈和响应式布局 | 用户管理、Agent编排、硬件池、HarnessRL、平台运维 | 用户和管理员 |
| PJ2026-010402 | HWLAB CLI | [PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md) | 短连接命令、同源 API 调用、结构化输出、错误语义和非视觉全流程复验 | 全部业务 L1 | 用户脚本、自动化脚本、内测复现 |
| PJ2026-010403 | API契约 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) | 同源 API path、schema、鉴权主体、错误码和兼容性 | 用户管理、Agent编排、硬件池、HarnessRL、平台运维 | Web、HWLAB CLI |

## 6. 原子需求

### 6.1 CLIENT-L1-REQ-001 Cloud Web 工作台

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-L1-REQ-001 | Web工作台 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |

客户端应提供 Cloud Web 工作台，使用户能够通过同一 Web 入口完成登录后的任务创建、会话操作、硬件资源选择、执行结果查看和管理能力访问。

Web 工作台只承载用户交互和展示契约。身份真相来自用户管理，任务事实来自 Agent编排，硬件事实来自硬件池，评价语义来自 HarnessRL，公开入口健康来自平台运维。具体工作台框架、会话输入、诊断反馈和响应布局由 [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) 约束。

Cloud Web 的认证态只能来自 `/auth/session` 返回的 canonical identity。前端不得保存或读取 user-billing token、API key secret、cookie prefix、Bearer token、localStorage authority 或测试专用后门来判断登录；业务页面只能根据后端 capability/blocker 展示可用、未开通、禁止或不可用状态。

### 6.2 CLIENT-L1-REQ-002 HWLAB CLI 入口

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-L1-REQ-002 | HWLAB CLI | [PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[用户管理](PJ2026-0105-user-management.md) |

客户端应提供可脚本化的 HWLAB CLI 入口，使用户和自动化脚本能用一致的运行端点、参数、输出和错误语义访问 HWLAB 能力。

HWLAB CLI 必须能以非视觉方式跑通内测和排障需要的完整用户流程：认证当前用户、恢复工作台、显式创建或选择 Agent session、提交任务、读取 result/trace、复现 Web trace renderer、触达 HWPOD/CaseRun 组合入口，并输出可继续查询的 sessionId、traceId、runId、commandId 或等价标识。

CLI 入口必须复用后端业务事实，不在命令行层重新定义 HWPOD、CaseRun、Agent session、用户额度或评价结果。命令行文本和 JSON 输出服务于自动化使用和人工排障，但不替代业务模块的完成标准。

### 6.3 CLIENT-L1-REQ-003 API 契约

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-L1-REQ-003 | API契约 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |

客户端应定义 HTTP API、schema、错误码和兼容性契约，使 Web、HWLAB CLI 和自动化脚本围绕同一接口语义访问 HWLAB。

API 契约负责调用形态、字段稳定性和错误表达，不拥有账号、任务、硬件或评价的业务真相。后端模块改变事实模型时，客户端负责把 Web、HWLAB CLI 和 HTTP API 的入口契约以一致方式暴露。

## 7. 过程控制

本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。客户端方向的阶段活动材料应引用本规格和各 L2 规格，不在本规格正文中展开执行流水。
