dsh-conversation-toc
中文 | English
GitHub · npm · MIT License
Conversation outline for DeepSeek Harness Web — a right-side topic sidebar (TOC) like the DeepSeek web app, with scroll-spy highlighting and click-to-jump navigation.
Overview
dsh-conversation-toc is a browser-side plugin for DeepSeek Harness Web. After installation, an 「Outline」 button appears on the right side of the session header, and a conversation outline panel (or a collapsed minimap rail) floats on the right of the chat — the same reading experience as the DeepSeek web app's right sidebar:
- Topic list — every user question is a top-level topic,
steering follow-ups are indented sub-topics, and ## / ### headings inside assistant answers become third-level topics, so you can jump into any section of a long answer;
- Scroll-spy — the outline highlights the topic you are currently reading as you scroll;
- Jump navigation — click any topic to smooth-scroll to the corresponding message;
- Minimap rail — when there isn't enough room (or you collapse it manually), only the capsule indicator rail stays on the right; click a capsule to jump, hover to preview the topic text.
Works on Windows / macOS / Linux — everything runs in the browser: no host service, no settings page, no platform-specific code.
Screenshots
Expanded outline panel
Expanded outline panel
Collapsed minimap rail
Collapsed minimap rail
Features
- Three display modes, cycled by the header「Outline」button:
expanded panel → minimap rail → hidden; the choice is remembered in localStorage.
- Hierarchical topics: user question (level 1) →
steering follow-up (level 2, indented) → assistant answer headings ## / ### (level 3).
- Scroll-spy highlight: the current reading position is tracked against the real chat scrollport and highlighted in blue; when scrolled to the bottom, the last topic is highlighted.
- Jump-to-section: reuses the core chat anchors (
[data-chat-anchor-key] / [data-conversation-scroll]) — no private stylesheets, resilient across DSH updates.
- Adaptive layout: the expanded panel floats in the whitespace to the right of the message column; when there isn't enough room it automatically falls back to the minimap rail, and it never overlaps the right "details" panel.
- Theme-aware: uses DSH theme tokens, so it follows light / dark themes; typography scales with the app's display-size setting.
- Live updates: topics come straight from the session store (
chat.order / chat.nodes), so new messages and streaming output are reflected automatically.
- Safe by design: no host API and no disk writes — the only persisted state is the display-mode preference in
localStorage.
Recommended Installation
Either method works and is equivalent. We recommend the one-command install.
Option 1 (recommended): one command
Published on npm — install with a single command:
dsh plugin --profile web add dsh-conversation-toc
Restart the dsh web service after installation.
Prefer installing from source? This GitHub repository or a local tarball work too:
# from GitHub
dsh plugin --profile web add git+https://github.com/twelvecarbon/dsh-conversation-toc.git
# or from a local tarball
dsh plugin --profile web add C:\path\to\dsh-conversation-toc-0.1.1.tgz
Option 2: manual install
Follow the detailed manual / wiring / uninstall guide below.
What's in the package
One npm package = a host half (an empty Cordis plugin row, lib/index.js — the feature is purely browser-side) + a client half (the outline UI, lib/client.js).
The package integrates with DSH through two declarations:
| Declaration | Purpose |
|---|
dsh.bundle.patch (cordis.patch.yml) | Lets DSH recognize it as a standard bundle plugin package: dsh plugin --profile <name> add <package> installs and wires it in one command, no manual config editing |
dsh.client + exports["./client"] | Lets the web client auto-load the outline UI at /plugins/<package>/client.js |
So for users, installation is one command — no YAML editing, no manual file copying.
Installation (for users)
0. Prerequisites
- DeepSeek Harness installed (
npm install -g @deepseek-ai/dsh, a desktop app built on it, or npx @deepseek-ai/dsh web).
- Option 1 needs pnpm:
npm install -g pnpm (or corepack enable).
- Make sure
dsh is on PATH.
1. Method A (recommended): one command
dsh plugin --profile web add dsh-conversation-toc
This does three things (all automatic):
- Installs the package via pnpm into
~/.dsh/profiles/web (auto-initializes the profile on first use);
- Detects the package's
dsh.bundle declaration and writes the package name into the profile's dsh.profile.bundles layer list;
- After restart, DSH reads the package's
cordis.patch.yml and mounts the plugin row into the app tree — no manual config editing.
Same for other profiles (replace web with your profile name, e.g. dsh plugin --profile headless add ...; dsh web equals dsh --profile web).
Test a local tarball: dsh plugin --profile web add C:\path\to\dsh-conversation-toc-0.1.1.tgz
2. Method B: manual install (no pnpm / no dsh plugin)
B1. Install the dependency:
cd ~/.dsh/profiles/web
pnpm add dsh-conversation-toc
# or from a local folder / tarball
# pnpm add C:\path\to\dsh-conversation-toc
B2. Wire it up (once, idempotent): append the package name to the profile's dsh.profile.bundles in ~/.dsh/profiles/web/package.json:
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-conversation-toc"
]
}
}
B3. Mount the plugin row: append to ~/.dsh/profiles/web/cordis.patch.yml (create it if missing):
- insert:
- id: conversation-toc
name: 'dsh-conversation-toc'
B4. Restart the dsh web service.
3. Uninstall
dsh plugin --profile web remove dsh-conversation-toc
Or manually: remove the dependency, the dsh.profile.bundles entry, and the cordis.patch.yml row, then restart.
Usage
- Open any conversation and send / view messages;
- The 「Outline」 button appears on the right of the session header;
- The outline panel floats on the right of the chat: click any topic to jump to the corresponding message; the current topic highlights in blue as you scroll;
- When there isn't enough room, the panel automatically collapses to the minimap rail; click the「Outline」button to cycle the three display modes (expanded → rail → hidden).
How it works
- Data source — the browser reads the session store (
useSession selectors over chat.order / chat.nodes), so topics stay in sync with new messages and streaming output;
- DOM anchors — it reuses the core
[data-chat-anchor-key] anchors and the [data-conversation-scroll] scrollport, no private class names;
- Host side — nothing to do:
lib/index.js is an empty host row that exists only so the package mounts as a standard DSH bundle plugin and its client bundle is discovered by the web boot graph.
File structure
dsh-conversation-toc/
├── package.json # dsh.bundle.patch + dsh.client declarations
├── cordis.patch.yml # host plugin row (mount layer)
├── lib/
│ ├── index.js # host half (empty — no host service)
│ └── client.js # client half (the whole feature)
├── scripts/
│ ├── check-package.js # pre-publish contract gate (npm run check)
│ ├── smoke-test.cjs # pure-logic smoke tests (npm run test)
│ └── generate-screenshots.ps1 # regenerates docs/assets mockups (Windows)
├── docs/assets/ # README screenshots
├── CHANGELOG.md
├── LICENSE
├── README.md # English
└── README.zh.md # 中文
Changelog
See CHANGELOG.md.
License
MIT
