dsh-turn-index

Readme

# dsh-turn-index

对话轮次索引：在 DeepSeek Harness Web GUI 右侧挂一条侧边栏，按顺序列出每一轮「你问过的话」。点击任意一条，聊天流平滑滚动到那一轮并闪烁高亮；滚动阅读时侧边栏同步高亮当前轮次。

A turn-index sidebar for the DeepSeek Harness web GUI: one entry per user turn, click to jump, scroll-spy keeps the current turn highlighted.

```
┌──────────────────────────────┬───────┐
│  聊天流                       │ 轮次 2│
│                              │ ─────│
│  ▸ #1 帮我查一下……（点击跳转） │  #1   │
│                              │  #2 ▸ │
└──────────────────────────────┴───────┘
```

## 功能

- **逐轮索引**：每条索引 = 一轮用户提问的开场消息；轮次内穿插的补充提问（steering）以 ↳ 缩进显示，不打断轮次编号。
- **点击跳转**：直接定位聊天流里对应的消息行，平滑滚动 + 1.6 秒闪烁高亮（尊重系统的减少动效偏好）。
- **阅读联动**：滚动阅读时索引自动高亮当前轮次，展开态的列表自动跟随，当前轮次始终可见。
- **历史分页**：会话历史窗口未加载完时，顶部出现「加载更早的轮次」，点一下继续向前加载。
- **轨迹视图兜底**：停留在轨迹视图时点击索引，给出提示并一键切回对话。
- **避让右侧详情面板**：工具详情（details）打开时索引栏自动左移避让。
- **响应式**：视口 ≤1024px 自动收成 44px 窄条（只留轮次圆点）；1280px 以下面板收窄；面板高度贴合聊天流区域（不遮 Session log、不压输入框）；偏好记忆在 localStorage。
- **双语文案**：通过 harness 的 locale 服务提供 中文 / English 文案，跟随界面语言。

## Compatibility

| 项 | 值 |
|---|---|
| 支持版本 | DSH `0.1.0-rc.6`（web profile，mainline） |
| 最后验证 | 2026-08-14 · Windows 11 · Node 24 · pnpm 11 |
| 依赖 | 宿主标准 web bundle（`slots` / `sessions` / `locale` 客户端服务 + `shell.overlay` 槽位）；react 为可选 peer |

## 安装

```sh
# npm（推荐，已发布 v0.1.1）
dsh plugin --profile web add dsh-turn-index

# GitHub tag tarball
dsh plugin --profile web add https://github.com/Simon314620/dsh-turn-index/archive/refs/tags/v0.1.1.tar.gz

# 本地目录（开发调试）
dsh plugin --profile web add file:D:/path/to/dsh-turn-index
```

安装后**重启 `dsh web`**，刷新页面即可在右侧看到索引栏。默认的 `dsh web` profile 已具备全部所需服务。

## 卸载

```sh
dsh plugin --profile web remove dsh-turn-index
```

移除后重启 `dsh web` 并硬刷新（Ctrl+Shift+R）。回滚方式同上：卸载后重装旧版本即可（如 `dsh plugin --profile web add dsh-turn-index@<旧版>`）。浏览器侧偏好（折叠状态等）仅存于 localStorage，卸载后是无害残留，可在开发者工具中清除。

## 实现原理

纯客户端插件：宿主侧（Node）无运行时逻辑，浏览器半边通过 `shell.overlay` 槽位（AppFrame 的加性浮层席位）挂载面板。会话数据取自 `ctx.sessions.binding(currentId).session`（`ConversationSnapshot` 的可观察快照），索引条目从 `chat.order` 中筛出 kind 为 `user` / `steering` 的可见节点；跳转时按节点 key 查找聊天流里带 `data-chat-anchor-key` 属性的 DOM 行（聊天流无虚拟化，行都在 DOM 里），因此跳转天然可靠。面板几何（上下界、details 避让）动态测量 `[data-conversation-scroll]`、`[data-composer-seat]` 与 AppFrame 的 grid 第三轨。

## 配置

无配置项。开箱即用；面板偏好（收起状态、窄条模式）仅存于浏览器 localStorage。

## 权限与数据

- **宿主侧（Node）零运行时逻辑**：不读写文件系统、不发起网络请求、不访问凭据。
- **会话数据只读**：仅订阅当前会话的可观察快照（`ctx.sessions.binding(currentId).session`）用于渲染轮次索引，不上传、不外发。
- **浏览器持久化**：唯一落盘数据是 localStorage 中的 UI 偏好。
- 无遥测、无埋点、无第三方脚本。

## 开发

```sh
pnpm add -D jsdom     # 测试依赖
node tests/edge.mjs   # 24 项边界单测（120 轮渲染、跳转命中/未命中、响应式、空态等）
node smoke.mjs        # 装配冒烟测试
```

## 已知限制

- 面板悬浮在聊天区右侧：宽屏下覆盖的是消息流的空白区，窄窗口下请用头部按钮收起（自动窄条在 ≤1024px 生效）。
- 跳转依赖 harness 聊天流的 DOM 契约（`data-chat-anchor-key` / `data-conversation-scroll` 等）；harness 大版本升级若改动这些属性需要适配。
- 索引只覆盖当前已加载的历史窗口，更早的轮次通过「加载更早」逐页加载。

## License

MIT

安全问题请通过 [GitHub Issues](https://github.com/Simon314620/dsh-turn-index/issues) 联系维护者私下报告，避免公开披露。