mirrors/pikasTech-HWLAB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 收口纯 Kafka 单步调试任务

Browse Source
This commit is contained in:
root
2026-07-10 14:12:37 +02:00
parent 3f8b6e2f67
commit 2f2b2a054c
5 changed files with 215 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.2_Task_Report.md
+44
View File
@@ -0,0 +1,44 @@
# R1.2 AgentRun stdio Kafka 源码重建 CLI 报告
## 结论
已提供可直接按既有 stdio Kafka sessionId 调用生产 `CodexStdioEventReducer` 的命令：
```bash
./scripts/agentrun kafka regenerate agentrun \
--session-id <ses_agentrun_...> \
--trace-id <trc_...>
```
命令直接读取 `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 独立跟踪。
docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.3_Task_Report.md
+44
View File
@@ -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 <ses_agentrun_...> \
--trace-id <trc_...> \
--input-topic agentrun.event.debug.v1 \
--expect-count <n>
```
命令复用生产 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`。
docs/MDTODO/details/pure-kafka-live-single-step-debug/R1.4_Task_Report.md
+50
View File
@@ -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 <observer> \
--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。
docs/MDTODO/details/pure-kafka-live-single-step-debug/R1_Task_Report.md
+73
View File
@@ -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，不影响本任务的数据正确性结论。
docs/MDTODO/pure-kafka-live-single-step-debug.md
+4 -4
View File
@@ -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)。