hawkongz/dsh-chat-locator

dsh-chat-locator
DSH Web 的回合轨道设置：刻度粗细、轨道位置，以及以悬停刻度为锚点的曲线长度渐变——外加一个纯文本悬停预览，其行数、字号和宽度均由你控制。

License: MIT
Platform
Node.js
Stars

语言： English | 简体中文

📋 目录

- 功能特性
- 快速开始
- 安装
- 使用方法
- 工作原理
- 主题
- 贡献
- 许可证

DSH Web 会在每个对话的边缘绘制一条回合轨道：每个回合对应一个刻度，让你能看清自己在长会话中的位置，并在回合之间跳转。这是一条不错的轨道，但它内置了三个固定主张。刻度始终是 2px。轨道始终位于右侧。而且指向某个刻度时，你无法得知该回合包含什么内容，因此在长对话中寻找特定回合意味着要逐个悬停刻度。

这些都无法配置。该轨道由 @deepseek-ai/dsh-client-ui-chat 中的 ChatView 直接渲染；Slot 系统没有为它预留位置，也没有在任何地方暴露粗细或位置的设置。

dsh-chat-locator 是一个持久化的 DSH 插件，它将这些固定主张转变为可配置的设置。它不会替换轨道——而是在运行时接管轨道的样式，因此内置的跳转到回合、未加载回合分页以及活动回合跟随功能都完全照常工作。

✨ 功能特性

- 刻度粗细（横线粗细）： 1–8px，而非固定的 2px。仅线条宽度改变；10px 的刻度间距保持不变。
- 轨道位置（轨道位置）： 左侧或右侧。悬停预览会自动在相反一侧打开，因此绝不会遮挡你正在阅读的文本。
- 悬停预览： 一张纯文本卡片，显示该回合的提示词和回复。思考内容绝不会出现在其中，空白会被折叠，因此不可能包含空行，长文本会以省略号截断。
- 预览正文行数（预览正文行数）： 1–6 行。卡片会真正变大——只有溢出的部分会被裁剪。
- 预览字号 / 预览框宽度（预览字号 / 预览框宽度）： 10–18px 和 200–420px。字号与行高成对缩放，因此放大文字绝不会使其拥挤或被裁剪。
- 曲线长度渐变： 指针下的刻度增长到 32px，其相邻刻度沿曲线递减——21 / 14 / 12——因此轨道看起来像一个指向你所在位置的钩子，而不是一条直线斜边。它有自己的开关；关闭时，每个刻度保持其内置宽度，其他一切不变。
- 恢复默认 (Restore defaults)： 一键将全部七项设置恢复为出厂值，通过逐字段 unset 而非重写默认值来实现。
- 专用设置页面： 设置 → 对话定位条，带有实时示例轨道和示例预览卡片，会随你更改每个值而重新绘制。
- 零依赖，无需构建步骤。 两部分都是纯 ESM，由 Node 和浏览器直接加载。

🚀 快速开始

你需要什么： 一个可用的 DSH 安装（dsh 命令）并带有一个 profile，以及 Node.js 20 或更新版本。插件本身没有需要安装的依赖。

第 1 步 — 打开终端

- macOS / Linux：打开终端。
- Windows：按 Win + R，输入 powershell，然后按 Enter。

第 2 步 — 将 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.4.0

这就是整个安装过程。该包是 DSH 插件 bundle 所需的四个文件——package.json（声明 bundle 和浏览器部分）、index.js（宿主部分——自 1.4.0 起为空操作桩）、client.js（浏览器部分）和 cordis.patch.yml（添加插件行的 patch）——无需编译，也没有依赖需要安装。

第 3 步 — 重启宿主

dsh web

宿主进程会缓存已导入的模块，因此新添加的 bundle 要等到宿主重启一次后才会被挂载。

第 4 步 — 完成。 在 http://127.0.0.1:3080 打开 DSH Web 后，如果满足以下条件，你就完成了：

- 设置 → 对话定位条 出现在设置侧边栏中，并且
- 在浏览器控制台中，在至少有两次对话轮次的会话上，以下代码返回 railFound: true：

__dshChatLocator.state()

打开一个会话，将指针沿轨道上下滑动：指针下方的刻度会变大，其相邻刻度会逐渐变细。

更新：运行 dsh plugin --profile web update dsh-chat-locator，然后重启宿主。卸载：运行 dsh plugin --profile web remove dsh-chat-locator，然后重启宿主。

想要最新的未发布提交、可编辑的本地副本，或离线安装？ 参见 安装方式。

📦 安装

要求

| 要求 | 版本 | 备注 |
| :--- | :--- | :--- |
| DSH | 0.1.7 或更新版本 | 提供 dsh 命令以及你安装到的 profile。浏览器部分通过 @deepseek-ai/dsh-client-store 持久化设置，更早的版本不包含该模块。 |
| Node.js | 20 或更新版本 | 供宿主部分和测试套件使用。 |
| 支持 :has() 的浏览器 | Chromium 105+ | 没有它时长度渐变不会生效；其他一切仍然正常工作。 |

安装方式

| 方式 | 最适合 |
| :--- | :--- |
| dsh plugin --profile web add dsh-chat-locator | 大多数用户。从 npm 安装已发布的版本；追加 @1.4.0 可固定到确切版本。 |
| dsh plugin --profile web add github:hawkongz/dsh-chat-locator | main 分支上的最新提交，无需手动克隆。锁定的是提交而非版本。 |
| 从 git 克隆安装 | 正在开发插件本身。 |
| 从四个下载的文件安装 | 无法访问 npm 或 GitHub 网络，或使用离线机器。 |

从 git 克隆安装

如果你更愿意用 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 安装

一个包就是四个文件。将它们下载到一个文件夹，安装该文件夹，然后重启宿主——无需其他操作。

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 会为你注册该包。 声明了 dsh.bundle.patch 的包会自动添加到你的配置文件的 dsh.profile.bundles 列表中，因此 dsh plugin add 是唯一的步骤。
- 没有构建步骤。 pnpm 可能会针对托管在 git 上的包打印一条关于构建脚本被阻止的提示；此插件没有 prepare 脚本，也没有依赖项，因此无需允许任何内容。
- 安装或移除后请重启宿主。 原因见工作原理。
- 安装是按配置文件进行的。 --profile web 是开发此插件时所用的配置文件；请替换为你自己的配置文件。

📖 用法

所有内容都在一个设置页面上：设置 → 对话定位条。下表列出了每个控件及其默认值和范围。

设置存储位置

设置存储在此浏览器的本地存储中（键为 dsh.chat-locator.settings），在你更改值时立即写入：

- 它们会在关闭并重启浏览器以及刷新 DSH Web 后保留。
- 它们不会在浏览器、配置文件或机器之间同步——每个浏览器保留自己的副本。
- 清除站点数据（或使用隐私窗口，或换一个浏览器）会重新从出厂值开始。
- 自 1.4.0 起，插件不再读取 DSH 设置文档，因此 1.3.0 或更早版本留在其中的任何 chat-locator: 部分都会被忽略。升级后，首次运行会显示出厂值。

| 设置 | 默认值 | 范围 | 作用 |
| :--- | :--- | :--- | :--- |
| 显示对话定位条显示对话定位条 | 开 | 开 / 关 | 隐藏整个定位条。跳转和未加载轮次分页不受影响。 |
| 长度渐变长度渐变 | 开 | 开 / 关 | 悬停刻度及其相邻刻度变长的曲线渐变。关闭后每个刻度都恢复其内置宽度——定位条、跳转、分页和预览均不受影响。 |
| 横线粗细横线粗细 | 2px | 1–8px | 每个轮次刻度的线宽。刻度间距保持 10px，因此 8px 是实际的上限。 |
| 轨道位置轨道位置 | 右 | 左 / 右 | 定位条贴近对话区域的哪一侧边缘。悬停预览会自动在相反一侧打开。 |
| 预览正文行数预览正文行数 | 3 | 1–6 | 显示回复的多少行。卡片随内容增长；只有溢出的部分会被裁剪。 |
| 预览字号预览字号 | 12px | 10–18px | 卡片的字号。行高按 1.5 倍随其缩放，卡片高度也按同一行高计算，因此更大的文字永远不会被裁剪。 |
| 预览框宽度预览框宽度 | 300px | 200–420px | 卡片的宽度。它保留内置的容器限制，因此在窄窗口中会自动收缩。 |
| 恢复默认恢复默认 | — | — | 将所有七项设置重置为出厂值。当所有设置都已为默认值时禁用。 |

长度渐变

你指向的刻度最长，其周围的刻度沿曲线逐渐变短：

| 与悬停刻度的距离 | 0 | ±1 | ±2 | ≥3 |
| :--- | :--- | :--- | :--- | :--- |
| 宽度 | 32px | 21px | 14px | 12px |
| 每级递减 | — | 11px | 7px | 2px |

相邻刻度让出的宽度最多，然后逐渐减少，在重新汇入定位条时趋于平缓。宽度表由 12 + 20 * (1 - d/3)^2 生成，docs/design-notes.md 记录了指数是如何调校的（2.5 是断崖，1.5 让相邻刻度太长，2.0 是当前采用的折中）。渐变以悬停刻度为锚点——活动轮次的刻度永远不会被调整大小——并且指针一离开就消失。与悬停预览不同（悬停预览没有开关，因为一个无法预览的定位条就不是定位条），渐变是装饰性的，并且有自己的设置行；关闭它也会取消边框加宽，因为没有 32px 的峰值需要腾出空间。

故障排除

插件附带一个调试钩子。在浏览器控制台中运行它：

__dshChatLocator.state()
// {
//   railPrefix: 'eGxaPq', railFound: true, rules: '…',
//   config: { … }
// }

| 你看到的内容 | 含义 |
| :--- | :--- |
| railPrefix: null | 此视图中不渲染导轨——少于两个轮次、容器宽度小于 900px，或非对话视图。没有任何损坏。 |
| 设置在浏览器重启后不会保留 | 它们保存在此浏览器的本地存储中。其他浏览器、隐私窗口或清除站点数据后都会从出厂值开始——没有跨设备同步。 |
| 你在 1.3.0 或更早版本中设置的值丢失了 | 自 1.4.0 起，设置仅存在于浏览器中；DSH 设置文档中的 chat-locator: 部分不再被读取。请在设置页面上重新设置一次。 |

🧠 工作原理

有三个约束塑造了实现，每一个都有完整记录——连同其背后的实验——见 docs/design-notes.md。

1. 导轨是被接管，而非重绘。 它不在任何 Slot 中，因此替换方案必须重新实现轮次跳转、未加载轮次分页和活动轮次跟随。相反，插件在运行时发现 CSS Module 前缀（查找包含 _mark 的 _frame），并注入一个自己拥有的、由 !important 覆盖组成的样式表。如果上游重命名了这些类，插件会静默，而不是破坏导轨。
2. 设置存在于浏览器中，而非宿主半边。 直到 1.3.0，宿主半边在 DSH 设置文档中注册了一个 chat-locator 命名空间，浏览器半边绑定到它。dsh 0.1.7 移除了客户端 settingsScope 服务，因此自 1.4.0 起，浏览器半边基于 @deepseek-ai/dsh-client-store 的 createSnapshotStore 构建自己的作用域，并持久化到本地存储中的 dsh.chat-locator.settings。这一取舍是刻意的：设置能在浏览器重启后保留，但不再跨浏览器或机器同步，并且旧版本存储在 DSH 设置文档中的任何内容都会被忽略。index.js 保留为空操作存根，因为补丁行解析到它——见 docs/design-notes.md。
3. 预览保持纯文本。 它由内置的轮次大纲构建，且仅来自文本块，因此思考内容无法进入其中，并且空白连续段会被折叠，因此它不能包含空行。

已知边界——上游类名契约、900px 容器截止值、加宽裁剪框所添加的 8px 交互条——列在同一文档中。

📌 主题

dsh dsh-plugin deepseek-harness cordis cordis-plugin web-ui conversation-navigation css-injection

🤝 贡献

见 CONTRIBUTING.md。无需安装任何东西：克隆仓库并运行 node test/verify-client.mjs 即可获得全部 125 条断言。
欢迎提交错误报告和功能请求——模板会要求提供 __dshChatLocator.state() 的输出，一次粘贴即可回答大多数分诊问题。

📄 许可证

MIT