Codex
126 lines
7.6 KiB
Markdown
126 lines
7.6 KiB
Markdown
# PJ2026-010103 HWPOD服务
|
||
|
||
## 修改历史
|
||
|
||
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|
||
| --- | --- | --- | --- |
|
||
|
||
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
|
||
|
||
## 正文
|
||
|
||
## PJ2026-010103 HWPOD服务需求规格
|
||
|
||
## 1. 文档控制
|
||
|
||
| 字段 | 内容 |
|
||
| --- | --- |
|
||
| 编号 | PJ2026-010103 |
|
||
| 短名 | HWPOD服务 |
|
||
| 层级 | L2 课题 |
|
||
| 状态 | 已生效 |
|
||
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
|
||
| 上级规格 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) |
|
||
| 规格治理索引 | [规格治理](spec-governance.md) |
|
||
|
||
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWPOD 服务的稳定使命、范围、术语、系统边界、内部分工和原子需求。
|
||
|
||
## 2. 目的和范围
|
||
|
||
### 2.1 目的
|
||
|
||
HWPOD服务负责服务端资源注册、健康、租约、占用释放、权限交接、请求接收、节点路由和结果归属，使 HWPOD 工具和上层任务能通过服务端 authority 访问真实硬件资源。
|
||
|
||
本课题的目标状态是：服务端只路由已声明、可用、已授权且租约一致的资源，并把每次操作结果归属到明确 HWPOD、node、租约和调用方。
|
||
|
||
### 2.2 范围内
|
||
|
||
- HWPOD registry、资源注册、spec 摘要、authority 和版本来源。
|
||
- HWPOD node 心跳接入、健康状态、可用性、能力摘要和路由状态。
|
||
- 租约、占用、释放、冲突处理、超时释放和写操作保护。
|
||
- 工具/API 请求接收、目标解析、节点路由、超时和错误分类。
|
||
- operation result 的归属、查询、摘要和对 HarnessRL/Agent编排/客户端的交接。
|
||
|
||
### 2.3 范围外
|
||
|
||
- HWPOD spec 字段和能力模型归 [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)。
|
||
- CLI 命令形态、工具输出和 workspace 内调用归 [PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md)。
|
||
- 节点侧适配器执行和原始硬件事实生产归 [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)。
|
||
- 用户身份、API key、额度和租户策略归 [用户管理](PJ2026-0105-user-management.md)。
|
||
|
||
## 3. 术语表
|
||
|
||
| 术语 | 定义 |
|
||
| --- | --- |
|
||
| registry | 服务端维护的 HWPOD 资源目录，包含身份、spec 摘要、状态和路由信息。 |
|
||
| authority | 对 HWPOD 资源事实具有当前解释权的服务端或配置来源。 |
|
||
| 租约 | 一次资源占用关系，约束调用方、HWPOD、操作类型、超时和释放。 |
|
||
| 路由 | 服务端把 HWPOD 操作请求转发到正确 HWPOD node 或 AI 网关的过程。 |
|
||
| operation result | 服务端接收并归属的一次硬件操作结果。 |
|
||
|
||
## 4. 系统边界和接口
|
||
|
||
本规格把 HWPOD服务作为硬件池的服务端资源管理层看待；本章只描述输入、输出和责任边界。
|
||
|
||
| 边界项 | 内容 |
|
||
| --- | --- |
|
||
| 外部使用者 | HWPOD工具、Agent编排、HarnessRL、客户端、用户管理、平台管理员。 |
|
||
| 外部输入 | HWPOD spec、node 心跳、能力上报、租约请求、操作请求、用户/任务上下文、释放请求和节点结果。 |
|
||
| 受控资源 | registry、资源状态、租约、路由表、操作请求、operation result 和错误分类。 |
|
||
| 外部输出 | 资源列表、健康状态、租约状态、路由结果、操作结果、错误语义和结果查询摘要。 |
|
||
| 用户接口 | HWLAB runtime API、HWPOD 服务端接口、工具调用接口和 CaseRun/Agent 消费接口。 |
|
||
| 系统边界 | HWPOD服务负责服务端硬件资源真相和路由归属；不定义 spec 字段、命令行体验、节点适配器内部实现或 Harness 评价。 |
|
||
|
||
## 5. 内部分工与规格索引
|
||
|
||
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| PJ2026-01010301 | 资源注册 | 本规格 6.1 | registry、spec 摘要、authority 和资源状态 | HWPOD标准、平台配置 | 工具、客户端、Agent编排 |
|
||
| PJ2026-01010302 | 租约占用 | 本规格 6.2 | 租约、占用、释放、冲突处理和写操作保护 | 用户管理、资源注册 | Agent编排、CaseRun |
|
||
| PJ2026-01010303 | 节点路由 | 本规格 6.3 | 请求接收、目标解析、node 路由、超时和错误分类 | AI网关、租约占用 | HWPOD工具、HarnessRL |
|
||
| PJ2026-01010304 | 结果归属 | 本规格 6.4 | operation result 归属、查询和摘要交接 | 节点路由、Agent上下文 | HarnessRL、客户端、用户管理 |
|
||
|
||
## 6. 原子需求
|
||
|
||
### 6.1 HWPOD-SVC-REQ-001 资源注册
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| HWPOD-SVC-REQ-001 | 资源注册 | PJ2026-01010301 资源注册 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)、[客户端](PJ2026-0104-client.md) |
|
||
|
||
HWPOD服务应维护 HWPOD registry，使已声明资源、spec 摘要、authority、状态、能力和路由信息能够被工具、客户端和上层任务查询。
|
||
|
||
Registry 必须以 HWPOD 标准解释资源事实。缺失 HWPOD spec 的真实设备不能被服务端当作可写资源暴露；客户端可以展示不可用或待配置状态，但不能把临时端点当作资源真相。
|
||
|
||
### 6.2 HWPOD-SVC-REQ-002 租约与占用
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| HWPOD-SVC-REQ-002 | 租约占用 | PJ2026-01010302 租约占用 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
|
||
|
||
HWPOD服务应提供租约、占用、释放、冲突处理和超时恢复能力，使真实硬件写操作不会被多个任务并发破坏。
|
||
|
||
租约只定义硬件资源占用事实。用户管理提供调用主体和权限约束，Agent编排提供任务上下文，HWPOD服务负责把这些约束落实到资源可用性和写操作保护。
|
||
|
||
### 6.3 HWPOD-SVC-REQ-003 节点路由
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| HWPOD-SVC-REQ-003 | 节点路由 | PJ2026-01010303 节点路由 | [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)、[PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md) |
|
||
|
||
HWPOD服务应把已授权且租约一致的操作请求路由到正确 HWPOD node，并把目标不存在、node 离线、路由超时、协议连接失败和节点返回失败区分输出。
|
||
|
||
节点路由必须禁止错误 HWPOD 复用。工具请求某个 `hwpod-id` 时，服务端只能使用该资源声明绑定的 node 和能力；无法找到声明或路由时必须返回明确失败。
|
||
|
||
HWPOD 服务端只作为云端请求接收、租约校验、目标解析和网关路由 authority；Cloud Web、Agent 和 CLI 不应直接连接用户 PC 上的 gateway。网关主动出站后，服务端仍必须把命令领取、in-flight、超时、`gateway_busy` 和节点返回失败归一为可查询的 operation 状态，避免调用方把 HTTP dispatch timeout 误判为硬件动作结果。
|
||
|
||
### 6.4 HWPOD-SVC-REQ-004 结果归属
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| HWPOD-SVC-REQ-004 | 结果归属 | PJ2026-01010304 结果归属 | [HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |
|
||
|
||
HWPOD服务应把每次 operation result 归属到明确的 HWPOD、node、租约、调用方、操作类型和时间上下文，使 HarnessRL、客户端和账务统计能消费同一结果事实。
|
||
|
||
结果归属不是长证据归档。服务端只负责保存和交接必要操作结果、摘要和查询指针；CaseRun 评价、回放、训练反馈和用户展示由对应模块在此事实上继续处理。
|