dsh-client-ui-timeline

Readme

# dsh-client-ui-timeline — DSH 会话问题导航条（对标 ZCode TurnNavigator）

给 DSH Web GUI 复刻 ZCode 桌面端的「对话问题导航」：

聊天区**左缘**一列小横杠——**一问一杠**（含会话中的 steering 追问），窗口够宽时常驻：

- **随滚动**：当前所在问题的杠高亮拉长（2.6×），相邻两根也按距离渐变拉伸，运行中的最后一问常亮；导航条自动滚动跟随当前杠。
- **悬停**某根杠：右侧弹出该轮问答预览气泡（用户问题 2 行加粗 + 助手回复 3 行，≤2 段、220 字截断；无正文显示「暂无助手正文」，回合运行中显示「助手仍在工作」）。
- **点击**：该问题的消息行平滑滚动到视口顶部（`prefers-reduced-motion` 时瞬时）；目标行未渲染时自动 `loadOlder` 翻页（上限 80 页）后再跳。
- 少于 2 问不显示；会话宽度 < 640px 隐藏（ZCode 原版阈值 864px，此处放宽）。

[English README](./README.en.md)

---

## 安装

在 DSH 的 profile（如 `desktop`）里，编辑 `profiles/<name>/package.json`：

1. 在 `dependencies` 加（**推荐**用 npm 已发布的稳定版本）：

```json
"dsh-client-ui-timeline": "^0.1.0"
```

   想固定某个历史提交，也可以用 GitHub 依赖（`<commit hash>` 换成你想固定的那次提交的完整 40 位 hash）：

```json
"dsh-client-ui-timeline": "github:hhb1028/dsh-client-ui-timeline#<commit hash>"
```

2. 在 `dsh.profile.bundles` 数组加 `"dsh-client-ui-timeline"`。
3. 在 `profiles/<name>` 目录下执行 `pnpm install`。
4. 重启 DSH。

包自带 `cordis.patch.yml`（insert id `ui-timeline-scrubber`），经 `dsh.bundle.patch` 自动生效；**勿**在 profile 的 cordis.patch.yml 重复 insert 同 id（Loader 会抛 duplicate loader entry id，vision-toolkit/meow-smooth 同款坑）。

## 兼容性

- 针对 **DSH Desktop 2.0.2**（`@deepseek-ai/*` `0.1.1-rc.2`）开发。
- 依赖会话 chat 节点形状与 `[data-conversation-scroll]` / `[data-chat-flow-key]` 的 DOM 契约。
- DSH 大版本更新可能改变上述形状/契约导致失效；失效时功能静默隐藏，不影响 DSH 本体。

## 卸载

从 `profiles/<name>/package.json` 删掉依赖与 bundles 条目，`pnpm install`，重启 DSH。

## 实现说明（对照 ZCode 原版）

- 原版：`out/renderer` 的 TurnNavigator 组件（`chat.turnNavigator.*` i18n），挂在虚拟化会话列表旁，`onJumpToQuery` 把 `data-row-id` 行滚到视口顶、行未挂载时 `scrollToIndex` + 12 帧 rAF 轮询。
- 本插件：DSH 会话无虚拟化，全部行在 DOM——坐标直接量 `[data-chat-flow-key]` 行的 `getBoundingClientRect`；数据链 `sessions.list.current` → `scope(id)`（ctx 代理）→ `sessionOf(ctx)` → `getSnapshot().chat.{order,nodes,timeline}`；一问一杠从 `kind:user/steering` 节点生成，回复预览取该回合首个有正文的 `assistant-step`。
- 视觉规格照抄原版：10px/杠、杠 12×2px 圆角、scaleX 距离渐变（2.6/1.7/1.25）、气泡 w-320 右偏 8px、line-clamp 2/3、220 字截断、`left-3 top-1/2` 导轨、隐藏滚动条；颜色换用 DSH 的 `--dsw-alias-*` 变量跟随主题/皮肤。
- 纯浏览器半区（`window.__ModuleLoader__` 模块，id 必须等于包名），零构建、不碰 dsh 本体；host 半区为惰性空插件。所有宿主访问有防御：上游形状变化时功能静默隐藏，不卡 web boot。

## 许可证

MIT