dsh-chat-locator

dsh-chat-locator
Turn-rail settings for DSH Web: tick thickness, rail side, and a curved length gradient anchored on the hovered tick — plus a plain-text hover preview whose line count, font size, and width you control.

Language: English | 简体中文

📋 Table of Contents

• Features
• Quick Start
• Installation
• Usage
• How It Works
• Topics
• Contributing
• License

DSH Web draws a turn rail down the edge of every conversation: one tick per turn, so you can see where you are in a long session and jump between turns. It is a good rail with three opinions baked into it. Ticks are always 2px. The rail always sits on the right. And pointing at a tick tells you nothing about what that turn contains, so finding a specific turn in a long conversation means hovering ticks one at a time.

None of that is configurable. The rail is rendered directly by ChatView inside @deepseek-ai/dsh-client-ui-chat; the Slot system gives it no seat, and no setting for thickness or side is exposed anywhere.

dsh-chat-locator is a persistent DSH plugin that turns those fixed opinions into settings. It does not replace the rail — it claims the rail's styles at runtime, so the built-in jump-to-turn, unloaded-turn paging, and active-turn following all keep working exactly as before.

✨ Features

• Tick thickness (横线粗细): 1–8px instead of a fixed 2px. Only the line width changes; the 10px tick spacing stays put.
• Rail side (轨道位置): Left or right. The hover preview automatically opens on the opposite side, so it never covers the text you are reading.
• Hover preview: The built-in plain-text card showing that turn's prompt and response. The plugin does not build it — it only styles how many lines it shows, its font size, and its width, and the built-in plain-text rendering (which never includes thinking content) is left alone.
• Preview line count (预览正文行数): 1–6 lines. The card really grows — only the overflow is clipped.
• Preview font size and width (预览字号 / 预览框宽度): 10–18px and 200–420px. Font size and line height scale as a pair, so enlarging the text never crowds or clips it.
• A curved length gradient: The tick under the pointer grows to 32px and its neighbours taper back along a curve — 21 / 14 / 12 — so the rail reads as a hook pointing at where you are, not as a straight diagonal. It has its own on/off switch; with it off every tick keeps its built-in width and nothing else changes.
• Restore defaults (恢复默认): All seven settings back to factory values in one click, via per-field unset rather than rewriting the defaults.
• A dedicated settings page: Settings → 对话定位条, with a live sample rail and sample preview card that redraw as you change each value.
• Zero dependencies, no build step. Both halves are plain ESM loaded directly by Node and the browser.

🚀 Quick Start

> What you need: a working DSH installation (the dsh command) with a profile, plus Node.js 20 or newer. The plugin itself has no dependencies to install.

Step 1 — Open a terminal

• macOS / Linux: open Terminal.
• Windows: press Win + R, type powershell, and press Enter.

Step 2 — Install the bundle into your profile

dsh plugin forwards its arguments to pnpm inside the profile directory, so this installs the package from npm and DSH picks up its patch automatically. Replace web with your own profile name if it differs.

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

To pin an exact version instead of tracking new releases, append it: dsh plugin --profile web add dsh-chat-locator@1.4.1

That is the whole install. The bundle itself is the four files a DSH plugin bundle needs — package.json (which declares the bundle and the browser half), index.js (the host half — a no-op stub since 1.4.0), client.js (the browser half), and cordis.patch.yml (the patch that adds the plugin row) — and there is nothing to compile and no dependency to install. Alongside those, the published package also ships this README and its zh-CN/ translation, docs/design-notes.md, CONTRIBUTING.md, SECURITY.md, and test/.

Step 3 — Restart the host

dsh web

The host process caches imported modules, so a newly added bundle is not mounted until the host restarts once.

Step 4 — Done. With DSH Web open at http://127.0.0.1:3080, you are finished if:

• Settings → 对话定位条 appears in the settings sidebar, and
• in the browser console, this returns railFound: true on a conversation with at least two turns:

__dshChatLocator.state()

Open a conversation and slide the pointer up and down the rail: the tick under the pointer grows and its neighbours taper.

> To update: run dsh plugin --profile web update dsh-chat-locator, then restart the host. To uninstall: dsh plugin --profile web remove dsh-chat-locator, then restart the host.
>
> Want the newest unreleased commit, a local copy you can edit, or an offline install? See Install methods.

📦 Installation

Requirements

Install methods

Install from a git clone

Use this if you would rather update with git pull than by re-downloading files.

git clone https://github.com/hawkongz/dsh-chat-locator.git
cd dsh-chat-locator
dsh plugin --profile web add "$(pwd)"
dsh web

Install without git

A bundle is four files. Download them into a folder, install the folder, and restart the host — nothing else is needed.

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"

Then restart the host:

dsh web

Notes on installation

• DSH registers the bundle for you. A package that declares dsh.bundle.patch is added to your profile's dsh.profile.bundles list automatically, so dsh plugin add is the only step.
• There is no build step. pnpm may print a note about blocked build scripts for git-hosted packages; this plugin has no prepare script and no dependencies, so there is nothing to allow.
• Restart the host after installing or removing. See How It Works for why.
• Installation is per profile. --profile web is the profile this plugin was developed against; substitute your own.

📖 Usage

Everything lives on one settings page: Settings → 对话定位条. The table below lists each control with its default and range.

Where settings live

Settings are stored in this browser's local storage (key dsh.chat-locator.settings), written the moment you change a value:

• They survive closing and restarting the browser, and refreshing DSH Web.
• They do not sync across browsers, profiles, or machines — each browser keeps its own copy.
• Clearing the site's data (or using a private window, or another browser) starts from factory values again.
• Since 1.4.0 the plugin no longer reads the DSH settings document, so any chat-locator: section left there by 1.3.0 or older is ignored. After upgrading, the first run shows factory values.

The length gradient

The tick you point at is the longest, and the ticks around it taper away along a curve:

The adjacent tick gives up the most width, then progressively less, flattening out as it rejoins the rail. The width table is generated from 12 + 20 * (1 - d/3)^2, and docs/design-notes.md records how the exponent was tuned (2.5 was a cliff, 1.5 left the neighbours too long, 2.0 is the compromise in use). The gradient anchors on the hovered tick, and the neighbour rules carry :not(.P_markActive) so the active turn's tick keeps its built-in width even when it sits one or two ticks from the pointer; the whole taper disappears the moment the pointer leaves. Unlike the hover preview (which has no switch, because a rail you cannot preview is not a rail), the gradient is decorative and has its own settings row; switching it off also drops the frame widening, since there is no 32px peak to make room for.

Troubleshooting

The plugin ships one debug hook. Run it in the browser console:

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

🧠 How It Works

Three constraints shaped the implementation, and each one is documented in full — with the experiments behind it — in docs/design-notes.md.

1. The rail is claimed, not redrawn. It sits in no Slot, so a replacement would have to re-implement turn jumping, unloaded-turn paging, and active-turn following. Instead the plugin discovers the CSS Module prefix at runtime (looking for a _frame that contains a _mark) and injects one owned stylesheet of !important overrides. If upstream renames those classes, the plugin goes quiet rather than breaking the rail.
2. Settings live in the browser, not in a host half. Up to 1.3.0 the host half registered a chat-locator namespace in the DSH settings document and the browser half bound to it. dsh 0.1.7 removed the client settingsScope service, so since 1.4.0 the browser half builds its own scope on createSnapshotStore from @deepseek-ai/dsh-client-store, persisted to local storage under dsh.chat-locator.settings. The trade-off is deliberate: settings survive browser restarts but no longer sync across browsers or machines, and anything stored in the DSH settings document by older versions is ignored. index.js remains as a no-op stub because the patch row resolves to it — see docs/design-notes.md.
3. The preview stays plain text. The card is the built-in one, built from the built-in turn outline and only from text blocks, so thinking content cannot reach it and whitespace runs are collapsed. The plugin does not read or rewrite that text; its CSS only decides how many lines are shown, the font size, the width, and which side the card opens to.

Known boundaries — the upstream class-name contract, the 900px container cutoff, the 8px interaction strip the widened clip box adds — are listed in the same document.

📌 Topics

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

🤝 Contributing

See CONTRIBUTING.md. There is nothing to install: clone the repository and run node test/verify-client.mjs to get all 127 assertions.

Bug reports and feature requests are welcome — the templates ask for the __dshChatLocator.state() output, which answers most triage questions in one paste.

📄 License

MIT