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

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。

• hwlab-cli kafka inspect order 用于定位同一 session 在纯 Kafka 刷新链路中的首个顺序分歧：

  • 已知 session 时使用 --session-id <sessionId>；
  • 只知道用户输入时使用 --contains-text <bounded-user-text> 从 HWLAB retention 解析唯一 session；
  • 文本发现只披露长度和 SHA-256，不回显用户正文；
  • 命令分别扫描 agentrun.event.v1 与 hwlab.event.v1 到启动时捕获的 topic 上界；
  • hwlabSessionId 及其 snake case 形式属于两个 topic 共用的正式 session identity 候选；
  • HWLAB retained event 复用生产 refresh handoff、SSE frame 解码、queue/reducer 和 timeline row model；
  • 输出逐层 transport、stable identity、sourceSeq、message index 和 DOM row index；
  • firstDivergence 只报告首个改变顺序的层，不过滤、重排或补写任何事件；
  • --row-limit 只限制返回的有界尾部明细，不改变全量计数和判定；
  • 任一 topic 未到捕获上界时返回 partial/source_scan_incomplete，禁止根据部分扫描下结论；
  • 命令只读取既有 Kafka retention，不发布事件，也不启动新的 AgentRun。

• Trace 渲染与 Web 共享最后一个展示分叉之前的生产管线：

  • JSON frame 使用 decodeWorkbenchRealtimeEventFrame 解码；
  • 事件使用 reduceWorkbenchRealtimeEvent 与 planWorkbenchRealtimeApply 分类；
  • 卡片使用 projectWorkbenchLiveKafkaMessage 增量归约；
  • Trace 行使用 traceDisplayRows 生成同一 row model；
  • assistant、tool 与 terminal 使用同一稳定 item lifecycle 收敛可见行；
  • 同一 itemId 已出现 completed-agent-message 后到达的 agent-message-delta-progress 不再生成第二条 assistant row；
  • lifecycle 收敛只影响可见行，不删除 source/applied 事件，也不使用正文、时间戳或 DOM 去重；
  • 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 时限内证明到达上界；
  • 未到捕获上界时，Trace 命令必须返回 status=partial、ok=false、source_scan_incomplete 和非零退出码，同时保留有界 Markdown artifact 供下钻；
  • 默认文本首词必须是 partial，并披露 completionReason 与 reachedEndOffsets，禁止用 ok 或 succeeded 表示部分扫描；
  • 没有匹配事件时以 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 的结构化证据；
  • replayLineage 分别披露 source、applied、render 与 outer final 层的计数；
  • 助手重复只披露正文 SHA-256、首次 identity、sourceSeq 和 Kafka transport，不回显正文；
  • source/applied 重复保持可见而 render 重复归零时，表示稳定 item lifecycle 已在共享 row model 收敛。

• 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 优先读取 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；
  • output topic 未注入时使用隔离合同值 hwlab.event.debug.v1；
  • Kafka 读取或发布缺少 group prefix 时失败关闭，不生成代码内运维默认值；
  • Workbench 消费 debug topic 由 HWLAB_WORKBENCH_KAFKA_DEBUG_REPLAY_ENABLED 独立控制；
  • CLI 的离线映射不依赖该运行面开关；
  • Kafka 输入默认只做映射预检和本地证据固化；
  • Kafka 输入未扫描到命令启动时捕获的 topic 上界时返回 partial/source_scan_incomplete，保留 artifact，但即使指定 --publish 也不得调用 producer；
  • 只有显式 --publish 才发布到独立 HWLAB debug topic。

• 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> 在映射和发布前锁定输入数量；
  • 每次预检生成 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；
  • 成功和失败都返回可执行的 next hint。