Codex
186 lines
18 KiB
Markdown
186 lines
18 KiB
Markdown
# 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 方向 |
|
||
| 状态 | 已生效 |
|
||
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-project-management-mdtodo; draft-2026-06-25-p0-mdtodo-web-active-editing-hwpod-source; draft-2026-07-13-p0-cloud-console |
|
||
| 需求规格模板 | [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 模型和错误语义协同演进。
|
||
|
||
客户端还负责把 Web CaseRun 暴露为用户可直接操作、可观察、可复验的端到端入口，使浏览器用户和自动化验收都通过同一 YAML-selected Cloud Web origin、同一 API 契约、同一 runId 和同一结果阅读模型触达 HarnessRL、Agent编排和硬件池能力。
|
||
|
||
### 2.2 范围内
|
||
|
||
- Cloud Web 工作台、登录后工作流、任务创建、会话入口、trace/result 展示和用户可见资源入口。
|
||
- Cloud Web 通过 `/auth/session` 消费 canonical identity，并以业务 API 返回的 capability/blocker 展示授权状态。
|
||
- Cloud Web 的 CaseRun 用户入口、run 状态卡、trace/aggregate/HWPOD 证据阅读入口和可操作 blocker 展示。
|
||
- Cloud Web 的项目管理根导航、MDTODO 页面、HWPOD-bound Source 配置、Rxx 任务树、主动编辑控件、项目任务 DTO、Workbench launch context 和任务到 Workbench session 的公共 ID 链接。
|
||
- Cloud Web 除 Workbench 外的统一应用壳、Dashboard、HWPOD 资源与 Node、节点接入、用户运营、管理和系统工具页面。
|
||
- Cloud Web 的工业设计系统、通用集合、Overlay、Viewer、异步状态、显示模式、URL view state、响应式和无障碍合同。
|
||
- HWLAB CLI 的运行端点解析、API key 鉴权入口、同源 API 调用、短连接命令、结构化输出、错误语义和脚本可用性。
|
||
- 通过 HWLAB CLI 覆盖账号/额度、工作台、显式 Agent session、Agent 任务、trace/result、HWPOD/CaseRun 组合入口和必要管理入口的非视觉全流程复验。
|
||
- web-probe 作为 Cloud Web 同源非视觉验收路径运行 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)。
|
||
- 项目管理的 source、任务投影、MDTODO adapter、Workbench link 和外部 PM adapter 归 [项目管理](PJ2026-010404-project-management.md)；Workbench 只消费公共 launch context 元数据。
|
||
- 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 调用方式。 |
|
||
| Web CaseRun 入口 | Cloud Web 中提交、观察和阅读 CaseRun 的用户界面，与同源 CaseRun API 和 HarnessRL run/read model 绑定。 |
|
||
| 项目管理入口 | Cloud Web 登录后的 `/projects` 和 `/projects/mdtodo` 用户入口，用于查看项目 source、MDTODO 任务树和 Workbench link。 |
|
||
| MDTODO Web 主动编辑 | `/projects/mdtodo` 中通过 Project Management API 修改 Markdown source-of-truth 的用户操作，包括 Source 配置、Rxx task mutation、reindex 和 Workbench launch。 |
|
||
| Workbench launch context | 项目管理等外部页面传给公共 Workbench Launch API 的脱敏启动上下文，只包含 `projectId`、`taskRef`、sourceKind、title 摘要和 prompt template 等元数据。 |
|
||
| selected Web origin | 由 node/lane YAML 声明并由客户端工具解析的 Web origin；默认是 public origin，本次 D601/v03 验收可选择 internal IP origin。 |
|
||
| web-probe CaseRun | 通过真实浏览器和 selected Web origin 执行的 CaseRun 验收路径；只模拟用户入口和同源 API，不直接访问未声明的内部服务。 |
|
||
| 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 操作、Web CaseRun 操作和管理操作。 |
|
||
| 受控资源 | Web 页面、HWLAB CLI 命令、HTTP API、共享 trace renderer 和同源 API 调用契约。 |
|
||
| 外部输出 | 用户可见任务入口、资源入口、CaseRun run 卡和 aggregate 阅读入口、命令响应、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 |
|
||
| PJ2026-010404 | 项目管理 | [PJ2026-010404 项目管理](PJ2026-010404-project-management.md) | 项目根导航、MDTODO 页面、独立项目管理微服务、任务投影、Workbench link 和项目管理 observe/analyze 验收 | 用户管理、Agent编排、平台运维、API契约 | Web、HWLAB CLI、web-probe |
|
||
| PJ2026-010405 | 云端控制台 | [PJ2026-010405 云端控制台](PJ2026-010405-cloud-console.md) | 非 Workbench 应用壳、领域页面、通用前端能力、typed read model 消费和原入口体验 | 用户管理、硬件池、Agent编排、HarnessRL、项目管理、平台运维 | Web 用户和管理员 |
|
||
|
||
## 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 的入口契约以一致方式暴露。
|
||
|
||
### 6.4 CLIENT-L1-REQ-004 Web CaseRun 用户入口
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| CLIENT-L1-REQ-004 | Web CaseRun入口 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md) | [HarnessRL](PJ2026-0103-harness-rl.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
|
||
|
||
客户端应提供 Web CaseRun 用户入口，使用户能在 Cloud Web 中选择 HWPOD 和 case，提交 CaseRun，观察 run stage，阅读 Agent trace、HWPOD build/download/UART 证据、artifact manifest 和 aggregate，并在失败时看到对应模块输出的结构化 blocker。
|
||
|
||
Cloud Web、HWLAB CLI 和 web-probe 必须使用 YAML 选中的同一 Web origin、同一同源 CaseRun API 和同一用户身份语义。客户端不得把 web-probe、CLI、本地脚本、未在 YAML 声明的内部 Cloud API 直连、数据库、SSH 或旧 lane 端口变成第二套 CaseRun 成功路径；非视觉验收只能证明同一 Web/API 用户路径可用。
|
||
|
||
客户端只拥有入口、展示、命令形态和错误呈现。CaseRun stage、aggregate、评价和回放归 HarnessRL；Agent run/command/trace 归 Agent编排；HWPOD 资源、租约、节点路由和 operation result 归硬件池。客户端发现能力缺失时应展示缺失能力和下一步诊断，不得用前端文案或脚本后处理合成通过状态。
|
||
|
||
### 6.5 CLIENT-L1-REQ-005 项目管理入口
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| CLIENT-L1-REQ-005 | 项目管理 | [PJ2026-010404 项目管理](PJ2026-010404-project-management.md) | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) |
|
||
|
||
客户端应提供登录后的项目管理入口，使用户能从 `/projects` 和 `/projects/mdtodo` 查看项目、source、MDTODO 文件摘要、任务树、任务状态、Workbench link 和结构化 blocker。
|
||
|
||
MDTODO 页面应提供高密度工作区：Source/File 以顶部状态栏下拉呈现，metric 摘要进入 info/diagnostic 弹窗，主版面优先展示 Rxx 任务树和详情/编辑区。页面应支持 Web 配置 HWPOD-bound Source，选择 `d601-f103-v2` 这类 HWPOD 的 `docs/MDTODO/` workspace 根，并通过同源 Project Management API 读写 Markdown source-of-truth。
|
||
|
||
MDTODO 页面必须对大 source 做有界读取：首屏不依赖 source 级全量任务响应，任务树按 selected file、parentTaskRef、搜索/状态过滤和 cursor/limit 窗口加载。`71-FREQ` 这类包含数百个 Rxx 任务的 HWPOD source 应能先完成 source/file 识别，再按用户选择加载任务窗口；不能因为一次全量 task payload 过大导致页面或 web-probe 进入 status=0/超时。
|
||
|
||
项目管理必须通过独立 `hwlab-project-management` 微服务和同源 Project Management API 暴露。客户端不得把项目管理实现并入 Workbench、Cloud Web 私有状态、Cloud API 内部模块、UniDesk `mdtodo` 或 UniDesk `project-manager` 服务。
|
||
|
||
MDTODO 主动编辑只能调用公开 Project Management API。标题/正文编辑、状态切换、添加、子任务、延续、删除和 reindex 必须带 revision/fingerprint 并发保护；冲突、parse error、HWPOD 不可用和 path 越界都应展示结构化 blocker，不能由前端本地状态、localStorage 或测试后门补造成成功。
|
||
|
||
MDTODO 页面启动 Workbench 时，只能调用公共 Workbench Launch API 并传递脱敏 `launchContext`、`projectId` 和 `taskRef`。Workbench 只消费这些元数据并按自身 session authority hydrate；项目管理页面不嵌入 Workbench、不 import Workbench store、不读取 Workbench 私有 reducer，Workbench 也不解析 Markdown 或 import MDTODO 页面。
|
||
|
||
项目管理原入口验收优先使用 web-probe observe/analyze，采样 `/projects`、`/projects/mdtodo` 和自然同源 `/v1/project-management/*` 请求；`script` 只能作为短 API matrix、截图或 observe command 缺口的补充证据。MDTODO Web closeout 必须至少有一次交互式 CLI 验收，使用同一个 observer 的 `observe command` 覆盖 Source 配置、HWPOD probe、文件选择、Rxx 树操作、编辑写回、reindex 和 Workbench launch，并用 `collect --view project-mdtodo-summary` 与 `observe analyze` 收口。
|
||
|
||
该验收必须证明 Project Management 的同源 API 代理支持 MDTODO source/file/task 的写方法，而不是只支持 Workbench link 写入或只验证只读投影。若 Source 配置、HWPOD probe、reindex、title/body/status 编辑、新增、延续、删除任一操作需要直连 `hwlab-project-management` service、Kubernetes、Postgres 或 D601 SSH 才能成功，则客户端入口验收不成立。
|
||
|
||
### 6.6 CLIENT-L1-REQ-006 云端控制台
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| CLIENT-L1-REQ-006 | 云端控制台 | [PJ2026-010405 云端控制台](PJ2026-010405-cloud-console.md) | [用户管理](PJ2026-0105-user-management.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[项目管理](PJ2026-010404-project-management.md)、[平台运维](PJ2026-0106-platform-ops.md) |
|
||
|
||
客户端应提供统一的非 Workbench 云端控制台，使项目、任务、硬件、用户运营、管理和系统状态以一致的工业工作界面呈现，并能够通过 typed API、稳定 ID、深链、渐进披露和统一错误语义继续操作。
|
||
|
||
控制台的页面信息架构、通用组件、HWPOD 入口、显示模式、服务边界、响应式、无障碍和原入口验收由 [PJ2026-010405 云端控制台](PJ2026-010405-cloud-console.md) 约束。客户端只拥有交互和展示，不重新定义领域事实。
|
||
|
||
## 7. 过程控制
|
||
|
||
本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。客户端方向的阶段活动材料应引用本规格和各 L2 规格，不在本规格正文中展开执行流水。
|