@kindred7/dsh-timeline

v0.5.2

Published

11 days ago

Conversation timeline plugin (left-side markers with hover tooltip and click-to-scroll) plus terminal-style history recall: ArrowUp on an empty composer fills the previous question directly into the input box

0High
0Medium
0Low

kindred7

dsh deepseek-harness plugin timeline conversation history recall arrow-up

DSH Timeline（@kindred7/dsh-timeline）

English

dsh web 对话增强插件：在对话界面左侧渲染一条极简的垂直刻度线，每一轮用户提问对应一个刻度，为长对话提供"全局地图"式的快速导航；同时内置终端式历史召回——输入框为空时按 ↑ 直接回填上一条提问，像终端一样翻阅历史。

功能描述

一句话简介（可直接用作 GitHub About / 仓库描述）：

@kindred7/dsh-timeline —— dsh web 对话导航时间线：左侧刻度标记每轮提问，悬停预览、点击定位、滚动跟随；附终端式 ↑ 键历史召回。

详细功能：

🧭 对话快速导航：每条用户提问在对话区左侧对应一条短刻度线；点击任意刻度，平滑滚动定位到对应消息；滚动浏览时自动高亮当前阅读位置所在的刻度
⌨️ 终端式历史召回：输入框为空时按 ↑ 直接回填最近一条提问；连续 ↑ 往前翻阅更早历史，↓ 往回翻，任意手动编辑即退出浏览态——不弹面板、不打断输入
💬 悬停预览：鼠标悬停时刻度拉长并弹出毛玻璃 tooltip，显示该轮提问的完整内容
✨ 波纹动效：悬停某刻度时，上下相邻刻度呈阶梯式长度衰减（波纹扩散），过渡动画细腻克制
📌 自适应定位：以对话容器为基准动态计算位置——侧边栏拉伸、窗口缩放、布局折叠时实时跟随，永不被遮挡；容器探测采用三级降级策略（消息行结构探测 → 语义标记 → 类名匹配），不依赖构建产物 hash 类名，跨版本、跨机器稳定可用
🌗 明暗主题：通过 CSS 变量适配 prefers-color-scheme，深浅色模式均自动切换
♿ 无障碍：遵循 prefers-reduced-motion 关闭动效；刻度带 aria-label 支持读屏

快速开始

方式一：一条命令安装（推荐）

dsh plugin --profile web <参数> 会进入 web profile 目录（%USERPROFILE%\.dsh\profiles\web，首次使用自动创建）并把参数转发给 pnpm；安装/更新/卸载成功后自动对账 dsh.profile.bundles——凡是声明了 dsh.bundle 的依赖都会被自动注册，无需手动执行注册命令。

# 从 npm 注册表安装——国内无需代理即可访问（npmmirror 自动同步）
dsh plugin --profile web add @kindred7/dsh-timeline

# 或从 GitHub 直装
dsh plugin --profile web add github:kindred-7/dsh-timeline

# 重启 DSH web 生效
dsh web

锁定版本与日常管理使用同一条命令：

dsh plugin --profile web add @kindred7/[email protected]           # 锁定 npm 版本
dsh plugin --profile web update @kindred7/dsh-timeline              # 更新到最新
dsh plugin --profile web remove @kindred7/dsh-timeline              # 卸载（同时取消注册）

npmmirror 镜像通常在发布后数分钟内自动同步；若刚发布的新版本在镜像上 404，稍等片刻重试，或临时在命令后追加 --registry=https://registry.npmjs.org。

方式二：在 profile 目录手动 pnpm 安装

在目标电脑上（需已安装 Node.js ≥ 18 和 pnpm）：

# 1. 进入 dsh web profile 目录
cd %USERPROFILE%\.dsh\profiles\web

# 2. 安装（任选其一）
pnpm add @kindred7/dsh-timeline                       # npm 注册表最新版
pnpm add @kindred7/[email protected]                 # 锁定版本
pnpm add github:kindred-7/dsh-timeline                # 或 GitHub 最新 main 分支
pnpm add https://registry.npmjs.org/@kindred7/dsh-timeline/-/dsh-timeline-0.4.0.tgz

# 3. 注册到 dsh.profile.bundles
pnpm exec dsh-timeline-register

# 4. 重启
dsh web

卸载：

pnpm exec dsh-timeline-register --remove
pnpm remove @kindred7/dsh-timeline

npm 用户同样适用：npm install github:kindred-7/dsh-timeline

方式三：一键脚本安装（无需 Node/pnpm）

将 dsh-timeline-<版本>.zip 解压到任意目录
在 PowerShell 中进入插件目录并运行安装脚本：

cd dsh-timeline
.\install.ps1

如遇执行策略限制，使用： powershell -ExecutionPolicy Bypass -File .\install.ps1

脚本会自动完成：复制文件到 %USERPROFILE%\.dsh\profiles\web\node_modules\、写入依赖声明、注册到 dsh.profile.bundles。支持重复运行（幂等覆盖更新）。

卸载：

.\uninstall.ps1

手动安装

复制插件文件

# Windows（把 <插件目录> 替换为解压后的实际路径）
xcopy /E /I "<插件目录>" "%USERPROFILE%\.dsh\profiles\web\node_modules\@kindred7\dsh-timeline"

编辑 web profile 配置

打开 %USERPROFILE%\.dsh\profiles\web\package.json，添加：

{
  "dependencies": {
    "@kindred7/dsh-timeline": "file:./node_modules/@kindred7/dsh-timeline"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@kindred7/dsh-timeline"
      ]
    }
  }
}

重启 DSH

dsh web

使用说明

安装后，插件会自动在对话窗口左侧显示时间线标记：

查看时间线

每个用户提问会在左侧显示一个灰色短线标记
标记垂直居中排列，间距 6px

预览问题

将鼠标悬停在标记上
短线会从 12px 平滑扩展到 24px
颜色从灰色变为蓝色，并带有发光效果
显示问题的 tooltip 预览

快速定位

点击任意标记
对话窗口会平滑滚动到对应的提问位置；即使已贴在对话最底部、或 AI 正在流式回复，点击跳转依然可靠
若目标提问已在物理滚动极限（如最新一条提问、且你正停在最底部），该行会短暂闪烁高亮提示"已在此处"——内容不足一屏时无法再滚动
支持键盘导航（Tab 键切换标记）

历史召回

输入框为空时按 ↑，即可像终端一样召回历史提问：

| 按键 | 行为 | |---|---| | ↑（输入框为空） | 直接把最近一条历史问题填进输入框（不弹面板） | | ↑（连续按） | 继续往前翻更早的历史 | | ↓ | 往回翻；翻过最新一条后恢复空白输入框 | | 任意手动编辑 | 结束浏览态，↑ 恢复「仅空框触发」 |

历史记录保存在浏览器 localStorage：上限 100 条、按文本去重、新→旧排序
自动捕获本浏览器内所有会话提交过的用户提问（含 steering 消息）
无修饰键、非输入法组合态才生效，不干扰 / @ 触发菜单

技术实现

架构

┌─────────────────────────────────────┐
│   DSH Web Application               │
│  ┌──────────────────────────────┐  │
│  │  Sidebar  │  Conversation    │  │
│  │           │  ┌────────────┐  │  │
│  │           │  │ Timeline   │  │  │
│  │           │  │ Markers    │←─┼──┼─ Plugin
│  │           │  └────────────┘  │  │
│  │           │                  │  │
│  └──────────────────────────────┘  │
└─────────────────────────────────────┘

核心代码

监听会话消息

const session = useSession();
const snapshot = session?.getSnapshot();
const userMessages = snapshot.events
  .filter(event => event.kind === 'user/message')
  .map(event => ({
    id: event.id,
    content: event.content?.[0]?.text,
    seq: event.seq
  }));

渲染时间线标记

<div className="timeline-container">
  {userMessages.map((message, index) => (
    <div
      key={message.id}
      className="timeline-marker"
      onClick={() => scrollToMessage(message.seq)}
      onMouseEnter={(e) => showTooltip(e, message)}
      onMouseLeave={hideTooltip}
    />
  ))}
</div>

CSS 动效

.timeline-marker {
  width: 12px;
  height: 3px;
  background-color: #6b7280;
  transition: all 0.25s cubic-bezier(0.4, 0, 0.2, 1);
}

.timeline-marker:hover {
  width: 24px;
  background-color: #3b82f6;
  box-shadow: 0 0 8px rgba(59, 130, 246, 0.5);
}

文件结构

dsh-timeline/
├── package.json          # 插件配置和依赖
├── cordis.patch.yml      # bundle patch 描述文件（DSH 注入用）
├── register.js           # 注册 CLI（bin: dsh-timeline-register）
├── install.ps1           # Windows 一键安装脚本
├── uninstall.ps1         # 卸载脚本
├── lib/
│   ├── index.js         # 插件入口
│   └── client.js        # 客户端实现（核心）
├── USAGE.md              # 使用指南
├── README.md             # 中文说明（本文件）
└── README.en.md          # English readme

自定义样式

插件使用 CSS 类名，可以通过覆盖样式来定制外观：

/* 在 web profile 的 cordis.patch.yml 中添加自定义样式 */

/* 修改标记颜色 */
.timeline-marker {
  background-color: #10b981; /* 绿色 */
}

/* 修改 hover 效果 */
.timeline-marker:hover {
  background-color: #059669;
  box-shadow: 0 0 12px rgba(16, 185, 129, 0.6);
}

/* 修改时间线位置 */
.timeline-container {
  left: 80px; /* 调整距离左侧的距离 */
}

故障排除

插件未显示

检查插件是否正确安装：

Test-Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\@kindred7\dsh-timeline"

检查 package.json 是否包含插件：

Get-Content "$env:USERPROFILE\.dsh\profiles\web\package.json" | Select-String "kindred7"

重启 DSH web 应用

时间线位置不正确

如果时间线标记与侧边栏重叠，调整 left 值：

.timeline-container {
  left: 80px; /* 增加这个值 */
}

Tooltip 被裁剪

如果 tooltip 在屏幕边缘被裁剪，可以修改 tooltip 位置逻辑：

// 在 client.js 中修改 tooltip 位置计算
const tooltipX = Math.min(rect.right + 10, window.innerWidth - 320);

开发

本地开发

cd dsh-timeline

修改代码后，重新安装到 profile：

.\install.ps1

刷新 DSH web 页面（Ctrl+F5）

调试

打开浏览器开发者工具（F12），查看：

Console：查看插件日志
Elements：检查 DOM 结构和样式
Network：确认插件文件加载

兼容性

✅ DSH 0.1.1-rc.2+
✅ React 18+
✅ Windows 10/11
✅ Chrome/Edge/Firefox
⚠️ 仅支持 Web 平台

贡献

欢迎提交 Issue 和 Pull Request！

开发规范

遵循现有的代码风格
添加必要的注释
测试后再提交
更新相关文档

更新记录

0.5.0

新增：终端式历史召回——输入框为空按 ↑ 回填最近提问，↑/↓ 翻阅历史，手动编辑退出浏览态（详见「使用说明 → 历史召回」）
新增：自动捕获会话提交的用户提问（含 steering 消息），localStorage 存储上限 100 条、文本去重、新→旧排序

0.4.1

变更：tooltip 视觉对齐 DSH 原生浮层（设计 token：深色板 rgb(44,44,46)、纯白文字、13px/20px、10px 圆角），最多显示 3 行后省略号截断

0.4.0

变更：发布到 npm，包名 @kindred7/dsh-timeline（未加 scope 的 dsh-timeline 已被占用）；裸包名直装无需访问 GitHub，国内经 npmmirror 同步后可达
修复：长对话最底部点击刻度跳转失效
- trajectory/多标签场景同一会话视图会挂载多份，全局 DOM 查询可能命中隐藏副本导致滚了看不见——现在只认可见行，并用 row.closest('[data-conversation-scroll]') 解析滚动容器（与宿主同款语义）
- 宿主的贴底跟随（ResizeObserver 回顶）会在动画头几帧把从底部启动的平滑滚动拽回——现在先瞬时预抬脱离贴底状态再平滑滚动
新增：目标行已在物理滚动极限时，闪烁高亮代替无效滚动，给出明确的定位反馈
修复：多视图挂载下当前阅读位置高亮可能跟随隐藏副本

0.3.0

首个公开发布版本

许可证

MIT License

致谢

感谢 DeepSeek Harness 团队提供的优秀插件系统！