fix(workbench): unify pre-admission failure projection

2026-07-12 11:02:24 +02:00
parent 77e975bbce
commit 6bf10b6d05
15 changed files with 617 additions and 102 deletions
@@ -0,0 +1,35 @@
+# R2.6 任务报告
+
+## 目标与来源
+
+- 来源：[HWLAB #2510](https://github.com/pikasTech/HWLAB/issues/2510)。
+- 固定诊断 trace：`ae0181ba9a18bad2a561157d312c3692`。
+- 目标是在纯 Kafka + SSE 架构内定位重复首层，禁止文本指纹去重、HTTP/数据库补洞、第二失败通道和新开真实 run。
+
+## 离线证据与根因
+
+- OTel 有界读取显示固定 trace 只有 `hwlab-cloud-api POST /v1/agent/chat` 一个 503 span；权威上游类型是 `schema-invalid`，错误层为 `agentrun`。
+- 失败时段候选 session `ses_d5511238-e999-48a8-a93e-eb3c3f93e540` 仍为 `messageCount=0`、`lastTraceId=null`，更新时间停在失败前。
+- `hwlab-cli kafka inspect order` 对该 session 完整扫描既有 `agentrun.event.v1` 与 `hwlab.event.v1` 后，两侧 `matchedCount=0`；共享 refresh handoff、Web reducer 与 DOM projection 也均为 0。没有读取事件值或 dump，也没有新建真实运行。
+- 因此首个重复环节不在 AgentRun event、HWLAB bridge、Kafka、SSE 或 reducer。失败发生在 durable admission 之前；Web 的 `projectLocalAdmissionFailure` 却伪造了一个 `workbench-local` terminal trace event，所以出现“运行记录 1 events”。同一错误随后又由 assistant 正文、synthetic timeline Error 与诊断摘要各显示一次。
+
+## 修复方案
+
+- 新增 pre-admission typed failure classifier。分类 authority 只读取正式 `failureKind`、显式 `retryable`、状态码和 correlation 字段；`rollout-in-progress` 只接受 AgentRun 权威 typed code，不按时间、503 或文案推断。
+- 保留 `failureKind/reason/retryable/userMessage/recoveryAction`，并透传 Workbench trace、upstream trace、run、command、dispatch intent 与 dispatch stage；尚未创建的 identity 显式为 `null`，admission state 为 `rejected-before-durable-dispatch`。
+- 覆盖 rollout、manager/service、admission/policy、runner capacity、provider/profile、Secret、image、workspace/materialization、lease/idempotency、dispatcher/runtime 与 unknown 类型。固定 `schema-invalid` 分类为不可重试的 `dispatcher-runtime-misconfigured`。
+- Web 不再把 HTTP admission rejection 制造成 trace/Kafka event，不再写假 terminal turn/session authority；只保留一个由稳定 assistant message/failure identity 拥有的失败正文。timeline Error 和诊断摘要依据 `failureIdentity + primaryPresentation + lifecycle` 收敛，不比较显示文本。
+- 诊断折叠区继续展示类型、恢复动作和 correlation；正式 Kafka failure 的原始 `runnerTrace.events` 与 raw HWLAB Event 数据不做删除或过滤。
+- optimistic session running authority 改为 HTTP durable admission 成功后才建立，避免未接纳请求污染 session 状态。
+
+## 验证
+
+- `bun test internal/cloud/code-agent-dispatch-failure.test.ts`：3/3 通过，覆盖 rollout transient、固定 schema-invalid permanent、provider/profile permanent 与 unknown 下钻。
+- `bun test internal/cloud/server-agent-chat.test.ts --test-name-pattern 'preserves typed schema-invalid'`：通过；503 响应保留完整 typed fields/correlation，且没有 false running/failed owner write。
+- `bun test web/hwlab-cloud-web/scripts/workbench-realtime-runtime.test.ts`：34/34 通过；固定 trace fixture 只有 `UserMessage + AssistantPart`，无 synthetic Error、无 local trace event；正式 Kafka failure 的两条 raw event 保持不变。
+- `bun run check:tsc`：通过 Web source scan、Vite/Vue build 与 source-shape 检查。
+- `git diff --check`：通过。
+
+## 待完成验收
+
+- 当前交付边界是未合并 PR，不手工部署或触发 CI/CD。PR 合并后应等待 GitHub webhook → mirror → PAC → CI/CD 自动发布，再用原 Workbench 入口验证失败正文只出现一次、无“运行记录 1 events”，并核对诊断字段；完成该运行面证据后再关闭 R2.6/#2510。