root
49 lines
3.1 KiB
Markdown
49 lines
3.1 KiB
Markdown
# 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 优先读取 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 输入默认只做映射预检和本地证据固化；
|
||
- 只有显式 `--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。
|