Codex
25 KiB
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 需求规格模板 |
| 上级规格 | PJ2026-010103 HWPOD服务 |
| 关联规格 | PJ2026-010101 HWPOD标准、PJ2026-010102 HWPOD工具、PJ2026-010104 AI网关、PJ2026-0103 HarnessRL、PJ2026-0104 客户端、PJ2026-010603 YAML运维、PJ2026-010604 公开入口、PJ2026-01060508 Web哨兵 |
| 规格治理索引 | 规格治理 |
本文采用 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-probeCLI 对 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-nodedirect-url 运行面、旧.device-podprofile 和历史gws_DESKTOP会话不保留支持或兼容；它们只能作为 legacy-retire 迁移输入和 drift 诊断证据。v0.3+ 受控 apply 必须停止或覆盖旧 direct-url runner，不能保留并行 fallback、alias、compat task 或旧 cloud URL 运行面。 - HWPOD spec 字段通用标准仍归 PJ2026-010101 HWPOD标准。
- HWPOD CLI 输出格式、交互体验和 validate/inspect 命令通用语义归 PJ2026-010102 HWPOD工具。
- 真实 adapter 执行、Keil、debug probe、UART、board-comm、ioProbe 和安全恢复归 PJ2026-010104 AI网关。
- CaseRun 评价、aggregate、artifact manifest 和 replay 归 PJ2026-0103 HarnessRL。
- Web 页面布局和用户入口通用体验归 PJ2026-0104 客户端。
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 解析图
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 图
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 数据流
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 时序图
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 验收时序图
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运维、HWPOD标准 |
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服务、HWPOD工具、公开入口 |
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网关、HWPOD服务 |
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源 | 客户端、HWPOD服务 |
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哨兵、公开入口、客户端 |
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、AI网关 |
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 代码引用 | 规格治理、YAML运维 |
本能力的代码和配置实现必须先引用本规格，再进入 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。