XiLuovo/dsh-session-timeline

dsh-session-timeline

DeepSeek Harness 会话时间轴插件：在会话左侧渲染一条横短横线时间轴，用于在长会话中快速定位、跳转和预览。

platform
license
npm

效果

会话时间轴主视图

悬停预览 tooltip

功能

- 横短横线时间轴：只在用户输入的位置显示一条横向短横线，无消息处无线；条数等于整个会话的用户消息数，放得下时居中排布，放不下时时间轴内部滚动（无滚动条）。
- 全量统计（投影机制）：通过 DSH sessionProjections 增量统计整个会话的用户消息与 AI 回复预览，持久化缓存保证刷新秒出、新消息实时更新；对长会话压力可控。
- 当前消息定位（scroll-spy）：激活条始终对应右侧视口当前显示的那条用户消息；滚动右侧对话，激活条随之移动（手动滚动时间轴后保持不动，点击某条跳转后恢复跟随）。
- 波浪聚焦：鼠标在时间轴上移动时，鼠标接近的那条变为激活色并变长，相邻条向上下递减，形成波浪效果。
- 圆角预览 tooltip：悬停某条时立即显示圆角提示——第一行用户消息（黑色加粗、单行省略），下方 AI 回复（灰色、多行），时间贴在最后一行右下角；字体与右侧对话一致。窗口外的历史消息同样可以预览。
- 点击跳转：点击任意横线，对话立即滚动到该次用户输入所在位置；窗口外（未加载）的历史消息会自动加载更早历史后跳转。
- 收起 / 展开：第一条消息上方有一个悬停淡入的胶囊把手（点击收起；悬停时第一、二条灰色递减，胶囊扮演激活条角色）。收起后变成一条全高细竖条，常态隐藏，鼠标接近识别区域时淡入，点击展开。任何滚动位置，胶囊与最上方条目之间始终保留固定空白。

安装

需要 DSH ≥ 0.1.0-rc（dsh CLI 已安装，web profile 含 sessionProjections 服务）。

方式一：npm 安装（推荐）

已发布到 npm，预构建安装无需 GitHub 构建授权：

dsh plugin --profile web add dsh-session-timeline

然后启动（或重启）web：

dsh web

方式二：GitHub 安装

dsh plugin --profile web add github:XiLuovo/dsh-session-timeline

然后启动（或重启）web：

dsh web

本包是纯 JS 实现，client.js 即最终 bundle 产物，无需 prepare 构建脚本，GitHub 直接安装即可用。

方式三：本地目录安装（开发调试）

git clone https://github.com/XiLuovo/dsh-session-timeline.git
dsh plugin --profile web add ./dsh-session-timeline
dsh web

方式四：会话内动态加载（快速体验，不落盘）

在 DSH Web 会话中让 agent 执行 cordis_define，粘贴 client.js 的内容作为 client 代码，cordis_run 启用。适合快速体验；注意动态方式没有 host 投影（全会话统计不可用），仅保留窗口内功能。

卸载

dsh plugin --profile web remove dsh-session-timeline

使用

打开任意会话，时间轴出现在对话区左侧：

| 交互 | 效果 |
| --- | --- |
| 悬停时间轴某条 | 显示该轮的用户消息 + AI 回复预览（圆角 tooltip） |
| 点击横线 | 跳转到对应消息（窗口外自动加载历史） |
| 鼠标在时间轴上移动 | 波浪跟随（激活条 + 长度递减） |
| 滚动时间轴 | 条目内部滚动（无滚动条），手动滚动后保持位置 |
| 悬停第一条上方的胶囊 | 胶囊淡入，第一、二条灰色递减 |
| 点击胶囊 | 收起时间轴 |
| 收起后悬停/点击竖条区域 | 竖条淡入 / 展开时间轴 |

依赖

完全建立在 DSH 宿主之上：

| 依赖 | 用途 | 来源 |
| --- | --- | --- |
| @deepseek-ai/dsh-client-runtime | 会话快照、useSessions、投影读取 faceOf | 宿主自带（peer） |
| @deepseek-ai/dsh-client-ui-layout | shell.overlay 浮层槽位 | 宿主自带（peer） |
| @deepseek-ai/dsh-session-projection | 投影注册 + 事件流 fold + 持久化缓存 | 宿主自带（peer） |
| zod ^4.4.3 | 投影 schema（数据校验） | 包自带（dependencies） |
| DSH 主题 CSS 变量（--dsw-alias-*） | 亮暗主题自适应 | 宿主 |

开发说明

- client.js：纯 JS UI（波浪、scroll-spy、tooltip、胶囊、内部滚动），无构建步骤，修改后直接提交；
- index.js：投影 fold 数学（init/apply/view + 紧凑截断）。修改投影状态结构时必须 bump stateVersion，否则旧持久化缓存会被错误复用；
- 浏览器半部通过 exports["./client"] 被发现，dsh.client 声明了运行依赖；
- 插件只读 sessions.binding(sessionId).session 快照、投影与 DOM 锚点（data-chat-anchor-key），不修改会话数据。

License

MIT