root
4.2 KiB
4.2 KiB
R2.3 隔离 Kafka 重放分层诊断任务报告
上下文
- 主问题：
- 隔离重放专项：
完成结果
- AgentRun 到 HWLAB 的 debug producer 增加批次关联合同：
- 每批生成或接受一个
replayId； - 每个
hwlab.event.debug.v1envelope 保留replayId、批次序号和原始 AgentRun lineage； - 正常 Kafka 调试默认读取 canonical
agentrun.event.v1； agentrun.event.debug.v1仅由调用方显式选择，用于 stdio partial reconstruction；- Kafka 读取只做映射预检，发布必须显式指定
--publish。
- 每批生成或接受一个
- debug producer 形成确定的输出 barrier：
- 只向 YAML 指定的隔离 debug topic 发布；
- 所有批次记录固定写入 debug topic 的 partition 0；
- 由 Kafka publish metadata 返回
firstOffset、lastOffset和count； - 发布后无法形成唯一 offset range 时，以
debug_publish_barrier_missing失败关闭。
- correlated v2 consumer 直接定位该 barrier：
- 新 group 完成 assignment 后执行
seek(firstOffset)，不从增长中的 debug topic 起点盲扫； - 观测
lastOffset后立即形成完成/停止边界； - 缺首尾 offset、缺中间 offset、重复 offset、parse/filter/delivery 少于整批 cardinality 均不能得到
terminal_complete； - 未携带 v2 参数时保留明确的
trace-only-v1诊断；出现任一 v2 参数时必须同时具备安全replayId和完整 offset range，显式 producer/source 失败证据不得降级成功。
- 新 group 完成 assignment 后执行
- debug SSE 在 JSON parse 和 trace/replay filter 前采集 broker 事实：
- 报告
scanned、barrierScanned、parsed、traceMatched、replayMatched、matched和delivered； - 分别保留 requested、scanned、matched 和 delivered offset range；
- completion 保留第一条匹配事件的脱敏 source lineage；
- 服务端明确声明 client counts unavailable；
clientReceived、decoded和applied保持null，不伪造浏览器成功计数。
- 报告
- 新增分层结果合同：
- producer/source：
producer_not_invoked、source_trace_missing； - Kafka/server：
topic_no_append_for_replay、record_parse_rejected、records_scanned_but_filter_mismatch、sse_write_failed； - client：
transport_failed、decoder_rejected、reducer_rejected； - terminal：
terminal_missing、terminal_complete。
- producer/source：
- 输入合同失败关闭：
- 不完整或逆序 offset range 返回
workbench_kafka_debug_offset_range_invalid； - 非
rpl_安全标识返回workbench_kafka_debug_replay_id_invalid； - product topic 和 product group 继续禁止作为隔离 debug 资源。
- 不完整或逆序 offset range 返回
验证
- 定向命令：
bun test \
internal/cloud/workbench-kafka-debug-replay-contract.test.ts \
internal/cloud/workbench-kafka-sse-debug.test.ts \
internal/cloud/kafka-event-bridge.test.ts \
tools/hwlab-cli/kafka-regenerate.test.ts
- 结果：
50 pass；0 fail。
- 已覆盖四类 MDTODO 验收结果：
- empty：
producer_not_invoked； - matched-no-terminal：
terminal_missing； - reducer-rejected：
reducer_rejected； - terminal-complete：
terminal_complete。
- empty：
- 产品路径回归：
hwlab与stdiodiagnostic stream 既有测试通过；- live Kafka direct publish/fanout 测试通过；
- 未启用 projector、read model、snapshot、sync、recovery replay 或 polling。
边界与后续集成
- 本子任务未部署或修改 NC01/v03 运行面。
- 集成分支已让 UI 支持透传
replayId/outputBarrier，并用同一 EventSource 的本地received/decoded/applied对服务端结果二次复判；四层计数不严格相等时分别返回 transport、decoder 或 reducer typed failure。 - debug topic、debug group 和结果合同仍只属于隔离调试，不接入产品实时事实源。
- 真实 Kafka
seek行为与浏览器分层计数仍须由 R2.4 在 NC01/v03 原入口受控验收。