docs: 恢复智能体观察纯 Kafka 权威
This commit is contained in:
Codex
@@ -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)。
|
||||
|
||||
@@ -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 动效只由真实状态驱动；
|
||||
|
||||
Reference in New Issue
Block a user