pikasTech-HWLAB/docs/reference/spec-v03-caserun-web.md

# HWLAB v0.3 CaseRun 独立页面设计规格

## 1. 设计结论

CaseRun 是硬件执行运行台，不是 Workbench 的附属诊断卡片。页面必须使用独立路由 `/caserun`，让用户从选择 case 到阅读执行证据都在同一条稳定深链内完成。

页面采用“命令栏 + 运行摘要 + 三栏运行工作区”的结构：

- 左栏负责 case、HWPOD 资源和执行上下文选择。
- 中栏负责当前 run 的阶段时间线、事件流和终态变化。
- 右栏负责 aggregate、artifact、Trace、HWPOD operation result 和 blocker 阅读。

工作台可以保留跳转入口，但不再嵌入 CaseRun 控制面板，避免同一 run 在两个页面各自维护选择、轮询和状态投影。

## 2. 调研依据

- AgentRun 运行观察页：采用窄命令栏、状态摘要条、可筛选主列表和右侧 Inspector，适合高密度运行状态扫描。
- TaskTree 页面：采用稳定 URL、主内容区占优、时间线和可折叠详情，适合执行阶段与长列表阅读。
- Temporal/CI 运行详情惯例：把 workflow/run identity、阶段、失败断点和产物引用分层展示，不能只用一个总体状态替代过程证据。
- HWLAB 当前 Workbench：已有 `CaseRunPanel`、CaseRun store/API 和 native fixture，但面板尺寸、工作台上下文和 HWPOD 操作共用空间，无法承载完整证据阅读。
- HarnessRL 合同：CaseRun 结果包含 `runId`、`caseId`、`status`、`stage`、`terminal`、`blocker`、events、aggregate、manifest、replay、Trace 和 HWPOD 引用，页面不得丢弃这些事实。

## 3. 视觉方向

采用“实验室控制台”视觉方向：

- 复用 HWLAB 现有浅色 console token、IBM Plex Sans/Mono、窄命令栏和状态条。
- 主色使用石墨、青绿色和少量琥珀/红色状态色，避免紫色渐变、营销式 hero 和装饰性大卡片。
- 页面首屏直接展示可操作运行对象，标题区保持紧凑，不添加说明型大段文案。
- 证据区使用浅色代码/日志表面，长文本内部滚动，不让原始 JSON 撑破页面。
- 所有按钮遵循已有图标与文字组合；刷新、复制、打开 Trace 等熟悉动作使用图标并保留无障碍名称。
- 卡片只用于重复的 case、阶段和证据条目，页面分区使用无装饰的 bounded layout，不嵌套卡片。

## 4. 页面信息架构

### 4.1 命令栏

- eyebrow：`HARNESSRL / CASERUN`
- 标题：`CaseRun 执行台`
- 描述：显示当前 selected origin、API mode 和最后一次读取时间。
- 操作：刷新 cases、重新读取当前 run、复制 runId；运行中提供取消入口时使用后端已有 cancel contract。
- 状态条：可用 cases、当前 status、stage、terminal、events 数量、artifact 数量。

### 4.2 左栏：执行选择

- case 列表显示 `caseId`、标题、mode、目标 HWPOD 和可用状态。
- 选择 case 后显示目标硬件、执行范围、workspace/能力摘要和已知 blocker。
- 启动按钮只提交 `caseId`，不在客户端拼接 workspace、node、runtime URL 或 fallback。
- 当前 run 进入深链后，左栏保留 case 选择但不覆盖当前 run。

### 4.3 中栏：运行过程

- 顶部显示 runId、caseId、当前 status、stage、terminal 和更新时间。
- 阶段时间线至少支持 `queued`、`preparing`、`agent-running`、`building`、`downloading`、`uart-reading`、`aggregating`、`completed`、`failed`、`canceled`、`blocked`。
- 事件流显示服务端返回的时间、stage、status 和脱敏 payload 摘要。
- 运行中按现有 API read model 轮询；terminal 只能由 API 返回的 `terminal` 决定。
- 空态、加载态、错误态和 blocker 态必须保留主区域结构，不能以空白或通用请求失败替代。

### 4.4 右栏：证据 Inspector

使用 Tab 或折叠区组织以下证据：

- `Aggregate`：status、summary、evidence、aggregate SHA 和 run identity。
- `Artifacts`：manifest 引用、artifact 数量、hash/ref 和可用状态。
- `Trace`：traceId、AgentRun/command/session 引用及只读下钻入口。
- `HWPOD`：hwpodId、nodeId、operation result、workspace、能力和连接状态。
- `Blocker`：code、summary、layer、details 和下一步只读诊断。

默认展开 Aggregate 和 Blocker；Trace、原始事件和 manifest 在需要时展开，避免长日志抢占首屏。

## 5. 深链与状态权威

- 基础路由为 `/caserun`。
- 当前 run 使用 `/caserun/runs/:runId`，刷新后恢复同一个 run。
- query 只承载 `case`、`tab` 等集合视图状态，不承载终态、stage、artifact 或 blocker。
- Web 只调用 selected origin 的同源 CaseRun API。
- API 的 `status`、`stage`、`terminal`、`events`、`aggregate` 和引用字段是唯一事实；客户端不能依据 elapsed time、事件数量、HTTP 200 或 fixture 名称合成终态。

## 6. L1 Native 合同

前后端必须独立启动、独立日志、独立停止：

- API/fixture：使用现有 `caserun:native:start|stop|status|logs`，默认 native API port 为 `4316`。
- Web：使用 `dev:native-caserun`，Vite HMR 与 `/v1/caserun/*` native proxy 独立运行。
- Native fixture：继续覆盖 queued、running、completed、failed、blocked、canceled、events 和 aggregate。
- Web smoke：使用 repo-owned `caserun-native-web-probe.mjs`，验证 `/caserun` 首屏、case 选择、启动、刷新、事件和 aggregate。
- Native 页面必须显示 `mode=native-test`，但生产 selected origin 不得读取 native fixture 或 native fallback。

## 7. 响应式与验收

- 桌面首屏使用三栏 bounded workspace，主 run 区域优先保证可读宽度。
- 中等宽度将右侧 Inspector 收为抽屉或下方区域，不能压缩事件流至不可读。
- 移动端按“命令栏 → 当前 run → case 选择 → 事件 → 证据”纵向排列，启动和刷新保持可达。
- L1 验收使用 `web-probe` custom/local 入口，覆盖桌面 `1920x1080` 和紧凑桌面视口。
- 必须确认首屏 DOM、启动/刷新交互、无 pageerror、无 console.error、无关键失败请求和无 document 横向溢出。

## 8. 非目标

- 不在本次页面改造中重写 HarnessRL API、Temporal workflow 或 CaseRun evidence contract。
- 不恢复 v0.2 direct URL、旧 runner、G14 fallback 或客户端第二状态源。
- 不把 CI/CD、Kubernetes、HWPOD node 或原始数据库访问暴露给浏览器。