diff --git a/.agents/skills/unidesk-webdev/SKILL.md b/.agents/skills/unidesk-webdev/SKILL.md index f84f6041..fb24bf99 100644 --- a/.agents/skills/unidesk-webdev/SKILL.md +++ b/.agents/skills/unidesk-webdev/SKILL.md @@ -181,10 +181,18 @@ description: UniDesk Web 开发与受控浏览器验证技能。用户提到 Web - Workbench Kafka 实时 fanout 的重复验收： - 使用 `observe command --type validateRealtimeFanout --profile --provider --text --second-text `； - connected、refresh/reconnect 和 capability 期望来自 owning YAML，可独立组合，禁止在命令中硬编码 live-only 或 refresh mode； + - 浏览器验收前先对同一已有 session 执行 `workbench events inspect --over-api`： + - `kafkaRefreshReplay=true` 时，connected 必须为 `kafka-retention-then-live`、`replay=true`、`liveOnly=false`； + - capability 已启用但 connected 仍为 `live-only` 时，直接检查 L1 native SSE 路由是否复用生产 retention handoff； + - 上述情况不得先重复扫描 Kafka、修改 reducer，或增加 snapshot 仲裁； - 每轮只把 `user`、`assistant` 和 `terminal` 对应的 AgentRun/HWLAB 事件族作为必需核心事件； - `tool_call`/`command_output` 与 HWLAB `tool`/`status` 是条件事件对，仅在实际出现时校验数量和 lineage； - 直接答复不得为了通过探针而合成工具事件，超时证据必须披露已经观测和仍然缺失的事件族； - refresh 启用时必须证明 retention 到 live handoff、正式 `user` event、`hwlab.event.v1` 同 envelope，以及主页面单一 EventSource 和同一 UI reducer 终态； + - 禁止用“陈旧快照不得覆盖 sealed final”一类优先级或封口 guard 处理刷新： + - 该模型仍保留多个业务写入路径及竞争仲裁； + - 必须删除 HTTP snapshot、submit response、result fallback 等业务状态写入； + - retention replay 与 live frame 只进入同一 SSE ingress 和同一 reducer； - observer 后台维持两个独立 product subscriber 和三条 debug SSE； - 命令提交后按 `status --command-id ` 轮询，不得回退为长连接 `web-probe script`。 - Workbench 隔离 Kafka debug 重放使用 `observe command --type validateWorkbenchKafkaDebugReplay`： diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index f92f18c1..7c2e0917 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -199,10 +199,14 @@ Workbench 浏览器回归需求以 UniDesk OA [PJ2026-010401 Web工作台](../.. - API 依赖就绪入口固定为 `/health/ready`； - `/health` 不是 Workbench L1 health 路由，禁止通过试探 404 判断服务异常； - 实时验收先启动 `hwlab-cli workbench events inspect --over-api --wait-for user,backend,assistant,terminal,final`，再向同一 session/trace 提交一个新 turn； + - 已有 session 的刷新验收必须先检查 connected contract： + - `kafkaRefreshReplay=true` 时要求 `deliverySemantics=kafka-retention-then-live`、`replay=true`、`liveOnly=false`； + - capability 已启用但仍返回 `live-only` 时，优先定位 L1 native API 是否仍保留独立 live-only SSE adapter； + - 此时 retention 查询尚未开始，不得先归因 Kafka 扫描超时或历史事件缺失； - 通过条件是 `connected=true`、`missingSemantics=[]` 且 `terminalStatuses` 出现明确终态； - `eventCount` 和 `--min-events` 不能证明 assistant、terminal 或 final，不得通过反复猜事件数量重开 inspect； - `event-timeout` 必须直接读取 `observedSemantics` 与 `missingSemantics` 分层定位； - - AgentRun 冷启动仍未终态时，报告上游运行状态，不得对已结束的 live-only 窗口补读 snapshot、read-model、AgentRun `/events` 或 `/result` 冒充产品 SSE 验收。 + - AgentRun 冷启动仍未终态时，报告上游运行状态，不得补读 snapshot、read-model、AgentRun `/events` 或 `/result` 冒充产品 SSE 验收。 - `workbench.connected` 已到达且 `filters.sessionId` 与当前会话一致时，delivery semantics、capabilities、contract version 和 authority metadata 的缺失或漂移只记录 `blocking=false` warning； - 上述内部元数据 warning 不得清空 realtime ready、禁用 Composer、覆盖业务错误或产生 `workbench_live_realtime_contract_invalid` 一类阻塞状态； - EventSource 未连接、连接进入 error/closed/blocked，或 connected session scope 与当前会话不一致时仍可阻断，并必须返回与 transport 或 session scope 对应的 typed error； @@ -350,6 +354,11 @@ HWLAB v0.3 订阅 AgentRun Kafka event 的权威输入是 `agentrun.event.v1`， - 到达 barrier 后必须退出，不得把每个浏览器连接变成新的长期 Kafka consumer； - 实时阶段继续复用进程级 shared consumer/fanout； - 同一 Workbench session 只建立一个产品 EventSource，刷新与重连不得复制业务 subscriber。 +- 单一路径禁止用状态优先级伪装： + - “陈旧快照不得覆盖 sealed final”、snapshot freshness、final authority priority 等 guard 都意味着多条业务写入路径仍在竞争； + - 应删除 HTTP session/message/turn/result、submit response 和本地缓存对业务状态的写入； + - retention replay 与 live frame 必须只通过同一 SSE ingress、queue、reducer、row model 和 card； + - HTTP 只负责命令接纳、鉴权和非业务辅助数据，不参与消息、终态或 Final Response 投影。 - `kafkaRefreshReplay` 与 `liveKafkaSse` 是可组合、可独立开关的 capability： - topic、group、扫描预算、等待预算、live buffer 上限和失败策略只从选中 node/lane 的 owning YAML/runtime config 读取； - replay 与 live frame 必须进入同一 decode、queue、reducer、row model 和 card；