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 方向
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-01 HWLAB 总规格
规格治理索引	规格治理

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

2. 目的和范围

2.1 目的

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

2.2 范围内

• CaseRun case definition、stage model、postValidation、run-local workspace 和 case registry 语义。
• 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 运行。
case registry	CaseRun 的结构化结果登记，用于保存 case、run、stage、artifact 和评价关系。
aggregate	面向人工和客户端的低噪声结果摘要，不替代原始执行事实。
ioProbe	由 HWPOD 服务管理的板外物理状态观测探针，输出带单位、采样和统计语义的数据。
replay	基于同一 case 和验证事实关系复核执行结果的能力。
训练反馈	从成功/失败路径中沉淀出的 prompt、skill、case、reward 或策略改进材料。

4. 系统边界和接口

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

边界项	内容
外部使用者	Agent编排、客户端、用户管理、硬件池和训练任务。
外部输入	case definition、workspace commit、HWPOD raw output、HWPOD 服务观测结果、Agent trace、artifact、diff、run context 和用户/资源摘要。
受控资源	CaseRun 定义、case registry、aggregate、评价模型、replay 入口、训练反馈样本和失败标签。
外部输出	CaseRun 结果、aggregate、评价结论、replay 线索、失败分类、训练反馈和可复验的验证关系。
用户接口	CaseRun CLI/API、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编排、用户管理

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 和运行支撑。

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 归因。