docs: add 71freq hwpod preinstall spec (#931)

Co-authored-by: Codex <codex@noreply.local>
2026-06-26 09:43:08 +08:00
parent 078bc61b0a
commit 86cc666e6d
3 changed files with 287 additions and 3 deletions
@@ -84,6 +84,7 @@ HWPOD服务负责服务端资源注册、健康、租约、占用释放、权限
 | PJ2026-01010302 | 租约占用 | 本规格 6.2 | 租约、占用、释放、冲突处理和写操作保护 | 用户管理、资源注册 | Agent编排、CaseRun |
 | PJ2026-01010303 | 节点路由 | 本规格 6.3 | 请求接收、目标解析、node 路由、超时和错误分类 | AI网关、租约占用 | HWPOD工具、HarnessRL |
 | PJ2026-01010304 | 结果归属 | 本规格 6.4 | operation result 归属、查询和摘要交接 | 节点路由、Agent上下文 | HarnessRL、客户端、用户管理 |
+| PJ2026-01010305 | 71FREQ预装 | [PJ2026-01010305 71FREQ预装](PJ2026-01010305-71freq-hwpod-v03-preinstall.md) | D601/v03 71-FREQ preinstalled HWPOD spec、运行发现、MDTODO source 和验收切片 | HWPOD标准、YAML运维、AI网关 | HWPOD工具、HarnessRL、客户端 |

 ## 6. 原子需求

@@ -0,0 +1,281 @@
+# PJ2026-01010305 71FREQ预装
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-01010305 71FREQ预装需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-01010305 |
+| 短名 | 71FREQ预装 |
+| 层级 | L3 子课题 |
+| 状态 | 已生效 |
+| 实现引用版本 | draft-2026-06-26-71freq-v03-hwpod-preinstall |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) |
+| 关联规格 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)、[PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md)、[PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)、[PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md)、[PJ2026-0104 客户端](PJ2026-0104-client.md)、[PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md)、[PJ2026-010604 公开入口](PJ2026-010604-public-entry.md)、[PJ2026-01060508 Web哨兵](PJ2026-01060508-web-probe-sentinel.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 D601 v0.3 71-FREQ HWPOD 预装挂载、网关出站、MDTODO 工作区源和 web-probe 验收切片的稳定边界。
+
+本规格范围内新增或修改的源码文件必须在文件头部标注 `SPEC: PJ2026-01010305 71FREQ预装 draft-2026-06-26-71freq-v03-hwpod-preinstall`，并用一句话说明文件职责。纯 YAML/config、锁文件、生成产物和无法承载注释头的二进制产物不要求加头部，但对应解析器、渲染器或 CLI 入口必须能追溯到本规格。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+71FREQ预装负责把 D601 v0.3 上已存在的 71-FREQ 项目资源声明为 YAML-first HWPOD 预装资源，使 HWLAB Cloud API、HWPOD 工具、CaseRun、MDTODO 项目管理页面和 web-probe 都通过同一套受控配置发现 `constart-71freq-c`，而不是依赖旧 v0.2 direct-url、D601 Windows 本地文件、一次性脚本或代码硬编码。
+
+本规格的目标状态是：UniDesk YAML 声明 D601/v03 node/lane、preinstalled HWPOD spec、project-management MDTODO source、public/API origin 和必要 Secret sourceRef；HWLAB runtime 只读取挂载到运行面的 spec registry 与 project-management source config；Windows gateway 只按声明的 outbound profile 主动轮询云端命令；CaseRun、MDTODO 和 web-probe 验收只访问 public API 或同源 Web/API，不直连本地文件或私有调试通道。
+
+### 2.2 范围内
+
+- D601 v0.3 node/lane、workspace、namespace、public URL 和 target 解析与 preinstall configRef 关系。
+- `constart-71freq-c` 的 preinstalled HWPOD spec、metadata sidecar、ConfigMap/volume/env 挂载和 Cloud API discovery。
+- 71-FREQ Windows gateway outbound profile、session/resource/capability 绑定和 poll/result 状态可见性。
+- Project-management MDTODO source 通过 HWPOD workspace ops 读取 `F:\Work\ConStart\docs\MDTODO`，不新增第二套文件读取器。
+- 顶层 `web-probe` CLI 对 HWPOD/MDTODO/Web 原入口的 observe、command、collect 和 analyze 验收。
+- CaseRun build、download、UART/ioProbe smoke 的最小闭环和 41 相关未决项的非阻塞边界。
+- Secret 与非 Secret 配置的 sourceRef、targetKey、fingerprint 和 redacted 输出边界。
+
+### 2.3 范围外
+
+- 旧 v0.2 `hwpod-node` direct-url 运行面、旧 `.device-pod` profile 和历史 `gws_DESKTOP` 会话不得成为 v0.3 runtime truth；它们只可作为迁移输入或对照证据。
+- HWPOD spec 字段通用标准仍归 [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)。
+- HWPOD CLI 输出格式、交互体验和 validate/inspect 命令通用语义归 [PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md)。
+- 真实 adapter 执行、Keil、debug probe、UART、board-comm、ioProbe 和安全恢复归 [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)。
+- CaseRun 评价、aggregate、artifact manifest 和 replay 归 [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md)。
+- Web 页面布局和用户入口通用体验归 [PJ2026-0104 客户端](PJ2026-0104-client.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| preinstalled HWPOD spec | 由 UniDesk YAML 声明并以 ConfigMap/volume 形式挂载到 HWLAB runtime 的 HWPOD spec，不随 cloud-api 镜像硬编码。 |
+| preinstall configRef | node/lane YAML 指向 HWPOD preinstall owning YAML 的引用，负责把目标、spec、metadata、mount、env 和 rollout 关联起来。 |
+| `constart-71freq-c` | D601 v0.3 71-FREQ 预装 HWPOD 的稳定资源 id；该 id 是 YAML 声明事实，不是代码默认值。 |
+| outbound gateway profile | Windows gateway 主动连接云端领取命令的运行 profile，包含 gatewayId、sessionId、resourceId、capabilityId、cloudUrl 和本地执行能力绑定。 |
+| MDTODO source | project-management 服务中的项目管理 source，使用 `sourceKind=hwpod-workspace` 经 HWPOD workspace ops 读取工作区内 Markdown todo 文件。 |
+| `readMdtodo` command | web-probe observe command 类型，用 public Web/API 或同源项目管理 API 触发 MDTODO source/files/tasks 读取和摘要采样。 |
+| configRef graph | 由 YAML path、object path、presence、fingerprint、target 和缺失字段组成的配置引用图，默认输出不得展开 Secret 或完整 Markdown。 |
+| selected origin | 由 D601/v03 YAML 声明的 Web/API origin；默认应是 public origin，只有 YAML 显式声明时才可用于 internal validation origin。 |
+
+## 4. 系统边界和接口
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | HWPOD工具、HarnessRL CaseRun、Project-management Web/API、web-probe、平台管理员和 D601 Windows operator。 |
+| 外部输入 | D601/v03 node/lane 选择、preinstall configRefs、HWPOD spec YAML、metadata sidecar、gateway outbound profile、MDTODO source config、Secret sourceRef、CaseRun case 和 web-probe command。 |
+| 受控资源 | cloud-api HWPOD registry、preinstalled spec ConfigMap/volume/env、project-management source registry、Windows gateway session/resource/capability、CaseRun operation result 和 observe artifacts。 |
+| 外部输出 | `/v1/hwpod/specs` 资源列表、`hwpod-ctl spec validate/inspect` 结果、gateway poll/result 摘要、MDTODO sources/files/tasks、web-probe collect/analyze report 和 CaseRun smoke 结果。 |
+| 用户接口 | HWLAB public Web/API、顶层 `bun scripts/cli.ts web-probe ...`、HWPOD 工具 CLI、project-management MDTODO 页面和 CaseRun CLI/Web 入口。 |
+| 系统边界 | 本规格只定义 D601/v03 71-FREQ 预装切片如何从 YAML 进入运行面并被原入口验证；不把运行面观测、Windows 本地文件或一次性脚本反向变成配置真相。 |
+
+### 4.1 Secret 与非 Secret 配置边界
+
+| 配置类别 | 示例 | 归属 | 输出边界 |
+| --- | --- | --- | --- |
+| 非 Secret 目标事实 | nodeId、laneId、namespace、hwpodId、workspaceRootRef、projectRoot、Keil project、target、probe UID、UART、board-comm endpoint、ioProbe id、ConfigMap 和 mount path | UniDesk/HWLAB owning YAML | 可输出 YAML path、presence、摘要 hash、fingerprint、目标 id 和缺失字段；不得在代码中硬编码为 fallback。 |
+| Secret 或敏感运行凭据 | API key、maintenance token、JWT/encryption key、gateway auth token、database URL、provider credential | YAML sourceRef/targetKey 或外部 Secret source | 只输出对象名、key 名、sourceRef、presence、字节数和 fingerprint；不得打印完整值、base64 payload、DSN 或可复制 token。 |
+| 迁移输入 | 旧 `.device-pod` profile、旧 v0.2 direct-url、D601 Windows 本地 profile | 一次性调查/迁移证据 | 不作为 runtime registry authority；只允许转换为 YAML 声明后进入运行面。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 内部模块 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-0101030501 | 配置真相 | 本规格 6.1 | D601/v03 target、preinstall、MDTODO source、gateway profile 的 YAML owning/ref 图 | YAML运维、HWPOD标准 | HWPOD discovery、PM source、gateway |
+| PJ2026-0101030502 | 运行发现 | 本规格 6.2 | ConfigMap/volume/env 挂载、cloud-api discovery、spec validate/inspect | 配置真相、HWPOD服务 | HWPOD工具、客户端、CaseRun |
+| PJ2026-0101030503 | 网关出站 | 本规格 6.3 | D601 Windows gateway outbound poll、resource/capability 和 result 状态 | AI网关、运行发现 | HWPOD路由、CaseRun |
+| PJ2026-0101030504 | MDTODO源 | 本规格 6.4 | `hwpod-workspace` source、workspace ops、source/files/tasks 投影 | 运行发现、客户端 | 项目管理页面、web-probe |
+| PJ2026-0101030505 | web-probe验收 | 本规格 6.5 | 顶层 `web-probe` observe/command/collect/analyze、`readMdtodo` 和单实现迁移 | Web哨兵、公开入口 | P4 原入口验收 |
+| PJ2026-0101030506 | CaseRun smoke | 本规格 6.6 | build/download/UART/ioProbe smoke 与 41 相关未决边界 | HarnessRL、AI网关 | 硬件闭环验收 |
+| PJ2026-0101030507 | 代码引用 | 本规格 6.7 | SPEC-first 文件头、配置追溯和 P0/P1+ 阶段边界 | 规格治理 | PR 审计 |
+
+### 5.1 D601 v0.3 target/lane 解析图
+
+```mermaid
+flowchart TD
+  Issue[执行入口声明 D601 + v03 + 71-FREQ] --> Lane[config/hwlab-node-lanes.yaml<br/>targets.D601.lanes.v03]
+  Lane --> Workspace[D601 HWLAB workspace<br/>/home/ubuntu/workspace/hwlab-v03]
+  Lane --> Namespace[HWLAB v0.3 namespace]
+  Lane --> Public[public web/api origin]
+  Lane --> HwpodRef[configRef: hwpod preinstalls]
+  Lane --> PmRef[configRef: project-management MDTODO source]
+  Lane --> GatewayRef[configRef: gateway outbound profile]
+  HwpodRef --> Renderer[UniDesk YAML-first renderer/plan]
+  PmRef --> Renderer
+  GatewayRef --> Renderer
+  Renderer --> Runtime[HWLAB runtime manifests and Windows profile]
+```
+
+目标解析要求：issue、CLI 或 YAML 已明确 D601/v03 时，解析器只校验该目标并输出来源路径；不得回退到全局 default、D601 legacy、G14、v0.2 或旧 direct-url。
+
+### 5.2 YAML configRef 图
+
+```mermaid
+flowchart LR
+  Lane[config/hwlab-node-lanes.yaml<br/>D601/v03] --> Pre[config/hwlab-hwpod-preinstalls.yaml<br/>constart-71freq-c]
+  Pre --> Spec[hwlab-hwpod/constart-71freq-c.yaml]
+  Pre --> Meta[hwlab-hwpod/constart-71freq-c.meta.json]
+  Pre --> Cm[ConfigMap<br/>hwlab-v03-hwpod-preinstalled-specs]
+  Pre --> Mount[/etc/hwlab/hwpod-specs readonly]
+  Pre --> Env[HWLAB_HWPOD_SPEC_REGISTRY_DIRS]
+  Lane --> PM[hwlab-project-management/constart-71freq-mdtodo.yaml]
+  PM --> Source[sourceId constart-71freq<br/>sourceKind hwpod-workspace]
+  PM --> Ops[HWLAB_PROJECT_MANAGEMENT_HWPOD_NODE_OPS_URL]
+  Lane --> GW[hwlab-gateway/constart-71freq-d601-v03.yaml]
+  GW --> SecretRefs[gateway/API Secret sourceRefs]
+```
+
+configRef 图要求 plan/status 默认展示引用链、presence、摘要 hash、target id、缺失字段和下一步命令；完整 YAML、Markdown 正文和 Secret 值只能在显式 raw/full 且满足脱敏边界时读取。
+
+### 5.3 Cloud API HWPOD spec discovery 数据流
+
+```mermaid
+flowchart TD
+  YAML[UniDesk HWPOD preinstall YAML] --> Render[render ConfigMap + env + volume]
+  Render --> Pod[cloud-api Deployment]
+  Pod --> Dir[/etc/hwlab/hwpod-specs]
+  Dir --> Discovery[internal cloud hwpod spec discovery]
+  Discovery --> Registry[HWPOD registry/read model]
+  Registry --> Api[/v1/hwpod/specs]
+  Registry --> Tool[hwpod-ctl spec validate/inspect]
+  Api --> Web[Cloud Web / clients]
+  Tool --> Evidence[operator validation summary]
+```
+
+运行发现要求 `constart-71freq-c` 的 runtime authority 来自挂载目录和 discovery 结果。cloud-api 代码不得把 71-FREQ 路径、COM 口、probe UID、board-comm IP、HWPOD id 或旧 node id 写成隐藏默认值。
+
+### 5.4 Windows gateway outbound poll 时序图
+
+```mermaid
+sequenceDiagram
+  participant Svc as HWLAB Cloud HWPOD service
+  participant GW as D601 Windows gateway
+  participant Keil as Keil/debug probe/UART
+  participant Board as 71-FREQ board and probes
+
+  GW->>Svc: register gatewayId/sessionId/resourceId/capabilityId
+  Svc-->>GW: poll lease / command / heartbeat interval
+  GW->>Svc: poll next command
+  Svc-->>GW: command request with requestId and adapter args
+  GW->>Keil: execute build/download/UART/diagnostic
+  Keil->>Board: flash/reset/read/probe
+  Board-->>Keil: raw hardware facts
+  Keil-->>GW: adapter result
+  GW-->>Svc: result requestId/status/facts/log refs
+  Svc-->>GW: ack and next poll policy
+```
+
+gateway 必须是可长期运行的 detached/service/scheduled-task 或等价托管进程。一次性 `cmd start`、交互式 PowerShell 或旧 v0.2 node 进程不能作为完成状态。
+
+### 5.5 CaseRun build/download/ioProbe 验收时序图
+
+```mermaid
+sequenceDiagram
+  participant U as Web/CLI/web-probe
+  participant HR as HarnessRL CaseRun
+  participant HP as HWPOD service
+  participant GW as D601 gateway
+  participant WS as ConStart workspace
+  participant HW as 71-FREQ hardware/ioProbe
+
+  U->>HR: submit smoke case with hwpodId constart-71freq-c
+  HR->>HP: acquire lease and route build/download/ioProbe ops
+  HP->>GW: dispatch workspace/build/download command
+  GW->>WS: read project and run Keil target
+  GW->>HW: download/reset/UART/ioProbe sampling
+  HW-->>GW: board facts and probe sample
+  GW-->>HP: operation result refs
+  HP-->>HR: route/result summary
+  HR-->>U: run stage, artifact refs and blocker/terminal status
+```
+
+CaseRun smoke 只要求证明 71-FREQ 最小硬件链路能通过 HWPOD 服务 route、gateway 执行和 HarnessRL result 引用闭环。41 相关外设或上游 issue 未完成时必须作为非阻塞边界输出，不能把其失败误判为 71-FREQ preinstall 失败。
+
+## 6. 原子需求
+
+### 6.1 HWPOD-PRE-REQ-001 YAML-first 预装配置真相
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-PRE-REQ-001 | 配置真相 | PJ2026-0101030501 配置真相 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[HWPOD标准](PJ2026-010101-hwpod-standard.md) |
+
+71-FREQ 预装配置必须由 UniDesk YAML 承载，并通过 configRef 串联 node/lane、HWPOD spec、metadata、project-management source、gateway profile、public/API origin 和 Secret sourceRef。代码只负责解析、校验和渲染，不得内置 `D601`、`v03`、`constart-71freq-c`、`F:\Work\ConStart`、Keil 路径、COM 口、probe UID、board-comm IP、ioProbe id、旧 cloud URL 或 gateway/session id 作为 fallback。
+
+HWPOD preinstall owning YAML 至少应声明 hwpodId、sourceRef、metadataRef、targetDevice、nodeBinding、workspaceRootRef、projectRoot、toolchain、debugProbe、uart、boardComm endpoints、ioProbe、ConfigMap 名称、mount path、environment key 和 rollout target。MDTODO source owning YAML 至少应声明 sourceId、sourceKind、projectId、hwpodId、nodeId、workspaceRootRef、mdtodoRootRef、focus files 和 hwpod node ops URL configRef。Gateway profile owning YAML 至少应声明 cloudUrl、gatewayId、sessionId、resourceId、capabilityId、secretRefs 和托管运行方式。
+
+### 6.2 HWPOD-PRE-REQ-002 Runtime discovery 与 HWPOD工具验证
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-PRE-REQ-002 | 运行发现 | PJ2026-0101030502 运行发现 | [HWPOD服务](PJ2026-010103-hwpod-service.md)、[HWPOD工具](PJ2026-010102-hwpod-tools.md)、[公开入口](PJ2026-010604-public-entry.md) |
+
+HWLAB v0.3 cloud-api 必须从 runtime 挂载的 preinstalled HWPOD spec registry 发现 `constart-71freq-c`，并通过 `/v1/hwpod/specs`、`hwpod-ctl spec validate --hwpod-id constart-71freq-c` 和 `hwpod-ctl inspect` 等入口返回可审计摘要。
+
+cloud-api Pod manifest 必须包含只读 mount `/etc/hwlab/hwpod-specs` 或 YAML 声明的等价 mount，并设置 `HWLAB_HWPOD_SPEC_REGISTRY_DIRS` 指向该目录。spec discovery 可以继续支持 workspace-local `.hwlab/hwpod-spec.yaml` 和 registry dirs，但 D601/v03 71-FREQ 的 completion authority 必须是运行面挂载的 YAML preinstall，不是镜像内文件、旧 `.device-pod` profile 或旧 direct cloud URL。
+
+### 6.3 HWPOD-PRE-REQ-003 D601 Windows gateway 出站托管
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-PRE-REQ-003 | 网关出站 | PJ2026-0101030503 网关出站 | [AI网关](PJ2026-010104-ai-gateway.md)、[HWPOD服务](PJ2026-010103-hwpod-service.md) |
+
+D601 Windows gateway 必须以 v0.3 outbound profile 长期运行，主动连接 YAML 声明的 HWLAB Cloud URL，注册 gateway/session/resource/capability，并持续 poll 命令、回传 result、暴露最近 poll/result 摘要和托管状态。
+
+gateway 配置和状态输出应能证明：它绑定 `constart-71freq-c` 对应 resource、能力覆盖 workspace/Keil/debug/UART/diagnostic/ioProbe 所需动作、服务托管方式不是交互式临时命令、最近 poll 正常或失败原因可见。Secret 只通过 sourceRef 注入；日志、status 和 issue evidence 不得打印完整 token、API key 或 DSN。
+
+### 6.4 HWPOD-PRE-REQ-004 MDTODO source 经 HWPOD workspace ops 解耦读取
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-PRE-REQ-004 | MDTODO源 | PJ2026-0101030504 MDTODO源 | [客户端](PJ2026-0104-client.md)、[HWPOD服务](PJ2026-010103-hwpod-service.md) |
+
+Project-management MDTODO source 必须使用 `sourceKind=hwpod-workspace` 和公共 HWPOD workspace ops 读取 71-FREQ 工作区内的 Markdown todo 文件。MDTODO 页面、sources/files/tasks API 和后续 web-probe 验收只通过 sourceId、projectId、hwpodId、nodeId 与 HWPOD 关联；不得把 Workbench 组件嵌入 MDTODO，也不得让 MDTODO 服务直接读取 D601 文件系统、SSH、Windows share、旧 submodule 路径或第二套文件 reader。
+
+71-FREQ MDTODO 的实际 authority 是 `F:\Work\ConStart\docs\MDTODO`。source config 应能选择 focus files，例如 `20260419_频率判断.md`、`20260609_频率判断_用户反馈.md` 和 `details/`，并在 reindex 后通过 public API 返回 source、file 和 task 摘要。Markdown 正文默认不进入 issue evidence 或 CLI 普通输出。
+
+### 6.5 HWPOD-PRE-REQ-005 顶层 web-probe 与 readMdtodo 验收
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-PRE-REQ-005 | web-probe | PJ2026-0101030505 web-probe验收 | [Web哨兵](PJ2026-01060508-web-probe-sentinel.md)、[公开入口](PJ2026-010604-public-entry.md)、[客户端](PJ2026-0104-client.md) |
+
+UniDesk CLI 必须提供顶层 `bun scripts/cli.ts web-probe ...` 作为 web-probe 的唯一执行入口。旧 `bun scripts/cli.ts hwlab nodes web-probe ...` 不得继续作为 alias 或第二执行路径，只能 fail-fast 输出迁移错误和顶层命令提示。observe runner、command parser、collect/analyze 和 canonical command renderer 必须共享同一实现，禁止出现第二套 runner/parser/analyzer。
+
+`web-probe observe command --type readMdtodo` 必须通过 public HWLAB Web/API 或 YAML selected origin 的项目管理 API/page route 读取 MDTODO source、files 和 tasks。它应向 `control.jsonl` 记录 commandId、sourceId、path、taskTree 摘要、reindex/result summary、documentCount、taskCount 和 fingerprint，不 dump Markdown 正文，不通过 `trans`、`cat`、SSH 或私有 debug API 作为验收路径。`observe collect/analyze` 必须把 MDTODO file/task 摘要纳入报告，使 P4 可以用交互式 CLI 验收项目管理页面。
+
+### 6.6 HWPOD-PRE-REQ-006 CaseRun 与硬件 smoke 验收边界
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-PRE-REQ-006 | CaseRun smoke | PJ2026-0101030506 CaseRun smoke | [HarnessRL](PJ2026-0103-harness-rl.md)、[AI网关](PJ2026-010104-ai-gateway.md) |
+
+P4 原入口验收必须覆盖 HWPOD discovery、gateway echo 或等价 command、MDTODO source/files/tasks、web-probe `readMdtodo`、以及 71-FREQ 最小 CaseRun smoke。CaseRun smoke 至少应证明 workspace、Keil project/target、debug probe、download/reset、UART 或 ioProbe 中的关键路径通过 HWPOD 服务和 gateway route 被执行，并把 operation result 引用回 CaseRun stage 或 blocker。
+
+41 相关设备或外设链路未完成时，应作为明确的 out-of-scope/non-blocking blocker 记录在 CaseRun 或 issue evidence 中。不得因为 41 相关未决项阻塞 `constart-71freq-c` 的 HWPOD 预装、MDTODO 读取和最小 smoke 收口；也不得把 71-FREQ smoke 失败归咎于未声明的外部依赖而不返回结构化原因。
+
+### 6.7 HWPOD-PRE-REQ-007 SPEC-first 与代码引用
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-PRE-REQ-007 | 代码引用 | PJ2026-0101030507 代码引用 | [规格治理](spec-governance.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md) |
+
+本能力的代码和配置实现必须先引用本规格，再进入 P1+ 变更。新增或修改的 UniDesk CLI/parser/renderer、HWLAB discovery/project-management/gateway/web-probe 相关源码文件头部必须标注 `SPEC: PJ2026-01010305 71FREQ预装 draft-2026-06-26-71freq-v03-hwpod-preinstall`，并说明文件职责。
+
+如果后续执行改变稳定数据流、API、配置字段、gateway 轮询模式、MDTODO source 语义、web-probe command schema 或 CaseRun 验收边界，必须先更新本规格和关联规格，再更新执行 issue 与代码实现。配置数值、路径、endpoint 和 Secret sourceRef 的真实值以 owning YAML 为准；规格只定义归属、边界和必需字段。
+
+## 7. 过程控制
+
+本规格不承载执行证据、运行日志、trace、CaseRun registry 或长 Markdown 样本；这些证据保留在对应 GitHub 执行 issue、PR closeout、运行面 artifact 和受控 CLI 输出中。
+
+执行阶段固定为 P0 SPEC-first、P1 YAML-first preinstall config/render plan、P2 runtime discovery 与 MDTODO source、P3 D601 Windows gateway 托管、P4 HWPOD/MDTODO/web-probe/CaseRun 原入口验收。P0 未完成前，不得推进代码实现、部署、CI/CD、测试补充或运行面 closeout。
@@ -31,7 +31,7 @@

 ### 2.1 目的

-Web哨兵负责把已经用于 HWLAB Cloud Web 原入口验收的 `hwlab nodes web-probe observe start/status/command/collect/analyze` 能力服务化为 YAML-first 生产哨兵，使平台能够持续观察 HWLAB Web public origin、Workbench 多轮任务、Trace/final/timing 投影和发布后恢复状态。
+Web哨兵负责把已经用于 HWLAB Cloud Web 原入口验收的顶层 `web-probe observe start/status/command/collect/analyze` 能力服务化为 YAML-first 生产哨兵，使平台能够持续观察 HWLAB Web public origin、Workbench 多轮任务、Trace/final/timing 投影和发布后恢复状态。

 本规格的目标状态是：人工 CLI、常驻调度器、dashboard、maintenance API、CI/CD targetValidation 和后续 dry-run 都消费同一套 observe runner、control queue、artifact JSONL、`collect` 渲染和 `observe analyze` 报告。哨兵服务只负责编排、索引、展示和发布联动；它不得复制第二套 Playwright runner、DOM sampler、offline analyzer、finding classifier、Workbench 状态机或业务事实源。

@@ -84,7 +84,7 @@ Web哨兵必须遵循 UniDesk YAML-first ops。目标 node/lane、public origin
 | 外部输入 | YAML configRefs、Secret sourceRef presence、HWLAB Web public origin、scenario cadence、maintenance 操作、observe artifacts、analyze reports、GitOps/Argo 状态。 |
 | 受控资源 | Web哨兵 Deployment、Service、PVC、ServiceAccount、NetworkPolicy、ConfigMap、publicExposure、SQLite index、dashboard 和 Prometheus metrics。 |
 | 外部输出 | sentinel status、health、metrics、dashboard、run list、report summary、turn-summary、findings、trace-frame、maintenance 状态和 targetValidation 结果。 |
-| 用户接口 | `bun scripts/cli.ts hwlab nodes web-probe sentinel ...`、`https://monitor.pikapython.com` dashboard、CI/CD maintenance 调用和受控 GitOps/control-plane CLI。 |
+| 用户接口 | `bun scripts/cli.ts web-probe sentinel ...`、`https://monitor.pikapython.com` dashboard、CI/CD maintenance 调用和受控 GitOps/control-plane CLI。 |
 | 系统边界 | Web哨兵只生产运行监控和发布恢复证据；不定义业务成功，不写第二套 Workbench 状态，不直接修复 Web，不读取或打印 Secret/prompt/provider payload。 |

 ## 5. 内部分工与规格索引
@@ -294,7 +294,9 @@ sequenceDiagram
 | --- | --- | --- | --- |
 | OPS-SENTINEL-REQ-001 | Wrapper边界 | PJ2026-0106050801 Wrapper边界 | [Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[Web工作台](PJ2026-010401-web-workbench.md) |

-Web哨兵必须只编排现有 `hwlab nodes web-probe observe start/status/command/collect/analyze` 命令语义。常驻服务可以把这些 verb 包成稳定 adapter，但底层采样器、control queue、artifact schema、collect 渲染和 offline analyzer 必须与人工 CLI 共享同一实现或同一生成物。
+Web哨兵必须只编排现有顶层 `web-probe observe start/status/command/collect/analyze` 命令语义。常驻服务可以把这些 verb 包成稳定 adapter，但底层采样器、control queue、artifact schema、collect 渲染和 offline analyzer 必须与人工 CLI 共享同一实现或同一生成物。
+
+旧 `hwlab nodes web-probe` 路径不得作为 alias、delegate 或第二执行路径继续运行；它只能 fail-fast 输出迁移说明并指向顶层 `web-probe`。常驻服务、人工 CLI、CI/CD targetValidation 和后续 YAML 示例都必须指向同一顶层入口。

 实现不得新增第二套 Playwright runner、DOM sampler、network sampler、control command 协议、JSONL artifact schema、offline analyzer、finding classifier 或 Workbench 状态机。若服务化需要能力增强，必须先补到现有 `web-probe observe` 命令面，再由哨兵调用。