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

[English](README.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)

把官方 DSH Web GUI 的 **轨迹（trajectory）** 账本变成可交互 DAG：与内置「轨迹」页同一份实时记录，用 ReactFlow 画出执行顺序与可证明的结构关系，一眼看清 agent 跑了什么。

> 发现约定：请为本仓库添加 GitHub Topic [`dsh-plugin`](https://github.com/topics/dsh-plugin)（官方推荐的社区发现标签）。安装不依赖任何「官方认证」，有地址即可 `dsh plugin add`。

![轨迹图谱示意图](docs/trace-graph-preview.png)

## 为什么用这个插件

官方「轨迹」表很强，适合逐行核查。本插件**不另起一本账**，在同一数据源上补一层空间化阅读：

- **同源真实数据** — 读取 `snapshot.views.get('trajectory')`（并带安全回退）。图上看到的就是会话已落盘的轨迹，不是 mock，也不是平行日志。
- **两种边，可信可读** — 灰色顺序边始终回答「接下来发生了什么」；彩色结构边只在行字段能证明因果 / 嵌套时出现。不画臆造箭头。
- **可视化调试 agent 循环** — 节点沿用真实标签（`SYSTEM` / `USER` / `CONTEXT` / `ASSISTANT` / `TOOL` / `SUBTOOL` / `COMPACTION` 等），展示 Summary、轨迹序号、延迟、状态与 Token；点击节点查看 Input / Output JSON。
- **融入官方界面** — 注册为官方会话视图 tab，无 Modal、无遮罩、无中央列 DOM 接管；外观跟随 `--dsw-*` 主题与皮肤。
- **两种布局按问题切换** — 默认 dagre 层级看因果深度；d3-force 看整体形态；工具栏随时切换。

## 图怎么读

| 视觉 | 含义 |
| --- | --- |
| **灰色虚线（`sequence`）** | **执行顺序**。相邻两条轨迹记录之间必有：先 A 后 B。图例：「执行顺序 / Sequence」。 |
| **彩色实线（`structure`）** | **结构 / 因果关系**（颜色按目标节点标签语义区分）。仅当字段能证明时生成——例如 prompt/context → 后续 assistant、assistant → 工具调用、tool/subtool 嵌套、工具结果被后续 assistant 消费。图例：「结构关系 / Structure」。 |
| **节点标签** | 真实轨迹标签（`SYSTEM`、`USER`、`CONTEXT`、`ASSISTANT`、`TOOL` …）。 |
| **节点内容** | 真实 Summary、轨迹序号、延迟、状态、Token 用量。 |
| **详情面板** | 点击节点查看记录的 Input / Output JSON。 |

**读图提示：** 只有灰线 = 只确定先后，更强关系尚未证明；灰线 + 彩线 = 既有顺序，又有已验证的上下游。

## 能力一览

- 会话区「轨迹图谱 / Trace Graph」标签，与官方视图并列。
- 悬停高亮上下游邻居。
- 工具栏布局切换：dagre / d3-force；视图或侧边栏尺寸变化时 ResizeObserver 自动适配。
- 设置卡（设置 → 插件配置）：`enabled`、`announceToAgent`、`defaultLayout`。
- 可选 host 公告，让 agent 知道本机已安装该插件。

## 环境要求

- Node.js `^22.19 || >=24`
- pnpm 11
- 已可用的 `dsh web`（官方 `@deepseek-ai/dsh` SDK）

## 安装

### 从 GitHub 安装（仓库公开后）

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

pnpm ≥10 可能在首次安装时拦截包的 `prepare` 脚本。若 `dsh` 提示需要允许构建，把打印的包键写入该 profile 的 `pnpm-workspace.yaml` 的 `allowBuilds`，再执行一次 `add`。

### 从本地仓库安装（开发）

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

重启 `dsh web` 并刷新页面，会话区 tab 旁出现 Trace Graph。

## 开发

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

升级 `@xyflow/react` 后，重新生成带作用域的 ReactFlow 样式表：

```sh
pnpm gen:reactflow-css
```

## 数据模型

浏览器 adapter 把每条实时轨迹行投影为 `TraceSpan`，保留标签、Summary、源 seq、turn、step、状态、耗时与 Input/Output 引用。相邻记录恒有 `sequence` 边；`structure` 边仅在行字段能证明关系时追加（详见 [图怎么读](#图怎么读)）。

## 已知限制

- 结构边采用保守策略：轨迹数据无法证明关系时，图谱只保留时间顺序边。
- ReactFlow 右下角的署名标记保持显示（未购买 Pro 授权时不应隐藏）。
- 大图会自动降低每条边的粒子数；数百节点规模下建议关闭节点的 `backdrop-filter`。

## 许可证

MIT © Changsheng Tie（[tieveto666-code](https://github.com/tieveto666-code)）