pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md

# PJ2026-0103 HarnessRL

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |
| v0.3 | b5d8cee438a3bd66ca440a25bf5a16d9081d9efa | 2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 |
| v0.2 | b0cbe9b721b50e9fff4d350ee50ed2af03cf0405 | 2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 |
| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从迁移来源 pikasTech/HWLAB#1205 迁移到 UniDesk 项目管理目录。 |

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。

## 正文

## PJ2026-0103 HarnessRL 需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-0103 |
| 短名 | HarnessRL |
| 层级 | L1 方向 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e; draft-2026-07-17-p0-temporal-native-agile |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HarnessRL 的稳定使命、范围、术语、系统边界、内部分工和原子需求。

## 2. 目的和范围

### 2.1 目的

HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较、可回流改进的 Harness/RL 闭环。它定义 CaseRun 语义、外部观测模型、评价回放和训练反馈，使 HWLAB 不只知道一次任务是否执行过，还能解释执行结果如何被判定和如何改进。

Web CaseRun 是 HarnessRL 面向用户的正式端到端能力：用户从 YAML 选中的 Cloud Web origin 或同源非视觉入口提交 CaseRun，经 AgentRun、HWPOD 服务和靠近硬件的 HWPOD node 执行，再把 trace、硬件 operation result、artifact manifest、aggregate 和回放线索回到同一入口。

### 2.2 范围内

- CaseRun case definition、stage model、postValidation、run-local workspace 和 case registry 语义。
- Web CaseRun 端到端语义，包括同源提交、短返回 runId、run stage 查询、AgentRun trace 引用、HWPOD operation result 引用、artifact/aggregate 归属和 web-probe 等价验收边界。
- CaseRun durable workflow、API/worker 分离、取消与重启恢复，以及 native 前后端独立开发和 smoke 合同。
- HWPOD raw output、Agent trace、artifact、diff、final response 和硬件观测之间的验证事实关系。
- CaseRun 对 HWPOD 服务返回观测事实的引用，包括 probeId、单位、采样、统计和与硬件动作的关联；ioProbe 是其中一种 HWPOD 观测输入。
- aggregate、评价、baseline、replay、失败分类和可复验比较。
- 训练反馈、失败标签、reward、prompt/skill/case 改进数据和 RL 闭环。

### 2.3 范围外

- 真实硬件资源、probe 能力、HWPOD node 和原始硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。
- Agent run、command、session、workspace 和 provider profile 生命周期归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
- Web、CLI 和 HTTP API 的用户入口体验归 [客户端](PJ2026-0104-client.md)。
- 用户身份、额度、账本和租户策略归 [用户管理](PJ2026-0105-user-management.md)。
- CI/CD、registry 保留、日志基础设施和平台发布归 [平台运维](PJ2026-0106-platform-ops.md)。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| CaseRun | 按 case definition 执行硬件研发任务并形成 registry 记录的 Harness 运行。 |
| Web CaseRun | 用户通过 Cloud Web 或同源自动化入口提交、观察和复验的 CaseRun 形态。 |
| case registry | CaseRun 的结构化结果登记，用于保存 case、run、stage、artifact 和评价关系。 |
| aggregate | 面向人工和客户端的低噪声结果摘要，不替代原始执行事实。 |
| operation result | HWPOD 服务归属的一次硬件操作结果，包含 HWPOD、node、租约、调用方、操作类型、时间上下文和原始硬件事实摘要。 |
| artifact manifest | CaseRun 对 trace、diff、build/download/UART 证据、日志片段、aggregate 和外部产物哈希的结构化索引。 |
| selected Web origin | 由 node/lane YAML 声明并经受控 CLI 解析的 Web origin；默认是 public origin，本次 D601/v03 端到端验收允许 YAML 选择 internal IP origin。 |
| web-probe | 通过 selected Web origin 运行的非视觉浏览器验收路径；它只能使用同源用户/API 路径，不是新的业务入口或后门。 |
| ioProbe | 由 HWPOD 服务管理的板外物理状态观测探针，输出带单位、采样和统计语义的数据。 |
| replay | 基于同一 case 和验证事实关系复核执行结果的能力。 |
| 训练反馈 | 从成功/失败路径中沉淀出的 prompt、skill、case、reward 或策略改进材料。 |
| CaseRun workflow | 由 Temporal 持久化推进的 CaseRun 编排历史，只拥有 stage 调度、retry、timer、signal、cancel 和恢复语义。 |
| HarnessRL API | 提供 CaseRun admission、query、events、aggregate 和 cancel 的无状态 API 进程，不执行硬件 activity。 |
| HarnessRL worker | 执行 CaseRun workflow 与 activity 的独立进程，不承载用户 HTTP API。 |
| native 模式 | 不依赖 Kubernetes 即可独立启动 Temporal 开发运行时、API、worker、CLI adapter 和前端测试服务的开发形态；它不构成生产 fallback。 |

## 4. 系统边界和接口

本规格把 HarnessRL 作为 HWLAB 内部的验证与训练反馈子系统看待；本章只描述该子系统的输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | Agent编排、客户端、用户管理、硬件池和训练任务。 |
| 外部输入 | case definition、Web/CLI/API 提交请求、workspace commit、HWPOD raw output、HWPOD 服务观测结果、Agent trace、artifact、diff、run context 和用户/资源摘要。 |
| 受控资源 | CaseRun 定义、case registry、aggregate、评价模型、replay 入口、训练反馈样本和失败标签。 |
| 外部输出 | CaseRun 结果、run stage、aggregate、artifact manifest、评价结论、replay 线索、失败分类、训练反馈和可复验的验证关系。 |
| 用户接口 | YAML-selected Cloud Web CaseRun 入口、同源 CaseRun API、web-probe 验收路径、CaseRun CLI、case registry、aggregate、评价/回放入口、Agent Review 后端语义。 |
| 系统边界 | HarnessRL 负责评价和反馈语义；不定义硬件可用性、Agent 生命周期、客户端布局、用户账本或平台发布。 |

## 5. 内部分工与规格索引

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-010301 | CaseRun规格 | 本规格 6.1 | case definition、stage model、postValidation、registry 语义 | Agent编排、硬件池、平台运维 | 客户端、用户管理 |
| PJ2026-010302 | 观测引用 | 本规格 6.2 | CaseRun 中引用 HWPOD 服务返回的外部观测、单位、采样、统计和硬件动作关联 | [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) | CaseRun、评价回放 |
| PJ2026-010303 | 评估回放 | 本规格 6.3 | aggregate、baseline、judge、replay 和失败分类 | CaseRun、Agent编排、硬件池 | 客户端、训练反馈 |
| PJ2026-010304 | 训练反馈 | 本规格 6.4 | reward、失败标签、prompt/skill/case 改进样本 | 评估回放、Agent编排 | Agent编排、用户管理 |
| PJ2026-010305 | Web CaseRun端到端 | 本规格 6.5 | Web/API/web-probe 入口到 CaseRun、AgentRun、HWPOD、artifact、aggregate 的端到端语义和验收边界 | 客户端、Agent编排、硬件池、平台运维 | 用户、内测、训练反馈 |

### 5.1 目标架构图

```mermaid
flowchart LR
  subgraph Client[客户端]
    W[Cloud Web CaseRun UI]
    P[web-probe 同源浏览器验收]
    C[HWLAB CLI thin client]
  end
  subgraph API[HarnessRL API]
    R[CaseRun REST API]
    T[Temporal client]
    A[Registry / aggregate read model]
  end
  subgraph Worker[HarnessRL Worker]
    WF[Temporal CaseRun workflow]
    AC[prepare / build / collect activities]
  end
  subgraph Agent[Agent编排]
    AR[AgentRun run / command / trace]
    WS[subject worktree / RuntimeAssembly]
  end
  subgraph Hwpod[硬件池]
    S[HWPOD service / lease / route]
    N[HWPOD node / Python UI node]
    HW[Keil / debug probe / UART / board]
  end
  W --> R
  P --> R
  C --> R
  R --> T
  T --> WF
  WF --> AC
  AC --> AR
  AR --> WS
  AC --> S
  S --> N
  N --> HW
  HW --> N
  N --> S
  S --> AC
  AR --> AC
  AC --> A
  A --> R
```

目标架构要求 Cloud Web、web-probe 和 CLI `--over-api` 都通过 YAML 选中的同一 Web origin 和同源 CaseRun API 访问同一 run 事实。HarnessRL API 与 worker 必须是独立进程和独立部署对象。Temporal workflow history 只作为 durable orchestration authority；HarnessRL registry 是 run、stage event、workflow identity、artifact manifest 和 aggregate 的产品 read model 与归档索引；Agent编排和硬件池的事实权威保持不变。API 或 worker 重启不得使 workflow 退回进程内 memory state，也不得从 Temporal UI、stdout 或客户端投影合成业务成功事实。

### 5.2 目标数据流图

```mermaid
flowchart TD
  Submit[用户或 web-probe 提交 caseId + hwpodId] --> Admission[CaseRun admission]
  Admission --> Registry[registry runId / stage=queued]
  Admission --> Workflow[Temporal workflow start]
  Workflow --> Lease[HWPOD lease request]
  Workflow --> AgentRun[AgentRun run/command]
  AgentRun --> Diff[subject worktree diff / final response]
  Lease --> Ops[HWPOD operation results]
  Ops --> Build[build/download/UART/raw facts]
  Diff --> Manifest[artifact manifest]
  Build --> Manifest
  AgentRun --> Manifest
  Manifest --> Aggregate[aggregate / evaluation / replay refs]
  Aggregate --> Registry
  Registry --> Status[CaseRun status/read model]
  Status --> Web[Cloud Web run card]
  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。共享 registry 必须提供纯读、游标分页的运行历史，使 Web 能发现并加载 CLI `--over-api` 已提交的 run；列表只交接运行身份、状态、阶段、时间和证据摘要，完整事件与 aggregate 仍按 runId 渐进读取。CLI local 模式复用同一 application service、DTO 和 workflow/activity 合同，但使用显式 local adapter，不把本地 fixture 写入生产 registry，也不得静默发布到 Web 所读取的共享 registry。

### 5.3 关键时序图

```mermaid
sequenceDiagram
  participant U as Web / web-probe
  participant API as CaseRun API
  participant HR as HarnessRL API / Registry
  participant TW as Temporal Workflow
  participant WK as HarnessRL Worker
  participant AR as AgentRun
  participant HP as HWPOD service
  participant PN as Python UI node
  participant HW as STM32 / Arm2D HWPOD
  U->>API: POST /v1/caserun/runs
  API->>HR: validate case + create registry run
  HR-->>U: 202 runId + statusUrl
  HR->>TW: start workflow
  TW->>WK: schedule idempotent activities
  WK->>AR: create AgentRun run/command
  WK->>HP: acquire lease + route operation
  HP->>PN: dispatch debug/workspace/UART op
  PN->>HW: build/download/reset/UART
  HW-->>PN: raw hardware facts
  PN-->>HP: operation result
  AR-->>WK: trace/result/diff refs
  HP-->>WK: operation result refs
  WK->>HR: write stage / manifest / aggregate refs
  WK-->>TW: activity result
  U->>API: GET status/events/aggregate
  API-->>U: run stage + trace + HWPOD evidence + aggregate
```

关键时序要求长任务异步推进。`POST /v1/caserun/runs` 不等待 Agent、Keil、download 或 UART 完成；Web 和 web-probe 通过 status、events 和 aggregate 观察 terminal。HWPOD 写操作必须经 HWPOD 服务租约和 node 路由，不允许 Web、web-probe、CLI 或 Agent 直接连接用户 PC gateway、旧 v0.2 direct-url 或手工 SSH 路径。

取消必须进入 Temporal signal/cancel 语义，并由 workflow 在 registry 中写入 durable `canceled` 终态。API 进程重启不得影响 workflow；worker 重启后必须从 Temporal history 恢复并继续未完成 activity。activity retry 不得复制 AgentRun command、HWPOD operation 或 artifact；已有下游 identity 必须通过稳定幂等键恢复。

### 5.4 Web CaseRun 独立页面与设计契约

Web CaseRun 必须作为独立产品页面提供，入口为 `/caserun`，运行详情支持稳定深链 `/caserun/runs/:runId`。它不是 Workbench 的附属面板，也不得要求用户先进入代码编辑或 Agent 对话上下文。导航、直接访问和刷新深链都必须使用同一 `workbench.code` 权限边界与同一 CaseRun API。

页面采用面向重复操作的实验室控制台布局：顶部命令栏承载页面身份、模式/来源、刷新、复制 runId 和启动动作；状态摘要集中显示当前 run 的终态、阶段、耗时和证据完整度；主体使用左侧 case/HWPOD 选择、中间运行时间线与事件流、右侧 aggregate/artifact/trace/HWPOD 证据检查器的三栏结构。窄屏按“选择上下文→运行状态→证据”顺序折叠，不能依靠横向滚动才能完成核心操作。

页面可见文案应以中文为主；`CaseRun`、`HarnessRL`、`HWPOD`、`runId`、`traceId`、`SHA256` 和 API 字段等领域标识可以保留原文，但状态、阶段、操作、空态和错误说明必须提供中文表达。页面必须采用受限工作区：AppShell 主内容区和 CaseRun 页面根容器不产生全局滚动，命令栏与状态摘要稳定可见，case 列表、事件流、阶段轨道和证据检查器只在所属 pane 内滚动；移动端按既定顺序在工作区内部纵向滚动，不把滚动责任退回 document。

视觉设计应服务于硬件执行的扫描、比较和故障定位：沿用 Cloud Web 控制台 token、清晰的状态色、紧凑的 IBM Plex Sans/Mono 信息层级、稳定的表格/时间线间距和可识别的图标按钮；不得使用营销式 hero、紫色渐变、装饰性背景块、嵌套卡片或把关键结果藏在视觉装饰中。按钮、标签、状态、时间线和证据区必须在桌面、紧凑桌面与移动视口下保持文本不重叠、控件不跳动和可读。

页面只投影 API 返回的 `status`、`stage`、`terminal`、`events`、`aggregate` 和 `references`。客户端不得依据 elapsed time、HTTP 状态码、事件数量、fixture 名称或本地计时器合成终态、成功或证据完整度。native test fixture 只能作为显式 `mode=native-test` 的开发输入，并且页面应与真实 API 的 DTO 和错误契约保持一致。

## 6. 原子需求

### 6.1 HARNESS-L1-REQ-001 CaseRun 执行语义

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HARNESS-L1-REQ-001 | CaseRun 语义 | PJ2026-010301 CaseRun规格 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md) |

HarnessRL 应定义 CaseRun 的 case definition、stage model、postValidation、run-local workspace 和 case registry 语义，使一次真实硬件任务可以被稳定表达和复验。

CaseRun 语义必须引用 Agent 执行上下文和硬件事实，但不接管这些事实的生产。Agent编排提供 run/session/workspace 指针，硬件池提供真实硬件输出，平台运维提供 registry 和运行支撑。

CaseRun stage model 至少应能表达 queued、preparing、agent-running、building、downloading、uart-reading、aggregating、completed、failed、canceled 和 blocked 等用户可理解状态。每个 stage 必须能关联其上游事实来源，例如 AgentRun run/command/trace、HWPOD operation result、artifact manifest 或 aggregate revision。

CaseRun 必须由 Temporal durable workflow 推进。workflow 代码只包含确定性编排，所有文件系统、网络、AgentRun、HWPOD、registry 和时间相关副作用必须进入 activity。HarnessRL API 与 worker 必须分离；API 只承担 admission、query、events、aggregate 和 cancel，worker 只承担 workflow/activity。运行中的 workflow 不得依赖 API 进程内 `Map`、后台 Promise 或 Pod 本地 record 才能恢复。

HarnessRL registry 必须使用 HWLAB 既有 PostgreSQL 运行面中的服务自有 schema/table 保存 run、stage event、workflow identity 和 artifact ref。Temporal history 与 registry 职责必须单向明确：Temporal 是编排历史权威，registry 是产品 read model 和归档索引；两者都不得覆盖 AgentRun 或 HWPOD 的领域事实。

### 6.2 HARNESS-L1-REQ-002 CaseRun 观测引用

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HARNESS-L1-REQ-002 | 观测引用 | PJ2026-010302 观测引用 | [硬件池](PJ2026-0101-hardware-pool.md)、[客户端](PJ2026-0104-client.md) |

HarnessRL 应在 CaseRun 语义中引用 HWPOD 服务提供的外部观测结果，使外部读数能够与 case stage、硬件动作、评价和回放关系稳定关联。

ioProbe 只是 HWPOD 观测输入的一种。probe 能力、probe 绑定、物理采样、HWPOD node 路由和原始硬件事实归 [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) 负责；HarnessRL 不自建 ioProbe 硬件模型，也不绕过 HWPOD 服务直接管理 probe。

HarnessRL 只负责把 HWPOD 服务返回的观测事实纳入 CaseRun stage、postValidation、评估和回放关系，并区分板内 echo、日志输出和板外真实读数。客户端只负责展示这些结果，不重新定义观测来源。

### 6.3 HARNESS-L1-REQ-003 评估与回放

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HARNESS-L1-REQ-003 | 评估回放 | PJ2026-010303 评估回放 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

HarnessRL 应提供评估与回放语义，使同一次硬件执行可以被 aggregate 阅读、被 baseline 或 judge 比较，并能基于同一验证关系复核结论。

评估回放不是客户端展示，也不是 Agent 执行状态。它定义判断结果如何产生、如何解释、如何复核；客户端可以展示结论，Agent编排可以消费反馈，但不能替代 HarnessRL 定义评价语义。

### 6.4 HARNESS-L1-REQ-004 训练反馈

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HARNESS-L1-REQ-004 | 训练反馈 | PJ2026-010304 训练反馈 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md) |

HarnessRL 应把成功路径、失败分类和评价结论转化为可回流的训练反馈，使 prompt、skill、case、node-op 或 reward 数据能进入后续改进。

训练反馈必须来自真实执行和可复验评价，不能绕过硬件事实或使用特权模拟路径制造成功样本。Agent编排消费改进材料，用户管理只在需要时提供租户、权限和 usage 归因。

### 6.5 HARNESS-L1-REQ-005 Web CaseRun 端到端

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HARNESS-L1-REQ-005 | Web CaseRun端到端 | PJ2026-010305 Web CaseRun端到端 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md) |

HarnessRL 应把 Web CaseRun 定义为正式端到端能力，使用户能从 Cloud Web 或同源非视觉入口选择 case 与 HWPOD，提交运行，观察 run stage、Trace、HWPOD evidence、artifact manifest 和 aggregate，并在终态后获得可回放、可复验的结果。

Web CaseRun 必须采用同源短返回 API：提交请求返回 runId 和状态查询入口，长执行由 HarnessRL、Agent编排和硬件池异步推进。Cloud Web、HWLAB CLI 和 web-probe 都必须使用 YAML 选中的同一 origin、同一 CaseRun API、同一用户身份、同一 run/read model 和同一 aggregate；web-probe 只是 Cloud Web 的非视觉验收路径，不能使用后门 API、未在 YAML 声明的内部服务端口、SSH、数据库或旧 lane 直连来替代用户路径。

Web CaseRun 的执行事实必须按职责分仓。AgentRun run、command、trace、diff 和 final response 归 Agent编排生产；HWPOD spec、租约、节点路由、operation result、Keil build、download、UART 和原始硬件事实归硬件池生产；HarnessRL 只把这些事实纳入 CaseRun stage、artifact manifest、aggregate、评价和 replay。任何模块缺失、延迟或失败时，CaseRun 应输出结构化 blocker 和事实来源，而不是用客户端文案、人工 steer、stdout 尾部或旧 CLI 成功样本补造成通过。

Web CaseRun 的最小完成标准应先覆盖 compile-only case：同一 run 能从 Web 或 web-probe 提交，终态包含 caseId、runId、hwpodId、nodeId、AgentRun traceId、HWPOD operation result 引用、artifact manifest hash 和 aggregate。download+UART 与 Arm2D 场景可作为增强阶段，但其证据仍必须进入同一 CaseRun manifest 和 aggregate 语义。

CaseRun 必须提供 repo-native 敏捷开发形态。后端应能在 Kubernetes 外独立启动 Temporal 开发运行时、HarnessRL API 和 worker，并分别支持 watch/reload；CLI 应提供默认 local 模式和显式 `--over-api` 模式，两者共享 application service、DTO、typed error 和 submit-and-poll 合同；前端应能独立启动 Vite HMR 与可热重载的 native CaseRun test API，覆盖 queued、running、completed、failed、blocked、canceled、events 和 aggregate。native fixture 必须显式标记 `mode=native-test`，不得成为生产 fallback 或通过判定来源。L1 的固定端口、host、状态目录和服务组成必须由 YAML-first 配置声明，API、worker 和 Web 的启动、停止、重启、状态和日志必须由项目 CLI 管理；裸起脚本只作为 CLI 内部实现。L1 浏览器和用户入口必须从 owning YAML 解析出的公网 IP 与固定 port 访问，localhost 只允许作为进程健康 probe。

交付顺序必须先完成 native smoke，再回归原 CI/CD。native smoke 至少验证 software-smoke、cancel、API restart、worker restart recovery 和 CLI local/`--over-api` 合同等价；生产回归只由 `v0.3` PR merge 触发既有 GitHub webhook、Gitea snapshot、PaC、Tekton、GitOps/Argo 自动链，不得人工补跑或同步。