dsh-visual-trace

Readme

# dsh-visual-trace

[English](README.en.md)

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

![dsh-visual-trace Web 界面](docs/dsh-visual-trace-demo.png)

## 支持范围

| 运行方式 | 使用方式 | 输出 |
|---|---|---|
| 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 侧边栏；它们输出的是同一套节点、顺序、自然语言说明和审查信号。

```mermaid
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`。

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

安装到需要使用的 profile：

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

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

## 使用

### Web

```sh
npx @deepseek-ai/dsh web
```

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

### 命令入口

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

```text
/visual-trace
/visual-trace markdown
/visual-trace json
```

### Headless

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

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

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

### ACP、SDK、自定义 UI 与 Hooks

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

```ts
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()` 可用于终端、协议响应、审计文件或外部可视化界面。

## 配置

插件默认配置如下：

```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
```

`auto` 只在官方 `headlessStartup` 服务出现时启用 stderr 输出，Web 服务不会打印会话轨迹。

## 两种对话引用方式

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

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

## 官方架构依据

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

- [`session/event` 是 UI、回放和持久化的通用事实来源](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md#session-log)
- [UI 与协议驱动都应从 `session/event` 渲染](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cookbook/extension-cookbook.md#a-ui-plugin)
- [`web` 与 `headless` 是建立在同一个 `dsh-base` 上的不同 profile](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md#profiles-and-bundles)
- [Headless 保持 stdout 为最终模型回答](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/headless/README.md)

## 兼容性

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

## 开发

```sh
npm run typecheck
npm test
npm run build
```

## 许可证

[MIT](LICENSE)