dsh-visual-trace: A DeepSeek Harness Plugin for Natural Language Trace Visualization and Review Across Execution Modes

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

2. 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.

• GitHub Repository
• Community Directory Page