From 6a119a5364d5ad4b8d985dfdf19d0c26ac38cb7d Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 11 Jul 2026 22:11:52 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20HWLAB=20Kafka=20?= =?UTF-8?q?=E5=88=B7=E6=96=B0=E5=AE=9E=E6=97=B6=E4=BA=A4=E6=8E=A5=E5=90=88?= =?UTF-8?q?=E5=90=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/hwlab.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 4ac45189..2656db39 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -226,6 +226,30 @@ HWLAB 与 AgentRun 协同修复必须按 `docs/reference/agentrun.md` 的职责 HWLAB v0.3 订阅 AgentRun Kafka event 的权威输入是 `agentrun.event.v1`，内存 direct mapper 的权威输出是 `hwlab.event.v1`；三 topic 的 ownership 统一见 `docs/reference/platform-infra.md#kafka-event-bus-boundary`。`directPublish` 使用固定独立 group 消费 AgentRun event、调用生产 mapper 并直接发布完整 HWLAB envelope；`liveKafkaSse` 使用另一个固定 group 的进程级 shared consumer，再向当前 SSE subscriber fanout，同一 Kafka record 不为每个浏览器重复消费。两者不读取数据库、projection inbox/checkpoint/outbox 或 snapshot，不得回写 `agentrun.event.v1`，也不得把 `codex-stdio.raw.v1` 混入 HWLAB product schema。transactional projector、projection outbox relay 和 projection realtime 是三个可独立组合的 capability，关闭时必须保持不启动、不就绪门禁、不参与产品链路。 +### 纯 Kafka 页面刷新与实时交接合同 + +- Workbench 的产品权威链固定为： + - `codex-stdio.raw.v1 -> agentrun.event.v1 -> HWLAB direct mapper -> hwlab.event.v1 retention -> bounded refresh bootstrap -> shared live fanout -> SSE -> Web ingress/reducer`； + - 用户输入必须先成为 `agentrun.event.v1` 的正式 `user_message`，再一对一映射为 `hwlab.event.v1` 的正式 user event； + - 用户消息、assistant、tool、terminal 和 final 不得另建数据库、HTTP history 或浏览器本地事实源。 +- 页面刷新只允许从 retained `hwlab.event.v1` 恢复已授权的 session/trace： + - 服务端先建立 shared live handoff 保护，再读取目标分区 end offset 作为 barrier； + - barrier 内由有界 retention bootstrap 输出，barrier 后由 shared live fanout 输出； + - overlap 只按 Kafka topic/partition/offset 与稳定 event identity 收敛； + - messageId 必须由正式 trace/item identity 派生，禁止按正文、时间戳、数组位置或 DOM 内容去重与重排。 +- refresh bootstrap 是短生命周期读取器： + - 到达 barrier 后必须退出，不得把每个浏览器连接变成新的长期 Kafka consumer； + - 实时阶段继续复用进程级 shared consumer/fanout； + - 同一 Workbench session 只建立一个产品 EventSource，刷新与重连不得复制业务 subscriber。 +- `kafkaRefreshReplay` 与 `liveKafkaSse` 是可组合、可独立开关的 capability： + - topic、group、扫描预算、等待预算、live buffer 上限和失败策略只从选中 node/lane 的 owning YAML/runtime config 读取； + - replay 与 live frame 必须进入同一 decode、queue、reducer、row model 和 card； + - barrier 不可获得、扫描或 buffer 超限、授权 scope 不完整时必须 typed fail-closed，不得回退 projector/read model/snapshot/sync/gap-fill/finalizer、polling 或 HTTP history。 +- 关闭此类问题时先用 repo-owned CLI 复用生产 bootstrap/codec/reducer，披露 scanned、matched、applied、barrier、buffered、deduplicated、terminal 与 stable identity： + - CLI 通过后，使用 semantic internal WebProbe 在同一已有 session 上执行只刷新、不提交新输入的验收； + - 刷新前后 user/agent identity 和可见顺序必须一致，retention 与产品 SSE envelope 多重集必须精确相等； + - OTel 应只出现 direct publish、shared fanout receive 和 product SSE write，projector/projection write span 必须为 0。 + 纯 Kafka 调试分成三个可复用入口，不以临时脚本作为长期路径。AgentRun 使用 `./scripts/agentrun kafka regenerate agentrun --session-id --trace-id `，从 stdio Kafka/JSONL 调用生产 reducer，只输出 `agentrun.event.debug.v1` 并明示 partial reconstruction；HWLAB 使用 `hwlab-cli kafka regenerate hwlab --from kafka|jsonl --session-id --trace-id ` 调用生产 mapper，只输出 `hwlab.event.debug.v1`。原 Workbench 页面的管理员 YAML 调试开关只在显式点击后按当前 traceId 建立唯一 debug group，清空隔离面板并复用生产 reducer/card；正式浏览器验收使用 `web-probe observe command --type validateWorkbenchKafkaDebugReplay`。typed command 继承 observer 的 YAML `internal|public` origin，不接受 URL/IP 来选择内外网。 产品实时链路的最小关闭证据必须来自一个真实 Workbench turn，并同时证明：AgentRun→HWLAB direct publish 数与 HWLAB shared fanout receive 数一致；产品 SSE 收到 terminal/final response；OTel 覆盖 `hwlab-cloud-api`、`agentrun-manager`、`agentrun-runner` 且 error=0；projection write/projector span 为 0。单步 debug 关闭证据另需证明 stdio frame→AgentRun debug→HWLAB debug→Workbench applied 的逐级 count、顺序、lineage 和 terminal，不得把 debug topic/group 冒充产品 topic/group。KafkaJS 2.2.4 `TimeoutNegativeWarning` 已由 `pikasTech/unidesk#1704` 跟踪空 pending queue 的 1ms 自循环；它不是数据丢失证据，也不得通过 suppress warning、全局 timer patch 或退回产品 polling 路径掩盖。