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

Kafka 源码直连调试

• hwlab-cli kafka regenerate hwlab 用于把指定 AgentRun session 的事件直接映射为 HWLAB debug 事件：

  • 调用生产路径同源的 AgentRun 解码与 HWLAB 事件映射函数；
  • 不启动 Cloud API；
  • 不访问数据库；
  • 不依赖 transactional projector；
  • 默认输出到 hwlab.event.debug.v1，并禁止写入产品 topic hwlab.event.v1。

• Kafka 输入适合验证真实 topic 中的 session 事件：

  • 命令为 hwlab-cli kafka regenerate hwlab --from kafka --session-id <sessionId>；
  • 默认输入 topic 为 agentrun.event.debug.v1；
  • 产品 canonical 输入可显式指定 --input-topic agentrun.event.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；
  • Workbench 消费 debug topic 由 HWLAB_WORKBENCH_KAFKA_DEBUG_REPLAY_ENABLED 独立控制；
  • CLI 的离线映射不依赖该运行面开关；
  • Kafka 输入默认发布到独立 HWLAB debug topic；
  • --no-publish 可只生成本地证据。

• JSONL 输入适合完全离线的单步测试：

  • 命令为 hwlab-cli kafka regenerate hwlab --from jsonl --session-id <sessionId> --jsonl-file <path> --no-publish；
  • 每行可直接放 envelope，也可使用 {topic,partition,offset,key,value,headers} transport wrapper；
  • JSONL 输入默认不连接 Kafka；
  • 完整映射结果写入 .state/hwlab-cli/kafka-debug/ 下的 JSONL artifact；
  • --output-jsonl 可显式选择 artifact 路径。

• 输入合同按来源隔离：

  • agentrun.event.v1 必须通过严格 canonical decoder；
  • agentrun.event.reconstruction.v1 只允许进入 debug decoder；
  • stdio reconstruction 的 eventId、outboxSeq、originalEventId 和 originalOutboxSeq 必须保持 null；
  • reconstruction 必须声明 stdio-derived partial reconstruction；
  • reconstruction 必须保留 identityDerivation，禁止静默猜测 HWLAB session identity。

• 输出验证采用一对一和原序映射：

  • --expect-count <n> 在映射和发布前锁定输入数量；
  • 命令验证 source sequence、trace、raw AgentRun session、派生 HWLAB session 和源消息哈希；
  • 默认输出为 compact text；
  • 只有显式 --json 才输出结构化 JSON；
  • 成功和失败都返回可执行的 next hint。