feat: manage D601 hwpod gateway from yaml (#995)
Co-authored-by: Codex <codex@noreply.local>
This commit is contained in:
Lyon
@@ -35,13 +35,13 @@
|
||||
|
||||
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，不直连本地文件或私有调试通道。
|
||||
本规格的目标状态是：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 gateway outbound profile、session/resource/capability 绑定和 poll/result 状态可见性。
|
||||
- 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 相关未决项的非阻塞边界。
|
||||
@@ -49,7 +49,7 @@
|
||||
|
||||
### 2.3 范围外
|
||||
|
||||
- 旧 v0.2 `hwpod-node` direct-url 运行面、旧 `.device-pod` profile 和历史 `gws_DESKTOP` 会话不得成为 v0.3 runtime truth；它们只可作为迁移输入或对照证据。
|
||||
- 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)。
|
||||
@@ -63,7 +63,7 @@
|
||||
| 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 和本地执行能力绑定。 |
|
||||
| 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。 |
|
||||
@@ -94,7 +94,7 @@
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 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-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网关 | 硬件闭环验收 |
|
||||
@@ -155,28 +155,27 @@ flowchart TD
|
||||
|
||||
运行发现要求 `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 时序图
|
||||
### 5.4 Windows outbound HWPOD node/gateway 时序图
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Svc as HWLAB Cloud HWPOD service
|
||||
participant GW as D601 Windows gateway
|
||||
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: 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->>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 poll policy
|
||||
Svc-->>GW: ack and next dispatch policy
|
||||
```
|
||||
|
||||
gateway 必须是可长期运行的 detached/service/scheduled-task 或等价托管进程。一次性 `cmd start`、交互式 PowerShell 或旧 v0.2 node 进程不能作为完成状态。
|
||||
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 验收时序图
|
||||
|
||||
@@ -212,7 +211,7 @@ CaseRun smoke 只要求证明 71-FREQ 最小硬件链路能通过 HWPOD 服务 r
|
||||
|
||||
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。Gateway profile owning YAML 至少应声明 cloudUrl、gatewayId、sessionId、resourceId、capabilityId、secretRefs 和托管运行方式。
|
||||
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。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工具验证
|
||||
|
||||
@@ -224,15 +223,17 @@ HWLAB v0.3 cloud-api 必须从 runtime 挂载的 preinstalled HWPOD spec registr
|
||||
|
||||
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 出站托管
|
||||
### 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 gateway 必须以 v0.3 outbound profile 长期运行，主动连接 YAML 声明的 HWLAB Cloud URL，注册 gateway/session/resource/capability，并持续 poll 命令、回传 result、暴露最近 poll/result 摘要和托管状态。
|
||||
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 所需动作、服务托管方式不是交互式临时命令、最近 poll 正常或失败原因可见。Secret 只通过 sourceRef 注入；日志、status 和 issue evidence 不得打印完整 token、API key 或 DSN。
|
||||
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 解耦读取
|
||||
|
||||
@@ -278,4 +279,4 @@ P4 原入口验收必须覆盖 HWPOD discovery、gateway echo 或等价 command
|
||||
|
||||
本规格不承载执行证据、运行日志、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。
|
||||
执行阶段固定为 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。
|
||||
|
||||
Reference in New Issue
Block a user