pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-0104-client.md

PJ2026-0104 客户端

修改历史

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

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

正文

PJ2026-0104 客户端需求规格

1. 文档控制

字段	内容
编号	PJ2026-0104
短名	客户端
层级	L1 方向
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-01 HWLAB 总规格
规格治理索引	规格治理

本文采用 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 和租户真相归 用户管理。
• Agent run、session、workspace 和 result 指针事实归 Agent编排。
• HWPOD 资源、硬件事实和 probe 能力归 硬件池。
• CaseRun 评价、aggregate、replay 和训练反馈归 HarnessRL。
• FRP、Caddy、TLS、CI/CD、Secret 和发布健康归 平台运维。

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工作台	Cloud Web 用户工作流、会话输入、诊断反馈和响应式布局	用户管理、Agent编排、硬件池、HarnessRL、平台运维	用户和管理员
PJ2026-010402	HWLAB CLI	PJ2026-010402 HWLAB CLI	短连接命令、同源 API 调用、结构化输出、错误语义和非视觉全流程复验	全部业务 L1	用户脚本、自动化脚本、内测复现
PJ2026-010403	API契约	PJ2026-010403 API契约	同源 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工作台	用户管理、Agent编排、硬件池、HarnessRL、平台运维

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

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

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	Agent编排、硬件池、HarnessRL、用户管理

客户端应提供可脚本化的 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契约	用户管理、Agent编排、硬件池、HarnessRL、平台运维

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

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

7. 过程控制

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