dsh-chat-locator · 对话定位条
DSH 轮次轨道的配置插件：刻度粗细、轨道左右侧、锚在悬停那根的曲线长度渐变，以及行数 / 字号 / 宽度都可调的纯文本悬停预览。
[](LICENSE)
[](https://nodejs.org)
[](https://github.com/hawkongz/dsh-chat-locator)
[](https://www.npmjs.com/package/dsh-chat-locator)
[](https://awesome-dsh-plugin.com/p/hawkongz/dsh-chat-locator/)
[](https://github.com/deepseek-ai/deepseek-harness)
语言： 简体中文 | English
---
## 📋 目录
- [功能特性](#-功能特性)
- [快速开始](#-快速开始)
- [安装](#-安装)
- [使用方法](#-使用方法)
- [实现要点](#-实现要点)
- [标签](#-标签)
- [贡献指南](#-贡献指南)
- [许可证](#-许可证)
---
DSH 会沿对话区边缘画一条轮次轨道：每轮对话一枚刻度，让你在长会话里看得见位置、跳得动轮次。这条轨道做得不错，但它把三个主张钉死在代码里 —— 刻度永远是 2px；轨道永远在右侧；把指针搁在刻度上，它不会告诉你那一轮讲了什么。于是想在一次长对话里找回某一轮，只能一根一根地悬停过去。
这三件事都没有开关。轨道由 `@deepseek-ai/dsh-client-ui-chat` 的 `ChatView` 直接渲染，Slot 系统没有给它留座位，界面上也没有任何地方暴露粗细与轨道侧的设置。
`dsh-chat-locator` 是一个持久插件，把这些钉死的主张变成设置项。它**不替换**轨道 —— 而是在运行时认领轨道的样式，所以内置的跳转轮次、未加载轮分页与活跃轮跟随全都照旧工作。
## ✨ 功能特性
- **横线粗细：** 1–8px，不再是固定的 2px。只改线宽，10px 的刻度间距原样不动。
- **轨道位置：** 左侧或右侧。悬停预览会自动改到另一侧展开，所以永远不会遮住你正在读的正文。
- **悬停预览：** 内置的那张纯文本卡片，显示该轮的提示词与回复。卡片不是本插件拼的，正文它也不读 —— 它只改这张卡的样式：显示几行、字号多大、多宽、最多长多高、往哪一侧展开。内置的纯文本呈现（思考内容本来就进不去）原样不动。
- **预览正文行数：** 1–6 行。卡片真的会跟着变高 —— 只有超出的部分被裁掉。
- **预览字号与预览框宽度：** 10–18px 与 200–420px。字号与行高成对放大，所以放大文字既不会挤在一起，也不会被裁掉。
- **曲线长度渐变：** 指针下那根长到 32px，两侧沿曲线收回 —— `21 / 14 / 12` —— 整条轨道读起来是一个指向你所在位置的弯钩，而不是一截直斜线。
悬停那根就是锚点，当前轮被指着时也一样；邻居规则会跳过当前轮，所以当前轮即使落在指针旁边一两格也保持内置宽度。它有独立的开关：关掉后刻度回到各自的内置长度（普通 12px，悬停那根 18px），其余一切不变。
- **恢复默认：** 七项一键回到出厂值。用户层里只存与出厂值不同的字段，所以「按钮置灰」恰好等于「没有东西可清」；清空只需一次写入，历史版本留下的字段也会一并清掉。
- **独立设置页：** 设置 → 对话定位条（英文界面为 Conversation locator），页内带一条实时小样轨道与示例预览卡，改哪一项它就变哪一项。
- **无内置依赖、无构建步骤。** 两个半侧都是纯 ESM，由 Node 与浏览器直接加载；React、Cordis 与 DSH 客户端模块都由宿主提供，唯一的依赖声明是可选的 peer 依赖。
## 🚀 快速开始
> **前置条件：** 一份可用的 DSH 安装（有 `dsh` 命令）和一个 profile，外加 Node.js 20 或更新版本。插件本身没有额外要安装的东西。
**第一步 — 打开终端**
- macOS / Linux：打开终端（Terminal）。
- Windows：按 `Win + R`，输入 `powershell`，回车。
**第二步 — 把 bundle 装进你的 profile**
`dsh plugin` 会把参数转发给 profile 目录里的 pnpm，于是这个包会从 npm 装上，DSH 自动读到它的 patch。如果你的 profile 不叫 `web`，换成你自己的名字。
```bash
dsh plugin --profile web add dsh-chat-locator
```
想锁死某个版本、不跟新版本走，就带上版本号：`dsh plugin --profile web add dsh-chat-locator@1.5.1`
装完就完了。DSH 插件 bundle 就是四个文件：
| 文件 | 作用 |
| :--- | :--- |
| `package.json` | 声明 bundle 与浏览器半侧 |
| `index.js` | 宿主半侧 —— 1.4.0 起是空桩 |
| `client.js` | 浏览器半侧 —— 所有行为都在这里 |
| `cordis.patch.yml` | 把插件行插进配置树的 patch |
没有东西要编译，也没有内置依赖要装。发布出去的包里还带这份中文 README 与 `README.en.md` 英文版、`docs/design-notes.md` 与 `zh-CN/docs/design-notes.md`、`docs/images/` 里的截图、`CONTRIBUTING.md`、`SECURITY.md` 与 `test/`。
**第三步 — 重启宿主**
```bash
dsh web
```
宿主进程会缓存已导入的模块，所以新装或卸载的 bundle 要等宿主重启一次才会挂载 —— 重启是最可靠的方式。当前的 DSH 版本能热合成客户端条目，所以重新启用一个已装好的 bundle 有时刷新页面就生效；但新装仍然需要重启。
**第四步 — 完成。** 打开 DSH（`http://127.0.0.1:3080`），满足下面两条就算装好了：
- 设置侧栏里出现了 **对话定位条**（英文界面为 Conversation locator）；
- 在一个至少两轮的对话里，浏览器控制台执行下面这行返回 `railFound: true`：
```js
__dshChatLocator.state()
```
打开任意对话，把指针沿轨道上下滑一次：指针下那根会变长，两侧依次收回。
> 以后想更新：执行 `dsh plugin --profile web update dsh-chat-locator`，再重启宿主。卸载：`dsh plugin --profile web remove dsh-chat-locator`，然后重启宿主。
>
> **想跟仓库最新代码、要一份能自己改的本地副本，或者要离线安装？** 见[安装方式](#安装方式)。
## 📦 安装
### 环境要求
| 项目 | 版本 | 说明 |
| :--- | :--- | :--- |
| DSH | 0.2.x（已在 0.2.1-rc.2 上验证） | 提供 `dsh` 命令，以及你要装进去的那个 profile。轨道选择器约定自 0.1.7 起没有变过，但 1.5.0 是在 DSH 0.2.1-rc.2 上开发并验证的。浏览器半侧需要宿主提供的 `@deepseek-ai/dsh-client-store`（已在 `dsh.client` 里声明）。 |
| Node.js | 20 或更新 | 宿主半侧与测试套件用它。 |
| 现代浏览器 | 当前版本的 Chromium / Firefox / Safari | 渐变用 CSS `:is()` 与 `:has()`。没有 `:has()` 时只有指针**上方**那一半收拢失效 —— 悬停那根照样会变长，指针下方的刻度也照样收拢。其余功能照常。 |
### 安装方式
| 方式 | 适合谁 |
| :--- | :--- |
| `dsh plugin --profile web add dsh-chat-locator` | 大多数人。从 npm 装已发布的版本；带 `@1.5.1` 可以锁死具体版本。 |
| `dsh plugin --profile web add github:hawkongz/dsh-chat-locator` | 想直接跟 `main` 上最新提交、又不想手动 clone。锁的是 commit，不是版本号。 |
| [用 git clone 安装](#用-git-clone-安装) | 要改这个插件本身。 |
| [下载四个文件后安装](#不用-git-安装) | 访问不到 npm 或 GitHub，或者要离线安装。 |
### 用 git clone 安装
如果你想用 `git pull` 更新，而不是每次重下文件，走这条路。
```bash
git clone https://github.com/hawkongz/dsh-chat-locator.git
cd dsh-chat-locator
dsh plugin --profile web add "$(pwd)"
dsh web
```
### 不用 git 安装
一个 bundle 就是四个文件。把它们下到一个文件夹里、装这个文件夹、重启宿主，除此之外没有别的步骤。
macOS / Linux：
```bash
mkdir -p ~/.dsh/plugin-src/dsh-chat-locator
cd ~/.dsh/plugin-src/dsh-chat-locator
curl -fsSLO https://raw.githubusercontent.com/hawkongz/dsh-chat-locator/main/package.json
curl -fsSLO https://raw.githubusercontent.com/hawkongz/dsh-chat-locator/main/index.js
curl -fsSLO https://raw.githubusercontent.com/hawkongz/dsh-chat-locator/main/client.js
curl -fsSLO https://raw.githubusercontent.com/hawkongz/dsh-chat-locator/main/cordis.patch.yml
dsh plugin --profile web add ~/.dsh/plugin-src/dsh-chat-locator
```
Windows（PowerShell）：
```powershell
$dir = "$env:USERPROFILE\.dsh\plugin-src\dsh-chat-locator"
$base = "https://raw.githubusercontent.com/hawkongz/dsh-chat-locator/main"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
foreach ($file in "package.json", "index.js", "client.js", "cordis.patch.yml") {
Invoke-WebRequest -Uri "$base/$file" -OutFile "$dir\$file"
}
dsh plugin --profile web add "$dir"
```
然后重启宿主：
```bash
dsh web
```
### 安装说明
- **DSH 会自动登记 bundle。** 声明了 `dsh.bundle.patch` 的包会被写进 profile 的 `dsh.profile.bundles` 列表，所以 `dsh plugin add` 就是全部步骤。
- **没有构建步骤。** 从 git 托管地址安装时 pnpm 可能提示构建脚本被拦；本插件既没有 `prepare` 脚本也没有内置依赖，所以没有任何需要放行的东西。
- **安装或卸载之后要重启宿主。** 重启是最可靠的方式；当前 DSH 版本能热合成客户端条目，重新启用已装好的 bundle 有时刷新页面就生效。原因见[实现要点](#-实现要点)。
- **安装是按 profile 生效的。** `--profile web` 是这个插件开发时用的 profile，换成你自己的即可。
## 📖 使用方法
所有配置都在一个页面里：**设置 → 对话定位条**（英文界面为 Conversation locator）。下表列出每个控件、默认值与可选范围。
