# DeepSeek Harness Message Navigator

[![npm version](https://img.shields.io/npm/v/dsh-codex-message-navigator.svg)](https://www.npmjs.com/package/dsh-codex-message-navigator)
[![npm downloads](https://img.shields.io/npm/dm/dsh-codex-message-navigator.svg)](https://www.npmjs.com/package/dsh-codex-message-navigator)
[![license](https://img.shields.io/npm/l/dsh-codex-message-navigator.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/miaomiao636/dsh-message-navigator.svg)](https://github.com/miaomiao636/dsh-message-navigator)

[English](README.en.md) | [中文](README.md)

A Codex-style message navigator for the DeepSeek Harness Web UI.

## Preview

![dsh-message-navigator](https://cdn.jsdelivr.net/gh/miaomiao636/dsh-message-navigator@main/dsh-message-navigator.png)

*What it looks like once installed: a Codex-style message navigator on the left side of the conversation — hover or click to browse and jump to any user message.*

## Features

- A tick is generated only for plain user messages and user interjections; AI replies, reasoning, tool calls and status content never count.
- Each user turn maps to exactly one tick; ordinary ticks are equal length and packed at a compact ~20px spacing.
- Full conversation history is auto-loaded, beyond DeepSeek Harness' default render-window limit.
- A dark, elongated tick follows your current reading position.
- Message previews appear on hover or keyboard focus.
- Click a tick or a preview card to smooth-scroll to that message; arrow keys, Home, End and Enter are supported.
- Handles streaming, new messages, older-history loading, content reordering and session switches automatically.
- Small tick counts use Codex-style compact fixed spacing; only very long sessions compress the spacing uniformly.
- Uses DeepSeek Harness `--dsw-*` theme variables; respects dark mode and reduced-motion settings.
- Auto-hidden on narrow screens; everything runs locally in the browser — no message content is sent or persisted.

## Compatibility

The current version targets the npm-installable DeepSeek Harness `0.1.0-rc.6` and relies on the public Web UI contracts that the official repo kept stable from `rc.5` through `rc.6`:

- `[data-conversation-scroll]`
- `[data-chat-flow]`
- `[data-chat-anchor-key]`
- `[data-chat-flow-kind]`
- the `shell.overlay` slot

DeepSeek Harness is still in Developer Preview. If upstream changes these contracts, this plugin needs a synchronized upgrade.

The `rc.6` client-module scanner cannot yet reliably discover third-party `dsh.client` packages from a profile's standalone dependency base. This plugin's Host entry provides a compatibility bridge through the official `webServer.register()` and `tapIndex()`; once Harness natively discovers external client packages, the duplicate-detection in the boot graph keeps the bridge idempotent automatically.

## Desktop compatibility

This plugin is a DSH Web UI extension verified against the `web` profile. Desktop builds that keep launching or embedding the official DSH Web UI — with the same profile, session runtime, plugin loader and client loader — are expected to work.

Community desktop projects checked and found architecture-compatible:

- [`anywhere-labs/deepseek-harness-desktop`](https://github.com/anywhere-labs/deepseek-harness-desktop): the docs state Desktop does not rewrite Harness but wraps the same runtime; users keep the official DSH profiles, plugins, sessions and Web UI. `upstream.json` pins `sourceVersion` to `0.1.0-rc.5` and `runtimePackageVersion` to `0.1.0-rc.6`, matching this plugin's target.
- [`hairyf/deepseek-harness-desktop`](https://github.com/hairyf/deepseek-harness-desktop): a Tauri WebView that starts `dsh --profile web --host 127.0.0.1 --port 3080` and embeds `http://127.0.0.1:3080/`.
- [`vibeinging/deepseek-harness-desktop-app`](https://github.com/vibeinging/deepseek-harness-desktop-app): starts the DSH Web Profile and keeps the same Session, Agent, Tool, Skill, MCP, Settings, Profile Bundle and Client Loader.
- [`dataelement/dsh-desktop`](https://github.com/dataelement/dsh-desktop): packages the local DeepSeek Harness Web experience and persists profiles, plugins and sessions.

Not guaranteed: desktop builds that rewrite the message renderer, do not use the `web` profile, disable frontend plugin injection, or pin an incompatible DSH Web UI internal version.

If a desktop build uses its own `DSH_HOME`, install the plugin into the profile that build actually uses, not the system default `~/.dsh`. Most desktop builds still use the `web` profile, but their data directory may be app-private.

## Notes for installing agents

If you are an AI agent, scripted helper, or installing this plugin on behalf of a user, please follow these rules:

- First confirm whether the user runs DSH Web or a DSH Desktop app.
- Confirm the actual profile name; default to `web`, never blindly install into other profiles.
- For desktop builds, confirm whether they use an app-private `DSH_HOME`. If so, install into the profile/data directory the desktop build actually uses, not the default `~/.dsh`.
- Never delete, rebuild or overwrite an existing profile. Keep other plugins, `pnpm-workspace.yaml`, `allowBuilds` and existing config.
- Never start, exit or restart DSH / DSH Desktop without the user's consent. Report verification results and let the user restart.
- After installing, verify the plugin appears in the target profile's dependency tree.

Recommended verification:

```sh
dsh plugin --profile web add dsh-codex-message-navigator
cd ~/.dsh/profiles/web
pnpm ls dsh-codex-message-navigator --depth 0
```

For desktop builds with a custom `DSH_HOME`, run the last command inside the corresponding profile directory.

## Building and packing from source

Requires Node.js 22+ and pnpm.

```sh
pnpm install
pnpm check
pnpm pack
```

`pnpm check` runs TypeScript checks, unit tests and the client-plugin build. The build produces:

```text
lib/index.js   # Harness host entry
lib/client.js  # browser plugin incl. the ModuleLoader registration wrapper
```

## Install

Recommended: install directly from npm.

```sh
dsh plugin --profile web add dsh-codex-message-navigator
dsh --profile web --dump-config
dsh --profile web
```

Alternatively, pack a tarball first to avoid install-time build authorization:

```sh
pnpm pack
dsh plugin --profile web add ./dsh-codex-message-navigator-0.1.4.tgz
```

For other profiles, replace `web` accordingly. Uninstall:

```sh
dsh plugin --profile web remove dsh-codex-message-navigator
```

If you previously only used the bare `dsh web` shortcut without a profile, create an extensible Web profile first:

```sh
dsh plugin --profile web add @deepseek-ai/dsh-web-app@next
dsh plugin --profile web add dsh-codex-message-navigator
dsh --profile web
```

On the first Web-profile install, pnpm may ask permission for `koffi`'s official native build script. Set `allowBuilds.koffi` to `true` in that profile's `pnpm-workspace.yaml` as the dsh output instructs, then retry.

## Install from source checkout

```sh
dsh plugin --profile web add /absolute/path/to/deepseek-message-navigator
```

Source installs run `prepare`. pnpm 10 may require allowing this package's build in the profile's `pnpm-workspace.yaml`:

```yaml
allowBuilds:
  dsh-message-navigator: true
```

Then re-run the install command.

## Privacy & accessibility

Previews only read text already rendered on the current DeepSeek Harness page — never model requests, hidden prompts or server logs. The plugin makes no network requests, has no telemetry and writes no local storage. All ticks are focusable buttons with Chinese accessibility labels.

## Project structure

```text
src/core.ts                       pure functions for positions, active message, text
src/client/MessageNavigator.tsx   DOM adaptation and full interaction
src/client/index.tsx              shell.overlay registration entry
src/index.ts                      Host entry
test/core.test.ts                 pure-function unit tests
cordis.patch.yml                  Profile install layer
```

## License

MIT