dsh-conversation-nav-dots

Readme

# dsh-conversation-nav-dots

> DSH 网页端对话导航点 — 快速跳转用户消息。

[![DSH](https://img.shields.io/badge/DSH-Plugin-4f8cff)](https://github.com/deepseek-ai/deepseek-harness)
[![DSH Market](https://raw.githubusercontent.com/2BingLing/dsh-market/master/assets/readme/badge-listed-zh.svg)](https://dsh.market/)
[![npm version](https://img.shields.io/npm/v/dsh-conversation-nav-dots)](https://www.npmjs.com/package/dsh-conversation-nav-dots)
[![npm downloads](https://img.shields.io/npm/dm/dsh-conversation-nav-dots)](https://www.npmjs.com/package/dsh-conversation-nav-dots)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/yuioi666/dsh-conversation-nav-dots?style=social)](https://github.com/yuioi666/dsh-conversation-nav-dots)
[![English](https://img.shields.io/badge/lang-en-blue)](https://github.com/yuioi666/dsh-conversation-nav-dots/blob/main/README.en.md)

---

## 📑 目录

- [📸 截图](#-截图)
- [概述](#概述)
- [功能特性](#功能特性)
- [快速开始](#快速开始)
- [安装](#安装)
- [使用说明](#使用说明)
- [工作原理](#工作原理)
- [代码示例](#代码示例)
- [常见问题 (FAQ)](#常见问题-faq)
- [包结构](#包结构)
- [依赖](#依赖)
- [贡献指南](#贡献指南)
- [协议](#协议)

---

## 📸 截图

| 寻常状态 | 悬停状态 |
|---|---|
| ![Normal](img/screenshot-normal.png) | ![Hover](img/screenshot-hover.png) |

---

## 概述

**dsh-conversation-nav-dots** 在 DSH Web 对话界面的右侧添加一列导航标记。每个标记对应一条用户消息。点击即可跳转，悬停可预览所有消息内容。

> 适用于长对话快速导航，类似代码编辑器的行号标记功能。

---

## 功能特性

| 特性 | 说明 |
|:----|:-----|
| 🎯 **极简 UI** | 寻常状态下，右侧只显示细横线标记，不干扰阅读 |
| 👁️ **悬停预览** | 鼠标悬停到右侧区域，展开完整消息预览面板 |
| ⚡ **即时跳转** | 点击任意标记或预览文本，直接跳转到对应消息（无动画） |
| 🔵 **活跃跟踪** | 当前可见消息对应的标记显示蓝色高亮 |
| 🔄 **自动更新** | 切换对话时自动刷新导航点 |
| 📜 **可滚动** | 消息过多时导航列表可滚动（最大高度约视口 20%） |
| 🪶 **轻量** | 纯 DOM 实现，无额外依赖，零运行时开销 |

---

## 快速开始

安装后 **30 秒** 即可体验：

```bash
# 1. 安装插件
dsh plugin --profile web add dsh-conversation-nav-dots

# 2. 重启 DSH Web
dsh web

# 3. 打开任意对话 → 查看右侧边缘的导航标记
```

---

## 安装

### 前提条件

- 已安装 [DSH](https://github.com/deepseek-ai/deepseek-harness)（DeepSeek Harness）
- 使用默认的 `web` 配置

### 从 npm 安装最新版

```bash
dsh plugin --profile web add dsh-conversation-nav-dots
```

### 安装指定版本

```bash
dsh plugin --profile web add dsh-conversation-nav-dots@1.0.0
```

### 从本地源码安装

```bash
dsh plugin --profile web add /path/to/dsh-conversation-nav-dots
```

安装完成后，**重启 DSH Web**：

```bash
dsh web
```

### 卸载

```bash
dsh plugin --profile web remove dsh-conversation-nav-dots
```

然后重启 DSH Web 即可。

---

## 使用说明

1. 在 DSH Web 中打开一个**对话**。
2. 查看屏幕 **右侧边缘** — 你会看到一列细横线标记。
3. **悬停** 到标记上，展开消息预览面板。
4. **点击** 任意标记或预览文本，跳转到对应消息。
5. **蓝色标记** 表示当前正在查看的消息。

> 💡 **提示**：如果对话只有几条消息，可能不需要导航。在长对话（10+ 轮）中效果最佳。

---

## 工作原理

插件监听对话的滚动容器（`[data-conversation-scroll]`）中的用户消息元素（`[data-chat-flow-kind="user"]`）。使用 `position: fixed` 在屏幕右侧构建一列垂直导航标记。通过 `requestAnimationFrame` + `IntersectionObserver` 跟踪当前可见的消息，并将对应标记高亮为蓝色。

核心流程：

```
用户消息变化 → 重建标记列表 → 注入 IntersectionObserver
    ↓                                       ↓
滚动时 RAF 节流 ← 更新活跃标记 ← IntersectionObserver 触发
```

---

## 代码示例

### 基本用法

安装后，插件自动生效。无需手动配置。

### 自定义主题色（通过 CSS 变量）

你可以在自己的样式表中覆盖以下 CSS 变量来定制外观：

```css
/* 自定义导航点颜色主题 */
:root {
  --dsh-nd-active: #ff6b6b;              /* 活跃标记颜色 */
  --dsh-nd-marker-active: #ff6b6b;        /* 活跃标记底色 */
  --dsh-nd-marker-active-glow: rgba(255,107,107,0.6); /* 活跃发光 */
  --dsh-nd-hover-bg: rgba(0,0,0,0.5);    /* 悬停背景 */
  --dsh-nd-text: rgba(255,255,255,0.8);   /* 文字颜色 */
  --dsh-nd-row-hover-text: #ffffff;       /* 悬停文字颜色 */
}
```

### 开发者：监听导航跳转事件

```javascript
// 在浏览器控制台中测试
document.querySelector(".dsh-nd-row")?.click();
```

---

## 常见问题 (FAQ)

### Q: 安装后看不到导航点？

**A:** 请确认：
1. 已重启 DSH Web（`dsh web`）
2. 打开了一个对话（不是设置页面）
3. 对话中至少有一条用户消息

### Q: 导航点会遮挡对话内容吗？

**A:** 不会。寻常状态下导航点只显示为细线标记（宽 24px），位于屏幕最右侧边缘。只有悬停时才会展开面板。

### Q: 支持暗色主题吗？

**A:** 原生支持。插件的颜色值在暗色背景下已优化，且所有颜色均通过 CSS 变量暴露，可自由定制。

### Q: 导航点在小屏幕（手机）上工作吗？

**A:** 插件设计用于桌面端。在移动端视口较窄时，导航点仍会显示，但体验可能不如桌面端。

### Q: 如何更新到最新版本？

**A:** 运行 `dsh plugin --profile web update dsh-conversation-nav-dots`，然后重启 DSH Web。

### Q: 会影响 DSH 性能吗？

**A:** 极低影响。插件使用 `IntersectionObserver`（非轮询）、`requestAnimationFrame` 节流、事件委托，并且 1 秒间隔的 watch 循环仅做引用比较，无 DOM 重查。

---

## 包结构

```
dsh-conversation-nav-dots/
├── lib/
│   ├── client.js        # 客户端插件（浏览器端）
│   └── index.js          # 服务端透传
├── cordis.patch.yml      # Bundle 层声明
├── scripts/
│   └── build.mjs         # 构建脚本
├── img/
│   ├── screenshot-normal.png
│   └── screenshot-hover.png
├── package.json
├── README.md
├── README.en.md
├── PUBLISHING.md         # 发布说明
├── .gitignore
└── LICENSE
```

---

## 依赖

| 包名 | 版本 | 说明 |
|------|------|------|
| `@deepseek-ai/cordis` | ^4.0.1 | Cordis 框架 |
| `@deepseek-ai/dsh-client-runtime` | ^0.1.1-rc.2 | DSH 客户端运行时 |
| `@deepseek-ai/dsh-client-ui-conversation` | ^0.1.1-rc.2 | 对话 UI 组件 |

---

## 贡献指南

欢迎贡献！无论是提交 bug 报告、功能建议，还是代码 PR，都感谢你的参与。

### 提交 Issue

- [GitHub Issues](https://github.com/yuioi666/dsh-conversation-nav-dots/issues)
- 请描述清楚：复现步骤、期望行为、实际行为、环境信息

### 提交 Pull Request

1. Fork 本仓库
2. 创建特性分支（`git checkout -b feature/my-feature`）
3. 提交更改（`git commit -m 'feat: add my feature'`）
4. 推送到分支（`git push origin feature/my-feature`）
5. 打开 Pull Request

### 开发环境

```bash
git clone https://github.com/yuioi666/dsh-conversation-nav-dots.git
cd dsh-conversation-nav-dots
npm install
npm run build
```

---

## 协议

MIT