docs: 校正 HWLAB 纯 Kafka 实时权威

docs/reference/hwlab.md

@@ -78,6 +78,8 @@ Code Agent trace 的长期 API 和 Web 行为规格以 UniDesk OA 为权威：AP
 
 实时 Trace 展示必须把 turn 状态和 trace event 分页视为两条独立读路径。`/v1/agent/turns/:traceId` 只回答 running/terminal/final/error 等 turn 状态；`/v1/agent/traces/:traceId` 只负责按下游读 cursor 拉取已经持久化的 trace events。Web 在运行中不能等 turn terminal 后才 hydrate trace，也不能让 compact turn snapshot 覆盖已经拉到的 trace rows。后端刷新 AgentRun 上游失败时，trace API 仍应返回本地 trace store 中已有的分页快照，并把 refresh failure 作为诊断字段暴露；已有事件不得被硬 502 遮住。关闭“运行中 Trace 加载不出”类 issue 时，应证明 running 期间 trace API 与 Web DOM 都能看到已写入事件，而不是只展示最终完成后的 timeline。
 
+下面三段 projection/read-model 规则只适用于 YAML 独立启用 `transactionalProjector`、`projectionOutboxRelay` 或 `projectionRealtime` 的能力组合。它们不是 NC01/v03 纯 Kafka 产品实时链路的默认权威，也不得用来要求 `directPublish + liveKafkaSse` 模式补 snapshot、sync、replay、gap-fill、finalizer 或 polling；当前 capability 值必须从选中 lane YAML 和运行时 status 读取。
+
 Workbench projection/read model 是持久化投影，不是 GET 侧隐式修复路径。Cloud API 重启、内存 finalizer 丢失或投影 worker 中断后，恢复只能由受控后台 projector/resumer 从 durable session、durable trace 和 AgentRun source cursor 继续推进；`/v1/agent/turns/:traceId`、`/v1/agent/traces/:traceId` 和 Web hydrate 不得为了让一次读取看起来正确而隐藏写入或 remap command。排查“AgentRun 已完成但 Workbench 仍 running/pending”时，先比较 AgentRun command result/session terminal、AgentRun raw event 最大 `sourceSeq`、HWLAB durable trace 最大 `sourceSeq` 和 session/turn 投影状态；若 AgentRun 已 terminal 且 HWLAB trace 落后，应归为 HWLAB projection resume gap，并用 YAML-first 配置的 projector/resumer 修复与验收。
 
 Workbench 投影相关问题的禁用模式以 HWLAB issue 历史为判定边界。`pikasTech/HWLAB#1585` 已证明 GET/read-side 补 AgentRun result 会把恢复能力藏进一次读取，Cloud API 重启、rollout 或内存 finalizer 丢失后仍会让 Workbench 长期停在旧 `lastProjectedSeq`；因此“事后修补/0repair”不能替代 durable projector/resumer。`pikasTech/HWLAB#1596` 已证明 turn/card completed 与 TraceEventPage 不一致会直接变成用户可见的“已完成但暂无可读 Trace”；因此不能让 AgentRun raw result、session summary、turn snapshot、trace tail 或 DOM 互相竞争，再用优先级规则仲裁显示状态。`pikasTech/HWLAB#1690` 进一步固定 Trace 视觉顺序权威：`projectedSeq` 必须由 durable projection 幂等分配，局部 `event.seq`、`sourceSeq`、输入顺序和 renderer 文本匹配不能参与视觉位置仲裁；历史 collision 应暴露为 projection blocker，而不是交给读侧重排。读侧也不得从 event `completed`、message text、elapsed timeout 或 final result cache 推测 lifecycle；这些只能作为诊断输入，最终事实必须由唯一 Workbench projection 写出。具体 Web/CLI renderer 和 web-probe 验收口径统一见 `$unidesk-webdev`。
@@ -192,11 +194,11 @@ 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` 日志摘要。
+HWLAB v0.3 订阅 AgentRun Kafka event 的权威输入是 `agentrun.event.v1`，内存 direct mapper 的权威输出是 `hwlab.event.v1`；三 topic 的 ownership 统一见 `docs/reference/platform-infra.md#kafka-event-bus-boundary`。`directPublish` 使用固定独立 group 消费 AgentRun event、调用生产 mapper 并直接发布完整 HWLAB envelope；`liveKafkaSse` 使用另一个固定 group 的进程级 shared consumer，再向当前 SSE subscriber fanout，同一 Kafka record 不为每个浏览器重复消费。两者不读取数据库、projection inbox/checkpoint/outbox 或 snapshot，不得回写 `agentrun.event.v1`，也不得把 `codex-stdio.raw.v1` 混入 HWLAB product schema。transactional projector、projection outbox relay 和 projection realtime 是三个可独立组合的 capability，关闭时必须保持不启动、不就绪门禁、不参与产品链路。
 
-Workbench 调试页的 Kafka SSE 子标签是三流实时观察入口。按 Workbench `traceId` 调试时，Cloud API 会先从本进程 Workbench trace store 解析 AgentRun `runId`/`commandId`，再用实际 Kafka 维度订阅 `codex-stdio.raw.v1`、`agentrun.event.v1` 和 `hwlab.event.v1`；SSE connected payload 必须同时暴露用户输入的 `filters` 和后端实际使用的 `resolvedFilters`，方便判断空流是关联字段缺失、上游未产生日志，还是订阅失败。若 `agentrun` 与 `hwlab` 流命中但 `stdio` 流为空，优先核对该 AgentRun command 是否真实进入 runner 并产生 stdio raw frame；不要把 stdio 空列表误判为调试页或 SSE 透传失败。
+纯 Kafka 调试分成三个可复用入口，不以临时脚本作为长期路径。AgentRun 使用 `./scripts/agentrun kafka regenerate agentrun --session-id <ses_agentrun_...> --trace-id <trc_...>`，从 stdio Kafka/JSONL 调用生产 reducer，只输出 `agentrun.event.debug.v1` 并明示 partial reconstruction；HWLAB 使用 `hwlab-cli kafka regenerate hwlab --from kafka|jsonl --session-id <id> --trace-id <id>` 调用生产 mapper，只输出 `hwlab.event.debug.v1`。原 Workbench 页面的管理员 YAML 调试开关只在显式点击后按当前 traceId 建立唯一 debug group，清空隔离面板并复用生产 reducer/card；正式浏览器验收使用 `web-probe observe command <observer> --type validateWorkbenchKafkaDebugReplay`。typed command 继承 observer 的 YAML `internal|public` origin，不接受 URL/IP 来选择内外网。
 
-Kafka event bridge 的最小关闭证据必须同时证明源流和目标流。先用 AgentRun 原入口或既有真实 run 生成 `sessionId`/`runId`，再在 HWLAB runtime pod 内用 HWLAB CLI 查询 `kafka tail --stream agentrun --session-id <sessionId>`，确认 `agentrun.event.v1` 中存在 run/command 或 durable event；随后用同一 id 查询 `kafka tail --stream hwlab --session-id <sessionId>`，确认 `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。
+产品实时链路的最小关闭证据必须来自一个真实 Workbench turn，并同时证明：AgentRun→HWLAB direct publish 数与 HWLAB shared fanout receive 数一致；产品 SSE 收到 terminal/final response；OTel 覆盖 `hwlab-cloud-api`、`agentrun-manager`、`agentrun-runner` 且 error=0；projection write/projector span 为 0。单步 debug 关闭证据另需证明 stdio frame→AgentRun debug→HWLAB debug→Workbench applied 的逐级 count、顺序、lineage 和 terminal，不得把 debug topic/group 冒充产品 topic/group。KafkaJS 2.2.4 `TimeoutNegativeWarning` 已由 `pikasTech/unidesk#1704` 跟踪空 pending queue 的 1ms 自循环；它不是数据丢失证据，也不得通过 suppress warning、全局 timer patch 或退回产品 polling 路径掩盖。
 
 ### Code Agent Provider Profile 配置与验收