docs(mdtodo): close pure Kafka replay correctness R5

2026-07-11 22:00:12 +02:00
parent 537dce97cc
commit 3c0ff62c14
5 changed files with 133 additions and 4 deletions
@@ -0,0 +1,44 @@
+# R5.1 任务报告：纯 Kafka 刷新顺序与稳定身份收口
+
+## 上下文
+
+- [HWLAB #2498](https://github.com/pikasTech/HWLAB/issues/2498)
+- [AgentRun #297](https://github.com/pikasTech/agentrun/issues/297)
+- [AgentRun #299](https://github.com/pikasTech/agentrun/issues/299)
+
+## 根因与修复
+
+1. AgentRun 初始生命周期事件可能先于正式用户输入事件发布，导致源端已经形成用户/代理反序。AgentRun PR #298（merge `85a913`）把用户输入作为 `agentrun.event.v1` 正式事件，并保证它先于同轮 run-created。
+2. stdio producer 在分配 `frameSeq` 后并发 fire-and-forget `producer.send`，同 partition 可出现 `5→4`、`7→6` 等真实 Kafka 反序。AgentRun PR #300（merge `07aa6b56335c710e9a0ea1b592a30f03a8ea9a15`）增加每个 publisher 独立的 Promise tail；失败不毒化后续发送，关闭阶段排空当前与 retired publisher。未增加全局队列或下游重排。
+3. Web optimistic/live identity 与 retention replay identity 不一致，使刷新后同一消息不能稳定收敛。HWLAB PR #2507（merge `537dce97cc457...`）统一采用 trace 派生的正式 messageId，未增加正文、时间戳或 DOM 去重。
+
+以上变更均由 PR merge 后的自动 CI/CD 链路交付；AgentRun 与 HWLAB 的 Argo 状态均为 `Synced/Healthy`、runtime `1/1 ready`、source relation `exact`。
+
+## 纯 Kafka 实时验收
+
+- Observer：`webobs-mrgs7bsm-a21bc8`
+- Command：`cmd-mrgs7itk-cc7434`
+- Session：`ses_4b7ed4bf-65a0-4dcc-8024-cd4162f26b52`
+- Trace：`trc_mrgs848auq9lmk`、`trc_mrgs97sctjnqo6`
+- Report SHA256：`329f422acf7f2c3ab34ce20adc78120d60804fb14f37e1ecbb59952f374e905d`
+
+两轮 stdio `frameSeq` 分别为 `1..36` 与 `1..23` 严格递增；AgentRun → HWLAB 的 event/sourceEventId lineage 与 Kafka/SSE fingerprint 精确一致。A/B subscriber 的 replay-live handoff 中 buffered、live-delivered、deduplicated 均为 0；页面只建立一个 session-scoped EventSource，两个 terminal 均由同页正式 reducer 渲染，禁用请求为 0。
+
+## 同 session 刷新验收
+
+- Command：`cmd-mrgsc5ps-34fdcd`
+- Report SHA256：`d80f149b73c5536773d257a0f3c695b5cca14bdc7c84471975497cb1f911cade`
+- Screenshot SHA256：`67a50a7d8bbe853694dcc084927227e09e3bf51463944faeda61c458694ff5c9`
+
+刷新前后消息均为 4 条，稳定 identity 与 DOM 顺序完全相同：
+
+1. `user:msg_mrgs848auq9lmk_user:trc_mrgs848auq9lmk`
+2. `agent:msg_mrgs848auq9lmk_agent:trc_mrgs848auq9lmk`
+3. `user:msg_mrgs97sctjnqo6_user:trc_mrgs97sctjnqo6`
+4. `agent:msg_mrgs97sctjnqo6_agent:trc_mrgs97sctjnqo6`
+
+Kafka retention matched/replayed 为 `53/53`；buffered、bufferedDelivered、liveDelivered、deduplicated 均为 0；正式 SSE business event 为 53，失败与禁用请求均为 0。
+
+## 结论
+
+用户第一条消息在实时与刷新后均稳定位于对应 agent 消息之前。修复发生在正式事件产生、producer 顺序和正式 identity 层，没有引入 projector/read model/snapshot/sync/gap-fill/finalizer、HTTP history fallback、下游重排或补洞。
@@ -0,0 +1,27 @@
+# R5.2 任务报告：Tool summary 可见行精简
+
+## 上下文
+
+- [HWLAB #2499](https://github.com/pikasTech/HWLAB/issues/2499)
+- HWLAB PR #2506，merge `ce313129`
+
+## 结果
+
+TraceTimeline 与 CLI 共用的 row model 已收敛为“时间 + 实际命令”。例如：
+
+`18:20:09 sed -n ...`
+
+可见行不再重复显示工具名、`ok/fail/running`、`total`、`duration`、`exit` 或 output 摘要。运行、成功、失败状态仅由整行颜色和运行中动效表达，同时保留非可见 ARIA 语义。
+
+HTML 与 Markdown 仍共享同一业务 renderer/row model，只在最终 HTML/Markdown 输出层分叉；未引入独立前端解释路径。
+
+## 验证
+
+- 固定 trace 的 CLI 同构 Markdown artifact SHA256：`c09565402844d8b34cf3990fc6e414b41d367fda4305cf772c1b8ab458ac5211`
+- Web/CLI 定向测试通过。
+- PR merge 后由自动 CI/CD 完成交付；未使用手工 mirror、PipelineRun、sync 或补触发。
+- 最终纯 Kafka 实时与刷新验收复用了该 renderer，页面 session/traces 正常完成，未出现 summary 造成的行身份或顺序变化。
+
+## 结论
+
+用户要求的高频 summary 已简化为单行命令可读形式；状态信息不再以冗余文字挤占可见空间。
@@ -0,0 +1,29 @@
+# R5.3 任务报告：临近终态 assistant 重复收口
+
+## 上下文
+
+- [HWLAB #2500](https://github.com/pikasTech/HWLAB/issues/2500)
+- 固定 trace：`trc_535e95438f144922`
+- HWLAB PR #2502，merge `b1bfe6679bc85ac438e8906a6b32f95d10ac4efe`
+
+## 根因与修复
+
+CLI 同构 Markdown 证明，`completed-agent-message` 之后仍可能到达属于同一稳定 itemId 的 late `agent-message-delta-progress`，旧 reducer 会把已经完成的 assistant 内容再次追加。
+
+修复只按正式稳定 `itemId` 收敛 completed 后的 late delta。没有删除 Kafka event，没有按正文、时间戳或 DOM 去重，也没有影响 tool、terminal 或 final event。
+
+## 固定 trace 验证
+
+- Kafka source/applied：`180/180`
+- 可见 assistant/tool/terminal/final：`23/54/1/1`
+- renderer assistant duplicate：`0`
+- handoff deduplicated：`0`
+- source 与 applied 中原始 occurrence 均保留为 `23`
+
+这证明修复保留权威 Kafka 事件，仅在正式 reducer 状态机中按 item 生命周期解释 late delta。
+
+PR merge 后自动 Pipeline 完成，GitOps/Argo 为 `Synced/Healthy`，runtime `1/1 ready`，source relation `exact`。
+
+## 结论
+
+临近终态不会再把旧 assistant 消息重放到内层；outer final 仍只展示一次，Kafka 实时/刷新语义未退化。
@@ -0,0 +1,29 @@
+# R5 任务报告：纯 Kafka 实时与刷新回访正确性收口
+
+## 范围
+
+本轮只完成 [HWLAB #2498](https://github.com/pikasTech/HWLAB/issues/2498)、[HWLAB #2499](https://github.com/pikasTech/HWLAB/issues/2499) 与 [HWLAB #2500](https://github.com/pikasTech/HWLAB/issues/2500) 已登记的主线问题：用户/代理顺序、刷新稳定 identity、临近终态 assistant 重复和 tool summary 可见性。未执行新支线。
+
+## 已完成子项
+
+- R5.1：修复 AgentRun 正式用户事件源序、stdio 同 publisher Kafka publish 顺序与 Web live/replay 稳定 messageId。
+- R5.2：tool summary 收敛为“时间 + 实际命令”，状态仅用颜色、动效与 ARIA 语义表达。
+- R5.3：按正式 itemId 收敛 completed 后 late delta，消除临近终态 assistant 重复。
+
+## 最终端到端证据
+
+最终实时 command `cmd-mrgs7itk-cc7434` 通过，报告 SHA256 为 `329f422acf7f2c3ab34ce20adc78120d60804fb14f37e1ecbb59952f374e905d`。两轮 stdio frameSeq 严格递增，AgentRun → HWLAB → SSE lineage/fingerprint 精确一致；单页只使用一个 session EventSource，两个 terminal 均完成。
+
+随后在同一 session 上只刷新、不提交输入，command `cmd-mrgsc5ps-34fdcd` 通过，报告 SHA256 为 `d80f149b73c5536773d257a0f3c695b5cca14bdc7c84471975497cb1f911cade`。刷新前后均为 4 条消息，identity 与顺序完全一致：
+
+`user(trace1) → agent(trace1) → user(trace2) → agent(trace2)`
+
+Kafka retention matched/replayed 为 `53/53`，buffer/live/deduplicated 均为 0；SSE failures 与 forbidden requests 均为 0。
+
+## 架构结论
+
+最终链路保持：
+
+`codex-stdio.raw.v1 → agentrun.event.v1 → HWLAB direct mapper → hwlab.event.v1 retention → shared live fanout → SSE → 同一 Web codec/queue/reducer/row model`
+
+未引入 projector/read model/snapshot/sync/gap-fill/finalizer、polling、HTTP history fallback、正文/时间戳去重或下游重排补洞。本轮主线目标已完成，可以停止。
@@ -49,15 +49,15 @@
 ## R4 [in_progress]

 支线：解决 Provider 缺失导致 stale-pending Runner 假活性无法自动回收；上下文 [AgentRun #282](https://github.com/pikasTech/agentrun/issues/282)；临时缓解已将 20 个 run 终态化并清空 20 个 Runner Job，永久修复由子代理交付且不得阻塞 R3，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R4_Task_Report.md)。
-## R5 [in_progress]
+## R5 [completed]

 刷新重放后的事件可见顺序与 Trace summary 视觉收口；上下文：[HWLAB #2498](https://github.com/pikasTech/HWLAB/issues/2498)、[HWLAB #2499](https://github.com/pikasTech/HWLAB/issues/2499)，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R5_Task_Report.md)。
-### R5.1 [in_progress]
+### R5.1 [completed]

 依据 [HWLAB #2498](https://github.com/pikasTech/HWLAB/issues/2498) 与 [AgentRun #297](https://github.com/pikasTech/agentrun/issues/297)，用既有 Kafka session/trace 对齐 agentrun.event、hwlab.event、SSE ingress、Web reducer 与 DOM 顺序；已锁定初始 run-created 早于 user_message 的 AgentRun 源序窗口，先修正式事件事务顺序，再以同一纯 Kafka 链验收，禁止下游过滤、重排或补洞，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R5.1_Task_Report.md)。
-### R5.2 [in_progress]
+### R5.2 [completed]

 依据 [HWLAB #2499](https://github.com/pikasTech/HWLAB/issues/2499) 精简 tool-call summary：可见行合并为“时间 + 实际命令”（例如 `02:14:17 find . -maxdepth 3 ...`），移除重复工具名、状态文字、total、duration 与 exit；状态仅用整行色彩、运行中动效及非可见无障碍语义表达，保持 HTML/Markdown 同构 model，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R5.2_Task_Report.md)。
-### R5.3 [in_progress]
+### R5.3 [completed]

 依据 [HWLAB #2500](https://github.com/pikasTech/HWLAB/issues/2500) 与固定 trace trc_535e95438f144922，优先用生产 Kafka CLI 与同构 Markdown 锁定临近终态重复旧 assistant 的首次发生层，修复 stable identity/replay-live/reducer 根因且不影响 tool、terminal、final，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R5.3_Task_Report.md)。