docs: 定义 CaseRun 共享运行历史合同

2026-07-18 09:42:52 +02:00
parent 17c0b9ea78
commit 95121b851c
6 changed files with 61 additions and 7 deletions
@@ -831,8 +831,8 @@ templates:
            - "#caserun-panel"
          minBodyTextLength: 40
          interaction:
-            selector: ".caserun-case-row:nth-child(2)"
-            observedSelector: ".caserun-case-row:nth-child(2)"
+            selector: ".caserun-run-row:first-child"
+            observedSelector: ".caserun-run-row:first-child"
            observedAttribute: class
          failedResponseStatus: 400
          criticalPathPrefixes:
@@ -844,6 +844,7 @@ templates:
            mainContentSelector: .platform-content
            internalScrollSelectors:
              - .caserun-case-list
+              - .caserun-run-list
              - .caserun-events
              - .evidence-body
          outputLimits:
@@ -865,8 +866,8 @@ templates:
            - "#caserun-panel"
          minBodyTextLength: 40
          interaction:
-            selector: ".caserun-case-row:nth-child(2)"
-            observedSelector: ".caserun-case-row:nth-child(2)"
+            selector: ".caserun-run-row:first-child"
+            observedSelector: ".caserun-run-row:first-child"
            observedAttribute: class
          failedResponseStatus: 400
          criticalPathPrefixes:
@@ -892,8 +893,8 @@ templates:
            - "#caserun-panel"
          minBodyTextLength: 40
          interaction:
-            selector: ".caserun-case-row:nth-child(2)"
-            observedSelector: ".caserun-case-row:nth-child(2)"
+            selector: ".caserun-run-row:first-child"
+            observedSelector: ".caserun-run-row:first-child"
            observedAttribute: class
          failedResponseStatus: 400
          criticalPathPrefixes:
@@ -906,6 +907,7 @@ templates:
            internalScrollSelectors:
              - .caserun-workspace
              - .caserun-case-list
+              - .caserun-run-list
              - .caserun-events
              - .evidence-body
          outputLimits:
@@ -0,0 +1,45 @@
+# R4.11 任务报告
+
+## 结论
+
+CaseRun Web 已具备从共享 HarnessRL PostgreSQL registry 发现和加载既有运行的完整代码与线上 API 能力。HWLAB CLI `--over-api` 已通过的真实 run `software-smoke-1784346141262` 已出现在公网运行历史列表首项，并可继续按同一 runId 读取 status、events 和 aggregate。
+
+本任务尚未标记完成。NC01 浏览器启动门禁持续因 `MemAvailable <= 4 GiB` 阻断，桌面、紧凑和移动三视口的 `web-probe native-readiness` 仍待资源恢复后执行。
+
+## 规格与边界
+
+- 更新 HarnessRL SPEC，规定 Web、CLI `--over-api` 和 web-probe 读取同一共享 registry。
+- 新增纯读、游标分页的运行历史合同，默认按 `createdAt DESC, runId DESC` 排序。
+- 历史摘要不暴露 `caseRepo`、`runDir` 和 `runtimeApiUrl`。
+- CLI local 继续使用显式 local adapter，不静默上传，不由 Web 扫描本地文件。
+- Web 选择历史项、粘贴 runId 和直接访问深链均读取既有 status、events 和 aggregate，不在客户端合成终态。
+
+## 实现
+
+- HWLAB PR：[pikasTech/HWLAB#2656](https://github.com/pikasTech/HWLAB/pull/2656)。
+- 功能提交：`6fff5d75e40f51685172a650b9261f942d7b84ba`。
+- 合并提交：`12e115d430f1e08dbd27b789e591c86d4e967955`。
+- 后端新增 `GET /v1/caserun/runs?status=&limit=&cursor=`。
+- 前端新增“最近运行 / 可执行用例”分段视图、runId 直达、历史项状态和证据摘要。
+- native fixture 预置一个 CLI 形态的已完成 software-smoke。
+- YAML readiness 的桌面、紧凑和移动 profile 改为点击首条历史运行，并允许历史 pane 内部滚动。
+
+## 验证证据
+
+- `bun run harnessrl:native:smoke`：12 项通过。
+- native fixture focused test：3 项通过。
+- CaseRun store focused test：3 项通过。
+- `bun run web:build`：通过。
+- L1 公网 API `http://152.53.229.148:4316`：历史列表、详情、6 条事件和 aggregate 均可读取同一 fixture run。
+- 正式公网 API `https://lab-dev.hwpod.com/v1/caserun/runs?limit=5`：HTTP 200，返回 2 个已完成 software-smoke；第一项为 `software-smoke-1784346141262`，`artifactCount=1`、`evidenceStatus=recorded`。
+- 正式公网 status：Temporal workflowId 为 `harnessrl-caserun-software-smoke-1784346141262`，workflowRunId 为 `019f7351-667b-7466-976e-c9c6d9d865a3`，产物 `software-smoke.json` 的 SHA256 为 `d69871dd289aea216298727c8014c76a88d52c8abb864232cc18b20e7a8642ab`。
+- 正式 Web chunk `/assets/CaseRunView.js` 已包含“最近运行”“输入 CLI 输出的 runId”“共享 registry 中暂无运行”等新交互文案。
+- 未修改 CI/CD 基础设施。PR merge 后自动链完成实际前后端交付；PaC status/history 读取连续两次在 25 秒预算返回 `pac-read-timeout` partial，但真实公网 API 与 Web bundle 已更新。
+
+## 当前阻塞与恢复入口
+
+- 首次 browser readiness 在启动浏览器前被 memory guard 阻断。
+- 按受控流程执行一次 `gc remote NC01 plan/run/status --memory-pressure-only`，job `nc01-memory-pressure-1784358458-406442` 成功，但 `MemAvailable` 未超过 4 GiB。
+- 后续只读复核分别为 2.5 GiB 和 2.3 GiB；按规则停止重复 GC 和浏览器重试。
+- 恢复条件：`bun scripts/cli.ts gc remote NC01 memory` 返回 `MemAvailable > 4 GiB`。
+- 恢复后依次执行 `caserun`、`caserun-compact`、`caserun-mobile` 三个 `web-probe native-readiness` profile；全部通过后再标记 R4.11 完成。
@@ -103,3 +103,7 @@ P5 CI/CD 与原入口回归：补齐服务制品和 GitOps，仅以 v0.3 PR merg
 ### R4.10 [completed]

 根据真实页面截图收敛 CaseRun 页头空间：将页面身份、说明和操作改为紧凑命令栏，将状态摘要固定为页头底栏，并把紧凑页头、状态底栏和主体高度预算沉淀为 unidesk-webdev 默认设计规则；通过桌面和移动端 L1 readiness 验证无全局滚动及交互回归，完成任务后将详细报告写入[任务报告](./details/hwlab-caserun/R4.10_Task_Report.md)。
+
+### R4.11 [in_progress]
+
+让 CaseRun Web 加载 CLI `--over-api` 已运行通过的共享 registry 结果：补充纯读游标分页运行历史接口、最近运行与 runId 直达交互、native fixture 和 focused tests，并用真实 software-smoke run 完成 L1 公网桌面与移动端验收；禁止读取 CLI 本地文件、静默发布 local 结果或引入第二权威，完成任务后将详细报告写入[任务报告](./details/hwlab-caserun/R4.11_Task_Report.md)。
@@ -168,7 +168,7 @@ flowchart TD
  Status --> Probe[web-probe report]
 ```

-数据流必须保证：CaseRun admission 只短返回 runId、workflow identity 和查询入口；workflow activity 必须幂等，并以稳定 activity identity 写入 registry；AgentRun trace、HWPOD operation result、diff、build/download/UART 证据和 aggregate 都以 artifact manifest 关联到同一 run。Web、CLI `--over-api` 和 web-probe 只读取同一 status/read model。CLI local 模式复用同一 application service、DTO 和 workflow/activity 合同，但使用显式 local adapter，不把本地 fixture 写入生产 registry。
+数据流必须保证：CaseRun admission 只短返回 runId、workflow identity 和查询入口；workflow activity 必须幂等，并以稳定 activity identity 写入 registry；AgentRun trace、HWPOD operation result、diff、build/download/UART 证据和 aggregate 都以 artifact manifest 关联到同一 run。Web、CLI `--over-api` 和 web-probe 只读取同一 status/read model。共享 registry 必须提供纯读、游标分页的运行历史，使 Web 能发现并加载 CLI `--over-api` 已提交的 run；列表只交接运行身份、状态、阶段、时间和证据摘要，完整事件与 aggregate 仍按 runId 渐进读取。CLI local 模式复用同一 application service、DTO 和 workflow/activity 合同，但使用显式 local adapter，不把本地 fixture 写入生产 registry，也不得静默发布到 Web 所读取的共享 registry。

 ### 5.3 关键时序图

@@ -521,6 +521,8 @@ Web 工作台应提供 CaseRun 用户入口，使用户能在登录后的 select

 CaseRun 入口应保持工作态密度。HWPOD 资源卡应展示资源身份、连接/可用状态、能力摘要和关键 blocker；case 列表应展示 caseId、目标硬件和执行范围；run 卡应以 queued、preparing、agent-running、building、downloading、uart-reading、aggregating、completed、failed、canceled、blocked 等状态表达进度。Trace、download/UART 原始片段和 artifact manifest 可以折叠，但 aggregate、终态、主要 blocker 和继续查询标识必须默认可见。

+CaseRun 独立页必须能发现并加载共享 registry 中已经存在的运行，包括由 HWLAB CLI `--over-api` 提交并完成的 run。页面应提供最近运行列表和 runId 直达入口；选择历史项、粘贴 runId、直接访问 `/caserun/runs/:runId` 或刷新深链必须读取同一 status、events 和 aggregate 资源，不得复制运行结果、扫描 CLI 本地目录或根据列表摘要合成终态。CLI local 模式的结果只有经过未来独立定义的显式发布合同后才能进入共享 registry，本入口不得静默上传。
+
 Web 工作台只调用 YAML-selected origin 下的同源 CaseRun API 和既有 Trace/aggregate/HWPOD 读侧入口。它不得直接访问 HWPOD node、本地 gateway、旧 v0.2 runner、数据库、Kubernetes、SSH 或未在 YAML 声明的临时内部服务来提交或判断 CaseRun。若 API 返回 HWPOD workspace missing、node offline、capability mismatch、probe mismatch、serial-monitor unavailable、AgentRun blocker 或 aggregate missing，Web 必须展示对应结构化 blocker 和可复制诊断，而不是改写为通用请求失败。

 CaseRun 前端必须支持独立 native 开发。Vite HMR 与 repo-owned native CaseRun test API 应能分别启动和热重载，前端不依赖 live Kubernetes、AgentRun、HWPOD 或生产数据库即可验证 queued、running、completed、failed、blocked、canceled、events 和 aggregate 展示。native test API 必须使用与生产 HarnessRL API 相同的 DTO 和相对 path，并显式返回 `mode=native-test`；它不得进入生产配置、selected origin 或线上 fallback。
@@ -378,6 +378,7 @@ API契约应定义 YAML-selected Cloud Web origin 下的 CaseRun RESTful 资源
 | Case list | `GET /v1/caserun/cases` | 可选 `hwpodId`、`target`、`capability` 筛选 | caseId、描述、目标硬件、stage 模板、所需 HWPOD capability | 200/401/403 | 只列出 HarnessRL 可运行 case，不证明资源当前可用 |
 | HWPOD readiness summary | `GET /v1/caserun/hwpods` 或复用正式 HWPOD spec/readiness 资源 | 可选 caseId | hwpodId、nodeId、capabilities、availability、blocker 摘要 | 200/401/403 | 硬件事实来自硬件池，CaseRun API 只交接摘要 |
 | Run admission | `POST /v1/caserun/runs` | caseId、hwpodId、providerProfile、subjectRef、可选 metadata | `202 Accepted`、runId、statusUrl、eventsUrl、aggregateUrl、traceUrl 可空 | 202/400/401/403/409/422 | 只表示提交被接收，不表示 Agent 或硬件动作完成 |
+| Run list | `GET /v1/caserun/runs` | 可选 status、limit、cursor | 按 createdAt 倒序的 runId、caseId、workflow identity、status、stage、terminal、时间与证据摘要，以及 nextCursor | 200/400/401/403 | 共享 HarnessRL registry 的纯读发现入口；不扫描 CLI 本地文件，不替代详情、事件或 aggregate |
 | Run status | `GET /v1/caserun/runs/{runId}` | path runId | stage、terminal、caseId、hwpodId、nodeId、traceId、AgentRun refs、HWPOD operation summaries、latest blocker | 200/401/403/404 | HarnessRL read model，不直接同步推进 AgentRun 或 HWPOD |
 | Run events | `GET /v1/caserun/runs/{runId}/events` | cursor/afterSeq、limit | stage/event page、next cursor、valuesRedacted | 200/401/403/404 | 事件阅读，不拥有第二套 run 状态 |
 | Run aggregate | `GET /v1/caserun/runs/{runId}/aggregate` | 可选 detail level | aggregate、artifact manifest hash、evidence refs、replay refs、diagnostic | 200/401/403/404/409 | 低噪声结果入口，评价语义归 HarnessRL |