[AutumnNazi]

背景

Kafka 单条消息可达十几 MB（实测 15,505,118 字节）。此前列表预览会把 payload 连同
flattenKafkaMap 展开出来的 value.xxx 列一起塞进每一行，单行 JSON 接近 30 MB，
直接顶满驱动代理 32 MiB 的单帧上限：

• 预览流中途中断——topic 明明有很多消息，列表却只出几条；
• 详情面板对十几 MB 内容做 JSON.parse + 缩进美化，界面卡死。

另外发现两处放大问题：conn.ReadMessage 内部是「每次新发一次 fetch，只取第一条，
丢弃批内其余消息」，等于一条一个网络来回；预览的 1500 ms 又是整个拉取的硬超时，
大消息读两三条就被截断。

变更点

驱动（kafka 专属）

• SELECT 支持列投影；WHERE partition = ? AND offset = ? 精确定位单条；新增
  FetchMessageAt 按定位读取；大 payload 不再展开成 value.xxx 列
• 预览读取改为按批消费（ReadBatch 读完批内消息），单次 fetch 上限 1 MiB → 16 MiB
• 预览读取改为空闲超时：每读一条重置窗口，ctx 30 秒仍是硬上限

客户端（不参与 agent 指纹）

• 收到「单帧超限」失败帧时不再终止 transport：一条超大消息不再让整个连接永久不可用；
  单帧上限维持 32 MiB 不变

前端

• Kafka 预览命令改为 SELECT timestamp, partition, offset, key, value_size
• 点击消息即按 partition+offset 拉取完整内容并缓存；「跟随最新消息」自动选中的那条同样触发加载
• 详情加载失败会给出错误提示，不再静默留白
• 超过 512 KB 的详情跳过 JSON 美化；列表卡片合并为单行展示 topic · #offset · 大小
• 详情头部时间并入右侧；加载态改骨架屏并显示消息大小，加载完成无布局跳动

i18n：补充加载/失败文案（6 个语言），同步 catalog.zip。

影响范围

• 列表帧从「每行十几 MB」降到几十字节，展示条数不再受单帧上限影响
• 详情按需拉取，单条消息（含十几 MB payload）仍在 32 MiB 之内
• 其余 25 个驱动行为与指纹均不变（改动全部落在 kafka 专属文件与客户端侧）
• 预览不再使用 consumer group（预览本就不该提交消费进度），仍保留其格式校验

验证

gofmt -l  → 无输出
go vet -tags gonavi_kafka_driver ./internal/db/  → 通过
go build -tags gonavi_kafka_driver ./internal/db/ ./cmd/optional-driver-agent/  → 通过
go test -tags gonavi_kafka_driver ./internal/db -run "TestKafka|TestParseKafkaSQL|TestOptionalDriverAgent"  → ok
go test ./cmd/optional-driver-agent/...  → ok
tsc --noEmit  → 通过
vitest run MessageQueueWorkbench + messageQueue  → 34 passed
i18n 六语言键数一致  → 12837

新增用例覆盖：列投影与定位解析、投影模式丢弃 payload、超大 payload 不展开、
详情命令构造、卡片摘要回退、字节大小格式化。

指纹表相对 origin/dev 只差 kafka 一行（src-11e403fa66ffcdb4），其余 25 个驱动不变。

需要重建 agent

改动包含 agent 侧逻辑，kafka 指纹已更新。重启 GoNavi 后首次连接 Kafka 会自动重建 agent；
其它驱动的 agent 不受影响。

[github-actions]

变更概览

• 变更规模：24 个文件，+661 / -84（大型变更）
• 测试行占比：37%（测试 +226 / 源码 +377）
• 规约扫描覆盖：65%（逐行扫描 435 / 新增 661，测试与生成文件只做文件级检查）
• 规约命中：需要处理 0 · 建议 1
• i18n 同步：100%（6/6 语言已更新）

建议

• frontend/src/components/messageQueue/MessageQueueStreamPane.tsx：界面文案请走 shared/i18n 的 t()，不要在组件里写死中文。

模型评审

模型评审本次不可用：groq: 模型接口返回 HTTP 413

CI 门禁

• CI Gate：已跳过
  • Frontend clean build：已跳过
  • Full backend suite：进行中
  • Platform-sensitive tests (${{ matrix.os }})：已跳过
  • Platform-sensitive tests (macos-latest)：进行中
  • Platform-sensitive tests (windows-latest)：进行中
  • Plugin and marketplace contract tests：进行中

门禁未通过。

规约意见不会代替 CI 门禁。这条评论会在后续推送和测试完成后更新。