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 集成。