feat(trace): add diagnosis trace workbench

2026-07-07 01:24:56 +08:00
parent b3315ead52
commit aa035b828c
9 changed files with 1505 additions and 2 deletions
@@ -0,0 +1,70 @@
+# Trace UI workbench design
+
+## Subject and audience
+
+Subject: a single-session diagnosis trace audit workbench.
+
+Audience: backend and AIOps engineers reviewing an MVP diagnosis run after a
+demo, incident drill, or regression check.
+
+Single job: turn one trace response into an inspectable ledger that exposes
+agent flow, evidence, verifier judgement, and skill boundaries without reading
+raw JSON first.
+
+## Frontend approach
+
+- Static `trace.html`, `trace.css`, and `trace.js`.
+- No dependency on a package manager, bundler, external fonts, or remote icons.
+- Fetches `/api/diagnosis/{sessionId}/trace` and renders client-side.
+- Accepts `?sessionId=...` and keeps the loaded session id in the URL.
+
+## Visual direction
+
+Palette:
+
+- `#111827` ink rail for the trace frame.
+- `#f7f3ea` warm ledger surface.
+- `#1f7a6b` evidence green.
+- `#b5472f` rejection red.
+- `#c58a19` warning amber.
+- `#5b6472` operational gray.
+
+Type:
+
+- UI/body: `Inter, ui-sans-serif, system-ui`.
+- Data and labels: `ui-monospace, SFMono-Regular, Consolas`.
+
+Layout:
+
+```text
+--------------------------------------------------------------------+
+| Session id input | Load | status / verdict / counts strip          |
+------------------+----------------------+--------------------------+
+| Agent trace rail | Evidence tool ledger | Inspector                |
+| ordered steps    | filters + calls      | verifier + RAG + skill   |
+------------------+----------------------+--------------------------+
+```
+
+Signature element: a trace rail that treats each agent step as a ledger entry
+with ordered markers, duration, token count, and expandable raw model excerpts.
+
+## Data mapping
+
+- `data.session`: summary strip, final answer, self-evaluation source.
+- `data.steps`: ordered trace rail.
+- `data.toolInvocations`: evidence ledger and selected tool inspector.
+- `data.session.selfEvaluation.verifier_evaluation`: verdict, groundedness,
+  facts table, and verifier `tool_trace_summary`.
+- `data.toolInvocations[*].retrievalDetails`: RAG query transform, retrieval
+  trace, context pack, rerank trace, and evidence blocks.
+- `steps[*].modelOutput`: best-effort extraction of `selected_skill`.
+- `steps[*].modelInput/modelOutput` and tool names: best-effort skill boundary
+  checks for `read_skill`.
+
+## Accessibility and states
+
+- Keyboard-focusable controls.
+- Loading, missing session id, API error, empty steps, empty tools, and missing
+  verifier states.
+- Responsive three-pane desktop layout that stacks on narrow screens.
+- Respects `prefers-reduced-motion`.