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 或原始数据库访问暴露给浏览器。