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

PJ2026-0103 HarnessRL

修改历史

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

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

正文

PJ2026-0103 HarnessRL 需求规格

1. 文档控制

字段	内容
编号	PJ2026-0103
短名	HarnessRL
层级	L1 方向
状态	已生效
实现引用版本	draft-2026-06-25-p0-web-caserun-e2e
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-01 HWLAB 总规格
规格治理索引	规格治理

本文采用 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 等价验收边界。
• 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 和原始硬件事实归 硬件池。
• Agent run、command、session、workspace 和 provider profile 生命周期归 Agent编排。
• Web、CLI 和 HTTP API 的用户入口体验归 客户端。
• 用户身份、额度、账本和租户策略归 用户管理。
• CI/CD、registry 保留、日志基础设施和平台发布归 平台运维。

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 或策略改进材料。

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服务	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 目标架构图

flowchart LR
  subgraph Client[客户端]
    W[Cloud Web CaseRun UI]
    P[web-probe 同源浏览器验收]
    C[HWLAB CLI thin client]
  end
  subgraph API[HWLAB Cloud API]
    R[CaseRun REST API]
    H[HarnessRL CaseRun service]
    A[Artifact / aggregate read model]
  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 --> H
  H --> AR
  AR --> WS
  H --> S
  S --> N
  N --> HW
  HW --> N
  N --> S
  S --> H
  AR --> H
  H --> A
  A --> R

目标架构要求 Cloud Web、web-probe 和 CLI 都通过 YAML 选中的同一 Web origin 和同源 CaseRun API 访问同一 run 事实。默认 origin 是 public URL；当 node/lane YAML 显式选择 internal IP origin 时，本次端到端验收可以走内部 IP，但仍必须由 YAML 声明、由受控 CLI 解析并在证据中输出 selectedMode/sourcePath。HarnessRL 拥有 CaseRun stage、artifact manifest、aggregate、评价和 replay 语义；Agent编排拥有 AgentRun 执行生命周期；硬件池拥有 HWPOD 资源、租约、路由、HWPOD node 和原始硬件事实；客户端只展示和调用这些事实。

5.2 目标数据流图

flowchart TD
  Submit[用户或 web-probe 提交 caseId + hwpodId] --> Admission[CaseRun admission]
  Admission --> Run[runId / stage=queued]
  Admission --> Lease[HWPOD lease request]
  Admission --> 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 --> Status[CaseRun status/read model]
  Status --> Web[Cloud Web run card]
  Status --> Probe[web-probe report]

数据流必须保证：CaseRun admission 只短返回 runId 和查询入口；AgentRun trace、HWPOD operation result、diff、build/download/UART 证据和 aggregate 都以 artifact manifest 关联到同一 run；Web 和 web-probe 只读取同一 status/read model，不直接拼接 AgentRun、HWPOD 或本地文件事实。

5.3 关键时序图

sequenceDiagram
  participant U as Web / web-probe
  participant API as CaseRun API
  participant HR as HarnessRL
  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 run
  HR-->>U: 202 runId + statusUrl
  HR->>AR: create AgentRun run/command
  HR->>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-->>HR: trace/result/diff refs
  HP-->>HR: operation result refs
  HR->>HR: write manifest + aggregate + stage terminal
  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 路径。

6. 原子需求

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

编号	短名	主责模块	关联模块
HARNESS-L1-REQ-001	CaseRun 语义	PJ2026-010301 CaseRun规格	Agent编排、硬件池、平台运维

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。

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

编号	短名	主责模块	关联模块
HARNESS-L1-REQ-002	观测引用	PJ2026-010302 观测引用	硬件池、客户端

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

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

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

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

编号	短名	主责模块	关联模块
HARNESS-L1-REQ-003	评估回放	PJ2026-010303 评估回放	客户端、Agent编排

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

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

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

编号	短名	主责模块	关联模块
HARNESS-L1-REQ-004	训练反馈	PJ2026-010304 训练反馈	Agent编排、用户管理

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端到端	客户端、Agent编排、硬件池、平台运维

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 语义。