diff --git a/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.2_Task_Report.md b/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.2_Task_Report.md new file mode 100644 index 00000000..4840b14d --- /dev/null +++ b/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.2_Task_Report.md @@ -0,0 +1,44 @@ +# R1.2 AgentRun stdio Kafka 源码重建 CLI 报告 + +## 结论 + +已提供可直接按既有 stdio Kafka sessionId 调用生产 `CodexStdioEventReducer` 的命令： + +```bash +./scripts/agentrun kafka regenerate agentrun \ + --session-id \ + --trace-id +``` + +命令直接读取 `codex-stdio.raw.v1` 或离线 JSONL，默认只写隔离 topic `agentrun.event.debug.v1`。产品 `agentrun.event.v1` 永久禁止作为输出，无 override。 + +## 合同与实现 + +- PR: pikasTech/agentrun#278；部署 source `021db77f6e564bf73183cf53214f56e22fac0d0b`。 +- producer 生命周期修复: pikasTech/agentrun#279；部署 source `ef241221ecd1ecbecc69a294c261b9c254f67550`。 +- 输出 schema: `agentrun.event.reconstruction.v1`。 +- 重建类型: `stdio-derived partial reconstruction`。 +- 不伪造 `eventId`、`outboxSeq`、`event.id` 或完整 lifecycle；这些字段保持 `null`。 +- 严格 UUID 形式的 AgentRun session 可逆派生 HWLAB session；其他 session 只保留原始 lineage。 +- CLI 不调用 manager/runner/数据库 API。在线验证在已部署源码容器内执行只是为了使用 YAML 注入的 Kafka DNS/config，不依赖服务 HTTP 路径。 + +## 真实验证 + +冻结断点 `trc_mretx18t3jl4tg`： + +- 扫描 3611 条 Kafka record，选择 74 个 stdio frame。 +- 生成并发布 16 个 debug event，其中 terminal 1 个。 +- producer 修复上线后命令打印结果并以 exit 0 自行退出，不再需要 Ctrl-C。 + +最终新 turn `trc_mrew3yvpvv2ep6`： + +- Workbench session: `ses_63ac7b49-a693-4e1b-80c0-f45ca96c773a`。 +- stdio Kafka session: `ses_agentrun_63ac7b49_a693_4e1b_80c0_f45ca96c773a`。 +- 选择 22 个 stdio frame，生成并发布 11 个 debug event。 +- 类型分布为 `backend_status=7`、`assistant_message=3`、`terminal_status=1`。 + +定向源码回归 22/22 通过。运行面 PaC、Argo 与 manager source 均 exact 对齐 `ef241221...`。 + +## 独立支线 + +KafkaJS 2.2.4 的空 pending queue 会触发 1ms timer 自循环和负 timeout warning；它不影响本次事件计数或映射正确性，也与 producer 未释放不是同一问题。依赖硬化已由 pikasTech/unidesk#1704 独立跟踪。 diff --git a/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.3_Task_Report.md b/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.3_Task_Report.md new file mode 100644 index 00000000..87fa921b --- /dev/null +++ b/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.3_Task_Report.md @@ -0,0 +1,44 @@ +# R1.3 AgentRun 到 HWLAB Kafka 源码映射 CLI 报告 + +## 结论 + +已提供不经过 Cloud API、数据库或 transactional projector 的源码直调命令： + +```bash +bun tools/hwlab-cli/bin/hwlab-cli.ts kafka regenerate hwlab \ + --from kafka \ + --session-id \ + --trace-id \ + --input-topic agentrun.event.debug.v1 \ + --expect-count +``` + +命令复用生产 AgentRun→HWLAB mapper，输出仅允许进入 `hwlab.event.debug.v1`。`hwlab.event.v1` 永久禁止作为调试输出。 + +## 配置与隔离 + +- 实现 PR: pikasTech/HWLAB#2471，merge source `540cdba2b9e76ca5c4fd7a8f73976fb379023423`。 +- Kafka output topic 来自 `HWLAB_KAFKA_HWLAB_DEBUG_EVENT_TOPIC`。 +- Kafka group prefix 来自 `--group-prefix` 或 YAML 注入的 `HWLAB_KAFKA_HWLAB_DEBUG_GROUP_PREFIX`；Kafka 模式不存在 node/lane 硬编码 fallback。 +- topic/group 必须含独立 `debug` 标识，产品 topic/group fail closed。 +- 离线 JSONL `--no-publish` 不要求 Kafka group，也不创建 consumer/producer。 +- 重建输入继续保持 durable identity 字段为 `null`，不把 partial reconstruction 冒充 canonical event。 + +## 真实验证 + +冻结断点 `trc_mretx18t3jl4tg`： + +- 从 `agentrun.event.debug.v1` 精确匹配 16 条。 +- 映射并发布 `hwlab.event.debug.v1` 16 条。 +- `oneToOne=true`、`orderPreserved=true`、`lineagePreserved=true`。 +- artifact SHA-256: `sha256:679b9e1b84b737b758bdc2651f97c6587efddc2249993bae01316949111ce4e0`。 + +最终新 turn `trc_mrew3yvpvv2ep6`： + +- 输入 11、匹配 11、发布 11。 +- `firstSourceSeq=1`、`lastSourceSeq=11`。 +- `oneToOne=true`、`orderPreserved=true`、`lineagePreserved=true`。 +- artifact SHA-256: `sha256:f338a09e2e44c2cb5ed3f22719d1e0e2a395953b3e448655ef3fa966e573b4c6`。 +- 命令披露的依赖为 `cloudApi=false`、`database=false`、`transactionalProjector=false`、`kafka=true`。 + +源码主线回归 70/70、renderer 1/1，Workbench 组件 1/1。NC01/v03 source、PipelineRun、GitOps mirror、Argo 和 13 个 workload 已 exact 对齐最终 source `3f8b6e2f676b3354b55fd0a42b19baec73f34568`。 diff --git a/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.4_Task_Report.md b/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.4_Task_Report.md new file mode 100644 index 00000000..063bf8d8 --- /dev/null +++ b/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.4_Task_Report.md @@ -0,0 +1,50 @@ +# R1.4 Workbench 隔离 Kafka 重放报告 + +## 结论 + +原 `/workbench` 页面已增加管理员可见、YAML-first 的独立调试开关。打开开关不会消费 Kafka；只有显式点击“重放”才会： + +1. 关闭旧 EventSource 并清空隔离面板。 +2. 按当前 traceId 请求 `stream=hwlab-debug&fromBeginning=true`。 +3. 使用每次唯一的 debug consumer group 消费 `hwlab.event.debug.v1`。 +4. 复用生产 reducer、apply plan 和 `WorkbenchMessageCard` 渲染。 + +该状态与 canonical Workbench store 完全隔离，不调用 sync/snapshot/gap-fill/projector，也不会清空产品消息。 + +## 交付 + +- HWLAB 页面、SSE 与 reducer: pikasTech/HWLAB#2471。 +- 页面重载后的 session trace fallback: pikasTech/HWLAB#2472。 +- 可复用 typed probe command: pikasTech/unidesk#1703。 +- owning YAML: + - `HWLAB_WORKBENCH_KAFKA_DEBUG_REPLAY_ENABLED=true` + - `HWLAB_KAFKA_HWLAB_DEBUG_EVENT_TOPIC=hwlab.event.debug.v1` + - `HWLAB_KAFKA_HWLAB_DEBUG_GROUP_PREFIX=hwlab-v03-workbench-isolated-debug` + - replay limit 200，timeout 15000ms。 + +web-probe 使用语义化入口： + +```bash +bun scripts/cli.ts web-probe observe command \ + --type validateWorkbenchKafkaDebugReplay +``` + +命令继承 observer 的 YAML `internal|public` origin，不接受 URL/IP 选择内外网；固定输出 report/screenshot SHA 和 topic/group/trace/count。 + +## 单步验收 + +旧 session 页面重载后没有历史 trace，typed command 正确 fail-fast；未通过 snapshot 或 sync 补洞。随后按正式单步计划在同一原页面创建新 session、完成一个纯实时 turn，再生成两级 debug Kafka 流并重放当前 trace。 + +- observer: `webobs-mrew0iwd-2953f1` +- command: `cmd-mrew61bl-2c468b` +- sessionId: `ses_63ac7b49-a693-4e1b-80c0-f45ca96c773a` +- traceId: `trc_mrew3yvpvv2ep6` +- topic: `hwlab.event.debug.v1` +- groupId: `hwlab-v03-workbench-isolated-debug-1783685292280-124e132b` +- clear 前置状态: `idle`、received/applied=`0/0` +- replay 结果: received/applied=`11/11`、terminal=`completed` +- report SHA-256: `sha256:64a71b768e86586c2d2a888fbe221f03d81597752693b28b7ae1c340fc94af2d` +- screenshot SHA-256: `sha256:3dfd53d3641f2b4fd7a1eb641fcdf14206bc749bcb87ad9708617946e33d6957` +- origin: YAML `internal` / `k8s-service-cluster-ip` + +最终 UI 命令状态为 `passed`，未修改产品 topic、产品 consumer group 或 canonical store。 diff --git a/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1_Task_Report.md b/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1_Task_Report.md new file mode 100644 index 00000000..c21ff29e --- /dev/null +++ b/docs/MDTODO/details/pure-kafka-live-single-step-debug/R1_Task_Report.md @@ -0,0 +1,73 @@ +# R1 纯 Kafka 实时链路与单步调试收口报告 + +## 总结论 + +产品主线未偏离，且已在 NC01/v03 拉通： + +```text +stdio -> codex-stdio.raw.v1 +AgentRun event -> agentrun.event.v1 +HWLAB direct map/publish -> hwlab.event.v1 +shared fixed-group consumer/fanout -> SSE -> Web +``` + +产品路径保持纯实时，不使用 snapshot、sync、replay recovery、gap-fill、finalizer 或 polling。transactional projector 代码保留但关闭，不参与本次链路。 + +## 产品实时证据 + +R1.1 的冻结 trace `trc_mretx18t3jl4tg` 已证明 AgentRun/HWLAB/SSE 为 `35/35/35`，eventId/sourceEventId 顺序逐项一致，terminal 1 个。 + +最终新 trace `trc_mrew3yvpvv2ep6` 又完成一次真实 Workbench turn，最终响应为 `KAFKA_DEBUG_REPLAY_READY`。OTel 证据： + +- OTel traceId: `98854312e576a7a7a0b96ced5702d8e3`。 +- 167 spans、0 error。 +- 服务覆盖: `hwlab-cloud-api`、`agentrun-manager`、`agentrun-runner`。 +- `hwlab.kafka.live.direct_publish=30`。 +- `hwlab.kafka.live.fanout_receive=30`。 +- `hwlab.workbench.live_sse.business_event_write=60`，对应两个同时在线的产品 SSE subscriber。 +- projection writes 为空，诊断结论 `PROJECTION=none`。 + +五个独立可组合 capability 保持： + +```text +directPublish=true +liveKafkaSse=true +transactionalProjector=false +projectionOutboxRelay=false +projectionRealtime=false +``` + +固定产品 group 保持： + +```text +hwlab-v03-agentrun-event-direct-publish +hwlab-v03-agentrun-event-projector +hwlab-v03-workbench-live-sse +``` + +projector group 在关闭状态下不活跃；debug consumer 使用独立、每次唯一的 group。 + +## 单步 debug 闭环 + +| 阶段 | 输入 | 输出 | 结果 | +|---|---:|---:|---| +| AgentRun stdio 源码 reducer | 22 个选中 frame | 11 个 AgentRun debug event | terminal 1，partial lineage 明示 | +| HWLAB 生产 mapper | 11 个 AgentRun debug event | 11 个 HWLAB debug event | 11→11，顺序/lineage 保持 | +| Workbench debug SSE/card | 11 个 HWLAB debug event | 11 个 applied event | terminal completed | + +隔离 topic 为 `agentrun.event.debug.v1` 与 `hwlab.event.debug.v1`，均由 YAML 声明并使用 1 天 retention。任何调试 CLI 都禁止写产品 topic。 + +## 交付与部署 + +- 产品纯实时主线: pikasTech/HWLAB#2466。 +- AgentRun 重建 CLI 与 producer 释放: pikasTech/agentrun#278、#279。 +- HWLAB 映射 CLI、Workbench debug 与 trace fallback: pikasTech/HWLAB#2471、#2472。 +- typed web-probe command: pikasTech/unidesk#1703。 +- debug topic YAML: pikasTech/unidesk#1701。 + +最终运行面： + +- AgentRun source `ef241221ecd1ecbecc69a294c261b9c254f67550`，PaC/Argo/manager 1/1 exact。 +- HWLAB source `3f8b6e2f676b3354b55fd0a42b19baec73f34568`，PipelineRun completed，GitOps `fd0558d5a38a`，Argo Synced/Healthy，workloads 13/13。 + +KafkaJS 2.2.4 空队列 1ms 自循环属于独立依赖风险，已转 pikasTech/unidesk#1704，不影响本任务的数据正确性结论。 diff --git a/docs/MDTODO/pure-kafka-live-single-step-debug.md b/docs/MDTODO/pure-kafka-live-single-step-debug.md index 503f3f30..5c6102de 100644 --- a/docs/MDTODO/pure-kafka-live-single-step-debug.md +++ b/docs/MDTODO/pure-kafka-live-single-step-debug.md @@ -1,18 +1,18 @@ # HWLAB #2467 纯 Kafka 实时链路单步调试 MDTODO -## R1 [in_progress] +## R1 [completed] 纯 Kafka 实时链路有界闭环与独立单步调试能力，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R1_Task_Report.md)。 ### R1.1 [completed] 使用 semantic internal origin 完成最多两轮 typed web-probe 闭环；仍失败则冻结 sessionId、traceId、artifact 与首个断点，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R1.1_Task_Report.md)。 -### R1.2 [in_progress] +### R1.2 [completed] 实现 AgentRun 按已有 stdio Kafka sessionId 直接调用源码 reducer 再生 AgentRun Kafka 事件的 CLI，不依赖运行面并披露 partial lineage，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R1.2_Task_Report.md)。 -### R1.3 [in_progress] +### R1.3 [completed] 实现 HWLAB 按 sessionId 加载 AgentRun Kafka 事件并直接调用源码映射/发布 HWLAB Kafka 事件的 CLI，不依赖运行面或 projector，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R1.3_Task_Report.md)。 -### R1.4 [in_progress] +### R1.4 [completed] 在原 Workbench 页面增加独立 YAML 调试开关，支持清空隔离面板并按当前 traceId 重放 HWLAB Kafka→SSE→生产卡片 reducer，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R1.4_Task_Report.md)。 \ No newline at end of file