From 3df61369f4b135671b731fc911bed885f8c48d55 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 9 Jul 2026 20:26:03 +0200 Subject: [PATCH] docs: record HWLAB Kafka event bridge closeout --- docs/reference/hwlab.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index d281a0c2..bb3e809f 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -188,6 +188,10 @@ DeepSeek profile 应优先使用成熟 Responses/Anthropic 协议桥接方案， HWLAB 与 AgentRun 协同修复必须按 `docs/reference/agentrun.md` 的职责边界执行：AgentRun 拥有的共享执行、trace/result、backend event、runner 和 CLI 能力缺失时改 AgentRun；HWLAB 拥有的鉴权、Cloud Web/CLI 对外 API、adapter 消费、业务和前端问题改 HWLAB。不得用一侧的观测、fallback 或兼容逻辑迁就另一侧未实现或未修复的能力。 +HWLAB v0.3 订阅 AgentRun Kafka event 的权威输入是 `agentrun.event.v1`，HWLAB 转换后的权威输出是 `hwlab.event.v1`；三 topic 的平台边界和 topic ownership 统一见 `docs/reference/platform-infra.md#kafka-event-bus-boundary`。HWLAB 侧只负责消费 AgentRun manager event、投影成 `hwlab.trace.event.projected` 并发布到 HWLAB event stream，不得回写或改写 `agentrun.event.v1`，也不得把 Codex stdio raw frame 直接混入 HWLAB event schema。该桥接的 runtime 配置必须来自 NC01/v03 受控部署配置，关键 env 至少包括 Kafka enable、bootstrap servers、AgentRun event topic、HWLAB event topic、client id 和 AgentRun consumer group id；运行面关闭证据应包含 `hwlab-kafka-event-bridge-started` 日志摘要。 + +Kafka event bridge 的最小关闭证据必须同时证明源流和目标流。先用 AgentRun 原入口或既有真实 run 生成 `sessionId`/`runId`，再在 HWLAB runtime pod 内用 HWLAB CLI 查询 `kafka tail --stream agentrun --session-id `，确认 `agentrun.event.v1` 中存在 run/command 或 durable event；随后用同一 id 查询 `kafka tail --stream hwlab --session-id `，确认 `hwlab.event.v1` 中存在对应的 `hwlab.trace.event.projected`、`runId`、`commandId`、label 和 status。默认查询只输出紧凑 rows，不展开 raw value；需要排查 schema 时才使用 full/raw 形式，并继续保持 `valuesPrinted=false`。KafkaJS `TimeoutNegativeWarning` 本身不等于桥接失败；只要 bounded query 在声明 timeout 内返回并退出，warning 应登记为 KafkaJS/client 层 follow-up，而不是回滚 HWLAB bridge 或改用裸 Kafka 直连绕过 CLI。 + ### Code Agent Provider Profile 配置与验收 本小节只适用于 NC01 `v0.3` provider profile。配置必须先按 `config/hwlab-node-lanes.yaml` 解析 NC01 运行面，再读取目标 HWLAB repo 的对应规则；AgentRun 内部 Secret 物化和 backend adapter 设计仍以 AgentRun 仓库自身为准。