fix: 增加隔离 Kafka 重放分层诊断

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

@@ -9,15 +9,17 @@
 
 - Kafka 输入适合验证真实 topic 中的 session 事件：
   - 命令为 `hwlab-cli kafka regenerate hwlab --from kafka --session-id <sessionId>`；
-  - 默认输入 topic 为 `agentrun.event.debug.v1`；
-  - 产品 canonical 输入可显式指定 `--input-topic agentrun.event.v1`；
+  - 默认输入 topic 优先读取 owning YAML 注入的 `HWLAB_KAFKA_AGENTRUN_EVENT_TOPIC`；
+  - 未注入时默认读取 canonical `agentrun.event.v1`；
+  - stdio partial reconstruction 必须显式指定 `--input-topic agentrun.event.debug.v1`；
   - output topic 优先读取 owning YAML 注入的 `HWLAB_KAFKA_HWLAB_DEBUG_EVENT_TOPIC`；
   - consumer group prefix 优先读取 owning YAML 注入的 `HWLAB_KAFKA_HWLAB_DEBUG_GROUP_PREFIX`；
-  - 未注入时使用离线合同值 `hwlab.event.debug.v1` 与 `hwlab-v03-workbench-isolated-debug`；
+  - output topic 未注入时使用隔离合同值 `hwlab.event.debug.v1`；
+  - Kafka 读取或发布缺少 group prefix 时失败关闭，不生成代码内运维默认值；
   - Workbench 消费 debug topic 由 `HWLAB_WORKBENCH_KAFKA_DEBUG_REPLAY_ENABLED` 独立控制；
   - CLI 的离线映射不依赖该运行面开关；
-  - Kafka 输入默认发布到独立 HWLAB debug topic；
-  - `--no-publish` 可只生成本地证据。
+  - Kafka 输入默认只做映射预检和本地证据固化；
+  - 只有显式 `--publish` 才发布到独立 HWLAB debug topic。
 
 - JSONL 输入适合完全离线的单步测试：
   - 命令为 `hwlab-cli kafka regenerate hwlab --from jsonl --session-id <sessionId> --jsonl-file <path> --no-publish`；
@@ -35,6 +37,11 @@
 
 - 输出验证采用一对一和原序映射：
   - `--expect-count <n>` 在映射和发布前锁定输入数量；
+  - 每次预检生成 `replayId`，也可用 `--replay-id rpl_...` 显式复用同一批次标识；
+  - `next.command` 保留同一个 `replayId`，用于先预检、再显式发布；
+  - 发布固定使用隔离 debug topic 的 partition 0；
+  - 成功发布必须从 Kafka metadata 形成 `firstOffset`、`lastOffset` 和 `count` barrier；
+  - 无法形成唯一 barrier 时以 `debug_publish_barrier_missing` 失败关闭；
   - 命令验证 source sequence、trace、raw AgentRun session、派生 HWLAB session 和源消息哈希；
   - 默认输出为 compact text；
   - 只有显式 `--json` 才输出结构化 JSON；