mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: declare web caserun e2e spec (#870)

Browse Source 
Co-authored-by: Codex <codex@noreply.local>
This commit is contained in:
Lyon
2026-06-25 12:00:21 +08:00
committed by GitHub
parent 681b9e3292
commit a5a171c09f
10 changed files with 250 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
project-management/PJ2026-01/specs/PJ2026-010101-hwpod-standard.md
+9
View File
@@ -19,6 +19,7 @@
| 短名 | HWPOD标准 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
@@ -33,6 +34,8 @@ HWPOD标准负责定义真实硬件资源的身份、四要素、能力声明、
本课题的目标状态是：任何可被 CaseRun 或 Agent 写入的真实设备，都必须先拥有明确 HWPOD spec、workspace authority、debug probe 绑定、io probe 绑定、board-comm 端点、恢复能力和可解释错误语义。
Web CaseRun 使用 HWPOD 时，caseId、hwpodId、nodeId、workspace、probe、能力声明和状态错误必须能被 Cloud Web、API、HWPOD 服务、Python UI node、AgentRun 和 HarnessRL 一致引用。
### 2.2 范围内
- HWPOD 身份、`hwpod-id`、目标设备、workspace、debug probe、io probe 和 HWPOD node 的关系。
@@ -40,6 +43,7 @@ HWPOD标准负责定义真实硬件资源的身份、四要素、能力声明、
- spec authority、版本来源、资源绑定校验和禁止错误设备替代的规则。
- 状态、健康、不可用、占用、probe mismatch、通信失败和未声明能力等错误语义。
- 真实频率源、外部电流、CANopen SDO、board-comm JSON-RPC、下载和 reset 等能力在 HWPOD spec 中的声明边界。
- Web CaseRun 可用性判断所需的 workspace、Keil build、download、UART、apply-patch、diagnostics 和 node-reported capability 声明边界。
### 2.3 范围外
@@ -57,6 +61,7 @@ HWPOD标准负责定义真实硬件资源的身份、四要素、能力声明、
| 能力声明 | HWPOD spec 中对 build、download、reset、UART、board-comm、ioProbe、CANopen SDO、电压、电流或频率等能力的声明。 |
| 绑定校验 | 对设备、workspace、probe、node 和通信端点之间关系的一致性校验。 |
| 恢复能力 | HWPOD 对 reset、重新连接、清理输出或回到安全态的受控能力声明。 |
| node-reported capability | HWPOD node 在心跳或 inventory 中上报的实际能力摘要，用于与 HWPOD spec 声明能力比对。 |
## 4. 系统边界和接口
@@ -92,6 +97,8 @@ HWPOD标准应为每个可执行真实硬件资源定义稳定身份，使目标
资源身份必须禁止静默替代。一个任务请求某个真实设备时，工具、服务和节点不得用另一个设备、另一个 probe 或另一个 workspace 代替成功结果。
Web CaseRun 的资源身份必须至少能稳定关联 caseId、hwpodId、nodeId、workspace authority、目标设备、debug probe、UART binding 和 service authority。Web、web-probe 或 CLI 不得用本地目录名、旧 direct-url、最近连接节点或人工选择文本替代 HWPOD spec 身份。
### 6.2 HWPOD-STD-REQ-002 能力声明
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -102,6 +109,8 @@ HWPOD标准应声明每个资源支持的操作能力和恢复能力，使 build
未声明能力不得被工具或节点临时猜测。涉及真实频率源、外部电流或板侧写入的操作必须在 spec 中明确端点、单位、方向、读写属性和安全恢复能力。
HWPOD spec 声明能力必须能与 node-reported capability 对齐。CaseRun 所需的 workspace apply-patch、Keil build、download/reset、UART read/write、diagnostics 和日志证据能力若在 spec 或节点任一侧缺失，应形成 capability mismatch，而不是等到 CaseRun 执行阶段以通用失败暴露。
### 6.3 HWPOD-STD-REQ-003 绑定校验
| 编号 | 短名 | 主责模块 | 关联模块 |
project-management/PJ2026-01/specs/PJ2026-010102-hwpod-tools.md
+9
View File
@@ -19,6 +19,7 @@
| 短名 | HWPOD工具 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
@@ -33,6 +34,8 @@ HWPOD工具负责把 HWPOD 标准和服务能力暴露为用户、Agent 和 Case
本课题的目标状态是：工具入口不静默切换目标，不把低层连接或协议错误包装成成功，并能为上层 CaseRun 提供稳定、低噪声、可判定的命令结果。
在 Web CaseRun 场景中，HWPOD 工具语义可以被 Cloud API、AgentRun runner、HWPOD 服务或节点适配器间接调用，但其完成态必须仍然表现为结构化 operation result，而不是只留在本地命令 stdout、Windows 控制台或人工 issue 评论。
### 2.2 范围内
- HWPOD spec 新建、修改、validate、inspect 和资源摘要输出。
@@ -40,6 +43,7 @@ HWPOD工具负责把 HWPOD 标准和服务能力暴露为用户、Agent 和 Case
- HWPOD runtime API、服务端 authority 和本地 workspace 之间的目标解析。
- 命令返回码、结构化输出、错误分类、read-only 诊断和写操作前置校验。
- Agent workspace、CaseRun 和人工 CLI 对同一 HWPOD 工具语义的复用。
- Web CaseRun 对 HWPOD 工具结果的引用边界，包括 operation result id、日志/证据路径、returnCode、target 摘要和可脱敏 blocker。
### 2.3 范围外
@@ -57,6 +61,7 @@ HWPOD工具负责把 HWPOD 标准和服务能力暴露为用户、Agent 和 Case
| 只读诊断 | 不改变硬件状态的 spec、status、api、inventory 或 read 类命令。 |
| 写操作 | download、reset、SDO write、输出刺激、电流/频率设定等会改变设备状态的命令。 |
| 结构化输出 | 可被上层解析的 JSON 或等价结构，包含状态、错误分类、目标身份和必要结果。 |
| CaseRun 工具结果 | 可被 CaseRun artifact manifest 引用的 HWPOD 工具执行摘要，至少包含目标身份、op 类型、结果状态、证据指针和脱敏诊断。 |
## 4. 系统边界和接口
@@ -102,6 +107,8 @@ HWPOD工具应提供 build、download、reset、UART、filesystem 和通用硬
执行动作入口必须在写操作前确认目标身份、租约状态和能力声明。缺少 spec、缺少恢复能力或无法确认 probe 绑定时，工具应停止在可理解错误上，而不是继续执行低层命令。
Web CaseRun 所需的 build、download、reset、UART 和 workspace 文件动作应保留 CaseRun 工具结果所需字段，使 HarnessRL 能把工具输出、HWPOD operation result、AgentRun trace 和 aggregate 关联到同一 run。工具入口不得要求 Web、web-probe 或 HarnessRL 解析未结构化 stdout 才能判断关键状态。
### 6.3 HWPOD-TOOL-REQ-003 观测与协议入口
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -121,3 +128,5 @@ HWPOD工具应提供 board-comm、ioProbe、CANopen SDO、频率读写和电流
HWPOD工具应输出可判定的结构化结果，使成功、未声明资源、目标不匹配、服务路由失败、节点离线、协议连接失败和板侧处理失败能够被上层区分。
诊断输出不得替代能力实现。工具只能把真实失败分类并暴露给用户、Agent、CaseRun 或客户端；缺失的 spec、路由、节点适配器或板侧处理能力仍必须由对应 L2 修复。
Web CaseRun 的工具诊断必须能进入云端日志和用户可见 blocker。路径不存在、Git/PATH/Keil 不可用、probe mismatch、download verify failure、UART/serial-monitor 不可用、capability mismatch 和节点协议异常都应有稳定错误分类和建议下一步；不能只打印到本地黑框或 GUI 日志后让 Cloud Web 显示通用失败。
project-management/PJ2026-01/specs/PJ2026-010103-hwpod-service.md
+11
View File
@@ -19,6 +19,7 @@
| 短名 | HWPOD服务 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
@@ -33,6 +34,8 @@ HWPOD服务负责服务端资源注册、健康、租约、占用释放、权限
本课题的目标状态是：服务端只路由已声明、可用、已授权且租约一致的资源，并把每次操作结果归属到明确 HWPOD、node、租约和调用方。
在 Web CaseRun 场景中，HWPOD服务是 Cloud API、HarnessRL、AgentRun 和用户 PC 侧 HWPOD node 之间唯一的硬件资源 authority。Cloud Web、web-probe、CLI 和 Agent 都不得直接连接本地 gateway 或旧运行面来判定硬件成功。
### 2.2 范围内
- HWPOD registry、资源注册、spec 摘要、authority 和版本来源。
@@ -40,6 +43,7 @@ HWPOD服务负责服务端资源注册、健康、租约、占用释放、权限
- 租约、占用、释放、冲突处理、超时释放和写操作保护。
- 工具/API 请求接收、目标解析、节点路由、超时和错误分类。
- operation result 的归属、查询、摘要和对 HarnessRL/Agent编排/客户端的交接。
- Web CaseRun 对 HWPOD readiness、租约、路由、operation result、capability mismatch 和结构化 blocker 的消费边界。
### 2.3 范围外
@@ -57,6 +61,7 @@ HWPOD服务负责服务端资源注册、健康、租约、占用释放、权限
| 租约 | 一次资源占用关系，约束调用方、HWPOD、操作类型、超时和释放。 |
| 路由 | 服务端把 HWPOD 操作请求转发到正确 HWPOD node 或 AI 网关的过程。 |
| operation result | 服务端接收并归属的一次硬件操作结果。 |
| CaseRun 调用方 | HarnessRL 为一次 CaseRun 持有的硬件操作调用上下文，至少携带 runId、caseId、actor、HWPOD 和租约摘要。 |
## 4. 系统边界和接口
@@ -102,6 +107,8 @@ HWPOD服务应提供租约、占用、释放、冲突处理和超时恢复能力
租约只定义硬件资源占用事实。用户管理提供调用主体和权限约束，Agent编排提供任务上下文，HWPOD服务负责把这些约束落实到资源可用性和写操作保护。
CaseRun 触发的 build、download、reset、UART 或 workspace 写操作必须绑定明确 runId、caseId、hwpodId、nodeId、actor 和租约。相同 HWPOD 在已有写租约期间不得被另一条 Web CaseRun、CLI 诊断或旧 runner 静默复用；冲突必须作为可查询 blocker 返回给 HarnessRL 和客户端。
### 6.3 HWPOD-SVC-REQ-003 节点路由
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -114,6 +121,8 @@ HWPOD服务应把已授权且租约一致的操作请求路由到正确 HWPOD no
HWPOD 服务端只作为云端请求接收、租约校验、目标解析和网关路由 authority；Cloud Web、Agent 和 CLI 不应直接连接用户 PC 上的 gateway。网关主动出站后，服务端仍必须把命令领取、in-flight、超时、`gateway_busy` 和节点返回失败归一为可查询的 operation 状态，避免调用方把 HTTP dispatch timeout 误判为硬件动作结果。
Web CaseRun 的所有硬件动作都必须通过 HWPOD 服务节点路由。服务端应在 route 摘要中暴露目标 hwpodId、nodeId、声明 capability、node 上报 capability、route authority、request id 和必要 trace 关联，使 HarnessRL 能区分 workspace missing、node offline、capability mismatch、probe mismatch、gateway busy、adapter failure 和硬件动作失败。
### 6.4 HWPOD-SVC-REQ-004 结果归属
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -123,3 +132,5 @@ HWPOD 服务端只作为云端请求接收、租约校验、目标解析和网
HWPOD服务应把每次 operation result 归属到明确的 HWPOD、node、租约、调用方、操作类型和时间上下文，使 HarnessRL、客户端和账务统计能消费同一结果事实。
结果归属不是长证据归档。服务端只负责保存和交接必要操作结果、摘要和查询指针；CaseRun 评价、回放、训练反馈和用户展示由对应模块在此事实上继续处理。
Web CaseRun 消费的 operation result 至少应能被 HarnessRL 引用到同一 run stage，并携带 op 类型、target path 或 probe 摘要、returnCode 或失败分类、日志/证据指针、valuesRedacted、requestId/trace 关联和 node-reported capability 摘要。HWPOD服务不生成 CaseRun aggregate，但必须提供足够稳定的 operation result 引用，使 aggregate、artifact manifest、Web run 卡和 web-probe report 指向同一硬件事实。
project-management/PJ2026-01/specs/PJ2026-010104-ai-gateway.md
+11
View File
@@ -19,6 +19,7 @@
| 短名 | AI网关 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
@@ -33,6 +34,8 @@ AI网关负责靠近真实硬件执行受控动作并回传原始硬件事实，
本课题的目标状态是：节点先完成只读连通与身份确认，再按声明能力执行写操作，并在失败时返回可区分的节点、协议、板侧处理或安全恢复错误。
在 Web CaseRun 场景中，PC 侧单文件 Python UI node 可以作为 HWPOD node 的一种实现形态。它提供本地连接状态、日志观察、托盘和更新等 operator 体验，但硬件事实、operation result 归属、租约和云端可见状态仍以 HWPOD 服务协议为准。
### 2.2 范围内
- HWPOD node / AI 网关进程、心跳、能力上报、健康和可用性。
@@ -40,6 +43,7 @@ AI网关负责靠近真实硬件执行受控动作并回传原始硬件事实，
- debug probe 下载、reset、UART、board-comm JSON-RPC、CANopen SDO、ioProbe、电压、电流和频率适配器。
- 只读诊断、写操作前置身份确认、安全态恢复和恢复失败分类。
- 原始硬件事实回传，包括板内 echo、板外采样、协议响应、适配器日志摘要和错误语义。
- Web CaseRun 所需的 workspace、Keil build、download、reset、UART、capability 上报、日志摘要和云端诊断回传。
### 2.3 范围外
@@ -53,6 +57,7 @@ AI网关负责靠近真实硬件执行受控动作并回传原始硬件事实，
| 术语 | 定义 |
| --- | --- |
| AI 网关 | 靠近真实硬件的节点侧执行能力，包含 PC 客户端、硬件网关盒子或等价 HWPOD node。 |
| Python UI node | 单文件 Python PC 客户端形态的 HWPOD node，面向本地 operator 提供简洁 GUI、日志、托盘和更新能力，同时通过主动出站协议领取云端命令。 |
| adapter | 网关侧执行某类硬件动作的适配器，例如 debug probe、UART、board-comm、ioProbe 或 CANopen。 |
| board-comm | 通过板侧通信协议访问目标固件接口的能力，可包含 JSON-RPC over TCP 等形态。 |
| CANopen SDO | 通过 CANopen Service Data Object 读写设备对象字典的协议动作。 |
@@ -98,6 +103,8 @@ AI网关应上报节点心跳、能力、健康、可用性和运行形态，使
AI网关默认采用主动出站连接模式：用户 PC、本地 gateway 或硬件盒子主动连接云端 HWPOD 服务并领取命令，云端不要求入站访问用户网络。网关注册和会话状态应暴露当前 in-flight 数量、并发上限和主要执行摘要，使一个长 Keil、下载或 Windows 命令不会遮蔽节点是否仍在心跳、是否仍能处理短状态查询。
Python UI node 作为 PC 客户端形态时，必须上报与 Web CaseRun 相关的实际能力，而不只是进程版本。能力摘要至少应覆盖 workspace 操作、apply-patch、Keil build、download/reset、UART read/write、diagnostics、日志回传和更新状态；缺失能力必须以 capability mismatch 暴露给 HWPOD 服务、HarnessRL 和客户端。
### 6.2 HWPOD-GW-REQ-002 适配器执行
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -110,6 +117,8 @@ AI网关应按 HWPOD spec 声明执行 debug、download、reset、UART、board-c
长时间执行的适配动作应作为网关内 in-flight 请求后台推进，poll loop 仍继续处理心跳、job-status、日志读取、取消和诊断请求。达到并发上限时，网关应返回结构化 `gateway_busy`，不得把请求静默排队到云端 dispatch timeout 后才暴露失败。
Web CaseRun 需要的 workspace patch、Keil build、download、UART 和诊断动作都应返回结构化 adapter result。节点侧本地黑框、GUI 文本框或托盘提示不能成为唯一错误载体；异常、stdout/stderr 摘要、日志路径、returnCode、probe mismatch、serial-monitor 状态和可恢复建议必须进入云端可查询的 operation result 或节点诊断摘要。
### 6.3 HWPOD-GW-REQ-003 安全恢复
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -129,3 +138,5 @@ AI网关应在写操作前后提供只读诊断、身份确认、reset 和安全
AI网关应回传原始硬件事实，使板内协议响应、板外 ioProbe 读数、adapter 摘要、连接失败、协议失败和板侧处理失败能被 HWPOD 工具与 HarnessRL 一致消费。
原始硬件事实必须区分板内 echo、板外真实读数和节点适配器状态。网关不能把 TCP 端口可达、进程在线或命令已发出等中间状态当作硬件动作成功。
Python UI node 本地日志应与云端诊断保持可关联。节点在处理 CaseRun 操作时应保留 requestId、runId 或等价 correlation 摘要，并把可脱敏的关键错误上报给 HWPOD 服务，使 Cloud Web、web-probe 和 issue evidence 能看到同一失败原因，而不是只能在 Windows 控制台或本地 GUI 中观察。
project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md
+8 -2
View File
@@ -22,6 +22,7 @@
| 短名 | Agent编排 |
| 层级 | L1 方向 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
@@ -37,6 +38,7 @@ Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执
### 2.2 范围内
- HWLAB 入口到 AgentRun run、command、runner job 的提交、短返回、轮询和终态管理。
- Web CaseRun 中 Code Agent 执行部分的 run、command、trace、subject worktree、diff 和 final response 指针。
- Queue task、run、command、runner job、session、thread、conversation、cancel、timeout、恢复和 read cursor 语义。
- RuntimeAssembly 装配，包括 BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef、gitbundle、promptRefs、skills、tools、workspaceFiles、SecretRef、provider profile 和模型配置。
- Backend adapter、Codex stdio backend、provider profile、profile 管理和 profile 隔离。
@@ -72,9 +74,9 @@ Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执
| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 客户端、HarnessRL、用户管理、硬件池、平台运维和训练任务。 |
| 外部输入 | 用户任务、conversation、session/thread、project/workspace/ref、HWPOD hint 或分配结果、provider profile、ResourceBundleRef、prompt、skills、tools 和 SecretRef。 |
| 外部输入 | 用户任务、CaseRun execution request、conversation、session/thread、project/workspace/ref、HWPOD hint 或分配结果、provider profile、ResourceBundleRef、prompt、skills、tools 和 SecretRef。 |
| 受控资源 | HWLAB Agent task、AgentRun run/command/runner job、session、RuntimeAssembly、workspace materialization 和执行事实指针。 |
| 外部输出 | runId、commandId、runnerJobId、sessionId、trace pointer、terminal status、liveness、failure kind、materialized commit 摘要和 artifact/tool 摘要。 |
| 外部输出 | runId、commandId、runnerJobId、sessionId、trace pointer、terminal status、liveness、failure kind、materialized commit 摘要、diff/final response 指针和 artifact/tool 摘要。 |
| 用户接口 | HWLAB Agent API、Cloud Web/CLI Agent 入口、AgentRun 资源原语、provider profile 管理入口。 |
| 系统边界 | Agent编排负责执行生命周期和资源装配正确性；不定义硬件事实、Harness 评分、用户账本、客户端布局或平台发布流程。 |
@@ -110,6 +112,8 @@ Agent编排应按 RuntimeAssembly 装配 BackendImageRef、ProfileRef、SessionR
资源装配必须能说明 runner 实际使用了哪个 repo/ref、actual commit、bundle、profile、session 和工具输入。硬件池提供 HWPOD hint 或分配结果，平台运维提供 Git mirror、Secret 和运行面支撑，HarnessRL 消费执行上下文。
Web CaseRun 使用 AgentRun 时，RuntimeAssembly 必须能说明 subject worktree、case bundle、provider profile、required skills/tools、HWPOD context 指针和可脱敏输入证明。AgentRun 可以给出 Code Agent trace、diff、final response 和 terminal/failureKind；它不判断 HWPOD operation result 是否满足 case，也不生成 CaseRun aggregate。
### 6.3 AGENT-L1-REQ-003 队列与会话
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -141,3 +145,5 @@ Agent编排应原样消费 AgentRun 的 run、command、runner job、event、ter
HWLAB 不应在客户端、adapter 或 prompt 中推断或补造 AgentRun 没有发出的事实。AgentRun 已正确输出时，HWLAB 负责消费和业务映射；AgentRun 合同缺失或行为错误时，应回到 AgentRun 实现与对应 OA 规格修复。
[PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 要求 Agent编排只把 AgentRun run、command、event、terminal status、failureKind 和 result envelope 交给 HWLAB接入的 projection writer/finalizer。Agent编排不得让 Web、CLI、Workbench GET、trace polling 或 legacy conversation path 分别读取 AgentRun 并各自推断 session running、assistant final response、turn terminal 或 trace terminal；同一 AgentRun 事实只能形成一份 HWLAB Workbench durable projection。
Web CaseRun 的 Agent 执行部分同样遵守该合同边界。CaseRun service 可以引用 AgentRun runId、commandId、traceId、terminal status、diff 和 final response，但不得通过 stdout 尾部、partial assistant、runner pod phase 或用户手工 steer 推断 CaseRun 成功。硬件动作、operation result 和 aggregate 仍由硬件池与 HarnessRL 生产，Agent编排只交付可引用的执行事实。
project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md
+122 -3
View File
@@ -22,6 +22,7 @@
| 短名 | HarnessRL |
| 层级 | L1 方向 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
@@ -34,9 +35,12 @@
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、失败分类和可复验比较。
@@ -55,8 +59,13 @@ HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较
| 术语 | 定义 |
| --- | --- |
| 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 或策略改进材料。 |
@@ -68,10 +77,10 @@ HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较
| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | Agent编排、客户端、用户管理、硬件池和训练任务。 |
| 外部输入 | case definition、workspace commit、HWPOD raw output、HWPOD 服务观测结果、Agent trace、artifact、diff、run context 和用户/资源摘要。 |
| 外部输入 | case definition、Web/CLI/API 提交请求、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 后端语义。 |
| 外部输出 | 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. 内部分工与规格索引
@@ -82,6 +91,100 @@ HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较
| 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[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 目标数据流图
```mermaid
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 关键时序图
```mermaid
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. 原子需求
@@ -95,6 +198,8 @@ HarnessRL 应定义 CaseRun 的 case definition、stage model、postValidation
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 观测引用
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -126,3 +231,17 @@ HarnessRL 应提供评估与回放语义，使同一次硬件执行可以被 agg
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 语义。
project-management/PJ2026-01/specs/PJ2026-0104-client.md
+22 -2
View File
@@ -22,6 +22,7 @@
| 短名 | 客户端 |
| 层级 | L1 方向 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
@@ -34,12 +35,16 @@
客户端负责 HWLAB 面向用户的统一入口，使 Web、HWLAB CLI 和 HTTP API 围绕同一任务模型、权限模型、资源模型、trace/result 模型和错误语义协同演进。
客户端还负责把 Web CaseRun 暴露为用户可直接操作、可观察、可复验的端到端入口，使浏览器用户和自动化验收都通过同一 YAML-selected Cloud Web origin、同一 API 契约、同一 runId 和同一结果阅读模型触达 HarnessRL、Agent编排和硬件池能力。
### 2.2 范围内
- Cloud Web 工作台、登录后工作流、任务创建、会话入口、trace/result 展示和用户可见资源入口。
- Cloud Web 通过 `/auth/session` 消费 canonical identity，并以业务 API 返回的 capability/blocker 展示授权状态。
- Cloud Web 的 CaseRun 用户入口、run 状态卡、trace/aggregate/HWPOD 证据阅读入口和可操作 blocker 展示。
- HWLAB CLI 的运行端点解析、API key 鉴权入口、同源 API 调用、短连接命令、结构化输出、错误语义和脚本可用性。
- 通过 HWLAB CLI 覆盖账号/额度、工作台、显式 Agent session、Agent 任务、trace/result、HWPOD/CaseRun 组合入口和必要管理入口的非视觉全流程复验。
- web-probe 作为 Cloud Web 同源非视觉验收路径运行 CaseRun；它不拥有新的业务事实或后门接口。
- HTTP API 的同源 path、schema、错误语义、鉴权主体和多端一致性。
### 2.3 范围外
@@ -57,6 +62,9 @@
| Cloud Web | HWLAB 的 Web 用户入口，承载登录、工作台、任务、资源和管理页面。 |
| HWLAB CLI | HWLAB 命令行入口，用于脚本化访问 Web 同源 API、Agent、CaseRun、HWPOD、用户和管理能力。 |
| 同源 CLI | 与 Cloud Web 使用同一 Web origin、同一相对 API path 和同一用户身份语义的 HWLAB CLI 调用方式。 |
| Web CaseRun 入口 | Cloud Web 中提交、观察和阅读 CaseRun 的用户界面，与同源 CaseRun API 和 HarnessRL run/read model 绑定。 |
| selected Web origin | 由 node/lane YAML 声明并由客户端工具解析的 Web origin；默认是 public origin，本次 D601/v03 验收可选择 internal IP origin。 |
| web-probe CaseRun | 通过真实浏览器和 selected Web origin 执行的 CaseRun 验收路径；只模拟用户入口和同源 API，不直接访问未声明的内部服务。 |
| API 契约 | HTTP API 和错误语义的稳定调用约定。 |
| 多客户端一致性 | 不同入口共享同一任务、权限、错误和结果语义。 |
| 短连接命令 | 发起后快速返回可查询 ID 或紧凑结果，再通过 status、trace、result 或 watch 继续观察的 CLI 命令。 |
@@ -69,9 +77,9 @@
| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 硬件研发用户、自动化脚本使用者、平台管理员。 |
| 外部输入 | 用户凭据、API key、运行端点选择、任务请求、workspace/HWPOD 选择、Agent session 操作、CaseRun 操作和管理操作。 |
| 外部输入 | 用户凭据、API key、运行端点选择、任务请求、workspace/HWPOD 选择、Agent session 操作、Web CaseRun 操作和管理操作。 |
| 受控资源 | Web 页面、HWLAB CLI 命令、HTTP API、共享 trace renderer 和同源 API 调用契约。 |
| 外部输出 | 用户可见任务入口、资源入口、命令响应、HTTP 响应、错误语义、trace/result 摘要和结果展示。 |
| 外部输出 | 用户可见任务入口、资源入口、CaseRun run 卡和 aggregate 阅读入口、命令响应、HTTP 响应、错误语义、trace/result 摘要和结果展示。 |
| 用户接口 | Cloud Web、HWLAB CLI、HTTP API。 |
| 系统边界 | 客户端负责入口一致性和用户可见契约；不定义后端业务事实、硬件事实、评价语义、账本真相或发布机制。 |
@@ -119,6 +127,18 @@ CLI 入口必须复用后端业务事实，不在命令行层重新定义 HWPOD
API 契约负责调用形态、字段稳定性和错误表达，不拥有账号、任务、硬件或评价的业务真相。后端模块改变事实模型时，客户端负责把 Web、HWLAB CLI 和 HTTP API 的入口契约以一致方式暴露。
### 6.4 CLIENT-L1-REQ-004 Web CaseRun 用户入口
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-L1-REQ-004 | Web CaseRun入口 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md) | [HarnessRL](PJ2026-0103-harness-rl.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
客户端应提供 Web CaseRun 用户入口，使用户能在 Cloud Web 中选择 HWPOD 和 case，提交 CaseRun，观察 run stage，阅读 Agent trace、HWPOD build/download/UART 证据、artifact manifest 和 aggregate，并在失败时看到对应模块输出的结构化 blocker。
Cloud Web、HWLAB CLI 和 web-probe 必须使用 YAML 选中的同一 Web origin、同一同源 CaseRun API 和同一用户身份语义。客户端不得把 web-probe、CLI、本地脚本、未在 YAML 声明的内部 Cloud API 直连、数据库、SSH 或旧 lane 端口变成第二套 CaseRun 成功路径；非视觉验收只能证明同一 Web/API 用户路径可用。
客户端只拥有入口、展示、命令形态和错误呈现。CaseRun stage、aggregate、评价和回放归 HarnessRL；Agent run/command/trace 归 Agent编排；HWPOD 资源、租约、节点路由和 operation result 归硬件池。客户端发现能力缺失时应展示缺失能力和下一步诊断，不得用前端文案或脚本后处理合成通过状态。
## 7. 过程控制
本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。客户端方向的阶段活动材料应引用本规格和各 L2 规格，不在本规格正文中展开执行流水。
project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md
+20 -1
View File
@@ -19,7 +19,7 @@
| 短名 | Web工作台 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p0-passive-web-probe-observer; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-24-p0-no-ui-timing-fabrication; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-24-p0-aggregate-event-stream |
| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p0-passive-web-probe-observer; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-25-p0-web-caserun-e2e; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-24-p0-aggregate-event-stream |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
@@ -42,6 +42,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
- 会话列表、当前 session、用户消息、Agent 消息、命令输入区、发送、引导、取消、重试和 pending 状态展示。
- 基本工作台 Agent 调用，包括最小任务输入、发送、短返回执行标识、状态查询入口和失败原因展示。
- 工作台诊断入口、运行状态摘要、probe/build/HWPOD/Agent 状态的低噪声展示方式。
- CaseRun 用户入口，包括 HWPOD 资源选择、case 列表、run 提交、run stage、Trace、HWPOD evidence、artifact manifest、aggregate 和 blocker 展示。
- 桌面多栏布局、侧栏折叠、移动端工作台布局和输入区可达性。
- Web 与 HWLAB CLI 共用的 Code Agent composer policy、trace renderer 和同源 API 行为。
- Web 入口对用户管理、Agent编排、硬件池、HarnessRL 和平台运维输出事实的展示契约。
@@ -67,6 +68,9 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
| 低噪声展示 | 诊断、trace、状态和辅助信息不抢占主任务区，也不伪装成用户或 Agent 正文。 |
| 响应式工作台 | 同一工作台在桌面和移动端按不同可视空间重排，但仍优先保证任务输入和状态理解。 |
| 同源业务入口 | Cloud Web 与 HWLAB CLI 通过同一 Web origin、相对 REST/JSON API path 和业务标识访问 HWLAB 能力的入口。 |
| Web CaseRun 视图 | Web 工作台或其相邻登录后页面中用于提交、观察和阅读 CaseRun 的用户界面。 |
| CaseRun run 卡 | 展示一次 CaseRun 的 runId、caseId、hwpodId、stage、Trace、HWPOD evidence、artifact manifest、aggregate 和 blocker 的紧凑工作态组件。 |
| selected Web origin | Web 工作台、CLI 和 web-probe 共同使用的 YAML-selected origin；默认 public，D601/v03 端到端验收可由 YAML 切换到 internal IP。 |
| 浏览器登录态 | Cloud Web 随同源请求携带的 `hwlab_session` Web session transport；前端只负责传递，不解释权限、project 归属或资源可见性。 |
| canonical identity | Web 工作台从 `/auth/session` 读取的最小身份结果，包含 actor、`authMethod`、`identityAuthority`、`sessionKind` 和 capability 摘要；它是 Web shell、导航和业务页面的唯一身份输入。 |
| Session权威入口 | Web 工作台按 sessionId 或后端认可的 opaque session handle 恢复当前会话消息、turn 摘要、trace 指针和状态的 RESTful detail API。 |
@@ -125,6 +129,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
| PJ2026-01040109 | 前端模块 | 本规格 6.9 | API client、event client、server-state、UI state 和组件职责拆分 | API契约、公开入口 | 可维护前端实现 |
| PJ2026-01040110 | 浏览器回归 | 本规格 6.10 | Playwright 独立测试、真实采集 fixture、mock server、截图 artifact 和状态投影断言 | API契约、平台运维 | Workbench 功能回归、防止刷新和会话切换退化 |
| PJ2026-01040111 | 长程观测 | 本规格 6.11 | 纯客户端 web-probe observer、命令文件控制、无副作用采样、JSONL artifact 和后处理分析 | 平台运维、公开入口 | Workbench 长程稳定性、瞬态竞态复现 |
| PJ2026-01040112 | CaseRun入口 | 本规格 6.12 | Web CaseRun 视图、run 卡、证据阅读、blocker 展示和 web-probe 同路径验收 | HarnessRL、API契约、硬件池、Agent编排 | 用户端到端硬件验证 |
### 5.1 目标数据流程图
@@ -472,6 +477,20 @@ web-probe observer 必须保持纯客户端形态。它可以作为目标 host
长程 observer 不替代 fake-server Playwright 回归。fake-server Playwright 负责确定性功能红灯和修复后回归；observer 负责在线 public origin 的长时间、无副作用、瞬态观测。observer 发现的 bug 必须沉淀成可复现 fixture 或 fake-server 用例后再作为 Web 工作台功能回归闭环；不得用 observer 的自动切换、reload、repair 或人工观察代替功能修复。
### 6.12 CLIENT-WB-REQ-012 CaseRun 入口
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-WB-REQ-012 | CaseRun入口 | PJ2026-01040112 CaseRun入口 | [HarnessRL](PJ2026-0103-harness-rl.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
Web 工作台应提供 CaseRun 用户入口，使用户能在登录后的 selected Web origin 中查看可用 HWPOD 资源和 case 列表，提交 CaseRun，看到 runId 和短返回状态，并在同一页面或相邻登录后页面观察 run stage、Trace、HWPOD evidence、artifact manifest、aggregate 和失败 blocker。
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 和继续查询标识必须默认可见。
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 和可复制诊断，而不是改写为通用请求失败。
线上 web-probe 对 CaseRun 的验收必须从同一 selected Web origin 进入。默认使用正式 public origin；本次 D601/v03 可以由 YAML 切换到 internal IP origin。web-probe 可以点击页面控件或调用页面同源正式 mutation，但不得绕过 Web session、不得使用未被 YAML 选中的内部 service URL、不得直接写 D601 文件系统、不得用 SSH 或手工 CLI 操作补齐硬件证据。web-probe 报告至少应记录 originMode、YAML source path、final URL、截图 SHA、caseId、runId、hwpodId、nodeId、traceId、HWPOD operation result 引用、aggregate 或 artifact manifest hash，以及是否存在用户可见 blocker。
## 7. 过程控制
本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。
project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md
+33 -1
View File
@@ -19,7 +19,7 @@
| 短名 | API契约 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-20-p0-workbench-pure-read-api; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-22-p1-workbench-redis-derived-cache; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-24-p0-aggregate-event-stream; PJ2026-01050105 Web鉴权 draft-2026-06-18-p0-auth |
| 实现引用版本 | draft-2026-06-20-p0-workbench-pure-read-api; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-22-p1-workbench-redis-derived-cache; draft-2026-06-25-p0-web-caserun-e2e; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-24-p0-aggregate-event-stream; PJ2026-01050105 Web鉴权 draft-2026-06-18-p0-auth |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) |
| 关联规格 | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) |
@@ -40,6 +40,7 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE
- Cloud Web 同源相对 REST/JSON path、route policy 和绝对 URL 禁止边界。
- Web session、API key、AuthPrincipal、actor 摘要和权限错误在客户端入口中的表达。
- Agent session、chat、steer、cancel、result、trace 和 inspect 的用户可见 API 形态。
- CaseRun case list、run admission、run status、events、aggregate、artifact manifest、cancel 和 HWPOD/AgentRun 引用的用户可见 API 形态。
- Workbench workspace、Admin Access、provider profile、HWPOD node-ops、gateway 和性能摘要等入口的字段稳定性。
- JSON 成功/失败响应、HTTP 状态、错误分类、脱敏、默认摘要和完整展开边界。
- Workbench pure-read API 的缓存诊断字段，包括 `cacheStatus`、`cacheAgeMs`、projection revision/seq、dbQueryAvoided 和 Redis unavailable/stale 的低基数表达。
@@ -62,6 +63,9 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE
| AuthPrincipal | 后端根据 Web session 或 API key 恢复出的用户主体摘要。 |
| CanonicalPrincipal | `/auth/session` 和受保护业务 route 共享的最小身份结果，包含 `authMethod`、`identityAuthority`、`sessionKind`、actor 摘要和后端 capability 摘要；它是业务 route 的唯一身份输入。 |
| 业务标识 | sessionId、turnId、traceId、runId、commandId、caseId 等用户可继续查询的稳定标识；projectId、workspaceId 和 conversationId 只能作为筛选、metadata 或兼容映射字段，不作为前端鉴权 authority。 |
| CaseRun resource | Cloud Web origin 下表达 CaseRun case、run、stage、event、aggregate 和 artifact manifest 的 RESTful 资源集合。 |
| Run admission | 接收 CaseRun 提交并返回 `202 Accepted`、runId、statusUrl 和下一步查询入口的短返回 mutation。 |
| selected origin mode | 客户端入口从 YAML 解析出的 origin 模式，至少区分 `public` 和 `internal`；API 只看到同源请求，不反推或硬编码入口地址。 |
| 错误语义 | HTTP status、错误码、blocker、failureKind、route 和下一步提示组成的可定位失败表达。 |
| W3C trace context | `traceparent` / `tracestate` / `baggage` 等跨进程传播上下文；API 响应只允许把 `traceparent` 和脱敏后的 OTel trace id 暴露给客户端，不向用户展示 `tracestate`、`baggage` 或上游私有上下文。 |
| OTel trace_id | OpenTelemetry/W3C trace context 中的 16-byte 非全零 trace id，以 32 位十六进制字符串表达；它用于从用户截图或复制信息跳转到 trace backend，不替代业务 `traceId`、`sessionId`、`runId` 或权限判断。 |
@@ -108,6 +112,7 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE
| PJ2026-01040304 | 资源接口 | 本规格 6.4 | workspace、access、provider、HWPOD node-ops、gateway 和性能摘要入口 | 全部业务 L1 | Web、CLI、admin |
| PJ2026-01040305 | 错误输出 | 本规格 6.5 | JSON 成功/失败响应、错误码、route/status、脱敏和渐进披露 | 全部业务 L1 | 用户、脚本、排障 |
| PJ2026-01040306 | 缓存诊断 | 本规格 6.6 | Workbench pure-read cache diagnostic 字段、脱敏边界和禁止状态仲裁 | Workbench唯一投影、Workbench性能 | Web、CLI、Performance 页 |
| PJ2026-01040307 | CaseRun接口 | 本规格 6.7 | CaseRun case/run/status/events/aggregate/cancel REST 资源、短返回和错误语义 | HarnessRL、硬件池、Agent编排 | Web CaseRun、CLI、web-probe |
目标后端模块应至少拆分为 route/handler、schema/contract、read model、persistence/projection、AgentRun adapter、trace event pager、SSE/event publisher 和 compat wrapper。route 文件只负责 HTTP 入口、鉴权桥接和错误映射；schema/contract 只负责类型和字段；read model 只组装查询模型；adapter 只转换外部执行事实；projection 只写 durable facts；compat wrapper 只提供旧 path 到新资源的兼容映射，不拥有第二套业务事实。
@@ -341,6 +346,33 @@ CacheDiagnostic 不得成为业务状态仲裁字段。Web、CLI、compat wrappe
CacheDiagnostic 必须脱敏并保持低基数。响应、日志、OTel span 和 `/performance` 默认展示不得包含完整 cache key、actor id 聚合维度、trace id 组合 key、prompt、assistant 正文、tool 参数、stdout/stderr、Secret、token、cookie、Authorization header、DB DSN 或 raw upstream payload。需要排查单次请求时，只允许通过 OTel trace id、request id、route、cacheKeyClass、projectionSeq 和 valuesRedacted 摘要关联。
### 6.7 CLIENT-API-REQ-007 CaseRun 用户接口
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-API-REQ-007 | CaseRun接口 | PJ2026-01040307 CaseRun接口 | [HarnessRL](PJ2026-0103-harness-rl.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) |
API契约应定义 YAML-selected Cloud Web origin 下的 CaseRun RESTful 资源，使 Web、HWLAB CLI 和 web-probe 能通过同一用户身份、同一相对 path 和同一错误 envelope 提交、查询、取消和阅读 CaseRun。origin 是 public 还是 internal 由 node/lane YAML 和客户端端点解析决定，API 契约只要求同源 path 与错误语义一致。
目标 CaseRun API 资源设计如下。具体字段可随实现演进，但资源身份、短返回、业务事实归属和禁止后门路径必须保持稳定。
| 资源 | Method / path | 请求字段 | 响应主体 | 状态码 | 权威边界 |
| --- | --- | --- | --- | --- | --- |
| 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 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 |
| Run artifact manifest | `GET /v1/caserun/runs/{runId}/artifacts` | 可选 artifact type | manifest、artifact refs、hash、size、redaction 摘要 | 200/401/403/404 | 只返回索引和允许下载的受控摘要 |
| Run cancel | `POST /v1/caserun/runs/{runId}/cancel` | reason 可选 | updated Run status 或 accepted cancel refs | 200/202/401/403/404/409 | 精确取消目标 run，不根据最新 run 或页面状态推断 |
CaseRun API 的 GET path 必须纯读。投影滞后、AgentRun 未终态、HWPOD node 离线、operation result 缺失、aggregate 未生成或 artifact store 不可达时，GET 应返回 projecting、degraded、blocked 或结构化 failure；不得在 GET 中同步触发 AgentRun dispatch、HWPOD 写操作、workspace repair、result polling finalizer 或旧 CLI 回放。
CaseRun API 必须把事实来源分仓输出。AgentRun refs 至少应能指向 runId/commandId/traceId 或等价执行标识；HWPOD refs 至少应能指向 hwpodId、nodeId、leaseId 或 operation result id；HarnessRL refs 至少应能指向 CaseRun runId、stage revision、artifact manifest hash 和 aggregate revision。API 不得把 stdout 尾部、客户端轮询耗时、trace tail、Web DOM、web-probe 报告或人工 issue 评论作为 run terminal 或 pass/fail 事实。
web-probe 使用 CaseRun API 时必须保持 YAML-selected origin 下的同源用户路径。它可以通过页面控件或同源正式 mutation 提交 run，并通过同一 status/events/aggregate 资源观察终态；当 YAML 选择 internal origin 时可以使用内部 IP，但仍不得调用未声明的内部 service URL、Kubernetes、Postgres、D601 SSH、本地 gateway 端口、旧 v0.2 runner 或测试 fixture 来补齐 CaseRun 成功证据。
## 7. 过程控制
本规格不单独索引一般过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。Workbench Redis 派生读缓存架构执行 issue 为 [#1870](https://github.com/pikasTech/HWLAB/issues/1870)，P0 SPEC-first 子 issue 为 [#1871](https://github.com/pikasTech/HWLAB/issues/1871)，后续实现必须引用 `draft-2026-06-22-p1-workbench-redis-derived-cache`。
project-management/PJ2026-01/specs/PJ2026-010604-public-entry.md
+5
View File
@@ -19,6 +19,7 @@
| 短名 | 公开入口 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
@@ -39,6 +40,7 @@
- FRP remote port、Caddy route、managed block、DNS/TLS、public health 和入口漂移处理。
- 同一公开入口下 Web route、API path、health path 的边界说明。
- 公开入口状态、渲染目标、健康探针和失败摘要的受控输出。
- Web CaseRun 和 web-probe 验收的入口选择边界：默认使用正式 public URL；本次 D601/v03 端到端验收可由 YAML 显式切换到 internal IP origin。内部端口、旧 lane 和临时转发未被 YAML 选中时只可作为诊断对照。
### 2.3 范围外
@@ -54,6 +56,7 @@
| --- | --- |
| 公开入口 | 用户或自动化从外部访问 HWLAB 的 Web/API/health 地址集合。 |
| public URL | YAML 和受控状态查询声明的正式外部 URL。 |
| internal validation origin | YAML 声明的内网 Web origin，用于受控端到端验收或排障，不替代长期 public URL 真相。 |
| FRP | 将目标 node/lane 内部服务暴露到公网入口的反向代理通道。 |
| Caddy managed block | 由受控 CLI 管理的 Caddy 配置片段，只更新所属服务块，不整文件覆盖共享配置。 |
| public health | 通过公开入口访问的健康检查，证明入口链路到达目标运行面。 |
@@ -111,6 +114,8 @@ Caddy 更新必须使用受控 managed block 合并，不能用某个服务的
API/edge 直达入口不需要为页面 route 返回 HTML fallback；Web public 入口需要按 route policy 把 API path 分流到 API 服务。内部 `:6666`/`:6667` 这类实现端口不能作为浏览器验收默认入口；对 Node/undici bad-port 有限制的内部探测应使用 repo-owned probe、curl 或正式 public URL。
Web CaseRun 与 web-probe 验收默认从正式 public Web URL 进入，并通过同一 origin 下的 CaseRun、Workbench、HWPOD 和 health path 观察结果。本次 D601/v03 端到端验收允许 YAML 把 selected Web origin 切换到 internal validation origin；切换结果必须在 CLI/web-probe 输出中显示 originMode、YAML source path 和 selected origin 摘要。公开入口可以暴露路由、TLS、Caddy、FRP 和 health 漂移诊断，但不得让 web-probe 退回未声明的内部 service URL、node port、旧 v0.2 runner 地址、D601 SSH、本地 gateway 端口或临时 port-forward 来证明 CaseRun 通过。
### 6.4 OPS-PUBLIC-REQ-004 入口漂移处理
| 编号 | 短名 | 主责模块 | 关联模块 |