dsh-conversation-nav-dots

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

---

📑 目录

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

---

📸 截图

寻常状态	悬停状态

---

概述

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