Introduction

The native debugging of DeepSeek Harness (DSH) primarily relies on trajectory snapshots on the Web. In non-browser environments such as Headless, ACP, or SDK, developers find it difficult to obtain a unified execution trace. The dsh-visual-trace plugin uses the official persistent session/event logs as a universal data source and applies a unified set of interpretation rules to output trajectories to the Web UI, command line, Headless standard error stream, and SDK context.

Core Capabilities

  • Unified data source: Uses official persistent session/event logs as the data foundation.
  • Multi-endpoint support: Covers Web, Headless, ACP/SDK, custom UI, and Hooks plugins.
  • Node visualization: Uses icons to distinguish user, model, tool, and system nodes.
  • Multi-dimensional filtering: Supports filtering flows by round, node type, pending review status, or keywords.
  • Flexible output: Supports the /visual-trace command to output text, Markdown, or JSON.
  • Headless compatibility: In Headless mode, writes the trace to stderr without disturbing the final answer on stdout.

Installation and Enablement

Requires DeepSeek Harness 0.1.0-rc.6 and Node.js ^22.19.0 || >=24.0.0.

  1. Clone the repository and install dependencies:
    git clone https://github.com/wikiiizhao/dsh-visual-trace.git
    cd dsh-visual-trace
    npm install
  1. Install to the specified profile (using Web as an example):
    npx @deepseek-ai/dsh plugin --profile web add .

Typical Usage

Web Interface

Start the Web service:

npx @deepseek-ai/dsh web

Open http://127.0.0.1:3080, and in an existing task select the “Trajectory Visualization” tab.

Command-line Interaction

In an interface that supports Harness Commands, enter:

/visual-trace
/visual-trace markdown
/visual-trace json

Headless Mode

Run a Headless task:

npx @deepseek-ai/dsh --profile headless "检查项目并运行测试"

The trace is written to stderr by default. If you need to save it separately, redirect the output:

npx @deepseek-ai/dsh --profile headless "检查项目并运行测试" 2>visual-trace.txt

SDK / ACP / Hooks

After installing the plugin, the Host-side Cordis plugin can call it directly:

// 构建标准节点
const nodes = ctx.visualTrace.build(session.events, 'zh')

// 渲染为 Markdown
const markdown = ctx.visualTrace.render(session.events, 'markdown', 'zh')

// 渲染为 JSON
const json = ctx.visualTrace.render(session.events, 'json', 'en')

Configuration

The plugin default configuration is as follows (YAML format):

- id: visual-trace
  name: dsh-visual-trace
  config:
    language: system        # system | zh | en
    headlessOutput: auto    # auto | off | stderr | stdout
    headlessFormat: text    # text | markdown | json

Applicable Scenarios and Notes

  • Applicable scenarios: Developers who need to track Agent execution flows in Headless or SDK environments; plugin developers who need a unified UI, command-line, and protocol output format.
  • Runtime permissions: The plugin runs with the permissions of the current DSH process. Check the source code and license before installing.
  • Ecosystem note: This plugin is a project listed in the community directory and has no official affiliation with DeepSeek / High-Flyer.

Summary

The plugin resolves the trace visualization issue for DSH across multiple runtime environments, providing a complete pipeline from data source to various output endpoints. Developers can review it via the Web UI or integrate it through SDK/API as needed.