mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refine HWLAB L1 ownership specs

Browse Source
This commit is contained in:
Codex
2026-06-14 17:17:50 +00:00
parent d4e7816bad
commit 985e3f6427
11 changed files with 95 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/unidesk-oa/SKILL.md
+1 -1
View File
@@ -34,7 +34,7 @@ description: UniDesk 项目管理运行技能。用户提到 UniDesk 项目管
- L0 系统边界必须把 HWLAB 作为完整系统看待，描述外部使用者、外部输入、受控资源、外部输出、用户接口和系统责任边界，不写内部治理材料。
- 稳定概念用术语表表达；不要写没有判定价值的“运行概念”流水。
- L0 的 L1 方向树和项目规格索引合并为内部模块分工与规格索引，用相对路径索引到每个内部模块规格文档。
- 原子需求每条独立成节，信息表使用横向表格且只放短元数据，推荐列为 `编号 | 短名 | 主责模块 | 关联模块`。主责模块必须带项目编号和相对路径链接；禁止把需求句、职责划分、验收口径或大段说明塞进表格，正文必须承载需求定义、职责边界、意图和范围。
- 原子需求每条独立成节，信息表使用横向表格且只放短元数据，推荐列为 `编号 | 短名 | 主责模块 | 关联模块`。主责模块必须写下一层主责单元并带项目编号：L0 原子需求写 L1，L1 原子需求写 L2，L2 原子需求写 L3；禁止在 L1/L2 原子需求里把主责模块写成本规格本级。禁止把需求句、职责划分、验收口径或大段说明塞进表格，正文必须承载需求定义、职责边界、意图和范围。
- 不要为了凑全局原子需求条数自动添加次要派生能力。证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包/结果收集等需求，除非用户明确授意，不得写入 OA 规格或 L0 原子需求。
- 平台运维在 L0 中只能作为支撑后勤职责出现；对外需求应写成系统可用性、可恢复、资源可控等用户可感知能力，不写成“HWLAB 对外提供平台运维能力”。
- 单一主责、关闭验收、规格沉淀、回写和偏离判定是治理规则，不得伪装成 L0 原子需求。
.agents/skills/unidesk-oa/references/project-planning.md
+3 -3
View File
@@ -143,7 +143,7 @@ L1 方向是直接服务 L0 使命的顶层能力域，不是项目管理工件
- L1 是验收主责，不是宽泛标签。每个非平凡 L2/L3/L4 issue 必须且只能有一个主责 L1。
- 可以列相关 L1 做交接，但主责 L1 是定义完成标准的方向。
- 主责不清楚时，问“什么证据能关闭这个 issue”：硬件资源就绪、Agent 执行生命周期、Harness/RL 证据、客户端/API 行为、用户/管理策略，还是平台交付/运维。
- 先按完成标准判断主责，再看实现表面。CLI、Web 页面、SDK、API、hwpod 工具或服务路由不会自动归入 `客户端`；它们主归属定义正确性的领域。只有当完成标准是多客户端入口行为、用户交互、兼容性、输出格式或公开 API/SDK 体验时，`客户端` 才是主责 L1。
- 先按完成标准判断主责，再看实现表面。CLI、Web 页面、HTTP API、hwpod 工具或服务路由不会自动归入 `客户端`；它们主归属定义正确性的领域。只有当完成标准是 Web、CLI、HTTP API 的入口行为、用户交互、兼容性或输出格式时，`客户端` 才是主责 L1。
HWLAB Cloud M1 当前 L1 职责矩阵：
@@ -152,7 +152,7 @@ HWLAB Cloud M1 当前 L1 职责矩阵：
| `PJ2026-0101` | 硬件池 | 硬件资源池：板卡、probe、HWPOD 节点、设备注册、占用、健康、可用性 | CaseRun pass/fail 标准、Agent 调度、UI/API 展示、CI/CD | 把 Harness 证据交给 HarnessRL；把资源分配 hook 交给 Agent编排 |
| `PJ2026-0102` | Agent编排 | Agent 执行生命周期：Code Agent、AgentRun、工作区、session、provider profile、任务恢复 | 硬件 inventory、Harness 评分、客户端 UX/API 契约、CI/CD | 从 硬件池 获取设备分配；向 HarnessRL 提供证据；向 客户端 提供状态 |
| `PJ2026-0103` | HarnessRL | Harness/RL 闭环：harness、CaseRun、ioProbe、证据、evaluation、replay、训练反馈、RL 收敛 | 硬件容量、Agent 调度、用户账户、rollout pipeline | 从 硬件池 获取设备事实；从 Agent编排 获取运行生命周期 |
| `PJ2026-0104` | 客户端 | 用户入口：Web、CLI、HTTP API、SDK/IDE plugin、webhook、公开文档、兼容性 | 用户/账本真相、Agent 调度内部、硬件 inventory、CI/CD | 向 用户管理 交接 auth/account 策略；从 Agent编排 获取运行状态 |
| `PJ2026-0104` | 客户端 | 用户入口：Web、CLI、HTTP API、兼容性、任务入口和结果获取 | 用户/账本真相、Agent 调度内部、硬件 inventory、CI/CD | 向 用户管理 交接 auth/account 策略；从 Agent编排 获取运行状态 |
| `PJ2026-0105` | 用户管理 | 用户和管理域：账户、注册/登录、权限、API key、credit、usage、billing、admin、tenant isolation | 客户端 UX、Agent 执行、硬件证据、部署机制 | 把用户入口交给 客户端；从 Agent编排/HarnessRL 获取 usage 来源 |
| `PJ2026-0106` | 平台运维 | 平台交付和运维：CI/CD、git mirror、YAML-first、Secret sync、rollout、observability、GC、platform release | 产品行为、用户策略、Agent 语义、硬件验收标准 | 承接所有 L1 的部署需求；把健康信号回传给负责人 |
@@ -181,7 +181,7 @@ HWLAB Cloud M1 当前 L1 职责矩阵：
| 编号 | 短名 | 主责 | 关联 L1 | 边界 |
| --- | --- | --- | --- | --- |
| `PJ2026-010101` | `HWPOD标准` | 定义 HWPOD-SPEC、硬件资源身份、能力模型、AI 网关接入标准、操作能力标准、状态/错误语义和验收基线。 | 客户端、HarnessRL、Agent编排 | 这是标准/协议型交付，不是单纯文档。它定义 HWPOD 资源和 AI 网关能力声明的正确性规则。 |
| `PJ2026-010102` | `HWPOD工具` | 实现硬件池领域工具侧，包括 `hwpod-ctl`、HWPOD-SPEC 新建/修改/校验，以及 compile、download、filesystem、IO 等操作入口。 | 客户端 | 这不是通用 `客户端` L1。只要完成标准由 HWPOD 语义或真实硬件执行定义，就主归属硬件池。通用 CLI 登录、profile 体验、公开 API 体验、SDK 对齐和多客户端一致性归 `客户端`。 |
| `PJ2026-010102` | `HWPOD工具` | 实现硬件池领域工具侧，包括 `hwpod-ctl`、HWPOD-SPEC 新建/修改/校验，以及 compile、download、filesystem、IO 等操作入口。 | 客户端 | 这不是通用 `客户端` L1。只要完成标准由 HWPOD 语义或真实硬件执行定义，就主归属硬件池。通用 CLI 登录、profile 体验、HTTP API 入口和多客户端一致性归 `客户端`。 |
| `PJ2026-010103` | `HWPOD服务` | 实现服务端 HWPOD 注册、管理、状态、必要的权限/租约、请求接收、路由、结果归档，并把工具侧请求转发到 AI 网关节点。 | 用户管理、Agent编排、平台运维 | 它负责 HWPOD 服务端语义，不负责全局部署机制、用户策略或 Agent 任务调度。 |
| `PJ2026-010104` | `AI网关` | 实现连接真实硬件到服务端的节点侧能力，包括 PC 客户端形态、硬件网关盒子形态、心跳、命令执行、日志/artifact/IO 结果回传和适配器执行。 | HarnessRL、Agent编排、平台运维 | debug probe、UART、board-comm、ioProbe、电压/电流/频率/CANopen 等适配器是网关侧能力切片，通常作为本 L2 下的 L3，除非发展成更大的工作计划。 |
.agents/skills/unidesk-oa/references/templates.md
+4 -4
View File
@@ -54,12 +54,12 @@
| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | <用户、外部系统、管理员或自动化任务> |
| 外部使用者 | <用户、管理员或自动化任务> |
| 外部输入 | <用户请求、业务对象、资源约束、身份凭据、文件或硬件选择> |
| 受控资源 | <系统管理的设备、数据、运行环境或外部资源> |
| 外部输出 | <用户可获得的状态、结果、产物、通知、报告或记录> |
| 用户接口 | <Web、CLI、API、SDK、Webhook 等> |
| 系统边界 | <系统负责什么；明确不替代用户或外部系统负责什么> |
| 用户接口 | <Web、CLI、HTTP API 等> |
| 系统边界 | <系统负责什么；明确不替代用户、管理员或运行环境负责什么> |
## 5. 内部模块分工与规格索引
@@ -75,7 +75,7 @@
| --- | --- | --- | --- |
| HWLAB-L0-REQ-001 | <需求短名> | [PJ2026-0101 <主责模块>](<相对路径>) | [<关联模块>](<相对路径>) |
<正文第一段写完整需求定义。正文后续段落写主责职责、关联模块职责、意图、范围和边界。不要把需求句、职责划分、类型、验证方法、验证入口、必需证据或接受标准塞进表格。不要为了凑条目自动添加证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包或结果收集类次要需求。>
<正文第一段写完整需求定义。主责模块必须写下一层主责单元：L0 写 L1，L1 写 L2，L2 写 L3，不重复当前规格本级。正文后续段落写主责职责、关联模块职责、意图、范围和边界。不要把需求句、职责划分、类型、验证方法、验证入口、必需证据或接受标准塞进表格。不要为了凑条目自动添加证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包或结果收集类次要需求。>
```
## L0 issue 正文
project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md
+8 -8
View File
@@ -40,7 +40,7 @@ HWLAB 的中心目标是把真实硬件资源、Agent 执行、Harness/RL 验收
- Agent 执行编排：Code Agent、AgentRun、workspace、session、provider profile、任务生命周期和任务恢复。
- Harness/RL 验收闭环：harness、CaseRun、HWPOD 观测引用、执行事实、评估、回放、训练反馈和 RL 闭环。
- 用户入口：Web、CLI、HTTP API、兼容性、任务入口、状态查看和结果获取。
- 用户与运营管理：用户、注册登录、权限、API key、credit、usage、billing、admin 和租户隔离。
- 用户与运营管理：用户、组织、组织项目、组织工作台、注册登录、权限、API key、credit、usage、billing、admin 和租户隔离。
- 系统可用性与服务保障：入口可访问、任务可恢复、资源使用可控、运行状态可观察和故障可处理。
### 2.3 范围外
@@ -61,7 +61,7 @@ HWLAB 的中心目标是把真实硬件资源、Agent 执行、Harness/RL 验收
| Agent编排 | 管理 Code Agent、AgentRun、workspace、session、provider profile、任务生命周期和任务恢复的内部模块。 |
| HarnessRL | 将硬件执行结果转化为执行事实、aggregate、评估、回放和训练反馈的内部模块。 |
| 客户端 | 面向用户的 Web、CLI 和 HTTP API 入口。 |
| 用户管理 | 管理用户身份、权限、API key、credit、usage、billing、admin 和租户隔离的内部模块。 |
| 用户管理 | 管理用户身份、组织协同、权限、API key、credit、usage、billing、admin 和租户隔离的内部模块。 |
| 平台运维 | 管理 CI/CD、git mirror、YAML-first 配置、Secret 下发、rollout、observability、GC 和平台发布的内部模块。 |
| 执行事实 | 可审计、可复验的硬件执行材料，包括硬件事实、执行 trace、ioProbe 数据、case registry、评估结果和必要日志摘要。 |
| 原入口验收 | 通过用户真实使用入口或该能力的原始执行入口完成验收，例如 Web、CLI、API、CaseRun、AgentRun 或 HWPOD 工具。 |
@@ -91,8 +91,8 @@ L1 划分保持现有六个内部能力模块；本章同时作为内部模块
| PJ2026-0102 | Agent编排 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | Code Agent、AgentRun、workspace、session、provider profile、任务生命周期、任务恢复 | [硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md)、[用户管理](PJ2026-0105-user-management.md) | [HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) |
| PJ2026-0103 | HarnessRL | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | harness、CaseRun、HWPOD 观测引用、执行事实、评估、回放、训练反馈、RL 闭环 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |
| PJ2026-0104 | 客户端 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | Web、CLI、HTTP API、兼容性、用户任务入口与结果获取 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) | 用户入口 |
| PJ2026-0105 | 用户管理 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | 用户、注册登录、权限、API key、credit、usage、billing、admin、租户隔离 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
| PJ2026-0106 | 平台运维 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | CI/CD、git mirror、YAML-first、Secret 下发、rollout、observability、GC、平台发布 | 全部 L1 的发布/配置/观测需求 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |
| PJ2026-0105 | 用户管理 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | 用户、组织、组织项目、组织工作台、权限、API key、credit、usage、billing、admin、租户隔离 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
| PJ2026-0106 | 平台运维 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | CI/CD、git mirror、YAML-first 自动化分布式运维、rollout、Prometheus 运维监控、平台发布 | 全部 L1 的发布、配置和监控需求 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |
## 6. 全局原子需求
@@ -150,11 +150,11 @@ HWLAB 应提供统一客户端入口，使 Web、CLI 和 HTTP API 围绕同一
| --- | --- | --- | --- |
| HWLAB-L0-REQ-005 | 用户与运营管理 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
HWLAB 应提供多用户与运营管理，使身份、权限、API key、credit、usage、billing、admin 和租户隔离具有统一真相。
HWLAB 应提供多用户与运营管理，使身份、组织、权限、API key、credit、usage、billing、admin 和租户隔离具有统一真相。
用户与运营管理定义平台多用户运行的业务事实。它必须保证用户身份、权限、额度、计量、账务和管理操作可以被统一查询和审计，避免同一用户或同一资源消费在不同入口出现不同真相。
用户与运营管理定义平台多用户和组织协同运行的业务事实。它必须保证用户身份、组织成员关系、组织内项目和工作台归属、权限、额度、计量、账务和管理操作可以被统一查询和审计，避免同一用户、同一组织或同一资源消费在不同入口出现不同真相。
用户管理负责身份、权限、API key、credit、usage、billing、admin 和租户隔离。客户端负责呈现入口，Agent编排、硬件池和 HarnessRL 消费用户、租户和额度约束。
用户管理负责身份、组织、权限、API key、credit、usage、billing、admin 和租户隔离。客户端负责呈现入口和组织工作台，Agent编排、硬件池和 HarnessRL 消费用户、组织、租户和额度约束。
### 6.6 HWLAB-L0-REQ-006 系统可用性与服务保障
@@ -166,4 +166,4 @@ HWLAB 应作为云端服务保持可访问、可恢复、资源使用可控，
系统可用性与服务保障不是 HWLAB 对外出售的功能模块，而是用户能够持续使用 HWLAB 的基础条件。用户感知到的是入口可访问、任务不中途丢失、故障后有恢复路径、资源不会被失控占用；平台运维只作为后勤职责支撑这些对外结果。
平台运维负责发布、配置、密钥、观测、资源清理和故障恢复支撑。客户端、Agent编排、硬件池、HarnessRL 和用户管理提供各自服务健康和资源需求，并通过平台运维获得运行保障。
平台运维负责发布、YAML-first 自动化分布式运维、Prometheus 运维监控和故障恢复支撑。客户端、Agent编排、硬件池、HarnessRL 和用户管理提供各自服务健康指标和运行需求，并通过平台运维获得后勤支撑。
project-management/PJ2026-01/specs/PJ2026-0101-hardware-pool.md
+5 -5
View File
@@ -48,7 +48,7 @@
- CaseRun 评价、pass/fail、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。
- Web、CLI 和 HTTP API 的通用用户入口体验归 [客户端](PJ2026-0104-client.md)。
- 用户身份、API key、额度、账本和租户策略归 [用户管理](PJ2026-0105-user-management.md)。
- CI/CD、Git mirror、Secret、发布、公开入口和运行保障归 [平台运维](PJ2026-0106-platform-ops.md)。
- CI/CD、Git mirror、YAML-first 运维、发布、公开入口和 Prometheus 运维监控归 [平台运维](PJ2026-0106-platform-ops.md)。
## 3. 术语表
@@ -89,7 +89,7 @@
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-L1-REQ-001 | HWPOD 标准 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
| HWPOD-L1-REQ-001 | HWPOD 标准 | PJ2026-010101 HWPOD标准 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
硬件池应定义并维护 HWPOD 标准，使每个真实硬件资源都有稳定的身份、四要素组成、能力声明、状态语义和错误语义。
@@ -99,7 +99,7 @@
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-L1-REQ-002 | HWPOD 工具 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
| HWPOD-L1-REQ-002 | HWPOD 工具 | PJ2026-010102 HWPOD工具 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
硬件池应提供 HWPOD 工具入口，使用户、Agent 或 CaseRun 能按同一 HWPOD 语义执行 spec validate、inspect、build、download、UART、board-comm 和 ioProbe 操作。
@@ -109,7 +109,7 @@
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-L1-REQ-003 | HWPOD 服务 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |
| HWPOD-L1-REQ-003 | HWPOD 服务 | PJ2026-010103 HWPOD服务 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |
硬件池应提供服务端资源管理能力，使真实设备能被注册、发现、查询健康、占用、释放、冲突处理并路由到正确的 HWPOD node。
@@ -119,7 +119,7 @@
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-L1-REQ-004 | HWPOD node | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) | [HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
| HWPOD-L1-REQ-004 | HWPOD node | PJ2026-010104 AI网关 | [HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
硬件池应通过 HWPOD node 或 AI 网关触达真实硬件，使下载、调试、UART、board-comm、ioProbe 和其他硬件动作在靠近设备的执行节点上受控执行。
project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md
+4 -4
View File
@@ -88,7 +88,7 @@ Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AGENT-L1-REQ-001 | 执行生命周期 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) |
| AGENT-L1-REQ-001 | 执行生命周期 | PJ2026-010201 任务生命周期 | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) |
Agent编排应通过 AgentRun durable resource 模型创建和跟踪 Agent 执行，使 run、command 和 runner job 能短返回、可轮询、可取消、可超时收口并进入明确终态。
@@ -98,7 +98,7 @@ Agent编排应通过 AgentRun durable resource 模型创建和跟踪 Agent 执
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AGENT-L1-REQ-002 | 资源装配 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
| AGENT-L1-REQ-002 | 资源装配 | PJ2026-010202 资源装配 | [硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
Agent编排应按 RuntimeAssembly 装配 BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef、workspace、tools、skills、promptRefs、provider profile 和 SecretRef。
@@ -108,7 +108,7 @@ Agent编排应按 RuntimeAssembly 装配 BackendImageRef、ProfileRef、SessionR
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AGENT-L1-REQ-003 | 会话连续性 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md) |
| AGENT-L1-REQ-003 | 会话连续性 | PJ2026-010201 任务生命周期 | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md) |
Agent编排应支持 SessionRef、thread continuation、session send、同 run 多 command 和 runner replacement，使用户任务可以在受控上下文中续跑。
@@ -118,7 +118,7 @@ Agent编排应支持 SessionRef、thread continuation、session send、同 run
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AGENT-L1-REQ-004 | AgentRun 合同 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | [平台运维](PJ2026-0106-platform-ops.md)、[客户端](PJ2026-0104-client.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
| AGENT-L1-REQ-004 | AgentRun 合同 | PJ2026-010202 资源装配 | [平台运维](PJ2026-0106-platform-ops.md)、[客户端](PJ2026-0104-client.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
Agent编排应原样消费 AgentRun 的 run、command、runner job、event、terminal status、liveness 和 failure kind 合同，并把这些事实映射为 HWLAB 可消费的执行语义。
project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md
+4 -4
View File
@@ -89,7 +89,7 @@ HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HARNESS-L1-REQ-001 | CaseRun 语义 | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md) |
| HARNESS-L1-REQ-001 | CaseRun 语义 | PJ2026-010301 CaseRun规格 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md) |
HarnessRL 应定义 CaseRun 的 case definition、stage model、postValidation、run-local workspace 和 case registry 语义，使一次真实硬件任务可以被稳定表达和复验。
@@ -99,7 +99,7 @@ CaseRun 语义必须引用 Agent 执行上下文和硬件事实，但不接管
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HARNESS-L1-REQ-002 | 观测引用 | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[客户端](PJ2026-0104-client.md) |
| HARNESS-L1-REQ-002 | 观测引用 | PJ2026-010302 观测引用 | [硬件池](PJ2026-0101-hardware-pool.md)、[客户端](PJ2026-0104-client.md) |
HarnessRL 应在 CaseRun 语义中引用 HWPOD 服务提供的外部观测结果，使外部读数能够与 case stage、硬件动作、评价和回放关系稳定关联。
@@ -111,7 +111,7 @@ HarnessRL 只负责把 HWPOD 服务返回的观测事实纳入 CaseRun stage、p
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HARNESS-L1-REQ-003 | 评估回放 | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
| HARNESS-L1-REQ-003 | 评估回放 | PJ2026-010303 评估回放 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
HarnessRL 应提供评估与回放语义，使同一次硬件执行可以被 aggregate 阅读、被 baseline 或 judge 比较，并能基于同一验证关系复核结论。
@@ -121,7 +121,7 @@ HarnessRL 应提供评估与回放语义，使同一次硬件执行可以被 agg
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HARNESS-L1-REQ-004 | 训练反馈 | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md) |
| HARNESS-L1-REQ-004 | 训练反馈 | PJ2026-010304 训练反馈 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md) |
HarnessRL 应把成功路径、失败分类和评价结论转化为可回流的训练反馈，使 prompt、skill、case、node-op 或 reward 数据能进入后续改进。
project-management/PJ2026-01/specs/PJ2026-0104-client.md
+3 -3
View File
@@ -84,7 +84,7 @@
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-L1-REQ-001 | Web工作台 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |
| CLIENT-L1-REQ-001 | Web工作台 | PJ2026-010401 Web工作台 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |
客户端应提供 Cloud Web 工作台，使用户能够通过同一 Web 入口完成登录后的任务创建、会话操作、硬件资源选择、执行结果查看和管理能力访问。
@@ -94,7 +94,7 @@ Web 工作台只承载用户交互和展示契约。身份真相来自用户管
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-L1-REQ-002 | CLI入口 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[用户管理](PJ2026-0105-user-management.md) |
| CLIENT-L1-REQ-002 | CLI入口 | PJ2026-010402 CLI入口 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[用户管理](PJ2026-0105-user-management.md) |
客户端应提供可脚本化的 CLI 入口，使用户和自动化脚本能用一致的参数、输出和错误语义访问 HWLAB 能力。
@@ -104,7 +104,7 @@ CLI 入口必须复用后端业务事实，不在命令行层重新定义 HWPOD
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-L1-REQ-003 | API契约 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |
| CLIENT-L1-REQ-003 | API契约 | PJ2026-010403 API契约 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |
客户端应定义 HTTP API、schema、错误码和兼容性契约，使 Web、CLI 和自动化脚本围绕同一接口语义访问 HWLAB。
project-management/PJ2026-01/specs/PJ2026-0105-user-management.md
+30 -13
View File
@@ -32,11 +32,12 @@
### 2.1 目的
用户管理负责 HWLAB 的用户身份、会话、API key、权限、额度、计量、账单、管理员操作和租户隔离，使多用户云服务中的任务发起、资源消费和运营管理都能引用同一套用户与账本真相。
用户管理负责 HWLAB 的用户身份、组织、会话、API key、权限、额度、计量、账单、管理员操作和租户隔离，使多用户云服务中的任务发起、组织协同、资源消费和运营管理都能引用同一套用户、组织与账本真相。
### 2.2 范围内
- 用户注册、登录、登出、session、会话检查和用户身份 source-of-truth。
- 组织、组织成员、组织角色、组织内项目和组织工作台归属。
- API key 创建、撤销、scope、脱敏展示、轮换、服务端校验和调用身份绑定。
- role、admin、plan、entitlement、quota、concurrency、RPM 和资源授权预检。
- credit ledger、reservation、usage record、幂等消费、回滚补偿和 usage 来源归因。
@@ -49,13 +50,16 @@
- Agent run、command、session、workspace 和 provider profile 生命周期归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
- HWPOD 资源身份、硬件事实、租约和物理资源状态归 [硬件池](PJ2026-0101-hardware-pool.md)。
- CaseRun 评价、回放、训练反馈和执行结果语义归 [HarnessRL](PJ2026-0103-harness-rl.md)。
- 数据库、Secret、发布、公开入口和运行保障归 [平台运维](PJ2026-0106-platform-ops.md)。
- 数据库、YAML-first 运维、发布、公开入口和 Prometheus 运维监控归 [平台运维](PJ2026-0106-platform-ops.md)。
## 3. 术语表
| 术语 | 定义 |
| --- | --- |
| 用户 | HWLAB 中拥有身份、权限、额度和资源消费记录的主体。 |
| 组织 | 可包含多个用户的 2B 协作边界，拥有组织内项目、工作台和成员权限。 |
| 组织项目 | 归属于某个组织并可由组织成员按权限共同访问的项目。 |
| 组织工作台 | 归属于某个组织并承载组织内任务、资源和结果入口的工作台。 |
| 会话 | 用户完成身份认证后获得的登录状态和服务端可检查的访问上下文。 |
| API key | 用户或自动化脚本用于调用 HWLAB API 的凭据，与用户身份、scope 和额度约束绑定。 |
| 权限 | 用户对管理操作、任务操作、资源操作和账单操作的访问许可。 |
@@ -70,11 +74,11 @@
| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 硬件研发用户、自动化脚本、平台管理员、Agent编排、客户端和需要授权判断的内部模块。 |
| 外部输入 | 登录凭据、API key、权限请求、计划和配额配置、任务消费事件、硬件资源约束、管理员操作和充值/兑换请求。 |
| 受控资源 | 用户记录、会话、API key、角色、计划、额度、credit ledger、usage record、billing summary、admin 操作记录和租户边界。 |
| 外部输出 | 用户身份、会话状态、API key 摘要、授权预检结果、额度状态、usage/credit 记录、账单摘要、管理员查询结果和租户隔离判断。 |
| 外部输入 | 登录凭据、API key、组织创建和成员分配请求、组织项目和工作台归属、权限请求、计划和配额配置、任务消费事件、硬件资源约束、管理员操作和充值/兑换请求。 |
| 受控资源 | 用户记录、组织、组织成员、组织项目、组织工作台、会话、API key、角色、计划、额度、credit ledger、usage record、billing summary、admin 操作记录和租户边界。 |
| 外部输出 | 用户身份、组织成员关系、组织项目和工作台可见性、会话状态、API key 摘要、授权预检结果、额度状态、usage/credit 记录、账单摘要、管理员查询结果和租户隔离判断。 |
| 用户接口 | Cloud Web 登录和账户入口、`hwlab-cli` 用户与管理命令、HTTP API、admin API。 |
| 系统边界 | 用户管理负责身份、权限、额度、计量、账单和租户隔离真相；不定义客户端界面、Agent 执行、硬件事实、Harness 评价或平台发布机制。 |
| 系统边界 | 用户管理负责身份、组织、权限、额度、计量、账单和租户隔离真相；不定义客户端界面、Agent 执行、硬件事实、Harness 评价或平台发布机制。 |
## 5. 内部分工与规格索引
@@ -86,6 +90,7 @@
| PJ2026-010504 | 计量账本 | 本规格 6.4 | credit ledger、reservation、usage record、幂等和补偿 | Agent/Harness 消费事件、平台数据库 | billing、admin、运营分析 |
| PJ2026-010505 | 账单后台 | 本规格 6.5 | billing summary、admin 调账、报表、导出、充值和兑换 | 计量账本、账号权限、客户端入口 | 用户、管理员、运营流程 |
| PJ2026-010506 | 租户隔离 | 本规格 6.6 | 多用户数据、资源和管理操作隔离 | 用户身份、权限配额、平台存储 | 全部 L1 |
| PJ2026-010507 | 组织管理 | 本规格 6.7 | 组织、成员、组织角色、组织项目和组织工作台归属 | 账号会话、权限配额、客户端工作台 | 客户端、Agent编排、硬件池、HarnessRL |
## 6. 原子需求
@@ -93,7 +98,7 @@
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| USER-L1-REQ-001 | 账号会话 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
| USER-L1-REQ-001 | 账号会话 | PJ2026-010501 账号会话 | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
用户管理应提供统一账号与会话能力，使 HWLAB 用户能够完成注册、登录、登出、会话检查和身份续用，并让 Web、CLI、API 和内部服务都引用同一用户身份。
@@ -103,7 +108,7 @@
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| USER-L1-REQ-002 | APIKey | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |
| USER-L1-REQ-002 | APIKey | PJ2026-010502 APIKey | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |
用户管理应提供 API key 生命周期能力，使用户和自动化脚本能够创建、撤销、轮换并以受限 scope 调用 HWLAB 服务。
@@ -113,7 +118,7 @@ API key 必须绑定用户身份、权限和额度约束，并在展示和日志
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| USER-L1-REQ-003 | 权限配额 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md) |
| USER-L1-REQ-003 | 权限配额 | PJ2026-010503 权限配额 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md) |
用户管理应提供权限、计划、额度和资源授权预检能力，使 HWLAB 在任务发起和资源占用前能够判断用户是否有权消费对应能力。
@@ -123,7 +128,7 @@ API key 必须绑定用户身份、权限和额度约束，并在展示和日志
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| USER-L1-REQ-004 | 计量账本 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |
| USER-L1-REQ-004 | 计量账本 | PJ2026-010504 计量账本 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |
用户管理应提供计量账本能力，使 reservation、usage record、credit 增减、幂等处理和回滚补偿都能落到同一用户消费真相中。
@@ -133,7 +138,7 @@ API key 必须绑定用户身份、权限和额度约束，并在展示和日志
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| USER-L1-REQ-005 | 账单后台 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md) |
| USER-L1-REQ-005 | 账单后台 | PJ2026-010505 账单后台 | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md) |
用户管理应提供账单与管理后台能力，使用户和管理员能够查看消费摘要、ledger 明细、额度状态，并完成受控的 credit 调整、兑换、充值和运营查询。
@@ -143,8 +148,20 @@ API key 必须绑定用户身份、权限和额度约束，并在展示和日志
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| USER-L1-REQ-006 | 租户隔离 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |
| USER-L1-REQ-006 | 租户隔离 | PJ2026-010506 租户隔离 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |
用户管理应提供租户隔离能力，使多用户环境中的账户、任务、资源、usage、账单和管理操作不会越权访问其他用户或租户的数据。
租户隔离必须成为各入口和内部模块共享的访问边界。客户端、Agent编排、硬件池、HarnessRL 和平台运维都应消费用户管理给出的身份和权限上下文，而不是在各自模块中发明不一致的隔离规则。
租户隔离必须成为各入口和内部模块共享的访问边界。组织内共享项目和工作台也必须受租户边界约束。客户端、Agent编排、硬件池、HarnessRL 和平台运维都应消费用户管理给出的身份、组织和权限上下文，而不是在各自模块中发明不一致的隔离规则。
### 6.7 USER-L1-REQ-007 组织管理
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| USER-L1-REQ-007 | 组织管理 | PJ2026-010507 组织管理 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
用户管理应提供组织管理能力，使多个用户能够被分配到同一个组织，并在组织边界内共享组织所属的项目和工作台。
组织管理是 HWLAB 的 2B 协同基础能力。它必须定义组织身份、组织成员关系、组织角色、组织内项目归属和组织工作台归属，使企业或团队用户可以围绕同一组织上下文发起任务、查看结果、管理资源和协同工作。
用户管理负责组织成员、角色和组织资源归属真相。客户端负责呈现组织切换、组织项目和组织工作台入口；Agent编排、硬件池和 HarnessRL 消费组织上下文与权限约束，不在各自模块中另建组织模型。
project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md
+29 -27
View File
@@ -32,17 +32,16 @@
### 2.1 目的
平台运维负责为 HWLAB 各业务方向提供受控发布、源码同步、YAML 配置、Secret 下发、公开入口、运行观测和资源清理支撑。它是 HWLAB 的后勤保障方向，不把运维动作包装成对外产品能力，也不替代业务 L1 定义功能需求。
平台运维负责为 HWLAB 各业务方向提供受控发布、源码同步、YAML-first 自动化分布式运维、公开入口和 Prometheus 运维监控支撑。它是 HWLAB 的后勤保障方向，不把运维动作包装成对外产品能力，也不替代业务 L1 定义功能需求。
### 2.2 范围内
- CI/CD、PipelineRun、image、rollout、trigger-current 和发布状态。
- Git mirror、source commit authority、bundle/mirror URL、lane source truth 和 GitOps 源同步。
- YAML-first target、lane、node、service 配置、render、validate 和配置可见性。
- Secret sourceRef、targetKey、fingerprint、presence、下发、轮换和敏感输出约束。
- YAML-first 自动化分布式运维，包括 target、lane、node、service 声明、render、validate、受控下发和配置可见性。
- YAML-first 运维下的 SecretRef 子项，包括 sourceRef、targetKey、fingerprint、presence、轮换和敏感输出约束。
- FRP、Caddy、domain、TLS、public health 和公开入口漂移处理。
- health、status、logs、trace、失败原因、运行事件和可见性先修。
- artifact、trace、workspace、session、log、cache、PVC 和 registry 的保留与清理。
- Prometheus metrics、scrape target、alert rule、服务健康指标、资源指标和运行面监控口径。
### 2.3 范围外
@@ -59,11 +58,10 @@
| --- | --- |
| 受控发布 | 通过标准 CI/CD、镜像、rollout 和状态查询入口完成的服务交付过程。 |
| Git mirror | 为目标运行面提供源码同步和 source commit authority 的镜像机制。 |
| YAML-first | UniDesk 自有配置以 YAML 为真相源，运行面和 CLI 从 YAML 渲染与校验。 |
| SecretRef | 指向密钥来源和目标 key 的声明式引用，运行输出只披露摘要和存在性。 |
| YAML-first | UniDesk 自有配置以 YAML 为真相源，运行面和 CLI 从 YAML 渲染、校验并受控下发。 |
| SecretRef | YAML-first 运维中的密钥声明子项，指向密钥来源和目标 key，运行输出只披露摘要和存在性。 |
| 公开入口 | FRP、Caddy、域名、TLS 和健康检查共同形成的外部访问面。 |
| 运行观测 | 对服务状态、日志尾部、trace、失败原因和运行事件的可见性能力。 |
| 保留清理 | 对产物、缓存、会话、日志、PVC 和 registry 资源的生命周期管理。 |
| Prometheus 运维监控 | 通过 Prometheus 采集 metrics、维护 scrape target、alert rule 和服务健康指标的运维监控能力。 |
## 4. 系统边界和接口
@@ -72,11 +70,11 @@
| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | HWLAB 各 L1 模块、平台管理员、发布操作人员和需要运行状态的自动化任务。 |
| 外部输入 | Git commit、PR merge、镜像产物、YAML 配置、SecretRef、公开入口声明、retention policy、服务健康请求和运行状态查询。 |
| 受控资源 | CI/CD pipeline、Git mirror、运行 lane、Kubernetes 资源、YAML 配置、Secret 分发、FRP/Caddy、日志、trace、缓存、PVC 和 registry。 |
| 外部输出 | 发布状态、source commit、配置渲染结果、Secret 摘要、public URL health、服务状态、日志尾部、失败原因、保留清理结果和运行支撑记录。 |
| 用户接口 | UniDesk CLI、HWLAB 控制面命令、受控 Secret 命令、平台基础设施命令、短查询 route。 |
| 系统边界 | 平台运维负责交付、配置、密钥、入口、观测和清理可控；不定义硬件、Agent、Harness、客户端或用户管理的业务成功标准。 |
| 外部输入 | Git commit、PR merge、镜像产物、YAML 配置、SecretRef 子项、公开入口声明、metrics endpoint、服务健康指标和运行状态查询。 |
| 受控资源 | CI/CD pipeline、Git mirror、运行 lane、Kubernetes 资源、YAML-first 运维配置、SecretRef 下发、FRP/Caddy、Prometheus scrape target、metrics 和 alert rule。 |
| 外部输出 | 发布状态、source commit、配置渲染结果、Secret 摘要、public URL health、Prometheus target 状态、metrics 查询结果、alert 状态和运行支撑记录。 |
| 用户接口 | UniDesk CLI、HWLAB 控制面命令、受控 Secret 命令、平台基础设施命令、Prometheus 查询和告警入口。 |
| 系统边界 | 平台运维负责交付、YAML-first 自动化分布式运维、入口和 Prometheus 运维监控可控；不定义硬件、Agent、Harness、客户端或用户管理的业务成功标准。 |
## 5. 内部分工与规格索引
@@ -84,9 +82,9 @@
| --- | --- | --- | --- | --- | --- |
| PJ2026-010601 | 发布流水 | 本规格 6.1 | CI/CD、PipelineRun、image、rollout、trigger-current 和发布状态 | Git commit、镜像配置、各 L1 发布需求 | 全部 L1 |
| PJ2026-010602 | 源码同步 | 本规格 6.2 | Git mirror、source commit authority、bundle/mirror URL 和 lane source truth | Git remote、运行 lane、Agent 资源装配需求 | Agent编排、HarnessRL、客户端 |
| PJ2026-010603 | 配置密钥 | 本规格 6.3 | YAML-first 配置、SecretRef、targetKey、fingerprint、下发和敏感输出约束 | 各 L1 配置需求、密钥来源 | 全部 L1 |
| PJ2026-010603 | YAML-first运维 | 本规格 6.3 | YAML-first 自动化分布式运维；SecretRef、targetKey、fingerprint 是其密钥分发子项 | 各 L1 配置需求、密钥来源 | 全部 L1 |
| PJ2026-010604 | 公开入口 | 本规格 6.4 | FRP、Caddy、domain、TLS、public health 和入口漂移处理 | 客户端/API 服务、运行 lane | 客户端、用户管理、Agent编排 |
| PJ2026-010605 | 运行保障 | 本规格 6.5 | health、status、logs、trace、失败原因、保留清理和资源回收 | 运行面状态、retention policy | 全部 L1 |
| PJ2026-010605 | 运维监控 | 本规格 6.5 | Prometheus metrics、scrape target、alert rule、服务健康指标和资源指标 | 运行面 metrics endpoint、各 L1 服务健康指标 | 全部 L1 |
## 6. 原子需求
@@ -94,7 +92,7 @@
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-L1-REQ-001 | 受控发布 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
| OPS-L1-REQ-001 | 受控发布 | PJ2026-010601 发布流水 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
平台运维应提供受控发布能力，使 HWLAB 服务变更能够通过标准 CI/CD、镜像构建、rollout、trigger-current 和状态查询进入目标运行面。
@@ -104,38 +102,42 @@
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-L1-REQ-002 | 源码同步 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) |
| OPS-L1-REQ-002 | 源码同步 | PJ2026-010602 源码同步 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) |
平台运维应提供源码同步与运行真相能力，使目标 lane 使用明确的 Git mirror、source commit、bundle/mirror URL 和 GitOps 来源。
源码同步必须让运行面能够说明自己来自哪个 commit 和哪条受控来源。Agent编排可以消费 source truth 装配 workspace，HarnessRL 可以引用源码上下文执行 CaseRun，但它们不接管 mirror 和 lane source authority。
### 6.3 OPS-L1-REQ-003 配置与密钥下发
### 6.3 OPS-L1-REQ-003 YAML-first 自动化分布式运维
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-L1-REQ-003 | 配置密钥 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md)、[硬件池](PJ2026-0101-hardware-pool.md) |
| OPS-L1-REQ-003 | YAML-first运维 | PJ2026-010603 YAML-first运维 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md)、[硬件池](PJ2026-0101-hardware-pool.md) |
平台运维应提供 YAML-first 配置与 Secret 下发能力，使 HWLAB 自有配置、lane 参数、SecretRef、targetKey、fingerprint 和 presence 通过受控入口进入运行面。
平台运维应提供 YAML-first 自动化分布式运维能力，使 HWLAB 自有配置、target、lane、node、service 声明、render、validate 和受控下发通过 YAML 真相源进入运行面。
配置与密钥下发必须把 YAML 和声明式 SecretRef 作为真相来源，并限制命令输出只披露摘要、对象名、key 名和存在性。业务模块负责定义自身需要的配置含义，平台运维负责把这些配置和密钥安全地送到运行面。
SecretRef、targetKey、fingerprint 和 presence 是 YAML-first 运维下的密钥分发子项，不单独作为 L2 边界。业务模块负责定义自身配置需求和密钥来源，平台运维负责把这些 YAML 声明和 SecretRef 子项安全地渲染、校验并下发到运行面。
YAML-first 运维的命令输出只能披露摘要、对象名、key 名、sourceRef、fingerprint 和存在性，不得泄漏敏感值，也不得用运行面反推本地配置真相。
### 6.4 OPS-L1-REQ-004 公开入口
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-L1-REQ-004 | 公开入口 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
| OPS-L1-REQ-004 | 公开入口 | PJ2026-010604 公开入口 | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
平台运维应提供公开入口支撑能力，使 HWLAB 的 Web、API 和管理入口能够通过正确的 FRP、Caddy、域名、TLS 和 health 目标暴露到外部。
公开入口负责外部流量到目标 runtime 的正确连通和漂移收敛。页面行为、API 契约、用户登录和 Agent 任务语义分别由客户端、用户管理和 Agent编排定义。
### 6.5 OPS-L1-REQ-005 运行观测与资源清理
### 6.5 OPS-L1-REQ-005 Prometheus 运维监控
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-L1-REQ-005 | 运行保障 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |
| OPS-L1-REQ-005 | 运维监控 | PJ2026-010605 运维监控 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |
平台运维应提供运行观测与资源清理能力，使 HWLAB 的服务状态、日志尾部、trace、失败原因、artifact、workspace、session、cache、PVC 和 registry 生命周期可控。
平台运维应提供基于 Prometheus 的运维监控能力，使 HWLAB 运行面能够通过 metrics endpoint、scrape target、alert rule 和服务健康指标表达服务状态与资源状态。
运行观测用于定位运行面问题，不能替代业务功能实现或业务完成标准。资源清理用于避免运行面被历史产物、缓存和残留会话拖垮，清理策略必须保护仍被业务模块引用的必要产物。
Prometheus 运维监控只负责运维指标、采集目标、告警规则和监控口径。各 L1 提供自身服务健康指标和运行需求；平台运维负责把这些指标接入 Prometheus 并维护可查询、可告警的监控面。
Prometheus 监控不能替代业务功能实现、CaseRun 评价、Agent 状态模型、硬件事实或用户账本。业务成功仍由对应 L1 定义，监控只用于运行面健康和资源状态判断。
project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md
+4 -4
View File
@@ -16,7 +16,7 @@
- 业务需求规格用于使命和商业目标，利益相关方需求规格用于用户和运营方诉求，系统需求规格用于跨硬件、软件、人员和流程的系统级要求，软件需求规格用于软件能力要求。运行流程和一次性执行过程不进入需求规格正文，稳定概念优先沉淀为术语表。
- HWLAB 的 L0、L1、L2 规格共用同一骨架，但粒度不同：L0 写使命、边界和全局需求；L1 写内部模块职责和验收边界；L2 写具体课题的交付物、阻塞项和验证计划。
- 规格正文只写稳定需求、系统边界、外部输入输出和职责；内部治理、阶段报告、执行流水、长日志、拉取请求过程和一次性运行材料不进入需求规格正文。
- 每条原子需求使用独立小节。信息表使用横向表格且只放短元数据，推荐包含编号、短名、主责模块和关联模块；需求定义、职责划分、意图、范围和边界写在正文中，避免表格厚而正文薄。
- 每条原子需求使用独立小节。信息表使用横向表格且只放短元数据，推荐包含编号、短名、主责模块和关联模块；主责模块填写下一层主责单元，L0 写 L1，L1 写 L2，L2 写 L3，不重复当前规格本级；需求定义、职责划分、意图、范围和边界写在正文中，避免表格厚而正文薄。
- 不要为了凑全局需求条目自动添加证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包或结果收集类次要需求；除非用户明确授意，这些内容不进入 OA 规格。
## 文档骨架
@@ -76,12 +76,12 @@
| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | <用户、外部系统、管理员或自动化任务> |
| 外部使用者 | <用户、管理员或自动化任务> |
| 外部输入 | <用户请求、业务对象、资源约束、身份凭据、配置项或文件> |
| 受控资源 | <系统管理的资源、数据、运行环境或外部设备> |
| 外部输出 | <用户可获得的状态、结果、产物、通知、报告或记录> |
| 用户接口 | <网页端、命令行、应用接口、开发工具包等> |
| 系统边界 | <系统负责什么；明确不替代用户或外部系统负责什么> |
| 系统边界 | <系统负责什么；明确不替代用户、管理员或运行环境负责什么> |
## 5. 内部分工与规格索引
@@ -95,7 +95,7 @@
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| <需求编号> | <需求短名> | <项目编号 短名，使用相对路径链接> | <关联模块，使用相对路径链接> |
| <需求编号> | <需求短名> | <下一层项目编号 短名，必要时使用相对路径链接> | <关联模块，使用相对路径链接> |
<正文第一段写完整需求定义。正文后续段落写主责职责、关联模块职责、意图、范围和边界。正文不放执行流水和长证据。>
```