轮次导航条 flyHZJ/dsh-turn-nav

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] 滚动容器内的位置，执行平滑滚动。

目录结构

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 插件命令安装：

从本地目录安装
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 的超级模组注入器环境中执行：

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

看到类似输出即成功：

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

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

从源码构建

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；
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