dsh-visual-trace

English

DeepSeek Harness 的跨运行方式自然语言轨迹可视化与审查插件。它不再只依赖 Web 的 trajectory 快照，而是以官方持久化的 session/event 日志为通用数据源，让 Web、headless、命令入口、ACP、SDK、自定义 UI 和 Hooks 插件共享同一套轨迹解释规则。

支持范围

运行方式	使用方式	输出
Web	对话中的“轨迹可视化”页签	可筛选时间线、详情面板、待审查确认、引用到对话
支持 Harness Commands 的界面	/visual-trace、/visual-trace markdown、/visual-trace json	文本、Markdown 或 JSON
Headless	安装到 headless profile 后正常运行任务	自然语言轨迹写入 stderr，最终模型回答仍保持在 stdout
ACP / JSON-RPC SDK	Host 适配器调用 ctx.visualTrace	标准节点或文本、Markdown、JSON
自定义 UI / TUI	读取 session/event，或直接调用通用服务	与 Web 相同的节点语义和审查规则
Hooks / 审计插件	在 Cordis 插件中调用 ctx.visualTrace.render()	可保存、上传或二次处理的轨迹报告

Headless、ACP 和 SDK 本身没有浏览器画布，因此不会强行模拟 Web 侧边栏；它们输出的是同一套节点、顺序、自然语言说明和审查信号。

flowchart LR
  A["官方 session/event 日志"] --> B["通用轨迹适配器"]
  B --> C["统一自然语言节点"]
  C --> D["Web 时间线"]
  C --> E["/visual-trace 命令"]
  C --> F["Headless stderr"]
  C --> G["ACP / SDK / Hooks"]

Web 功能

• 摘要语言跟随系统语言，支持中文和英文，不额外发起模型请求。
• 用 👤、✨、🧩、⚙️ 区分用户、模型、工具和系统节点，👀 标记待审查节点。
• 按轮次、节点类型、待审查状态或关键词筛选完整流程。
• 展开官方 tool/code-dispatch-* 子调用，web_search 等真实工具不会被外层 bash / run_code 隐藏。
• 点击节点后查看通俗说明、审查原因、原始输入、原始输出和原始 JSON。
• 在待审查卡片上直接确认，筛选结果和统计数量同步更新。
• 右键节点可“引用关键信息”或“引用完整记录”；详情面板中选中文字可添加到对话草稿。
• 引用后自动回到“对话”页签，保留用户已有草稿且不会自动发送。

安装

需要 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
npm run check

安装到需要使用的 profile：

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

自定义 profile 使用相同命令，将 profile 名称替换为自己的名称。

使用

Web

npx @deepseek-ai/dsh web

打开 http://127.0.0.1:3080，进入一个已有执行记录的任务，然后选择“轨迹可视化”。

命令入口

在任何支持 Harness Commands 的交互界面输入：

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

Headless

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

插件默认把轨迹写入 stderr，不会破坏 headless 原有的 stdout 最终回答。需要单独保存轨迹时可以重定向 stderr：

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

ACP、SDK、自定义 UI 与 Hooks

安装插件后，Host 侧 Cordis 插件可以直接使用：

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

build() 返回与 Web 时间线一致的标准节点（包括 Code Mode 的嵌套子工具）；render() 可用于终端、协议响应、审计文件或外部可视化界面。

配置

插件默认配置如下：

- 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 只在官方 headlessStartup 服务出现时启用 stderr 输出，Web 服务不会打印会话轨迹。

两种对话引用方式

• 引用关键信息：加入节点位置、自然语言说明、审查原因、原始输入和输出，适合日常定位问题。
• 引用完整记录：在上述内容之外加入完整原始事件，适合字段缺失、适配问题或逐项核对。

两种方式都只写入对话草稿，不会自动发送。引用内容会标记为不可信执行证据，并遮盖常见 API Key、Token、Secret 和 Password。

官方架构依据

本插件遵循 DeepSeek Harness 的以下设计：

• session/event 是 UI、回放和持久化的通用事实来源
• UI 与协议驱动都应从 session/event 渲染
• web 与 headless 是建立在同一个 dsh-base 上的不同 profile
• Headless 保持 stdout 为最终模型回答

兼容性

Harness 仍处于开发者预览阶段。本插件有意将依赖范围限定在 0.1.0-rc.6。官方事件类型变化时，只需更新 src/host/session-adapter.ts 和 src/client/adapter.ts，各输出界面无需分别重写。

开发

npm run typecheck
npm test
npm run build

许可证

MIT