dsh-client-ui-trace-graph

@tieveto666-code/dsh-client-ui-trace-graph

English | 中文

Turn the official DSH Web GUI trajectory ledger into an interactive DAG: the same live records as the built-in「轨迹」tab, rendered as a ReactFlow graph so you can see execution order and proven structure at a glance.

Why this plugin

Official「轨迹」is a powerful inspection table. This plugin keeps that same source of truth and adds a spatial reading of the run:

• Same data, no second ledger — reads snapshot.views.get('trajectory') (plus safe fallbacks). What you see in the graph is what the session already recorded, not a mock or a parallel log.
• Two edge kinds you can trust — gray sequence edges always show what happened next; colored structure edges appear only when row fields prove a causal / nesting link. No invented arrows.
• Debug the agent loop visually — SYSTEM / USER / CONTEXT / ASSISTANT / TOOL / SUBTOOL / COMPACTION as typed nodes, with summary, sequence #, latency, status, and token usage; click a node for Input / Output JSON.
• Fits the official shell — mounts as a first-party conversation view tab (not a modal or center-column takeover); chrome colors follow --dsw-* themes and skins.
• Layouts for different questions — dagre hierarchy (default) for causal depth; d3-force for an organic overview; switch anytime from the toolbar.

How to read the graph

Visual	Meaning
Gray dashed edge (sequence)	Chronological execution order. Always drawn between adjacent trajectory records: A happened, then B. Legend: 「执行顺序 / Sequence」.
Colored solid edge (structure)	Proven structure / causality (semantic color by target label). Emitted only when fields prove a link — e.g. prompt/context → next assistant, assistant → tool call, tool/subtool nesting, tool result consumed by a later assistant. Legend: 「结构关系 / Structure」.
Node label	Real trajectory label (SYSTEM, USER, CONTEXT, ASSISTANT, TOOL, …).
Node body	Real summary, sequence number, latency, status, token usage.
Detail panel	Click a node to inspect recorded Input / Output JSON.

Reading tip: gray is known, stronger relationship is not proven; gray + color = order plus a verified upstream/downstream link.

Features

• Conversation tab 「轨迹图谱 / Trace Graph」 beside official views.
• Hover highlighting of upstream / downstream neighbors.
• Toolbar layout toggle: dagre / d3-force; ResizeObserver re-fits when the view or sidebar resizes.
• Settings card (Settings → Plugins): enabled, announceToAgent, defaultLayout.
• Optional host announcement so agents know the plugin is installed.

Requirements

• Node.js ^22.19 || >=24
• pnpm 11
• A working dsh web install (official @deepseek-ai/dsh SDK)

Install

From GitHub (after you publish this repository)

dsh plugin --profile web add github:tieveto666-code/dsh-client-ui-trace-graph

pnpm ≥10 may block the package prepare script on first install. If dsh tells you to allow builds, add the printed package key to that profile's pnpm-workspace.yaml under allowBuilds, then run add again.

From a local checkout (development)

git clone https://github.com/tieveto666-code/dsh-client-ui-trace-graph.git
cd dsh-client-ui-trace-graph
pnpm install
pnpm build
dsh plugin --profile web add link:$(pwd)

Restart dsh web and refresh the page; the Trace Graph tab appears beside the conversation tabs.

Develop

pnpm install
pnpm typecheck
pnpm test
pnpm build

After upgrading @xyflow/react, regenerate the scoped ReactFlow stylesheet:

pnpm gen:reactflow-css

Data model

The browser adapter projects each live trajectory row into a TraceSpan, preserving label, summary, source seq, turn, step, status, timing, and Input/Output references. Every pair of adjacent records gets a sequence edge; structure edges are added only for relationships proven by row fields (see How to read the graph).

Known limitations

• Structure edges are conservative: when the trajectory data does not prove a relationship, the graph keeps only the chronological sequence edge.
• ReactFlow keeps its attribution mark in the corner unless a Pro license is used; it is intentionally not hidden.
• Large graphs reduce the per-edge particle count automatically; with hundreds of nodes, consider disabling backdrop-filter on nodes.

License

MIT © Changsheng Tie (tieveto666-code)