dsh-visual-trace

中文

A cross-surface plain-language trajectory visualization and review plugin for DeepSeek Harness. It no longer relies only on the Web trajectory snapshot. The durable official session/event log is its shared source for Web, headless, commands, ACP, SDK, custom UIs, and hook plugins.


Support matrix

Headless, ACP, and SDK do not have a browser canvas, so the plugin does not imitate a Web drawer there. They receive the same nodes, ordering, summaries, and review signals in portable formats.

flowchart LR
  A["Official session/event log"] --> B["Shared trajectory adapter"]
  B --> C["Normalized plain-language nodes"]
  C --> D["Web timeline"]
  C --> E["/visual-trace command"]
  C --> F["Headless stderr"]
  C --> G["ACP / SDK / Hooks"]

Web features

• Chinese or English summaries follow the system language without extra model requests.
• 👤, ✨, 🧩, and ⚙️ distinguish user, model, tool, and system nodes; 👀 marks review items.
• Filter by turn, node type, review status, or keyword.
• Expand official tool/code-dispatch-* children so tools such as web_search are not hidden behind an outer bash / run_code call.
• Inspect a node's explanation, review hints, raw input, raw output, and raw JSON.
• Confirm review items directly on their cards; counts and filters update immediately.
• Right-click a node to reference key details or its full record; select text in the details panel to add only that excerpt.
• Referencing evidence returns to Chat, preserves the current draft, and never sends automatically.

Installation

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

git clone https://github.com/wikiiizhao/dsh-visual-trace.git
cd dsh-visual-trace
npm install
npm run check

Install into each profile that should expose the plugin:

npx @deepseek-ai/dsh plugin --profile web add .
npx @deepseek-ai/dsh plugin --profile headless add .

Use the same command with your own profile name for custom profiles.

Usage

Web

npx @deepseek-ai/dsh web

Open http://127.0.0.1:3080, select a task with execution history, and open Visual Trace.

Commands

In any interactive surface that dispatches Harness Commands:

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

Headless

npx @deepseek-ai/dsh --profile headless "inspect the project and run tests"

The trace goes to stderr by default, preserving the official final-answer-only stdout behavior. Redirect stderr to save it separately:

npx @deepseek-ai/dsh --profile headless "inspect the project and run tests" 2>visual-trace.txt

ACP, SDK, custom UIs, and hooks

Once mounted, another Host-side Cordis plugin can use:

const nodes = ctx.visualTrace.build(session.events, 'en')
const markdown = ctx.visualTrace.render(session.events, 'markdown', 'en')
const json = ctx.visualTrace.render(session.events, 'json', 'en')

build() returns the same normalized nodes used by the Web timeline, including nested Code Mode tools. render() is suitable for terminals, protocol responses, audit artifacts, and external visualization layers.

Configuration

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

auto enables stderr output only when the official headlessStartup service is mounted. It never prints session traces from the Web server.

Chat reference modes

• Reference key details includes the node locator, explanation, review signals, raw input, and raw output.
• Reference full record additionally includes the complete source event for adapter or field-level investigation.

Both actions only update the conversation draft. Inserted evidence is marked untrusted, and common API keys, tokens, secrets, and passwords are redacted.

Official architecture basis

• session/event is the shared source for UI, replay, and persistence
• UI and protocol drivers render from session/event
• web and headless are profiles over the same dsh-base
• Headless keeps stdout for the final assistant answer

Compatibility

Harness is still a developer preview. Compatibility is intentionally pinned to 0.1.0-rc.6. When official event types change, update src/host/session-adapter.ts and src/client/adapter.ts; individual output surfaces do not need separate rewrites.

Development

npm run typecheck
npm test
npm run build

License

[MIT](LICENSE)