fix: 修复纯 Kafka Trace 实时可见性

docs/reference/kafka-source-direct-debug.md

@@ -1,5 +1,50 @@
 # Kafka 源码直连调试
 
+- `hwlab-cli kafka render trace` 用于把持久 HWLAB Kafka 事件直接渲染为与 Web 同构的 Markdown Trace：
+  - 命令为 `hwlab-cli kafka render trace --from kafka --trace-id <traceId> --format markdown`；
+  - 默认输入 topic 优先读取 owning YAML 注入的 `HWLAB_KAFKA_EVENT_TOPIC`；
+  - 未注入时使用 canonical `hwlab.event.v1`；
+  - Kafka 读取必须使用 `--group-prefix` 或 owning YAML 注入的 `HWLAB_KAFKA_HWLAB_DEBUG_GROUP_PREFIX`；
+  - group prefix 必须标识独立 debug group，不复用产品 consumer group；
+  - 命令只读取 Kafka，不发布事件，不启动 Cloud API，不访问数据库，也不依赖 projector。
+
+- Trace 渲染与 Web 共享最后一个展示分叉之前的生产管线：
+  - JSON frame 使用 `decodeWorkbenchRealtimeEventFrame` 解码；
+  - 事件使用 `reduceWorkbenchRealtimeEvent` 与 `planWorkbenchRealtimeApply` 分类；
+  - 卡片使用 `projectWorkbenchLiveKafkaMessage` 增量归约；
+  - Trace 行使用 `traceDisplayRows` 生成同一 row model；
+  - Web 最后渲染 HTML，CLI 最后使用 `renderTraceRowsMarkdown` 渲染 Markdown；
+  - Final Response 只放在 Trace 外层，Trace 内保留非最终的助手进展消息。
+
+- Kafka Trace 查询必须披露有界扫描事实：
+  - `--run-id` 与 `--command-id` 用于在复用或异常混合的 traceId 内精确隔离一轮；
+  - `--command-id` 先按 trace、session 与 run 读取基础流，再在 CLI 内形成 command 生命周期；
+  - 只有基础流中至少存在一条精确 commandId 事件，才允许吸附同一 run 的无 commandId final/terminal；
+  - 精确 commandId 不存在时必须返回 `source_command_missing`，不得由 commandless 生命周期冒充成功；
+  - 精确 command 事件保留；
+  - 同一 run 中缺少 commandId 的 final/terminal 生命周期事件保留；
+  - 其他 command 和无法归属的 commandless 事件排除；
+  - 禁止把 commandId 直接下推后丢失 run-scoped terminal/final；
+  - identity 输出必须同时披露观测到的 session、run、command 和 source event 去重计数；
+  - command scope 输出必须披露每个 commandId 的计数、缺失 commandId 数、可归属生命周期数、歧义数与排除数；
+  - command 生命周期只有在 `scanComplete=true` 时才可判定完整；
+  - `limit` 或 `timeout` 只能作为部分流证据，`commandLifecyclePreserved` 必须保持 false；
+  - 输出 `scannedCount`、`parsedCount`、`matchedCount`、`invalidJsonCount` 与 `filterRejectedCount`；
+  - 输出 topic end offsets、最后扫描 offsets 与 `completionReason`；
+  - `completionReason=end-offset` 表示已经扫描到命令启动时捕获的 Kafka 上界；
+  - `completionReason=limit` 表示达到显式事件上限，不能冒充完整 trace；
+  - `completionReason=timeout` 表示未在 YAML 或 CLI 时限内证明到达上界；
+  - 没有匹配事件时以 `source_trace_missing` 失败，并保留上述扫描计数。
+
+- Trace Markdown artifact 默认写入 `.state/hwlab-cli/kafka-render/`：
+  - `--output-markdown` 可显式选择路径；
+  - `--from jsonl --jsonl-file <path>` 可完全离线复用同一管线；
+  - 默认文本输出保持 compact；
+  - 默认 JSON 只返回 `--row-limit` 指定的尾部行，并披露 returned/omitted/window；
+  - `--full` 仅用于显式下钻完整 row payload；
+  - `--format markdown` 输出 Markdown 正文；
+  - `--json` 输出身份、投影、row model、终态、计数和 artifact SHA 的结构化证据。
+
 - `hwlab-cli kafka regenerate hwlab` 用于把指定 AgentRun session 的事件直接映射为 HWLAB debug 事件：
   - 调用生产路径同源的 AgentRun 解码与 HWLAB 事件映射函数；
   - 不启动 Cloud API；