dsh-chat-nav

Readme

# dsh-chat-nav

**对话问题导航** — 为 [dsh（DeepSeek Harness）](https://deepseek-harness.github.io/deepseek-harness/) 开发的 Web UI 客户端插件：聊天视图左侧一条导航栏，每根横条对应一条真实发送的用户问题，悬浮有波浪反馈与内容预览，点击平滑跳转到对应消息，长会话自动补齐历史。

> dsh（DeepSeek Harness，[GitHub](https://github.com/deepseek-ai/deepseek-harness)）是一款"万物皆插件"的 DeepSeek 智能体框架。本插件是它的第三方插件，从 ZCode 桌面端的同款功能移植而来。

## 功能特性

- **问题导航栏**：对话列左侧一条悬浮竖轨，每条真实已发送的用户问题一根横条（排队介入的消息也会收录）；当前视口内的问题条自动高亮，并保持居中
- **悬停波浪**：横条按与指针的距离伸缩（2.6 / 1.7 / 1.25 倍），150ms 缓动，跟随系统「减少动态效果」设置自动关闭动画
- **内容预览**：悬停弹出预览卡，提问最多 2 行、回答最多 3 行；未开始回答 / 正在作答时显示占位文案
- **点击跳转**：平滑滚动定位到对应消息；目标在更早页（未加载）时自动逐页补拉后再精确锚定，锚点挂载超时兜底
- **历史补齐**：会话打开后后台逐页拉取全部更早历史（50 条/页），失败按 250ms / 1s 退避后终止；页面上滚到接近顶部时也会主动预取更早内容
- **可自定义**：设置 → 通用设置 → 「横条长度 / 条目间距」，实时生效并持久化

## 安装

需要先安装并运行 [dsh](https://deepseek-harness.github.io/deepseek-harness/)（Web UI profile）。

```sh
# 从 npm 安装
dsh plugin --profile web add dsh-chat-nav

# 本地目录
dsh plugin --profile web add ./dsh-chat-nav
```

安装后重启 dsh（客户端 bundle 在启动时加载）。

## 使用

打开任意会话，发送至少两条消息后，导航条出现在对话列左侧：

- 悬停横条查看该问题与回答的预览
- 点击横条跳转到对应消息
- 当前阅读位置的高亮自动跟随

定制外观：设置 → 通用设置 → 「对话问题导航」，可调整横条长度（8–48px）与条目间距（6–40px），修改即生效。

## 实现说明

纯客户端插件（浏览器半），宿主半为零依赖占位：

- 通过 `shell.overlay` 插槽挂载到 dsh Web UI，定位跟随对话区域（侧边栏/对话分界线右侧）
- 数据来自 `ctx.sessions` 会话快照（`chat.nodes`），跳转/滚动基于稳定 DOM 属性（`[data-conversation-scroll]`、`[data-chat-anchor-key]`）与官方同款 `flowTop` 几何方案
- 无状态管理框架依赖：localStorage 持久化配置，SnapshotStore 订阅驱动更新

## 与 ZCode 原版对照

| 特性 | ZCode（原版） | 本插件 |
|---|---|---|
| 悬停波浪 | 距离 → scaleX 2.6/1.7/1.25/1 | 同参数移植 |
| 预览裁剪 | 220 字符 / 2 段 + 省略号 | 同规则 |
| 预览布局 | 提问 2 行 / 回答 3 行 | 同 |
| 跳转 | 直滚 → 补拉 → rAF 轮询 12 帧 | 同 |
| 补拉节奏 | 250ms → 1s → 终止 | 同 |
| 近顶预取 | max(64, 2×视口) | 同 |
| active 判定 | 视口相交取最近起始行 | 同几何 |
| 自定义 | 无（固定 10px/条） | 横条长度与间距可在设置调整 |