dsh-chat-locator

dsh plugin --profile web add dsh-chat-locator

<div align="center">

<h1>dsh-chat-locator · 对话定位条</h1>

<p>DSH 轮次轨道的配置插件：刻度粗细、轨道左右侧、锚在悬停那根的曲线长度渐变，以及行数 / 字号 / 宽度都可调的纯文本悬停预览。</p>







<p><strong>语言：</strong> 简体中文 | <a href="README.en.md">English</a></p>

</div>

---

📋 目录

• [功能特性](#-功能特性)
• [快速开始](#-快速开始)
• [安装](#-安装)
• [使用方法](#-使用方法)
• [实现要点](#-实现要点)
• [标签](#-标签)
• [贡献指南](#-贡献指南)
• [许可证](#-许可证)

---

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，换成你自己的名字。

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/。

第三步 — 重启宿主

dsh web

宿主进程会缓存已导入的模块，所以新装或卸载的 bundle 要等宿主重启一次才会挂载 —— 重启是最可靠的方式。当前的 DSH 版本能热合成客户端条目，所以重新启用一个已装好的 bundle 有时刷新页面就生效；但新装仍然需要重启。

第四步 — 完成。 打开 DSH（http://127.0.0.1:3080），满足下面两条就算装好了：

• 设置侧栏里出现了 对话定位条（英文界面为 Conversation locator）；
• 在一个至少两轮的对话里，浏览器控制台执行下面这行返回 railFound: true：

__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 更新，而不是每次重下文件，走这条路。

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：

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）：

$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"

然后重启宿主：

dsh web

安装说明

• DSH 会自动登记 bundle。 声明了 dsh.bundle.patch 的包会被写进 profile 的 dsh.profile.bundles 列表，所以 dsh plugin add 就是全部步骤。
• 没有构建步骤。 从 git 托管地址安装时 pnpm 可能提示构建脚本被拦；本插件既没有 prepare 脚本也没有内置依赖，所以没有任何需要放行的东西。
• 安装或卸载之后要重启宿主。 重启是最可靠的方式；当前 DSH 版本能热合成客户端条目，

…(truncated)