@tieveto666-code/dsh-client-ui-trace-graph
English | 中文
  
把官方 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/dshSDK）
安装
从 GitHub 安装（仓库公开后）
dsh plugin --profile web add github:tieveto666-code/dsh-client-ui-trace-graphpnpm ≥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）