dsh-visual-trace：DeepSeek Harness 跨運行方式自然語言軌跡可視化與審查插件

前言¶

DeepSeek Harness (DSH) 的原生調試主要依賴 Web 端的 trajectory 快照。在 Headless、ACP 或 SDK 等非瀏覽器環境下，開發者難以獲取統一的執行軌跡。dsh-visual-trace 插件以官方持久化的 session/event 日誌爲通用數據源，通過一套統一的解釋規則，將軌跡輸出到 Web 界面、命令行、Headless 標準錯誤流以及 SDK 上下文中。

核心能力¶

統一數據源：以官方持久化的 session/event 日誌爲數據基礎。
多端支持：覆蓋 Web、Headless、ACP/SDK、自定義 UI 和 Hooks 插件。
節點可視化：使用圖標區分用戶、模型、工具和系統節點。
多維篩選：支持按輪次、節點類型、待審查狀態或關鍵詞篩選流程。
靈活輸出：支持 /visual-trace 命令輸出文本、Markdown 或 JSON。
Headless 適配：在 Headless 模式下將軌跡寫入 stderr，不干擾 stdout 的最終回答。

安裝與啓用¶

需要安裝 DeepSeek Harness 0.1.0-rc.6 和 Node.js ^22.19.0 || >=24.0.0。

克隆倉庫並安裝依賴：

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

安裝到指定的 profile（以 Web 爲例）：

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

典型用法¶

Web 界面¶

啓動 Web 服務：

npx @deepseek-ai/dsh web

打開 http://127.0.0.1:3080，在已有任務中選擇“軌跡可視化”頁籤。

命令行交互¶

在支持 Harness Commands 的界面輸入：

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

Headless 模式¶

運行 Headless 任務：

npx @deepseek-ai/dsh --profile headless "檢查項目並運行測試"

軌跡默認寫入 stderr。若需單獨保存，可重定向輸出：

npx @deepseek-ai/dsh --profile headless "檢查項目並運行測試" 2>visual-trace.txt

SDK / ACP / Hooks¶

安裝插件後，Host 側 Cordis 插件可直接調用：

// 構建標準節點
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')

配置項¶

插件默認配置如下（YAML 格式）：

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

適用場景與注意¶

適用場景：需要在 Headless 或 SDK 環境下追蹤 Agent 執行流程的開發者；需要統一 UI、命令行和協議輸出格式的插件開發者。
運行權限：插件以當前 DSH 進程的權限運行，安裝前應檢查源碼與許可證。
生態說明：本插件爲社區目錄收錄項目，與 DeepSeek / 幻方無官方從屬關係。

總結¶

該插件解決了 DSH 在多運行環境下的軌跡可視化問題，提供了從數據源到多種輸出端的完整鏈路。開發者可根據需求選擇 Web 界面審查或通過 SDK/API 集成。