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

English | [中文](README.zh.md)

[![powered by dsh](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
[![dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-4D6BFE?style=flat-square)](https://github.com/topics/dsh-plugin)
[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](./LICENSE)

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.

![Trace graph preview](docs/trace-graph-preview.png)

## 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 only = order 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)

```sh
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)

```sh
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

```sh
pnpm install
pnpm typecheck
pnpm test
pnpm build
```

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

```sh
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](#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](https://github.com/tieveto666-code))