dsh-plugin-message-timeline-navigation

Readme

# dsh-plugin-message-timeline-navigation

A Codex-style **message timeline navigation** plugin for [DSH (DeepSeek Harness)](https://github.com/deepseek-ai/deepseek-harness) web clients.

It overlays a vertical rail of dense short ticks on the left edge of the conversation view — one tick per **user turn** (your message plus its assistant reply). Hover a tick to preview the message, click to jump straight to it, and watch the rail track your reading progress as you scroll.

DSH（DeepSeek Harness）web 端插件：在对话区左侧叠加一根 **Codex 风格的消息时间线**——密集的短横线，每条横线对应一个**用户回合**（你的消息及其完整的 agent 回复）。悬停可预览消息、点击可直接跳转、滚动时当前阅读进度会自动标记在时间线上。

---

## Features / 功能

- **One tick per user turn / 每回合一个节点**
  Each tick represents a user message **plus** its whole assistant reply. Agent-only tail nodes are filtered out (`[data-turn-tail]`), so the rail never shows "phantom" agent ticks.

- **Hover preview with cascade effect / 悬停级联预览**
  Hover a tick: it stretches to a longer dark line while its 3 neighbors on each side lengthen in a stepped cascade (matching the classic Codex look). A small card shows the message text preview.

- **Click to jump / 点击跳转**
  Click any tick to smoothly scroll that message to the **top** of the viewport and briefly highlight it.

- **Reading-progress tracking / 当前阅读进度**
  The tick for the turn you are currently reading (the turn whose segment contains the **scrollport top edge**) stays dark even when not hovered — the moment a turn scrolls into view from the top, its tick turns dark. Length is unchanged; only the color changes.

- **Only user messages / 只显示用户消息**
  The rail strictly tracks user messages (ruled by the DOM contract below), so the timeline is dense and predictable.

## Install / 安装

The plugin is a pure overlay and only needs a DSH web client. Install it as a DSH plugin (pnpm is recommended for DSH workspace setups):

```powershell
dsh plugin add dsh-plugin-message-timeline-navigation
```

Or install directly from this repository:

```powershell
dsh plugin add dsh-plugin-message-timeline-navigation@github:cokiscarazo-rgb/dsh-plugin-message-timeline-navigation
```

**中文说明：** 通过 DSH 的插件命令安装即可（推荐使用 pnpm 环境；不要把插件装成全局包）。安装后刷新对话页面（或等待 client HMR 热更 1–2 秒）即可看到左侧时间线。

> 注：本插件为纯前端浮层，不修改 DSH 本体；程序本体与个人配置分离，插件文件仅存在于你的 DSH 插件目录。

## Usage / 使用说明

1. Open any conversation in a DSH web client.
2. On the left edge of the chat you'll see the vertical rail of ticks.
3. **Hover** a tick → preview card + cascade expansion.
4. **Click** a tick → jumps to that message, top-aligned, with a temporary highlight.
5. **Scroll** the conversation → the tick for the current turn stays dark.

## How it works / 实现原理

- The overlay mounts its own React root on `document.body` (same pattern as other DSH client plugins).
- It reads the conversation DOM directly using DSH's public DOM contract:
  - scrollport: `[data-conversation-scroll]`
  - user message: `div[data-time-hover-root]` minus `div[data-turn-tail]`
- A `MutationObserver` + `ResizeObserver` + scroll listener keep the rail in sync with message changes, view switches, and scrolling.
- Dashes are distributed by index down the scrollport height (with a fixed 10px rhythm mirroring the classic sidebar), so every tick stays visible even in very long conversations.

## Directory / 目录结构

```
dsh-plugin-message-timeline-navigation/
├── package.json       # manifest: dsh.bundle.patch + dsh.client.inject
├── cordis.patch.yml   # bundle-level mount for the host half
├── LICENSE            # MIT
├── lib/
│   ├── index.js       # host half (minimal: config defaults)
│   ├── client.js      # client half (the timeline rail core)
│   └── types/         # type declarations
└── README.md
```

## Compatibility / 兼容性

- DSH web client (conversation view). Tested against recent DSH client releases (`dsh-client-ui-conversation` DOM contract).
- Requires `react` / `react-dom` 18+ and `cordis` rc line, declared as peer dependencies.

## License / 许可证

[MIT](LICENSE) © 2026 [cokiscarazo-rgb](https://github.com/cokiscarazo-rgb)