dsh-milestone

会话里程碑导航条（DeepSeek Harness 插件）。在会话视图右侧渲染一条垂直 scrubber，每个 user 发言 对应一个进度点：鼠标悬停预览该条消息的前 80 字，点击平滑跳转到对应位置。

dsh-plugin · 适配 DeepSeek Harness (deepseek-ai/deepseek-harness) Web UI。

功能

• 进度点（tick）：每条真实 user 消息 = 一个 tick，按真实渲染偏移定位（非等距），跟随滚动与内容变化实时更新。
• 悬停预览：hover 显示该条 user 消息的前 80 字。
• 点击跳转：点击 tick 平滑滚动到对应消息（scrollIntoView）。
• 少于 2 条 user 消息时不渲染（无导航价值）。

安装

# 本地目录（开发）
dsh plugin --profile demo add ./dsh-milestone

# npm 包（发布后）
dsh plugin --profile demo add dsh-milestone

# GitHub 仓库（需 prepare 脚本 + allowBuilds 许可）
dsh plugin --profile demo add github:you/dsh-milestone

然后 npx @deepseek-ai/dsh web 启动 Web UI 即可看到右侧里程碑条。

开发

要求 Node.js >= 24（官方 harness 要求 ^22.19 || >=24，本仓库已验证 24.19.0）。依赖从 npm 安装（0.1.0-rc.6 系列，完整可用）。

pnpm install
pnpm run build       # 产出 lib/index.js (node half) + lib/client.js (browser half)
pnpm exec tsc --noEmit   # 类型检查
pnpm run watch       # 监听构建

构建产物：lib/index.js（node half，空 apply）+ lib/client.js（browser half，CJS closure，window.__ModuleLoader__.load banner）。

架构

双半边插件（Host = Node 进程，Client = 浏览器）：

src/index.ts            node half —— 空 apply，让插件进入 host cordis 配置树
src/client/index.ts     browser half —— 两个 slot 注册
src/client/MilestoneOverlay.tsx  shell.overlay entry（root scope）
                                   └─ 声明 session 子槽 milestone.rail
                                   └─ 通过 SessionProvider 桥接到会话区
src/client/MilestoneRail.tsx      milestone.rail entry（session scope）
                                   └─ useSession 读取会话快照
                                   └─ DOM 锚点定位 + tick 渲染 + 跳转

关键机制：

• 注入点：shell.overlay（kind: 'list'，scope: 'root'）——全框架浮动层，附加式、点击穿透，是"悬浮 rail"的唯一正确位置。
• 会话数据：通过声明 session-scope 子槽 milestone.rail，框架自动注入 SessionProvider（PropsRenderSlots 从子槽 scope 推导），rail 组件因此拿到 useSession / sessionId。
• 消息定位：useSession(s => s.chat.order) + s.chat.nodes.get(key) 过滤 kind === 'user'；DOM 锚点 data-chat-anchor-key（节点 key = 13:input-message<messageId>），scrollport 为 [data-conversation-scroll]。
• 性能：行元素按消息列表版本缓存（O(n) 重算）；scroll/resize 通过 requestAnimationFrame 节流。

已知限制

• 仅覆盖当前已加载的消息窗口（harness 初始加载最近 50 条事件，向上滚动触发 loadOlder 分页）；rail 会随分页自动更新，但更早的消息需要先滚动加载。
• preview 从 DOM textContent 提取，长消息截断为 80 字。
• 尚未实现"当前定位"高亮（P1）。

License

MIT