From c57b5823e3cd59a99fedb913b46e211050c84338 Mon Sep 17 00:00:00 2001 From: pikastech Date: Tue, 21 Jul 2026 01:57:10 +0200 Subject: [PATCH] =?UTF-8?q?spec(hwpod):=20=E5=AE=9A=E4=B9=89=20runtime=20s?= =?UTF-8?q?pec=20CRUD=20=E4=B8=8E=E5=86=85=E7=BD=AE=E5=86=BB=E7=BB=93?= =?UTF-8?q?=E5=90=88=E5=90=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../specs/PJ2026-010102-hwpod-tools.md | 17 +++++++++--- .../specs/PJ2026-010103-hwpod-service.md | 26 ++++++++++++++++--- ...26-01010305-71freq-hwpod-v03-preinstall.md | 5 ++++ 3 files changed, 42 insertions(+), 6 deletions(-) diff --git a/project-management/PJ2026-01/specs/PJ2026-010102-hwpod-tools.md b/project-management/PJ2026-01/specs/PJ2026-010102-hwpod-tools.md index 8b45db00..c774c3af 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010102-hwpod-tools.md +++ b/project-management/PJ2026-01/specs/PJ2026-010102-hwpod-tools.md @@ -38,7 +38,7 @@ HWPOD工具负责把 HWPOD 标准和服务能力暴露为用户、Agent 和 Case ### 2.2 范围内 -- HWPOD spec 新建、修改、validate、inspect 和资源摘要输出。 +- HWPOD spec 新建、读取、列表、修改、删除、validate、inspect 和资源摘要输出。 - build、download、reset、UART、filesystem、board-comm、ioProbe、CANopen SDO 和频率/电流类硬件动作入口。 - HWPOD runtime API、服务端 authority 和本地 workspace 之间的目标解析。 - 命令返回码、结构化输出、错误分类、read-only 诊断和写操作前置校验。 @@ -80,7 +80,7 @@ HWPOD工具负责把 HWPOD 标准和服务能力暴露为用户、Agent 和 Case | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | | --- | --- | --- | --- | --- | --- | -| PJ2026-01010201 | Spec工具 | 本规格 6.1 | spec 新建、修改、validate、inspect 和摘要输出 | HWPOD标准 | HWPOD服务、客户端 | +| PJ2026-01010201 | Spec工具 | 本规格 6.1 | spec CRUD、validate、inspect 和摘要输出 | HWPOD标准 | HWPOD服务、客户端 | | PJ2026-01010202 | 执行动作 | 本规格 6.2 | build、download、reset、UART、filesystem 和通用硬件动作入口 | HWPOD标准、HWPOD服务 | Agent编排、CaseRun | | PJ2026-01010203 | 观测工具 | 本规格 6.3 | board-comm、ioProbe、CANopen SDO、频率和电流读写入口 | AI网关、HWPOD服务 | HarnessRL、Agent编排 | | PJ2026-01010204 | 诊断输出 | 本规格 6.4 | 结构化结果、返回码、错误分类和目标摘要 | HWPOD标准、HWPOD服务、AI网关 | 客户端、CaseRun | @@ -93,10 +93,21 @@ HWPOD工具负责把 HWPOD 标准和服务能力暴露为用户、Agent 和 Case | --- | --- | --- | --- | | HWPOD-TOOL-REQ-001 | Spec工具 | PJ2026-01010201 Spec工具 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)、[PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) | -HWPOD工具应提供 spec 新建、修改、validate 和 inspect 能力，使硬件资源身份、能力声明和绑定关系能在执行前被用户和自动化任务检查。 +HWPOD工具应提供 spec 新建、读取、列表、修改、删除、validate 和 inspect 能力， +使硬件资源身份、能力声明和绑定关系能在执行前被用户和自动化任务检查。 Spec 工具必须以 HWPOD 标准为准输出校验结果。服务端 registry 可以提供 authority 摘要，但工具不得用服务端缺省值静默补齐未声明的危险写操作能力。 +Spec CRUD 必须在 L0 与 L1 使用同一 repository 合同： + +- L0 由 `hwpod spec list|get|create|update|delete --local` 直接调用 native function； +- L1 由同一命令加 `--over-api` 调用 owning YAML 固定端口上的 HWPOD API； +- create 和 update 接收完整 spec document，并在写入前执行与 validate 相同的校验； +- list 默认返回有界摘要，get 返回单个完整 document； +- create、update 和 delete 必须输出 authority、mutable、frozen、hwpodId 和 mutation； +- YAML-first 内置 spec 的 update 和 delete 必须返回 `hwpod_spec_frozen`，不得复制为 runtime spec、写入覆盖层或修改 owning YAML； +- runtime spec 与内置 spec 同名时，create 必须返回 `hwpod_spec_frozen`，不得形成遮蔽或优先级覆盖。 + ### 6.2 HWPOD-TOOL-REQ-002 执行动作入口 | 编号 | 短名 | 主责模块 | 关联模块 | 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 ddca73ed..4af93632 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010103-hwpod-service.md +++ b/project-management/PJ2026-01/specs/PJ2026-010103-hwpod-service.md @@ -68,7 +68,7 @@ HWPOD服务负责服务端资源注册、健康、租约、占用释放、权限 ### 2.2 范围内 -- HWPOD registry、资源注册、spec 摘要、authority 和版本来源。 +- HWPOD registry、资源注册、runtime spec CRUD、spec 摘要、authority 和版本来源。 - HWPOD node 心跳接入、健康状态、可用性、能力摘要和路由状态。 - 租约、占用、释放、冲突处理、超时释放和写操作保护。 - 工具/API 请求接收、目标解析、节点路由、超时和错误分类。 @@ -129,6 +129,20 @@ HWPOD服务应维护 HWPOD registry，使已声明资源、spec 摘要、authori Registry 必须以 HWPOD 标准解释资源事实。缺失 HWPOD spec 的真实设备不能被服务端当作可写资源暴露；客户端可以展示不可用或待配置状态，但不能把临时端点当作资源真相。 +Registry 必须区分两种 authority： + +- `yaml-first-builtin` 来自 owning YAML 解析后注入的内置 spec，`mutable=false`、`frozen=true`； +- `runtime` 来自 HWPOD 服务状态目录，`mutable=true`、`frozen=false`，重启后继续可读。 + +Runtime CRUD 只能修改 `runtime` authority： + +- create 在 hwpodId 不存在时原子写入 runtime state； +- get 和 list 合并返回内置与 runtime spec，并保留 authority、mutable 和 frozen； +- update 只能完整替换已有 runtime spec； +- delete 只能删除已有 runtime spec； +- 内置 spec 的同名 create、update 和 delete 均返回 `hwpod_spec_frozen`； +- runtime spec 不得遮蔽、覆盖、复制或回写 YAML-first 内置 spec。 + ### 6.2 HWPOD-SVC-REQ-002 租约与占用 | 编号 | 短名 | 主责模块 | 关联模块 | @@ -206,7 +220,7 @@ flowchart LR - L0 必须能在不启动 API、worker、Temporal、Web 或 Kubernetes workload 的情况下，直接验证 spec 解析、topology 投影、workflow 输入和错误分类。 - L1 必须能按 owning YAML 独立启动 API、worker 和 Web，并用同一 HWPOD API 合同完成健康、spec、topology、operation 和 workflow smoke。 -- L1 Web 的首选入口为 owning YAML 声明的 HTTPS origin；公共入口不可用时，只能使用同一 YAML 声明的固定公网 HTTP 降级入口。 +- L1 API 与 Web 验收使用 owning YAML 声明的 native host 和固定端口；公网域名、TLS、public-edge、CI/CD 和 Kubernetes 不进入 L1 完成条件。 - L1 API、worker 和 Web 必须分别暴露健康/就绪检查；worker 不得创建公网业务入口。 - L1 Web 必须支持 HWPOD 资源列表、节点状态、operation 状态和明确 blocker 展示，且页面刷新后仍通过 API 恢复同一投影。 @@ -214,6 +228,10 @@ flowchart LR - `GET /health/live` 和 `GET /health/ready`：分别返回进程存活和 HWPOD/Temporal 依赖就绪状态。 - `GET /v1/hwpod/specs`：返回有界 HWPOD spec 摘要和可用性。 +- `GET /v1/hwpod/specs/{hwpodId}`：返回单个完整 spec document 与 authority。 +- `POST /v1/hwpod/specs`：创建 runtime spec。 +- `PUT /v1/hwpod/specs/{hwpodId}`：完整替换 runtime spec。 +- `DELETE /v1/hwpod/specs/{hwpodId}`：删除 runtime spec。 - `GET /v1/hwpod/topology`：返回 node、HWPOD、能力、占用、最近 operation 和 blocker 投影。 - `POST /v1/hwpod/operations`：提交带有 `operationId`、`hwpodId`、`nodeId`、调用方和租约摘要的 workflow。 - `GET /v1/hwpod/operations/{operationId}`：读取同一 operation 的 durable 状态和结果摘要。 @@ -222,7 +240,9 @@ flowchart LR ### 7.4 验收契约 -- L0：spec、topology、workflow contract 和 typed error 测试通过；默认路径不产生外部 mutation。 +- L0：spec、topology、workflow contract 和 typed error 测试通过；runtime CRUD 只修改 disposable state，内置 spec mutation 返回 `hwpod_spec_frozen`。 +- L1：通过 native API 完成 runtime spec create、list、get、update、delete，并证明 API 重启后 create/update 结果仍可读取。 +- L1：对 YAML-first 内置 spec 的同名 create、update 和 delete 均返回 `hwpod_spec_frozen`，内置 document 指纹保持不变。 - L1：API、worker、Web 可分别重启；worker 重启后未完成 workflow 可继续；Web 通过固定入口完成首屏、资源列表和 operation 状态交互。 - L1：D601 节点注册后，HWPOD topology 同时显示 node online、spec available 和 capability match；节点断开后显示 node offline，不得伪造硬件成功。 - L1：Cloud API 代理、独立 HWPOD API 和 CLI 对同一 operation 返回相同的 operation identity、状态和 blocker code。 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 index 8799b135..54aa2319 100644 --- 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 @@ -224,6 +224,11 @@ 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。 +YAML-first 预装 spec 在所有运行等级都必须标记为 `yaml-first-builtin`、 +`mutable=false` 和 `frozen=true`。Runtime spec CRUD 不得修改、删除、遮蔽、复制或 +回写该对象；同名 create、update 和 delete 必须返回 `hwpod_spec_frozen`，并保留 +owning configRef 与变更前 document 指纹。 + ### 6.3 HWPOD-PRE-REQ-003 D601 Windows v0.3+ 出站托管 | 编号 | 短名 | 主责模块 | 关联模块 |