From 86cc666e6de89401763fb0854c2c1d35dfe6d7f1 Mon Sep 17 00:00:00 2001 From: Lyon <88232613+pikasTech@users.noreply.github.com> Date: Fri, 26 Jun 2026 09:43:08 +0800 Subject: [PATCH] docs: add 71freq hwpod preinstall spec (#931) Co-authored-by: Codex --- .../specs/PJ2026-010103-hwpod-service.md | 1 + ...26-01010305-71freq-hwpod-v03-preinstall.md | 281 ++++++++++++++++++ .../PJ2026-01060508-web-probe-sentinel.md | 8 +- 3 files changed, 287 insertions(+), 3 deletions(-) create mode 100644 project-management/PJ2026-01/specs/PJ2026-01010305-71freq-hwpod-v03-preinstall.md diff --git a/project-management/PJ2026-01/specs/PJ2026-010103-hwpod-service.md b/project-management/PJ2026-01/specs/PJ2026-010103-hwpod-service.md index 0eddc0d5..679cd961 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010103-hwpod-service.md +++ b/project-management/PJ2026-01/specs/PJ2026-010103-hwpod-service.md @@ -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. 原子需求 diff --git a/project-management/PJ2026-01/specs/PJ2026-01010305-71freq-hwpod-v03-preinstall.md b/project-management/PJ2026-01/specs/PJ2026-01010305-71freq-hwpod-v03-preinstall.md new file mode 100644 index 00000000..00d1b01d --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-01010305-71freq-hwpod-v03-preinstall.md @@ -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
targets.D601.lanes.v03] + Lane --> Workspace[D601 HWLAB workspace
/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
D601/v03] --> Pre[config/hwlab-hwpod-preinstalls.yaml
constart-71freq-c] + Pre --> Spec[hwlab-hwpod/constart-71freq-c.yaml] + Pre --> Meta[hwlab-hwpod/constart-71freq-c.meta.json] + Pre --> Cm[ConfigMap
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
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。 diff --git a/project-management/PJ2026-01/specs/PJ2026-01060508-web-probe-sentinel.md b/project-management/PJ2026-01/specs/PJ2026-01060508-web-probe-sentinel.md index ba7f85cb..9fc2a7b8 100644 --- a/project-management/PJ2026-01/specs/PJ2026-01060508-web-probe-sentinel.md +++ b/project-management/PJ2026-01/specs/PJ2026-01060508-web-probe-sentinel.md @@ -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` 命令面，再由哨兵调用。