dsh-user-question-nav

Readme

# dsh-user-question-nav

ChatGPT 风格的问题导航插件：在 DeepSeek Harness 对话区域右侧显示一个胶囊轨道，包含双箭头（⏫⏬）和刻度尺（tick marks），悬停停留 1 秒后自动展开贴边抽屉目录，列出全部用户问题，点击即可跳转。

## 核心功能

| 功能 | 行为 |
|---|---|
| **胶囊轨道** | 对话区右侧浮动的纵向轨道，包含上下箭头 + 刻度线（每条刻度对应一个用户问题）|
| **悬停停留** | 鼠标悬停在刻度区域 **持续 1 秒**后，贴边抽屉自动滑出，展示全部问题列表 |
| **快速扫过** | 鼠标快速扫过刻度区域（少于 1 秒）不会打开抽屉，避免误触 |
| **进度条反馈** | 悬停期间刻度区域底部出现蓝色进度条，1 秒填满后展开抽屉（无反馈的等待会让 UI 感觉卡顿）|
| **贴边抽屉** | 从对话区右缘内侧滑出的面板，包含搜索框 + 全部问题目录，每行显示 `序号 · 问题原文` |
| **搜索过滤** | 在抽屉顶部搜索框输入关键词，实时筛选问题列表，计数文案从「共 N 条」切换为「筛出 N 条」|
| **一键跳转** | 点击抽屉中的任意行 → 对话平滑滚动到对应问题（居中显示）|
| **刻度同步** | 滚动对话时，胶囊上的刻度自动跟随：当前问题刻度高亮为品牌蓝色，鼠标悬停的刻度加深 |
| **边界提示** | 到达第一条/最后一条问题时，对应箭头变灰但仍可点击；点击时弹出气泡提示「已经是第一个问题」/「已经是最后一个问题」，1.5 秒自动消失 |
| **会话切换** | 切换对话时分两步：旧滚动容器断开 → 自动回退默认位置 → MutationObserver + 轮询双通道等待新容器 → 重新挂载校准 |
| **位置漂移补偿** | 文本区可能因上方面板折叠/展开而整体位移（自身尺寸不变），低频定时器（1s）检测并自动校准轨道/抽屉位置 |

## 交互合约

| 操作 | 结果 |
|---|---|
| 鼠标在刻度区域停留 ≥ 1 秒 | 抽屉打开，进度条填满 |
| 快速扫过 / 提前离开 | 抽屉不打开 |
| 点击抽屉中任意行 | 跳转到对应问题 |
| 悬停 / 点击 ⏫⏬ 箭头 | 永不触发抽屉展开；直接跳转 |
| 抽屉打开时点击箭头 | 箭头仍可点击（轨道 z-index 高于抽屉），抽屉保持打开 |
| 到达边界时点击已变灰的箭头 | 弹出气泡提示，不跳转 |
| 在搜索框输入关键词 | 实时过滤，计数文案切换为「筛出 N 条」|
| 清空搜索框 | 恢复全部行，计数文案切回「共 N 条」|
| 切换会话 | 自动重新挂载到新对话容器 |

## 安装

### 方式一：从 npm 一键安装（推荐）

要求：已安装并运行过一次 [DeepSeek Harness Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop)。

```bash
dsh plugin --profile desktop add dsh-user-question-nav
```

完成后 **Cmd+Q** 退出 DSH Desktop，重新打开。

### 方式二：从源码安装（开发者）

适合修改源码、二次开发：

```bash
git clone git@github.com:xiaomujiang/dsh-user-question-nav.git
cd dsh-user-question-nav
pnpm install && pnpm build
./install-user-question-nav.command
# Cmd+Q 退出 DSH Desktop，重新打开
```

## 升级

```bash
dsh plugin --profile desktop add dsh-user-question-nav@latest
```

完成后重启 DSH Desktop。

## 卸载

```bash
dsh plugin --profile desktop remove dsh-user-question-nav
```

## 效果预览

![v0.2.0 预览 — 胶囊轨道 + 刻度 + 贴边抽屉](docs/screenshot-v0.2.0.png)

*截图展示：右侧胶囊轨道（⏫ 双箭头 + 8 条刻度 + ⏬ 双箭头），鼠标悬停 1 秒后贴边抽屉展开，搜索框 + 8 行问题目录，第 4 条高亮为当前问题。*

## 实现原理

### 挂载策略

`apply()` 中**立即创建完整 DOM（轨道 + 抽屉）并挂载到 `document.body`**，不等待对话区域出现。默认定位在视口右侧中间，然后异步查找对话滚动容器 (`[data-conversation-scroll]`)，找到后自动校准位置到对话区右侧边缘。

### 刻度布局

- **PITCH_MAX (13px) / PITCH_MIN (4px)**：刻度中心距的上限和下限
- 问题数少时用大间距，问题数多时压缩到最小 4px
- 压缩触发条件：`rail 可用高度 / 问题数量 < PITCH_MAX`
- 目标间距优先保证排在 `rail 可用高度` 之内；超出时才逐级压缩

### 导航逻辑

1. 通过 `[data-chat-flow-kind="user"]` 选择器定位所有用户消息
2. 用**消息中心位置**（而非顶部）判断跳转目标，避免连续点击时选中同一消息
3. `scrollTo({ behavior: 'smooth' })` 平滑滚动到视口中间

### 当前问题识别 (`updateCurrent`)

1. 已经滚到底部 → 最后一条就是当前
2. 否则找「最后一个已经滚到视口上方的消息」（top ≤ 视口 top）
3. 一条都没滚过去（在顶部）→ 第一条可见的消息

### 会话切换

- `MutationObserver` 监听 body 变化，检测 scrollport 的 `isConnected` 状态
- 旧 scrollport 断开 → 尝试重新查找 → 找到新容器自动挂载 → 没找到则重启轮询
- 同时观察 `[data-chat-flow]` 的 `childList`，消息增删时重建刻度/行

### 位置漂移

对话区域可能在不改变自身尺寸的情况下整体位移（上方出现横幅、面板折叠等），`ResizeObserver` 无法捕获这种情况。低频定时器（1 秒间隔）比对矩形位置，漂移超过 0.5px 则自动校准。

### 边界反馈

遵循项目「雷区.md #6」的既定决策：箭头到达边界时**只变灰、不 disable**。禁用按钮会让用户以为功能已坏。变灰按钮仍可点击，点击时弹出气泡提示。

### 图标区分

使用**双箭头**（⏫⏬）而非单箭头，与 DSH 自带的「回到底部」按钮（↓）明确区分。

## 开发

```bash
pnpm install        # 安装依赖
pnpm build          # 构建
pnpm typecheck      # 类型检查
```

### 端到端自检

```bash
# 在浏览器中打开 test/harness.html（需先 pnpm build）
open test/harness.html
# 或命令行无头执行（需要 Chrome）：
# 参考 test/harness.html 内注释的 Chrome headless 命令
```

## 结构

```
dsh-user-question-nav/
├── dsh.plugin.json        # DSH 插件清单
├── package.json           # npm 包元数据 + dsh.client 配置
├── cordis.patch.yml       # 挂载声明
├── tsconfig.json          # TypeScript 配置
├── tsdown.config.ts       # 构建配置（host + 两个 client bundle）
├── install-user-question-nav.command  # 一键安装脚本
├── docs/
│   └── screenshot-v0.2.0.png  # 效果预览
├── design/
│   ├── rail-live-proto.html    # 交互原型（3 种模式切换）
│   ├── README.md               # 设计迭代记录
│   └── ...
├── test/
│   ├── harness.html            # 端到端自动检验（33 条断言）
│   └── preview.html            # 真实产物视觉预览
└── src/
    ├── index.ts           # Host 端（空壳）
    ├── invariant.ts       # 不变量
    └── client/
        └── index.ts       # 客户端逻辑（轨道 + 抽屉 + 导航）
```

## 版本历史

### v0.2.0
- **新增**：胶囊轨道 + 刻度尺，每一条刻度对应一个用户问题
- **新增**：贴边抽屉目录，悬停停留 1 秒展开，搜索过滤 + 一键跳转
- **新增**：悬停进度条，停留 1 秒填满后展开（用户可见的等待反馈）
- **新增**：当前问题刻度高亮（蓝色），悬停刻度加深（深灰）
- **改进**：`updateCurrent` 算法重写（"滚到上方"判定 + 二分 + 底部兜底）
- **改进**：位置漂移低频兜底（ResizeObserver 盲区补偿）
- **改进**：会话切换恢复轮询，MutationObserver + 定时器双通道
- **变更**：按钮交互从 `disabled` 改为 `data-dim` + 气泡提示（遵循雷区.md #6）
- **测试**：33 条端到端自动检验全部通过

### v0.1.3 及更早
- 双箭头浮动按钮（⏫⏬）
- 消息中心导航 + 平滑滚动
- 会话切换自动重挂载
- DSH-better-sidebar 风格挂载策略

## 参考项目

- [deepseek-harness-desktop](https://github.com/anywhere-labs/deepseek-harness-desktop) — DeepSeek Harness 桌面客户端
- [DSH-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) — DSH 侧边栏插件，本插件的挂载策略参考了该项目

## 贡献

欢迎提 Issue 和 PR！

- **Bug 报告**：使用 [Bug 报告模板](https://github.com/xiaomujiang/dsh-user-question-nav/issues/new?template=bug_report.md)
- **功能请求**：使用 [功能请求模板](https://github.com/xiaomujiang/dsh-user-question-nav/issues/new?template=feature_request.md)

**PR 流程**：

```bash
git checkout dev
git checkout -b feat/your-feature    # 或 fix/your-bugfix
# ... 修改代码 ...
git commit -m "feat: 你的功能"
git push -u origin feat/your-feature
# 在 GitHub 上创建 PR → base: dev
# review 通过后合并到 dev
# 稳定后从 dev 合并到 main 发版
```

## 许可

MIT