diff --git a/docs/MDTODO/hwlab-web-product-experience.md b/docs/MDTODO/hwlab-web-product-experience.md index 136103a6..8086c695 100644 --- a/docs/MDTODO/hwlab-web-product-experience.md +++ b/docs/MDTODO/hwlab-web-product-experience.md @@ -80,4 +80,4 @@ ## R3 [in_progress] -设计并实现 HWLAB v0.3 AgentRun 智能体运行观察页([HWLAB #2541](https://github.com/pikasTech/HWLAB/issues/2541)):集成“智能体管理”,默认表格并可切换卡片/树状视图;三视图共享唯一 snapshot BFF、Pinia 规范化 store、selector 和页面级轮询控制器,禁止 SSE、组件级请求、状态猜测及任何 fallback;默认 5 秒且用户可在 Web 调频,页面隐藏/离线暂停,以 singleflight、取消、退避、抖动、条件请求和 BFF 请求合并防过载;可调参数 YAML-first,并在 NC01/v03 公网原入口完成响应式、可访问性、数据一致性和限载验收,完成任务后将详细报告写入[任务报告](./details/hwlab-web-product-experience/R3_Task_Report.md)。 +设计并实现 HWLAB v0.3 AgentRun 智能体运行观察页([HWLAB #2541](https://github.com/pikasTech/HWLAB/issues/2541)):默认高密度表格并可切换卡片/树状视图,三视图与 Inspector 只消费 `agentrun.event.v1` 经 HWLAB mapper 写入 `hwlab.event.v1` 后形成的 Kafka retention replay SSE 与 live SSE,并共享唯一 reducer/store、selector、查询和选择状态;删除 snapshot BFF、定时轮询、AgentRun HTTP 补投影、数据库 projector/migration、fallback 和第二 authority;防过载窗口与 SSE/reducer 上限 YAML-first,并在 NC01/v03 原入口完成 lineage、replay-to-live handoff、断线恢复、幂等终态、响应式和可访问性验收,完成任务后将详细报告写入[任务报告](./details/hwlab-web-product-experience/R3_Task_Report.md)。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010405-cloud-console.md b/project-management/PJ2026-01/specs/PJ2026-010405-cloud-console.md index d1c4b382..6f2d45b2 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010405-cloud-console.md +++ b/project-management/PJ2026-01/specs/PJ2026-010405-cloud-console.md @@ -22,7 +22,7 @@ | 实现引用版本 | draft-2026-07-13-p0-cloud-console | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | -| 关联规格 | [HWPOD服务](PJ2026-010103-hwpod-service.md)、[AI网关](PJ2026-010104-ai-gateway.md)、[项目管理](PJ2026-010404-project-management.md)、[用户管理](PJ2026-0105-user-management.md) | +| 关联规格 | [HWPOD服务](PJ2026-010103-hwpod-service.md)、[AI网关](PJ2026-010104-ai-gateway.md)、[项目管理](PJ2026-010404-project-management.md)、[用户管理](PJ2026-0105-user-management.md)、[Workbench 实时权威](PJ2026-010401080313-workbench-realtime-authority.md) | | 规格治理索引 | [规格治理](spec-governance.md) | 本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版,定义 HWLAB Cloud Web 除 Workbench 主工作流之外的统一产品壳、页面能力、数据消费边界和原入口验收。 @@ -67,6 +67,7 @@ | view state | 纯显示状态,包括视图、密度、筛选、排序、cursor、选中对象和详情标签。 | | PCB 设备卡片 | 用电路板拓扑表达 HWPOD 四要素及真实状态的 SVG 实体卡片,不是装饰插画。 | | 节点接入阶段 | `downloaded`、`installed`、`desktop-visible`、`registered`、`workspace-ready` 和 `hwpod-ready` 的分阶段 readiness。 | +| 智能体运行观察 | 以 AgentRun/HWLAB Kafka 产品事件为唯一事实流,统一观察 task、run、command、attempt、runner 和 session 的工作页。 | ## 4. 系统边界和目标架构 @@ -220,9 +221,45 @@ sequenceDiagram - Performance、Gate、Skills 和 OpenCode 外壳按“状态到问题到证据到动作”渐进披露。 - Skills 不在缺少正式 API 时虚构删除或启停;OpenCode 保留同源 ticket、认证和安全 URL。 +### 7.4 AgentRun 智能体运行观察 + +- 智能体运行观察属于“智能体管理”下的单一工作页: + - 默认使用高密度表格; + - 可切换图标卡片与关系树; + - 三种视图共用同一查询、选择、排序、详情 Inspector 和 URL 深链。 +- 页面事实流固定复用 [Workbench 实时权威](PJ2026-010401080313-workbench-realtime-authority.md): + - AgentRun 把规范事件写入 `agentrun.event.v1`; + - HWLAB mapper 映射并写入 `hwlab.event.v1`; + - Cloud API 从 Kafka retention 提供有界 replay SSE,并无缝交接 live SSE; + - 浏览器使用单一 `agentObserver` reducer/store 归一化 task、run、command、attempt、runner 和 session; + - 表格、卡片、树和 Inspector 只消费该 store 的共享 selector。 +- 页面刷新和恢复只能通过 Kafka retention replay 到 live handoff 完成: + - 浏览器断线后从已确认事件位置继续 replay; + - 切换视图、打开 Inspector、调整密度或本地筛选不得新建请求源; + - 后台恢复只重连同一产品事件流,不执行 snapshot 补偿; + - reducer 按稳定 event identity 幂等,transport 状态与 AgentRun 业务状态分层表达。 +- 本页面不得引入以下路径: + - snapshot polling、定时轮询或页面级轮询 controller; + - Cloud API 直查 AgentRun manager、queue、session 或其他 HTTP read model 补投影; + - 数据库 projector、schema migration 或数据库 readiness 前置; + - SSE 失败时切换 HTTP snapshot、旧 API、mock、字段猜测或第二 authority; + - 表格、卡片、树或 Inspector 各自持有 EventSource、store 或状态推断。 +- 防过载参数由 owning YAML 唯一声明: + - Kafka retention 与 replay 有界窗口; + - SSE heartbeat、重连、批次和客户端缓冲上限; + - reducer 事件窗口、实体上限、树节点上限和详情尾部上限; + - 页面只读取渲染配置,不在组件、store 或 API client 中保存第二套默认值。 +- 页面状态必须区分: + - 首次 replay、retention-to-live 交接、live、reconnecting、stale 和 error; + - AgentRun admission、等待 runner、运行中、业务失败和终态; + - transport 失败不得改写业务终态,最后成功投影不得伪装为当前 live。 + ## 8. 后端与服务边界 - 页面所需聚合优先由 typed BFF/read model 提供,不让前端跨服务猜测事实。 +- 7.4 定义的智能体运行观察是事件流投影: + - 只复用既有 Kafka retention replay SSE 与 live SSE; + - 不为页面新增 snapshot BFF、AgentRun HTTP 聚合或数据库 read model。 - 只有独立数据所有权、生命周期、伸缩或连接故障域、权限边界成立时才拆微服务。 - 项目管理继续由独立 `hwlab-project-management` 拥有。 - 用户和账本事实继续由用户管理域拥有。 @@ -260,6 +297,10 @@ sequenceDiagram 控制台应在桌面、紧凑桌面和手机宽度保持明确导航、滚动所有者与可操作主路径;长表、长树和长日志 DOM 必须有界,隐藏 pane 停止高频更新。 +### 9.7 CONSOLE-REQ-007 智能体观察实时权威 + +AgentRun 智能体运行观察页应只消费 `agentrun.event.v1` 经 HWLAB mapper 进入 `hwlab.event.v1` 后形成的 Kafka retention replay SSE 与 live SSE,并由单一 reducer/store 投影表格、卡片、树和 Inspector;不得以 snapshot polling、AgentRun HTTP、数据库 projector、migration、fallback 或第二 authority 补齐页面状态。 + ## 10. 验收 - 规格与契约: @@ -274,6 +315,12 @@ sequenceDiagram - 覆盖 loading、refreshing、partial、empty、error 和 ready; - 覆盖大表、长树、长日志和隐藏 pane; - 卡片/列表共享同一状态和 blocker。 +- 智能体运行观察: + - 校对 `agentrun.event.v1` 到 `hwlab.event.v1` 的 lineage; + - 校对 retention replay 到 live handoff、断线恢复、幂等去重和终态保持; + - table/cards/tree 切换期间不得增加产品 EventSource 或请求源; + - 页面不得访问 snapshot polling、AgentRun HTTP 或数据库投影入口; + - 覆盖 replay、handoff、live、reconnecting、stale 和 transport error 的用户可见状态。 - HWPOD: - 覆盖一 node 多设备、声明离线 node、在线无 spec、invalid spec、capability mismatch、busy、update available 和诊断错误; - 验证 PCB 动效只由真实状态驱动;