71 lines
2.5 KiB
Markdown
71 lines
2.5 KiB
Markdown
# 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`.
|