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 注入时，修改源码并重新构建后执行：

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

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

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

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

---

卸载

卸载 super-injector 注入版

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

卸载 bundle 安装版

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

---

上传到 DSH 插件市场

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

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

详细上传步骤见：

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，可以手动执行构建步骤：

$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）。 当前版本已经正确声明：

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

2. 悬停没有卡片

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

3. 卡片太窄

插件已设置：

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