Preface

When running agent tasks in DeepSeek Harness (DSH), the conversation window typically only shows the “finally selected path”: which tool calls succeeded and what the model said next. Failed retries, empty retrievers, and circuitous backtracking are often scattered across multiple rounds of output, requiring manual log inspection to piece together the full picture.

If you want to compare two runs (e.g., the same task using Flash vs. Pro) or visualize where time is spent in a long conversation, a plain text session log isn’t intuitive. The community-maintained DSH client plugin introduced below, dsh-trace-compare, visualizes the execution trace as a “maze”: main paths, branches, and backtracking points are laid out on a single timeline, supporting offline comparison and real-time tracking.

What Is It

dsh-trace-compare (GitHub: lamost423/dsh-trace-compare) is developed by maintainer lamost423 and categorized as a client-side plugin. The npm package name is dsh-trace-compare, with the current repository version at 0.6.2.

The plugin does one thing: parse tool calls and answer nodes from the session log or the live event stream, then draw the agent’s exploration process using a unified visual language—showing the main path of successful progression, branches for failures/empty retrievals/invalid retries, and return lines back to branch points.

Two entry points share the same legend and judgment logic:

  • Trace Comparison (sidebar): Upload one log to view the maze of a single run, or upload two logs for a coaxial comparison.
  • Real-time Maze (in-session tab): The maze grows in real time as the current session executes, with branches appearing immediately after tool results are resolved.

Core Features

Maze Legend

The meaning of each element on the graph is as follows (all from the plugin’s README):

  • Solid Main Line: Steps and answer nodes where tool calls successfully advanced the process.
  • Duration Capsule Bar: Each step is drawn as a rounded bar from start to end, colored based on judgment; when the bar is wide enough, the duration is written inside. When a step has ≥2 parallel tool calls (from v0.3.2), each call is drawn as a thin bar below the capsule, positioned by its start and end times.
  • Dashed Arc (Branch): Tool failure (red ✗), empty retrieval (gray ·), blind retry (gray ↻), and return lines back to branch points.
  • Sub-agent Branch (from v0.4.0, real-time tab): Sub-agent sessions derived by the model (origin: 'subagent') are drawn as aggregate nodes branching from the main path, sharing the same timeline; running sub-agents grow in real time. Manual branches and side-chats are not included.

Hover over a node or arc for a quick preview; click to open a details panel on the right, which includes the full command and return value (with copy buttons, return truncated to 5000 characters), duration, judgment, and a summary of the reasoning.

Trace Comparison (Dual Sessions)

After uploading two session logs, the plugin automatically aligns the answer nodes by round and supports:

  • Round Alignment Lines (from v0.3.0): Each round’s answer nodes are connected, showing the duration, duration difference, and branch count difference for both sides; from v0.5.1, the duration metric is “start of the round → completion of the answer”, excluding user idle time between rounds.
  • Manual Anchors: Click one node in each lane to pin a comparison line with a time difference, useful for moments that are semantically equivalent but misaligned in rounds.
  • Branch Summary: Lists the branch step count, wall-clock duration, category composition, and difference conclusions by round for both sides; click a row to zoom to that round.

Real-time Maze

The same graph within the session tab grows as execution proceeds. The details panel has a “Locate this step in conversation” button; the host switches back to the conversation page and highlights the corresponding tool line (degrades to switching only the tab if the line is too old or beyond the loaded window).

The real-time tab only draws events within the loaded conversation window (annotated from v0.2.3); earlier steps outside the window are discarded with a note “N earlier steps not loaded.” To view the entire session, use “Download session log → Upload for comparison.”

Interaction & Export

  • Zoom & Navigate: Scroll wheel zooms horizontally centered on the cursor, drag to pan, double-click blank or “Fit View” to reset; axis ticks become denser with zoom (down to 1 second).
  • Search & Filter: Toggle “Show only failures/retries,” filter by tool type, full-text search of commands and returns; non-matching nodes are faded to 15% opacity.
  • Playback: Replay the entire run at up to 300× speed.
  • Export: Export the current view as SVG or 2x PNG; exports use a fixed light background.
  • Bilingual Interface (from v0.5.0): Follows the dsh language setting when embedded in the host; defaults to browser language when opened standalone.
  • Theme Following (from v0.3.1): Switches with the host’s light/dark theme.

Timeline & Judgment Rules

Honest conventions on the timeline:

  • Intervals with no activity over 60 seconds are compressed into a thin gap marked with ⏸, indicating the omitted duration; ticks within active segments remain true wall-clock values.
  • Step identifiers include the round number (e.g., S15·47); tokens are read from the usage in the session log’s assistant/message (from v0.2.2); if the log lacks usage data, the label falls back to “Reasoning N segments (token usage not reported in log).”

Branch Judgment (introduced in v0.2.1, shared between the page and real-time tabs via VERDICT_RULES in src/client/verdict.js):

  1. Error flag (isError) → failure;
  2. Strong/weak failure features are scanned only in the output’s leading and trailing windows, avoiding misjudgment of “quoted” error text in the middle of long texts;
  3. Classified by tool: write-type tools succeed if no error; retrieval tools are empty only if the result is empty; bash and unknown tools are empty only if output is empty;
  4. Behavioral detection: consecutive calls with “same tool + similar parameters” where at least one in the cluster is a failure mark non-failure members as invalid retries.

Whether a step advances the main path or a branch is determined by the worst tool judgment in that step.

Supported Log Formats

Identified by file content, regardless of filename:

  • Plain text .jsonl (session format v0 event stream)
  • Original .jsonl.zstd under ~/.dsh/sessions/ (decompressed in the browser, preferring native DecompressionStream('zstd'), otherwise falling back to bundled fzstd)

Installation & Enabling

The plugin has been verified with the official 0.1.0-rc.6 (build + full tests) and rc.8 (slot/type check + real-device validation); the peer range covers rc.6 to the current rc line.

The following installation steps are from the README. The plugin runs with the current dsh process permissions; it’s recommended to review the GitHub repository source code and license before installation.

npm install --global @deepseek-ai/dsh@0.1.0-rc.8
dsh plugin --profile web add dsh-trace-compare
dsh web

To pin a specific release version, use the tgz from the Release (README example is v0.5.2):

dsh plugin --profile web add https://github.com/lamost423/dsh-trace-compare/releases/download/v0.5.2/dsh-trace-compare-0.5.2.tgz

Install from source:

git clone https://github.com/lamost423/dsh-trace-compare.git
cd dsh-trace-compare
corepack enable
pnpm install
pnpm build
dsh plugin --profile web add .
dsh web

After restarting dsh web, a “Trace Comparison” entry appears at the bottom of the sidebar, and a “Real-time Maze” tab is added to each session view.

Community directory page: SkillHub · lamost423/dsh-trace-compare. The DSH ecosystem embraces “everything is a plugin”; community directories like SkillHub are independent sites with no official affiliation to DeepSeek or幻方.

Typical Usage

Comparing Two Runs

  1. Run the same task twice in DSH (or export two session logs).
  2. Open the sidebar “Trace Comparison” and upload the two .jsonl or .jsonl.zstd files.
  3. View the coaxial dual lanes: round alignment lines compare duration and branch differences per round; use “Add Anchor” to pin semantically equivalent moments if needed.
  4. Click “Branch Summary” to view the composition of failures/retries/empty retrievals by round; click a row to zoom to that round’s details.

Observing the Current Session in Real Time

  1. Install the plugin and start dsh web.
  2. Enter any session and switch to the “Real-time Maze” tab.
  3. Observe the maze grow with tool calls; click nodes for details, and use “Locate this step in conversation” to jump back to the original text if needed.
  4. Use filters and search to locate failed steps; after the session ends, export SVG/PNG to share.

Analyzing Long Sessions

The README mentions the plugin can handle large logs (example: 14 hours, 8.6MB), laid out to fill the width and supporting vertical scrolling with a pinned timeline; ⌘/Ctrl+scroll zooms to any segment. If the real-time tab indicates earlier unloaded history, download the full session log and upload it via Trace Comparison.

Use Cases & Notes

Who is it for:

  • Agent developers who need to compare different models or prompts for the same task;
  • Debugging tool call failures, invalid retries, empty retrievals, etc.;
  • Analyzing complex sessions with sub-agent derivations (real-time tab, relies on the host’s “background loading of sub-session history” capability);
  • Scenarios where trace graphs need to be exported and shared with colleagues.

Usage notes:

  • The real-time maze only reflects events within the loaded conversation window, not the complete session; for full analysis, use log upload.
  • Branch judgment is based on deterministic rules; thresholds can be adjusted in VERDICT_RULES for project-specific data, but no LLM secondary judgment is invoked.
  • Sub-agent branches are automatically hidden when the official rc line temporarily lacks “background loading of sub-session history” support.
  • Node engine requirement: ^22.19.0 || >=24.0.0 (see package.json).

Conclusion

dsh-trace-compare extracts the agent’s “actual path taken” from logs and renders it as a scalable, comparable, exportable maze graph. Offline dual-session comparison and the real-time tab share the same judgment and timeline rules, making it suitable for trace review and run variance analysis in the DSH development workflow.