# dsh-beacons

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-%E2%89%A5%200.1.0--rc.6-0b63ce)](https://github.com/deepseek-ai/deepseek-harness)
[![design reference: OpenChamber](https://img.shields.io/badge/design%20reference-OpenChamber-8b5cf6)](https://github.com/openchamber/openchamber)

**Codex/OpenChamber 风格的提示词导航条（含滚动跟随）—— 一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）Web UI 插件。**

> English docs: [README.md](./README.md)。

对话右侧常驻一条 **scrub rail（提示词导航条）**，每个真实用户提示词对应一个刻度。滚动时，你正在阅读的那条提示词刻度会保持高亮；悬停可预览，点击可跳转。

![Prompt navigator rail](docs/screenshot.png)

> **设计参考** —— 导航条交互（scrub rail、reading-line 滚动跟随、悬停波浪、预览面板、边缘轮播、listbox 键盘语义、加载更早）改编自 **OpenChamber**（[github.com/openchamber/openchamber](https://github.com/openchamber/openchamber)）：
>
> - `packages/ui/src/components/chat/components/PromptNavigatorRail.tsx`
> - `packages/ui/src/components/chat/lib/scroll/scrollSpy.ts`

## 快速开始

```sh
dsh plugin --profile web add github:Da-Mie/dsh-beacons
```

重启 DSH 并刷新 Web UI。任何包含 ≥ 2 条用户提示词的会话，其右侧都会出现导航条；按 `Alt+P` 进入键盘导航。

## 功能

### 提示词导航（Web UI）

- **常驻右侧导航条** —— 锚定在对话列右缘（不会压到详情面板）、垂直居中；会话 ≥ 2 条真实用户提示词时才显示。
- **滚动跟随（scroll-spy）** —— reading-line 算法高亮当前阅读位置（顶部 + 100px）的那条提示词；接近底部时高亮最后一条。单调判定，长提示词内不会来回跳变；rAF 节流，ResizeObserver + MutationObserver 自动刷新。
- **悬停波浪** —— 光标附近的刻度变长、两侧逐渐回落（Codex 风格 proximity wave）。
- **悬停预览面板** —— 左侧弹出滑动小列表（最多 8 行），高亮行居中；滚轮逐行移动；行可点击。
- **窗口化刻度** —— 最多同时显示 30 个刻度；悬停槽位上下边缘可滚动浏览更长的历史。
- **自动加载更早历史** —— 滚动到顶部自动加载（阈值 `max(900px, 1.5 × 视口高)`，相邻加载间隔 1.2s）；槽位上方的 **↑ 加载更早按钮** 可手动触发。
- **点击跳转** —— 点击刻度或预览行，平滑滚动到该提示词所在消息。
- **键盘导航** —— `Alt+P` 打开键盘模式（listbox 语义）：↑/↓ 移动、Home/End 首尾、Enter 选择、Esc 关闭。
- **过滤** —— 只索引真实用户提示词（user + steering 节点），排除注入的上下文。


## 环境要求

- DeepSeek Harness ≥ `0.1.0-rc.6`（Web UI profile；可用 `dsh --version` 检查）
- Node.js ≥ 22（仅从源码构建时需要）

## 安装

包已预构建（`lib/` 已提交），所有安装方式都无需构建步骤。

### 用 DSH 安装（AI 助手）

把这个仓库链接直接发给你的 DSH：

```text
https://github.com/Da-Mie/dsh-beacons
```

DSH 会读取仓库里的 [`AGENTS.md`](./AGENTS.md) 并自动完成安装（需要 DSH ≥ `0.1.0-rc.6`）。下面的命令行安装方式效果相同。

### 从 GitHub 安装

```sh
dsh plugin --profile web add github:Da-Mie/dsh-beacons
```

### 从 tarball 安装

```sh
dsh plugin --profile web add ./dsh-beacons-0.1.0.tgz
```

### 从 npm 安装

```sh
dsh plugin --profile web add dsh-beacons
```

> 需先将包发布到 npm registry（见 [开发](#开发)）。

安装后，**重启 DSH**（插件集变更需重启生效），然后刷新 Web UI。

## 使用

- **打开** —— 会话 ≥ 2 条提示词时导航条自动出现；按 `Alt+P` 聚焦以进入键盘控制。
- **滚动** —— 高亮刻度跟随你正在阅读的提示词；到底部时落在最后一条。
- **预览** —— 悬停刻度，左侧显示预览列表。
- **跳转** —— 点击刻度或预览行，滚动到该提示词。
- **加载更多** —— 点击槽位上方的 **↑ 按钮**，或直接滚动到顶部自动加载更早历史。
- **键盘**（`Alt+P` 后）—— ↑/↓ 移动、Home/End 首尾、Enter 选择、Esc 关闭。


## 开发

```sh
npm install
npm run build
```

客户端 bundle（`lib/client.js`）是 `window.__ModuleLoader__.load({ id, factory })` 格式的 CJS 工厂，由 DSH 的 client-modules 服务在 `/plugins/<id>/client.js` 提供。

## 架构

- `src/index.ts` —— host 端：空入口（导航为纯浏览器端）。
- `src/client/index.tsx` —— 客户端入口：会话订阅（sessions list → binding → conversation snapshot）、Alt+P 快捷键、`shell.overlay` 槽位注册。
- `src/client/store.ts` —— 模块级导航状态（root 作用域的 overlay 入口拿不到 session kit）。
- `src/client/scroll-spy.ts` —— reading-line 滚动跟随（OpenChamber `scrollSpy.ts` 的移植）。
- `src/client/PromptNavRail.tsx` + `.module.css` —— 导航条组件（OpenChamber `PromptNavigatorRail.tsx` 的移植）。

## 已知限制

- 仅已加载进对话窗口的历史可导航；更早的提示词需先加载更早历史（自动或手动）。
- 预览仅显示文本内容。

## 许可

[MIT](LICENSE)