spec(hwpod): 定义 runtime spec CRUD 与内置冻结合同

2026-07-21 01:57:10 +02:00
parent 1a796c3ff4
commit c57b5823e3
3 changed files with 42 additions and 6 deletions
@@ -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 执行动作入口

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -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。
@@ -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+ 出站托管

 | 编号 | 短名 | 主责模块 | 关联模块 |