# dsh-session-navigator

面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的会话导航与轮次 Minimap 插件。

[English](README.md) · [MIT License](LICENSE)

`dsh-session-navigator` 给 DSH Web 界面补上优雅的全高会话导航轨道与轮次 Minimap：按真实比例在对话流右侧标注每一轮提问，悬停预览问答摘要并提供快捷操作（一键复制、导出 Markdown、快速翻轮），拖拽统一的滚动滑块极速浏览长对话——**不改任何官方包**。

## 解决什么问题

在多轮长会话中（动辄几十轮提问、代码生成与工具调用输出），通过普通滚动条查找特定轮次或早前的问题极其繁琐。DSH 官方目前缺乏会话 Minimap 或轮次大纲能力。本插件在对话流右侧提供一条轻量无感的全高导航轨道：

```
超长多轮对话流（50+ 轮代码 / 工具执行输出）
  -> 右侧全高极简导航轨道
  -> 悬停任意刻度点：浮现预览卡片，展示轮次编号、提问摘要与问答状态
  -> 卡片快捷操作：导出单轮 Markdown、一键复制问答、上一轮/下一轮步进
  -> 点击刻度点或卡片：平滑滚动直达目标提问，并触发聚焦点波纹动画
  -> 统一的拖拽滚动滑块，自动隐藏系统原生重复滚动条
```

## 特性

- **全高极简轨道**：贴合对话流右侧边缘的 1px 细线轴，无笨重胶囊外壳，视觉克制干净，完全融入界面。
- **真实比例刻度**：根据每轮对话在整页滚动高度中的实际物理 offsetTop 坐标计算 Marker 分布。
- **活跃轮次指示**：当前视口所处轮次以优雅的垂直细长条（Pill）高亮展示，随滚动动态平滑过渡（ScrollSpy）。
- **统一拖拽滑块**：内置平滑拖拽滚动滑块，自动隐藏浏览器原生重复滚动条，杜绝双滚动条重叠。
- **浮动预览卡片**：
  - 轮次徽标（如 `#2 Prompt` / `Q&A`）。
  - **导出 Markdown**：一键将该轮提问与回答下载为独立 `.md` 文件。
  - **一键复制**：复制该轮问答完整文本（带绿色对勾成功反馈）。
  - **轮次步进**：上一轮（`▲`）与下一轮（`▼`）快速翻页与平滑跳转。
  - 3 行自适应文本截断摘要与加粗序号。
- **平滑直达与波纹聚焦**：点击刻度点或预览卡片平滑定位至对应气泡，并带聚焦高光动画。
- **零核心修改**：纯 bundle 插件（`dsh.bundle` patch 层），通过官方 `shell.overlay` slot 注入，不改任何官方包。

## 安装

```sh
# 一行安装（git 源）
dsh plugin --profile web add github:wuxiangru915/dsh-session-navigator

# 重启 web 服务，然后强制刷新页面
```

本地开发：

```sh
dsh plugin --profile web add /path/to/dsh-session-navigator
```

仓库随附纯 JS 的 `lib/` 产物，无构建步骤，git 源安装无需在用户机器上执行任何构建。

## 用法

### Web UI

![会话导航](assets/session-navigator.png)

在 DSH Web 中打开任意会话：

- **导航轨道**：对话区域右侧边缘按真实比例呈现每轮提问的刻度点。
- **悬停预览**：鼠标悬停在刻度点上，浮现预览卡片展示提问摘要与操作栏。
- **点击直达**：点击刻度点或卡片直接平滑滚动定位到该轮消息。
- **快捷操作**：在卡片顶部可导出 Markdown、复制文本、或使用步进按钮前后翻轮。
- **拖拽滚动**：按住轨道上的视口滑块可直接拖拽滚动长对话。

## 架构

```
lib/
├── index.js   宿主端：cordis 插件空入口
└── client.js  浏览器端：__ModuleLoader__ bundle，挂载 shell.overlay slot
cordis.patch.yml   dsh.bundle patch 层——一行 insert 同时驱动宿主端与浏览器端
assets/
└── session-navigator.png   预览效果截图
```

```
浏览器端（shell.overlay slot）
  -> 扫描 [data-conversation-scroll] 与 [data-chat-anchor-key] 节点
  -> 计算真实高度比例坐标与滚动监听（ScrollSpy）
  -> 渲染全高轨道 + 浮动卡片 + 平滑滚动控制器
```

## Roadmap

- [x] 全高极简导航轨道
- [x] 真实比例刻度点与活跃 Pill 指示器
- [x] 浮动预览卡片（导出 MD、复制、上一轮/下一轮）
- [x] 统一视口拖拽滑块（隐藏重复原生滚动条）
- [x] 点击平滑直达与高光波纹
- [ ] 关键词搜索过滤 Marker
- [ ] 发布到 npm（`@dsh-plugin/dsh-session-navigator`）

## 要求

- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) >= 0.1.0-rc.5 (Cordis 4.x)
- Node.js >= 22

## License

[MIT](LICENSE)