dsh-turn-nav

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# dsh-turn-nav

DSH（DeepSeek Harness）右侧会话轮次导航栏插件。

像 DeepSeek 网页端聊天界面右侧的目录一样，在 DSH 聊天窗口右侧悬浮一条窄导航，让你在多轮长会话中快速定位、跳转到任意一个历史轮次。

---

## 功能特性

- **右侧悬浮导航**：默认只显示数字圆点，不遮挡聊天内容。
- **悬停卡片**：鼠标悬停到某个圆点时，左侧弹出该轮次的提示卡片（显示“Q + 用户问题摘要”）。
- **快速跳转**：点击圆点，平滑滚动定位到对应轮次。
- **当前阅读位置高亮**：随滚动自动高亮当前所在轮次（蓝色圆点）。
- **自动刷新**：新消息、流式输出、加载历史时自动重建导航。
- **自动加载更早历史**：自动调用 DSH 的 `loadOlder()`，把之前分页未加载的轮次也补全，不需要手动滚动到顶部点“加载更早”。
- **不侵入官方 UI**：使用 `shell.overlay` 全局浮层，不替换、不遮挡 DSH 官方聊天界面。
- **DSH Bundle 兼容**：已声明 `dsh.bundle.patch`，可通过 `dsh plugin add` 安装。

---

## 界面效果

```
┌─────────────────────────────────────┐
│                                     │   ┌───┐
│  用户问题 1                          │   │ 1 │  ← 悬停弹出卡片：
│  AI 回答 1                           │   └───┘    “Q 用户问题摘要...”
│                                     │   ┌───┐
│  用户问题 2                          │   │ 2 │
│  AI 回答 2                           │   └───┘
│                                     │   ┌───┐
│  ...                                │   │ 3 │  ← 当前阅读位置高亮蓝色
│                                     │   └───┘
└─────────────────────────────────────┘
```

---

## 工作原理

1. 插件通过 DSH 的 `shell.overlay` slot 注册一个全局浮层组件。
2. 组件扫描当前会话中已渲染的聊天节点：

   - 优先取 `data-chat-flow-kind="user"` / `"steering"` 的行作为“轮次”；
   - 如果没有用户行，则回退取 `assistant-step` / `turn-tail`。

3. 每个轮次生成一个导航圆点，并提取消息文本作为悬停卡片内容。
4. 使用 `MutationObserver` 监听聊天 DOM 变化，自动重建导航。
5. 使用 DSH 的 `session.loadOlder()` 自动向后翻页，把更早的历史轮次也加载进 DOM，从而被导航识别。
6. 点击圆点时，计算目标节点在 `[data-conversation-scroll]` 滚动容器内的位置，执行平滑滚动。

---

## 目录结构

```text
dsh-turn-nav/
├── package.json            # 插件元信息、dsh.bundle、client 注入声明
├── cordis.patch.yml        # bundle patch：安装时自动挂载插件行
├── tsconfig.json           # host 编译配置（只编译 src/index.ts）
├── tsdown.config.ts        # client 打包配置（生成 lib/client.js）
├── scripts/
│   └── build.sh            # host 构建脚本（依赖 DSH checkout）
├── src/
│   ├── index.ts            # host 侧：API 路由 + 状态工具
│   └── client/
│       └── index.ts        # client 侧：右侧导航浮层实现
├── lib/                    # 构建产物
│   ├── index.js            # host 产物
│   └── client.js           # client 产物（ModuleLoader bundle）
├── MARKET.md               # 上传插件市场详细教程
└── README.md
```

---

## 环境要求

- 已安装并运行 DSH（DeepSeek Harness）
- Node.js（构建时需要）
- 可选：DSH 源码 checkout（`deepseek-harness-master`），用于本地构建

---

## 安装方法

### 方法一：DSH Bundle 安装（推荐给普通用户）

因为插件已经声明 `dsh.bundle`，用户可以直接用 DSH 插件命令安装：

```sh
# 从本地目录安装
dsh plugin --profile web add ./dsh-turn-nav

# 或从 npm 安装（发布后）
dsh plugin --profile web add dsh-turn-nav

# 或从 GitHub 安装
dsh plugin --profile web add github:flyHZJ/dsh-turn-nav
```

安装后重启 `dsh web`，右侧导航即生效。

### 方法二：super-injector 运行时注入（适合本地开发调试）

在 DSH 的超级模组注入器环境中执行：

```text
dev_inject_plugin  {"dir": "C:/Users/J/Desktop/新建文件夹/dsh-turn-nav"}
```

看到类似输出即成功：

```text
OK: dsh-turn-nav 已注入
- host ✓
- client ✓ (lib/client.js)
```

重启后 super-injector 的 `autoRestore` 会自动恢复。

---

## 从源码构建

```bash
# 1. 设置 DSH 源码目录
export DSH_CHECKOUT="D:/ai小工具开发/dsh/deepseek-harness-master"

# 2. 构建 host
bash scripts/build.sh

# 3. 构建 client
npm run build:client
```

> 如果 Windows 环境没有 `bash`，可以参考下方“PowerShell 手动构建”章节。

---

## 热重载 / 更新

使用 super-injector 注入时，修改源码并重新构建后执行：

```text
dev_reload_package  {"packageName": "dsh-turn-nav"}
```

浏览器里刷新 DSH 页面即可看到最新效果。

使用 bundle 安装时，重新发布 npm 包后用户执行：

```sh
dsh plugin --profile web update dsh-turn-nav
```

---

## 卸载

### 卸载 super-injector 注入版

```text
dev_uninject_plugin  {"match": "dsh-turn-nav"}
```

### 卸载 bundle 安装版

```sh
dsh plugin --profile web remove dsh-turn-nav
```

---

## 上传到 DSH 插件市场

插件已经按 DSH 插件市场要求改造：

- 包名：`dsh-turn-nav`
- 声明了 `dsh.bundle.patch`
- 包含 `cordis.patch.yml`
- 包含已构建的 `lib/`
- 包含中英文 README 和 LICENSE

详细上传步骤见：

```text
MARKET.md
```

主要包括：

1. 确认 `package.json` 中 `repository` / `homepage` 已指向 `flyHZJ/dsh-turn-nav`；
2. `npm run build && npm run build:client`；
3. `npm publish` 发布到 npm；
4. Fork [awesome-dsh-plugin/awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)；
5. 在 `plugins.json` 中添加插件条目；
6. 提交 Pull Request。

---

## PowerShell 手动构建（无 bash 环境）

如果 Windows 上没有 `bash`，可以手动执行构建步骤：

```powershell
$root = "C:\Users\J\Desktop\新建文件夹\dsh-turn-nav"
$checkout = "D:\ai小工具开发\dsh\deepseek-harness-master"

# 1. 链接构建依赖
New-Item -ItemType Directory -Force -Path "$root\node_modules\@deepseek-ai" | Out-Null

$links = @{
  "node_modules\cordis" = "$checkout\vendor\cordis"
  "node_modules\cosmokit" = "$checkout\vendor\cosmokit"
  "node_modules\schemastery" = "$checkout\vendor\schemastery"
  "node_modules\@deepseek-ai\dsh-tools" = "$checkout\packages\core\tools"
  "node_modules\@deepseek-ai\dsh-llm" = "$checkout\packages\llm\llm"
  "node_modules\@deepseek-ai\dsh-system-prompt" = "$checkout\packages\core\system-prompt"
  "node_modules\@types\node" = "$checkout\node_modules\@types\node"
}

foreach ($name in $links.Keys) {
  $path = Join-Path $root $name
  if (Test-Path $path) { Remove-Item -Recurse -Force $path }
  New-Item -ItemType Directory -Force -Path (Split-Path $path -Parent) | Out-Null
  New-Item -ItemType Junction -Path $path -Target $links[$name] | Out-Null
}

# 2. 编译 host
& "$checkout\node_modules\.bin\tsc.cmd" -p "$root\tsconfig.json"

# 3. 编译 client
& "$checkout\node_modules\.bin\tsdown.cmd" --config "$root\tsdown.config.ts" --cwd "$root"
```

---

## 故障排查

### 1. 重启后 DSH 起不来，报 `declares no dsh.bundle`

如果你使用的是旧版本（`@dsh-external/dsh-turn-nav`），请升级到当前版本（`dsh-turn-nav`）。
当前版本已经正确声明：

```json
"dsh": {
  "bundle": {
    "patch": "./cordis.patch.yml"
  }
}
```

### 2. 悬停没有卡片

- 确认已重新构建并热重载 `lib/client.js`
- 刷新浏览器页面
- 检查是否有多个 DSH 窗口 / 缓存

### 3. 卡片太窄

插件已设置：

```css
min-width: 240px;
max-width: 400px;
```

如果仍觉得窄，可以修改 `src/client/index.ts` 里的 `STYLE_TEXT` 中 `.dsh-turn-nav-card` 的 `min-width` / `max-width`，然后重新构建、热重载。

### 4. 识别不到更早的轮次

插件会自动调用 `loadOlder()` 加载更早历史，最多 200 页。

如果仍然不全：

- 确认会话已打开（`openState === 'open'`）；
- 检查 DSH 是否处于加载中；
- 如果历史超过 200 页，可以调大 `MAX_OLDER_PAGES` 后重新构建。

---

## 自定义

| 配置项 | 位置 | 说明 |
|---|---|---|
| 卡片最小宽度 | `STYLE_TEXT` → `.dsh-turn-nav-card` → `min-width` | 默认 `240px` |
| 卡片最大宽度 | `STYLE_TEXT` → `.dsh-turn-nav-card` → `max-width` | 默认 `400px` |
| 导航右侧间距 | `STYLE_TEXT` → `.dsh-turn-nav` → `right` | 默认 `10px` |
| 导航垂直位置 | `STYLE_TEXT` → `.dsh-turn-nav` → `top` | 默认 `50%` |
| 自动加载历史页数上限 | `src/client/index.ts` → `MAX_OLDER_PAGES` | 默认 `200` |
| 摘要长度 | `src/client/index.ts` → `summarizeText()` → `max` | 默认 `60` 字符 |

---

## 相关文件

- 插件源码：`C:\Users\J\Desktop\新建文件夹\dsh-turn-nav`
- 上传市场教程：`MARKET.md`
- 注入 registry：`C:\Users\J\.dsh\super-injector\registry.json`
- Web profile：`C:\Users\J\.dsh\profiles\web\package.json`