对话导航点yuioi666/dsh-conversation-nav-dots

dsh-conversation-nav-dots

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

DSH
DSH Market
npm version
npm downloads
License
GitHub stars
English

📑 目录

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

📸 截图

| 寻常状态 | 悬停状态 |
|---|---|
| Normal | Hover |

概述

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

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

功能特性

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

快速开始

安装后 30 秒 即可体验：

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

2. 重启 DSH Web
dsh web

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

安装

前提条件

- 已安装 DSH（DeepSeek Harness）
- 使用默认的 web 配置

从 npm 安装最新版

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

安装指定版本

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

从本地源码安装

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

安装完成后，重启 DSH Web：

dsh web

卸载

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 变量来定制外观：

/* 自定义导航点颜色主题 /
: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;       / 悬停文字颜色 */
}

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

// 在浏览器控制台中测试
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
- 请描述清楚：复现步骤、期望行为、实际行为、环境信息

提交 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

开发环境

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

协议

MIT