spec: 定义 HWPOD Web 工作区操作

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 观测与协议入口

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、截图和报告摘要；