pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-01010305-71freq-hwpod-v03-preinstall.md

# 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；D601 Windows 运行面只按声明的 v0.3+ outbound HWPOD node/gateway 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 v0.3+ outbound HWPOD node/gateway profile、session/resource/capability 绑定和 dispatch/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` 会话不保留支持或兼容；它们只能作为 legacy-retire 迁移输入和 drift 诊断证据。v0.3+ 受控 apply 必须停止或覆盖旧 direct-url runner，不能保留并行 fallback、alias、compat task 或旧 cloud URL 运行面。
- 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 HWPOD node/gateway profile | Windows 运行面主动连接云端领取命令的 v0.3+ profile，包含 gatewayId/sessionId、resourceId、capabilityId、cloudUrl/nodeOps WebSocket URL 和本地执行能力绑定。 |
| 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、project-management HWPOD node-ops bearer、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 v0.3+ outbound HWPOD node/gateway、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]
  PM --> OpsAuth[HWLAB_PROJECT_MANAGEMENT_HWPOD_NODE_OPS_API_KEY secretRef]
  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 outbound HWPOD node/gateway 时序图

```mermaid
sequenceDiagram
  participant Svc as HWLAB Cloud HWPOD service
  participant GW as D601 Windows HWPOD node/gateway
  participant Keil as Keil/debug probe/UART
  participant Board as 71-FREQ board and probes

  GW->>Svc: connect/register via v0.3 cloud URL and nodeOps WebSocket
  Svc-->>GW: accepted nodeId/resource/capability and heartbeat policy
  Svc-->>GW: dispatch 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 dispatch policy
```

D601 Windows 运行面必须是可长期运行的 detached/service/scheduled-task 或等价托管进程，且启动命令必须由 v0.3+ YAML profile 渲染。一次性 `cmd start`、交互式 PowerShell、旧 v0.2 direct-url node 进程、并行 compat task 或旧 cloud URL 进程不能作为完成状态。

### 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。71-FREQ 的 boardComm endpoints 必须显式包含 `freq71` 和 `main41`，ioProbe 必须显式包含 `main41.ai0.current`，这些字段必须进入最终挂载给 cloud-api 的 `specDocument`，不能只停留在运维 YAML 的旁路摘要字段。MDTODO source owning YAML 至少应声明 sourceId、sourceKind、projectId、hwpodId、nodeId、workspaceRootRef、mdtodoRootRef、focus files、hwpod node ops URL configRef 和 HWPOD node-ops API key sourceRef；project-management Deployment 只能通过显式 env/SecretRef 注入该 bearer，不得匿名调用 cloud-api 管理 HWPOD route。Gateway profile owning YAML 至少应声明 cloudUrl、nodeOps websocketUrl、gatewayId、sessionId、resourceId、capabilityId、secretRefs、runtimeRoot、bunPath、taskName、periodicTaskName、runKeyName、start/status command、processPattern 和重连参数；代码不得为这些运行面事实提供隐藏默认。

### 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 inspect --hwpod-id constart-71freq-c --dry-run` 等入口返回可审计摘要。该摘要必须能证明 ConStart root、projectRoot、Keil project、debug probe UID、`freq71`、`main41` 和 `main41.ai0.current` 均来自 YAML-first spec authority。

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 v0.3+ 出站托管

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-PRE-REQ-003 | 网关出站 | PJ2026-0101030503 网关出站 | [AI网关](PJ2026-010104-ai-gateway.md)、[HWPOD服务](PJ2026-010103-hwpod-service.md) |

D601 Windows HWPOD node/gateway 必须以 v0.3+ outbound profile 长期运行，主动连接 YAML 声明的 HWLAB Cloud URL 或 nodeOps WebSocket URL，注册 nodeId/gateway/session/resource/capability，并持续接收命令、回传 result、暴露最近 dispatch/result 摘要和托管状态。

gateway 配置和状态输出应能证明：它绑定 `constart-71freq-c` 对应 resource、能力覆盖 workspace/Keil/debug/UART/diagnostic/ioProbe 所需动作、服务托管方式不是交互式临时命令、最近 dispatch 正常或失败原因可见。Secret 只通过 sourceRef 注入；日志、status 和 issue evidence 不得打印完整 token、API key 或 DSN。

v0.2 不再是兼容目标。受控 `apply` 必须从 YAML 生成 v0.3+ runner/env/status/install 文件并覆盖同名 legacy runner，停止仍连接旧 `http://74.48.78.17:19667` 或其他非 YAML cloud URL 的 `hwpod-node.ts connect` 进程，重建 scheduled task/HKCU Run 指向 v0.3+ runner。状态命令必须把旧 v0.2 process、旧 direct cloud URL、旧 `.device-pod` profile 和 compat task 判定为 legacy drift，而不是 fallback 或 degraded-but-compatible。

### 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。

当 project-management service 需要调用 cloud-api `/v1/hwpod-node-ops` 执行 workspace ops 时，必须使用 YAML 声明的 `HWLAB_PROJECT_MANAGEMENT_HWPOD_NODE_OPS_API_KEY` SecretRef 作为 bearer 认证，并继续在下游请求中保留服务来源标识。缺少该 SecretRef 或认证失败应作为 project-management source blocker 暴露，不能降级为匿名内部 route、旧 direct-url、SSH 读取或本地文件 fallback。

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。

CaseRun v0.3 的 runtime API authority 必须来自同源 public/API origin、YAML selected origin 或显式 v0.3 env/configRef。内置 case、CaseRun library 和 Web CaseRun worker 不得保留旧 v0.2 `http://74.48.78.17:19667`、`http://74.48.78.17:19666`、`runtime.apiUrl` fallback、direct-url alias 或 compat route；缺少 v0.3 runtime origin 时必须 fail-fast 返回结构化配置错误，而不是自动降级到 v0.2。

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 v0.3+ HWPOD node/gateway 托管、P4 HWPOD/MDTODO/web-probe/CaseRun 原入口验收。v0.2 支持和兼容路径不进入本规格完成态；发现旧 v0.2 runner 只作为 legacy drift 处理。P0 未完成前，不得推进代码实现、部署、CI/CD、测试补充或运行面 closeout。