轨迹图谱视图tieveto666-code/dsh-client-ui-trace-graph

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

powered by dsh
dsh-plugin
License: MIT

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

发现约定：请为本仓库添加 GitHub Topic dsh-plugin（官方推荐的社区发现标签）。安装不依赖任何「官方认证」，有地址即可 dsh plugin add。

轨迹图谱示意图

为什么用这个插件

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

- 同源真实数据 — 读取 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 安装（仓库公开后）

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

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

从本地仓库安装（开发）

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。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build

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

pnpm gen:reactflow-css

数据模型

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

已知限制

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

许可证

MIT © Changsheng Tie（tieveto666-code）