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 方向
状态	已生效
实现引用版本	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
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-01 HWLAB 总规格
规格治理索引	规格治理

本文采用 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 链接。
• 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 和租户真相归 用户管理。
• Agent run、session、workspace 和 result 指针事实归 Agent编排。
• HWPOD 资源、硬件事实和 probe 能力归 硬件池。
• CaseRun 评价、aggregate、replay 和训练反馈归 HarnessRL。
• 项目管理的 source、任务投影、MDTODO adapter、Workbench link 和外部 PM adapter 归 项目管理；Workbench 只消费公共 launch context 元数据。
• 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 调用方式。
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工作台	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
PJ2026-010404	项目管理	PJ2026-010404 项目管理	项目根导航、MDTODO 页面、独立项目管理微服务、任务投影、Workbench link 和项目管理 observe/analyze 验收	用户管理、Agent编排、平台运维、API契约	Web、HWLAB CLI、web-probe

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 的入口契约以一致方式暴露。

6.4 CLIENT-L1-REQ-004 Web CaseRun 用户入口

编号	短名	主责模块	关联模块
CLIENT-L1-REQ-004	Web CaseRun入口	PJ2026-010401 Web工作台、PJ2026-010403 API契约、PJ2026-010402 HWLAB CLI	HarnessRL、硬件池、Agent编排

客户端应提供 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-010401 Web工作台、PJ2026-010403 API契约、Agent编排、用户管理、平台运维

客户端应提供登录后的项目管理入口，使用户能从 /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 才能成功，则客户端入口验收不成立。

7. 过程控制

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