From d53637673f4d190c333df18c3d85e7fdaefa836c Mon Sep 17 00:00:00 2001 From: pikastech Date: Tue, 21 Jul 2026 09:31:53 +0200 Subject: [PATCH] =?UTF-8?q?spec:=20=E5=AE=9A=E4=B9=89=20HWPOD=20Web=20?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8C=BA=E6=93=8D=E4=BD=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../specs/PJ2026-010102-hwpod-tools.md | 15 ++++++++++++++ .../specs/PJ2026-010405-cloud-console.md | 20 +++++++++++++++++++ 2 files changed, 35 insertions(+) diff --git a/project-management/PJ2026-01/specs/PJ2026-010102-hwpod-tools.md b/project-management/PJ2026-01/specs/PJ2026-010102-hwpod-tools.md index cf2c6f97..352ceb1d 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010102-hwpod-tools.md +++ b/project-management/PJ2026-01/specs/PJ2026-010102-hwpod-tools.md @@ -126,6 +126,21 @@ HWPOD工具应提供 build、download、reset、UART、filesystem 和通用硬 执行动作入口必须在写操作前确认目标身份、租约状态和能力声明。缺少 spec、缺少恢复能力或无法确认 probe 绑定时，工具应停止在可理解错误上，而不是继续执行低层命令。 +工作区浏览必须复用 `workspace.ls`、`workspace.cat` 和已有的有界文件操作语义： + +- `workspace.ls` 返回相对路径、条目类型、名称和有界元数据，目录按需展开， + 不把 Windows 绝对路径或节点文件系统暴露为浏览器路由； +- `workspace.cat` 只读取 workspace policy 允许范围内的单个文件，返回内容类型、 + 字节数、文本内容或不可预览原因，并对大文件和二进制文件保持有界； +- CLI、Web、Agent 和 CaseRun 必须调用同一 compiler、operation plan 和节点路由， + 不得为 Web 增加文件直连、共享目录、SSH reader 或第二套执行器。 + +Web 触发 build、download、UART 和 workspace 操作时必须提交与 CLI 等价的 HWPOD +operation，并通过 operationId 查询 accepted、running 和 terminal result。download、reset、 +串口发送等写操作必须在服务端重新校验能力和目标，浏览器本地按钮状态不得作为授权或 +安全边界。执行结果必须包含 operation、目标、节点、returnCode、artifact 或串口摘要、 +结构化 blocker 和脱敏诊断，不得要求前端解析未结构化 stdout。 + Web CaseRun 所需的 build、download、reset、UART 和 workspace 文件动作应保留 CaseRun 工具结果所需字段，使 HarnessRL 能把工具输出、HWPOD operation result、AgentRun trace 和 aggregate 关联到同一 run。工具入口不得要求 Web、web-probe 或 HarnessRL 解析未结构化 stdout 才能判断关键状态。 ### 6.3 HWPOD-TOOL-REQ-003 观测与协议入口 diff --git a/project-management/PJ2026-01/specs/PJ2026-010405-cloud-console.md b/project-management/PJ2026-01/specs/PJ2026-010405-cloud-console.md index 6f2d45b2..4b1e5897 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010405-cloud-console.md +++ b/project-management/PJ2026-01/specs/PJ2026-010405-cloud-console.md @@ -183,6 +183,20 @@ sequenceDiagram - 动效只能由真实连接、单 node in-flight、operation 进度或 capability mismatch 驱动。 - `prefers-reduced-motion` 下停止非必要循环动画；状态不得只依赖颜色。 - 列表模式必须保留相同状态语义，并提供服务端排序、筛选和详情深链。 +- 设备深链必须提供工作区和操作工作面： + - 左侧使用支持虚拟列表、键盘导航和按需展开的成熟 Vue 文件树组件； + - 中间区域预览选中文本文件、路径、大小和不可预览原因； + - 右侧或底部显示 build、download 和 UART operation 的状态、结果、artifact、 + returnCode 与结构化 blocker； + - 工作区目录和文件选择进入 URL query，刷新、前进和后退后能够恢复； + - 文件树只消费 HWPOD 服务的 typed workspace DTO，不直连 Windows 文件系统、 + SSH、共享目录或节点私有地址。 +- 高频操作区必须支持编译、下载和串口： + - 编译使用 spec 声明的 project 和 target，允许用户在声明集合内选择 target； + - 下载只能消费成功编译产生或 spec 声明的 artifact，并要求明确确认； + - 串口支持打开、关闭、发送文本和查看有界接收尾部，端口与波特率来自 spec； + - 所有动作提交同一 HWPOD operation API，页面按 operationId 查询终态， + 不得将 accepted 或本地按钮反馈显示为执行成功。 ### 6.3 HWPOD Node @@ -285,6 +299,9 @@ sequenceDiagram 云端控制台应提供设备资源、HWPOD Node 和节点接入三个可深链子标签，并以 HWPOD 服务与 AI 网关的 typed 事实表达 node 到设备拓扑、readiness、blocker 和 operation。 +设备资源深链应提供成熟文件树驱动的工作区浏览、文件预览、编译、下载和串口操作， +并与 CLI 复用同一 HWPOD operation、节点路由和终态结果合同。 + ### 9.4 CONSOLE-REQ-004 领域事实隔离 云端控制台不得通过字段猜测、名称去重、浏览器多接口拼装或 localStorage 生成硬件、任务、用户、权限、账本和评价事实。 @@ -325,6 +342,9 @@ AgentRun 智能体运行观察页应只消费 `agentrun.event.v1` 经 HWLAB mapp - 覆盖一 node 多设备、声明离线 node、在线无 spec、invalid spec、capability mismatch、busy、update available 和诊断错误； - 验证 PCB 动效只由真实状态驱动； - 验证 Python 下载元数据和分阶段 readiness。 + - 验证工作区目录按需展开、文件预览、路径深链恢复和越界拒绝； + - 验证 Web 编译、下载和串口动作提交 operation、显示 running 状态并取得真实终态； + - 验证 accepted、节点离线、能力不匹配和节点执行失败不会被页面显示为成功。 - 原入口： - 使用 YAML 选中的 NC01/v03 Cloud Web origin； - 使用 `web-probe observe/command/collect/analyze` 保存 command、observer、截图和报告摘要；