dsh-agent-trace

Agent Trace — a DeepSeek Harness plugin that visualizes an agent's reasoning, parallel tool calls, and results as an interactive DAG inside the chat stream.

Because agent execution is a graph, not a line.

English · 中文

English

Why

Most agent UIs render execution as a linear timeline or a tree-style mind map. But real agent execution is a directed graph:

• A single reasoning step can fan-out to N parallel tool calls (parallel tool calls are first-class in DeepSeek/OpenAI APIs).
• Tool results fan-in back to the next reasoning step.
• Failures branch into retries / alternative paths.

Agent Trace renders this real shape — a DAG, not a sequence — so you can actually see what the agent did, in parallel, and why.

What it does

Every time the model answers, it goes through one or more steps. Each step contains:

• reasoning-delta — streaming chain-of-thought
• text-delta — the user-visible answer
• tool/call — a tool invocation (name + arguments); multiple can be emitted in parallel
• tool/result — the tool's result or error

deepseek-harness records all of these as durable session events. This plugin subscribes to those events, accumulates the per-turn state, and renders it as a zoomable, panable node graph with react-flow + dagre auto-layout.

Node types:

Key interactions:

• Default: one card per step (coarse-grained overview)
• Click a Step card → expand into its sub-graph (reasoning → parallel tool calls → results → response)
• Scroll to zoom, drag to pan, MiniMap for navigation
• Streaming: nodes appear one-by-one as events arrive; fan-out is visible the moment parallel tool calls land
• JSON button exports the current graph

Architecture

session log  ──►  assistant/chunk (reasoning-delta, text-delta)
              ──►  tool/call, tool/result
              ──►  step/start, step/end, turn/start, turn/end
                          │
                          ▼
        ┌──────────────────────────────────┐
        │  ConversationNodeDefinition       │  ← this plugin
        │  kind: 'trace-turn'               │
        │  target: 'chat'                   │
        │  match() → turn-scoped id         │
        │  update() → accumulate state      │
        │  buildViewNode() → TraceChatData  │
        └──────────────────────────────────┘
                          │
                          ▼
        ┌──────────────────────────────────┐
        │  conversation.chat.node slot      │
        │  key: 'trace-turn'                │
        │  → TraceNodeView (React)          │
        │     ├─ buildFullGraph()           │
        │     ├─ applyCollapse()            │
        │     ├─ dagre layout               │
        │     └─ react-flow SVG render      │
        └──────────────────────────────────┘

Install

As a workspace subpackage of dsh (recommended today)

Assumes you have cloned deepseek-harness and use pnpm workspaces.

cd <dsh-checkout>/packages
git clone https://github.com/goldgish/dsh-agent-trace.git
cd dsh-agent-trace
pnpm install
pnpm run bundle

Add - packages/dsh-agent-trace to pnpm-workspace.yaml in the dsh checkout, then:

pnpm install
cd ../..
dsh web --patch packages/dsh-agent-trace/cordis.yml

As an external npm package (once @deepseek-ai/dsh-client-* are published)

Replace every "workspace:^" in peerDependencies with a concrete version, then:

cd dsh-agent-trace
pnpm install
pnpm run bundle
pnpm link --global

# inside your dsh checkout
pnpm link --global dsh-agent-trace
dsh web --patch /path/to/dsh-agent-trace/cordis.yml

Live demo (no dsh / npm / API key needed)

A standalone offline demo lives in demo/index.html. It replays a mocked turn's session events through the exact same graph-building logic the plugin uses.

cd demo
python -m http.server 8765
# open http://127.0.0.1:8765/

Limitations

• Chat-stream placement, not standalone view: doing a full-screen trace view would require ConversationViewDefinition plus a new outlet in packages/client/web-react. The buildViewNode contract is already shaped for that upgrade.
• Per-turn scope: one trace graph per turn, no session-wide merge (to prevent DAG node explosion in long sessions).
• tool/result parsing: only content[*].text and content[*].content shapes are recognised; custom tools with other shapes may render an empty result field (status / error still populate correctly).

Roadmap

• [ ] Subagent sub-graph expansion (parse dsh-subagent delegate events into nested DAGs)
• [ ] Background jobs / workflow branches (parse dsh-jobs / dsh-workflow events into parallel branches with running/done states)
• [ ] Session-wide overview graph linking turn roots
• [ ] Click-to-jump from a trace node to the corresponding chat position
• [ ] Standalone full-screen view via ConversationViewDefinition

License

MIT

中文

为什么做这个

大多数 agent UI 把执行过程渲染成线性 timeline 或树状思维导图。但真实的 agent 执行是有向图:

• 一个 reasoning 步骤可以 fan-out 到 N 个并行工具调用(并行 tool calls 是 DeepSeek/OpenAI API 的一等公民)
• 工具结果再 fan-in 回下一个 reasoning 步骤
• 失败会分叉出重试 / 备选路径

Agent Trace 把这种真实形状——DAG 而非线性序列——渲染出来,让你真正看清 agent 做了什么、哪些是并行的、为什么这么做。

它做什么

每次模型回答会经历一或多个 step,每个 step 包含:

• reasoning-delta — 流式思考过程
• text-delta — 给用户的可见回复
• tool/call — 一次工具调用(name + arguments),多个可并行
• tool/result — 工具结果或错误

deepseek-harness 把这些都作为持久化 session 事件记入日志。本插件订阅这些事件,累积 per-turn 状态,用 react-flow + dagre 自动布局渲染成可缩放、可平移的节点图。

节点类型:

核心交互:

• 默认:每个 step 一个卡片(粗粒度总览)
• 点击 Step 卡片 → 展开成子图(reasoning → 并行 tool calls → results → response)
• 滚轮缩放、拖拽平移、MiniMap 导航
• 流式:节点按事件到达顺序逐个出现,fan-out 在并行 tool calls 落地的瞬间可见
• JSON 按钮导出当前图

安装

作为 dsh 的 workspace 子包(当前推荐)

适用于你已 git clone 了 deepseek-harness 并用 pnpm workspace。

cd <dsh-checkout>/packages
git clone https://github.com/goldgish/dsh-agent-trace.git
cd dsh-agent-trace
pnpm install
pnpm run bundle

在 dsh checkout 的 pnpm-workspace.yaml 加 - packages/dsh-agent-trace,然后:

pnpm install
cd ../..
dsh web --patch packages/dsh-agent-trace/cordis.yml

作为外部 npm 包(等 @deepseek-ai/dsh-client-* 正式发到 npm 后)

把 peerDependencies 里所有 "workspace:^" 改成具体版本号,然后:

cd dsh-agent-trace
pnpm install
pnpm run bundle
pnpm link --global

# 在你的 dsh checkout 内
pnpm link --global dsh-agent-trace
dsh web --patch /path/to/dsh-agent-trace/cordis.yml

在线 demo(无需 dsh / npm / API key)

独立离线 demo 在 demo/index.html,用 mock 数据重放一个 turn 的 session 事件,渲染逻辑与真实插件完全一致。

cd demo
python -m http.server 8765
# 打开 http://127.0.0.1:8765/

局限性

• 挂在 chat 流末尾,不是独立全屏视图:做全屏 trace 视图需要 ConversationViewDefinition + 在 packages/client/web-react 加新 outlet(改主仓库)。buildViewNode 接口已为这种升级预留。
• per-turn 范围:每个 turn 一张图,不做 session 级合并(避免长会话里 DAG 节点爆炸)。
• tool/result 解析:只识别 content[*].text 和 content[*].content 两种结构;自定义工具若用其他结构,result 字段可能为空(但 status / error 仍能正确显示)。

路线图

• [ ] subagent 子图展开(解析 dsh-subagent delegate 事件成嵌套 DAG)
• [ ] 后台 jobs / workflow 分支(解析 dsh-jobs / dsh-workflow 事件成并行分支,带 running/done 状态)
• [ ] session 级总览图,串联各 turn 根节点
• [ ] 点击 trace 节点跳转到 chat 对应位置
• [ ] 用 ConversationViewDefinition 做独立全屏视图

License

MIT