dsh-conversation-navigator 0.1.24 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +104 -0
- package/README.md +100 -92
- package/lib/client.js +1363 -1182
- package/package.json +47 -47
package/README.en.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# DSH Conversation Navigator (dsh-conversation-navigator)
|
|
2
|
+
|
|
3
|
+
[English](README.en.md) | [中文](README.md)
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/dsh-conversation-navigator)
|
|
6
|
+
[](https://www.npmjs.com/package/dsh-conversation-navigator)
|
|
7
|
+
[](https://github.com/gjj-star/dsh-conversation-navigator)
|
|
8
|
+
[](https://github.com/gjj-star/dsh-conversation-navigator)
|
|
9
|
+
[](https://www.npmjs.com/package/dsh-conversation-navigator)
|
|
10
|
+
[](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
|
|
11
|
+
[](https://github.com/deepseek-ai/deepseek-harness)
|
|
12
|
+
|
|
13
|
+
A **DeepSeek Harness (DSH) Web conversation navigator panel**: a turn-folded outline floating on the **right** side of the conversation page. Click any node to smooth-jump, watch the current reading position highlight as you scroll, with step badges colored to match the built-in "Trajectory" view.
|
|
14
|
+
|
|
15
|
+
Browser-only (no host behavior), plain JavaScript, zero build step, zero npm dependencies (buttons/tooltips reuse the official primitives from the DSH kernel seed).
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
> Four forms: full, hidden, minimal-right, and minimal-left (the minimal strips collapse to the in-row indicator bars; hover expands the positioning panel). More screenshots in [assets/screenshots](./assets/screenshots). The two "community skins" shots are taken under third-party skins (whale-girl maid theme and the "Your Name" theme), not bundled with the plugin.
|
|
23
|
+
|
|
24
|
+
## Features
|
|
25
|
+
|
|
26
|
+
- **Turn-folded outline**: shows "Turn N + your question" rows by default, long conversations at a glance
|
|
27
|
+
- **Keyword filter**: click the top-left search icon to reveal the inline input; matches only your questions + the assistant's actual reply text (context, tool calls, commands, compaction and reasoning never match); hits are highlighted and the list text is windowed to the keyword
|
|
28
|
+
- **Expand / collapse steps**: the arrow button on the right of each turn row (`▸ N`, rotates to `▾` when expanded) smoothly expands or collapses the turn's step details (assistant replies, tool calls, commands, compaction points, etc.)
|
|
29
|
+
- **Hover full text**: rest the mouse on a turn row and a bubble shows the user's complete question, no longer truncated to one line
|
|
30
|
+
- **Full / Hidden / Minimal modes**: the header toggle cycles four states —
|
|
31
|
+
- **Full**: the classic grouped view (system events like compaction are shown bold, at the same level as turns)
|
|
32
|
+
- **Hidden**: every row is a trajectory badge + text (user = business blue, assistant = violet, compaction = neutral gray)
|
|
33
|
+
- **Minimal-right**: the indicator-bar strip docked to the right edge of the viewport
|
|
34
|
+
- **Minimal-left**: the same strip pinned to the left edge of the conversation area (at the right border of the DSH sidebar), leaving the right side for dsh-better-sidebar
|
|
35
|
+
- The minimal strip collapses to the in-row indicator bars (current = solid brand color, others = 40% foreground-color mix); hovering expands a fixed 7-row positioning panel (click to jump, hover bubble for the full question, thumb-only scrollbar beyond 7 rows; right-aligned expands from right to left, left-aligned from left to right); a floating button above the bars keeps cycling forward (minimal-right → minimal-left → Full); the toggle yields while the search input is open
|
|
36
|
+
- **Draggable panel**: in Full / Hidden mode, grab the header to drag the panel anywhere in the viewport (auto-clamped to the edges; the expanded height is capped at half the viewport with the top edge fixed and the panel growing downward — expanding a huge turn scrolls the list internally while the "Back to latest / Collapse all" footer stays reachable); the pin button in the header toggles between the default right-dock and the last dragged position; the dragged position and the minimal left/right alignment survive page reloads via localStorage
|
|
37
|
+
- **Silky motion**: panel fade, step expand/collapse height transitions, staggered fade-in of filter results, rotating collapse arrow — all pure CSS, zero dependencies
|
|
38
|
+
- **Click to locate**: click a turn or a step to smooth-scroll the conversation to that exact position (fold state is preserved)
|
|
39
|
+
- **Load earlier / Load all**: two buttons on top — "Load earlier" pages one batch back, "Load all" loads every historical turn into the navigator for arbitrary jumps (the page itself stays lazily loaded until you click)
|
|
40
|
+
- **Position tracking**: scrolling the conversation highlights and follows the turn you are currently reading
|
|
41
|
+
- **Right-side docking (default)**: the panel is anchored to the right edge of the viewport and stays put when the left sidebar collapses or expands; unpin (drag it or hit the pin) to place it anywhere
|
|
42
|
+
- **Back to latest / Collapse all**: two shortcut buttons at the bottom; "Collapse all" is disabled when no turn is expanded, so it never looks broken for doing nothing
|
|
43
|
+
- **Trajectory colors**: user/steering = business blue, context = success green, assistant = violet, tool = amber, compaction = neutral gray (`--dsw` theme tokens matching the built-in trajectory view, light/dark adaptive)
|
|
44
|
+
- **Native DSH look**: action buttons reuse the official `Button`/`Tooltip` components and official icons (search, close); the remaining icons (navigate, load earlier, load all, back to latest, collapse all, switch modes, …) are outline icons from **Lucide** (ISC License, [lucide.dev](https://lucide.dev)), `currentColor` adaptive to light/dark themes
|
|
45
|
+
- Follows workspace/session switches automatically and rebuilds the outline
|
|
46
|
+
|
|
47
|
+
## Install
|
|
48
|
+
|
|
49
|
+
This plugin is a spec-compliant **bundle** (`dsh.bundle` manifest + `dsh.client` declaration), plain JavaScript with no build step. Install with the official CLI:
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
# Option 1: npm (no build authorization needed once published)
|
|
53
|
+
dsh plugin --profile web add dsh-conversation-navigator
|
|
54
|
+
|
|
55
|
+
# Option 2: GitHub (pure JS package, no prepare/allowBuilds required)
|
|
56
|
+
dsh plugin --profile web add github:gjj-star/dsh-conversation-navigator
|
|
57
|
+
|
|
58
|
+
# Option 3: local tarball
|
|
59
|
+
pnpm pack
|
|
60
|
+
dsh plugin --profile web add ./dsh-conversation-navigator-<version>.tgz
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`dsh plugin` forwards to pnpm inside the profile directory, so **pnpm must be on your PATH**; installation appends this package to the profile's `dsh.profile.bundles`, and its bundled `cordis.patch.yml` layer inserts the plugin row. Restart `dsh web` and the panel appears (expanded by default).
|
|
64
|
+
|
|
65
|
+
> Manual install (no pnpm): place the repo at `<DSH_HOME>\profiles\<profile>\node_modules\dsh-conversation-navigator` and append the content of [`example.patch.yml`](./example.patch.yml) to the top-level array of the profile's `cordis.patch.yml`.
|
|
66
|
+
|
|
67
|
+
## Updates
|
|
68
|
+
|
|
69
|
+
Edit `lib/client.js` and restart `dsh web`. Only the panel position, docked state and minimal alignment persist (localStorage `dsh-cnvnav:ui:v1`); expand/collapse, mode selection and search keywords still live only within the page session.
|
|
70
|
+
|
|
71
|
+
## How it works
|
|
72
|
+
|
|
73
|
+
- Slots: `conversation.session.header.utilities` (the "导航" toggle in the title bar) + `shell.overlay` (the floating panel)
|
|
74
|
+
- Data: the session-level standard props `useSession` (selects the stable render order `order` of `ConversationSnapshot.chat` + the `ChatNodeStore`), grouped by `node.location` turn
|
|
75
|
+
- History backfill: pages back through `sessions`'s `binding(sessionId).session.loadOlder()`, "Load all" loops until `hasMore=false`
|
|
76
|
+
- Jumping: reuses the DSH chat view's own stable DOM anchor `[data-chat-anchor-key]` (the same anchor the product uses internally for paging/scroll positioning) with `scrollIntoView` smooth scrolling
|
|
77
|
+
- Position tracking: captures scroll events on the `[data-conversation-scroll]` container (throttled 120ms) and computes the first visible node at the viewport top
|
|
78
|
+
- Keyword filter: extracts searchable text only for `user` and `assistant-step` nodes (`dialogueText`), case-insensitive matching, hits wrapped in `<mark>` and the display windowed around the first hit
|
|
79
|
+
- Hover full text: the turn-row bubble reads `fullDialogueText` (all text blocks of the user node joined), shown via `Tooltip` with a 340px width cap
|
|
80
|
+
- Modes: the header button cycles `viewMode` (full/hidden/minimal/minimal-left); hidden replaces the turn head title with a trajectory badge (`titleNode` strategy); minimal-right is docked by CSS `right`, minimal-left is pinned to `scrollport.left + 12` (the placement key includes `r.left` and a ResizeObserver on the chat area re-anchors it whenever the left sidebar expands or collapses); the toggle yields while the search input is open
|
|
81
|
+
- Drag & persistence: the full-panel header is draggable (pointer events, clamped to the viewport); dragging or the pin toggles `docked`; `place()` only clamps a freely-placed panel into the viewport instead of re-docking it; the position, docked state and alignment choice persist in localStorage (`dsh-cnvnav:ui:v1`)
|
|
82
|
+
- Styling: `Button`/`Tooltip`/search & close icons reuse `@deepseek-ai/dsh-client-ui-primitives`, the rest are inline Lucide SVGs (ISC License); the panel injects its own `<style>` element, colors use `--dsw-*` theme tokens; everything is cleaned up with the fiber on unload
|
|
83
|
+
|
|
84
|
+
## Compatibility
|
|
85
|
+
|
|
86
|
+
- Target platform: DSH Web (`dsh.client.platform: web`), depends on the kernel seed's `react`, `slots`, `sessions` services and `@deepseek-ai/dsh-client-ui-primitives`, plus the standard capabilities provided by `dsh-client-runtime` and `dsh-client-ui-conversation` (`dsh.client.inject` declares runtime and conversation)
|
|
87
|
+
- **Version-sensitive points**: `[data-chat-anchor-key]` / `[data-conversation-scroll]` are the current DOM anchor conventions of the DSH chat view; if they change after a DSH upgrade, only `findAnchor` / `computeActiveKey` in `lib/client.js` need adjusting
|
|
88
|
+
- No hard `timer` dependency: the client timer service is used for throttling when present, and degrades to unthrottled otherwise
|
|
89
|
+
|
|
90
|
+
## Structure
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
lib/
|
|
94
|
+
index.js # empty host entry (browser-only plugin)
|
|
95
|
+
client.js # full browser implementation (window.__ModuleLoader__ module format)
|
|
96
|
+
assets/
|
|
97
|
+
screenshots/ # screenshots (README hero + market gallery)
|
|
98
|
+
cordis.patch.yml # bundle patch layer (inserts the plugin row)
|
|
99
|
+
example.patch.yml # patch example for manual installs
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## License
|
|
103
|
+
|
|
104
|
+
MIT
|
package/README.md
CHANGED
|
@@ -1,92 +1,100 @@
|
|
|
1
|
-
# DSH 会话导航插件(dsh-conversation-navigator)
|
|
2
|
-
|
|
3
|
-
[
|
|
4
|
-
|
|
5
|
-
[ | 中文
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/dsh-conversation-navigator)
|
|
6
|
+
[](https://www.npmjs.com/package/dsh-conversation-navigator)
|
|
7
|
+
[](https://github.com/gjj-star/dsh-conversation-navigator)
|
|
8
|
+
[](https://github.com/gjj-star/dsh-conversation-navigator)
|
|
9
|
+
[](https://www.npmjs.com/package/dsh-conversation-navigator)
|
|
10
|
+
[](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
|
|
11
|
+
[](https://github.com/deepseek-ai/deepseek-harness)
|
|
12
|
+
|
|
13
|
+
**DeepSeek Harness(DSH)Web 端会话导航面板**:在对话页**右侧**悬浮展示按轮折叠的对话大纲,点击任意节点平滑跳转,滚动对话时实时高亮当前阅读位置,步次徽标配色与内置"轨迹"视图统一。
|
|
14
|
+
|
|
15
|
+
纯浏览器插件(无宿主行为)、纯 JavaScript、零构建、零 npm 依赖(按钮/Tooltip 复用 DSH 内核 seed 的官方 primitives)。
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
> 四种形态:显示轮次、隐藏轮次、极简·右、极简·左(极简收起仅露行内指示条,悬停展开定位面板)。完整截图见 [assets/screenshots](./assets/screenshots)。其中「社区皮肤适配」两张为第三方皮肤下的效果(鲸鱼娘女仆主题与君の名は主题),非插件自带。
|
|
23
|
+
|
|
24
|
+
## 功能
|
|
25
|
+
|
|
26
|
+
- **按轮折叠大纲**:默认只显示"第 N 轮 + 你的问题"列表,长对话一目了然
|
|
27
|
+
- **关键词过滤**:点击左上角搜索图标呼出输入框,只按「你的提问 + 助手实际回复文本」过滤(上下文、工具、命令、压缩、推理等不参与匹配),命中词高亮,列表文本自动定位到关键词处
|
|
28
|
+
- **展开/折叠步次**:点击轮次行右侧的箭头按钮(`▸ N`,展开时旋转为 `▾`)平滑展开/折叠该轮的步次明细(助手回复、工具调用、命令、压缩点等)
|
|
29
|
+
- **悬停查看全文**:鼠标在轮次行停留片刻,气泡显示该轮用户提问的完整原文,不再被单行截断
|
|
30
|
+
- **显示 / 隐藏 / 极简四种形态**:头部切换按钮四态循环——「显示轮次」为经典分组视图(压缩等系统事件与轮次同级加粗展示)→「隐藏轮次」每行统一为轨迹徽标 + 文本(用户 = 业务蓝、助手 = 紫罗兰、压缩 = 中性灰)→「极简·右」视口右缘指示条→「极简·左」锚定对话区左缘(为 dsh-better-sidebar 让出右侧),再回到「显示轮次」;
|
|
31
|
+
- 「极简」形态收起时只露行内指示条(当前 = 品牌色实色、非当前 = 主题前景色掺 40%),悬停展开 7 行画幅的定位面板(点击跳转、悬停全文气泡、超 7 条仅滑块滚动;右对齐从右向左展开、左对齐向右展开),外置悬浮按钮继续循环(极简·右→极简·左→显示轮次),搜索框展开时按钮自动让位
|
|
32
|
+
- **面板可拖动**:显示轮次 / 隐藏轮次面板按住头部即可拖到视口任意位置(自动夹边;展开高度至多半屏,上边缘固定、下边缘展开,超长轮次时列表内部滚动,底部「回到最新/全部折叠」始终可达),头部图钉按钮在「默认右侧停靠」与「上次拖动位置」间切换;拖动位置与极简左/右对齐选择持久化于 localStorage,刷新页面原样恢复
|
|
33
|
+
- **丝滑动效**:面板开合淡入淡出、步次展开/折叠高度过渡、过滤结果逐条级联淡入、折叠箭头旋转——全部纯 CSS 实现,零依赖
|
|
34
|
+
- **点击定位**:点击轮次主体或步次条目,平滑滚动跳转到对话中对应位置(不改变折叠状态)
|
|
35
|
+
- **加载更早 / 加载全部**:面板顶部两个按钮——「加载更早」向后翻一页、「加载全部」一键把所有历史轮次载入导航,之后可任意跳转(页面默认仍懒加载,只有点按钮才补载)
|
|
36
|
+
- **位置跟踪**:手动滚动对话时,面板自动高亮并跟随当前正在阅读的轮次
|
|
37
|
+
- **右侧定位**:默认锚定视口右侧,收起/展开左侧边栏时纹丝不动;解除停靠(拖动/图钉)后可自由放置
|
|
38
|
+
- **回到最新 / 全部折叠**:面板底部两个快捷按钮;「全部折叠」在没有展开的轮次时置灰,避免误以为失效
|
|
39
|
+
- **轨迹配色**:用户/插话 = 业务蓝、上下文 = 成功绿、助手 = 紫罗兰、工具 = 琥珀、压缩 = 中性灰(与内置轨迹视图一致的 `--dsw` 主题 token,自动适配明暗主题)
|
|
40
|
+
- **DSH 原生风格**:操作按钮复用官方 `Button`/`Tooltip` 组件与官方图标(搜索、关闭);其余操作图标(导航、加载更早、加载全部、回到最新、全部折叠、切换轮次等)取自 **Lucide** 描边图标集(ISC License,[lucide.dev](https://lucide.dev)),`currentColor` 自动适配明暗主题
|
|
41
|
+
- 切换工作区/会话自动跟随并重建大纲
|
|
42
|
+
|
|
43
|
+
## 安装
|
|
44
|
+
|
|
45
|
+
本插件是官方规范的**组合包**(`dsh.bundle` manifest + `dsh.client` 声明),纯 JavaScript、无构建步骤,推荐用官方 CLI 安装:
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
# 方式一:npm(发布后,用户无需任何构建授权)
|
|
49
|
+
dsh plugin --profile web add dsh-conversation-navigator
|
|
50
|
+
|
|
51
|
+
# 方式二:GitHub(纯 JS 包无需 prepare/allowBuilds,直接可用)
|
|
52
|
+
dsh plugin --profile web add github:gjj-star/dsh-conversation-navigator
|
|
53
|
+
|
|
54
|
+
# 方式三:本地 tarball
|
|
55
|
+
pnpm pack
|
|
56
|
+
dsh plugin --profile web add ./dsh-conversation-navigator-<version>.tgz
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`dsh plugin` 在 profile 目录内转发给 pnpm,因此需要 **pnpm 在 PATH 上**;安装会自动把本包追加进 profile 的 `dsh.profile.bundles`,其自带的 `cordis.patch.yml` 层负责插入插件行。重启 `dsh web` 后生效,面板默认展开。
|
|
60
|
+
|
|
61
|
+
> 手动方式(不依赖 pnpm):把仓库放进 `<DSH_HOME>\profiles\<profile>\node_modules\dsh-conversation-navigator`,并在 profile 的 `cordis.patch.yml` 顶层数组追加 [`example.patch.yml`](./example.patch.yml) 的内容。
|
|
62
|
+
|
|
63
|
+
## 更新
|
|
64
|
+
|
|
65
|
+
修改 `lib/client.js` 后重启 `dsh web` 即可;仅面板位置、停靠状态与极简左/右对齐持久化于 localStorage(`dsh-cnvnav:ui:v1`),展开/折叠、模式、搜索关键词等界面状态仍只存于页面会话内。
|
|
66
|
+
|
|
67
|
+
## 工作原理
|
|
68
|
+
|
|
69
|
+
- 注册槽位:`conversation.session.header.utilities`(标题栏「导航」开关)+ `shell.overlay`(浮动面板)
|
|
70
|
+
- 数据来源:会话级标准 props 的 `useSession`(选择 `ConversationSnapshot.chat` 的稳定渲染顺序 `order` + `ChatNodeStore`),按 `node.location` 的 turn 分组
|
|
71
|
+
- 历史补载:通过 `sessions` 服务的 `binding(sessionId).session.loadOlder()` 分页向后加载,「加载全部」循环至 `hasMore=false`
|
|
72
|
+
- 跳转定位:复用 DSH 聊天视图自身的稳定 DOM 锚点 `[data-chat-anchor-key]`(与产品内部 paging/scroll 定位同源),`scrollIntoView` 平滑滚动
|
|
73
|
+
- 位置跟踪:捕获 `[data-conversation-scroll]` 滚动容器的 scroll 事件(节流 120ms),计算视口顶部首个可见节点
|
|
74
|
+
- 关键词过滤:仅为 `user` 与 `assistant-step` 节点提取检索文本(`dialogueText`),大小写不敏感匹配,命中片段以 `<mark>` 高亮并按首个命中位置截取显示窗口
|
|
75
|
+
- 悬停全文:轮次头气泡读取 `fullDialogueText`(用户节点全部文本块拼接),用 `Tooltip` 展示并限宽 340px
|
|
76
|
+
- 显示/隐藏/极简模式:`viewMode` 四态循环(full/hidden/minimal/minimal-left),隐藏时仅把轮次头标题替换为轨迹徽标(`titleNode` 策略);极简右对齐由 CSS `right` 锚定视口右缘、左对齐以 `scrollport.left + 12` 钉在对话区左缘(定位 key 含 `r.left`,并用 ResizeObserver 监听对话区宽度变化,左侧栏展开/折叠时紧贴跟随);搜索框展开时按钮让位
|
|
77
|
+
- 拖动定位与持久化:面板头部拖拽(pointer events,视口夹边),拖动或图钉切换 `docked` 状态;`place()` 对自由放置的面板只做视口夹边、不再自动停靠;位置、停靠状态与对齐选择存于 localStorage(`dsh-cnvnav:ui:v1`)
|
|
78
|
+
- 样式:`Button`/`Tooltip`/搜索与关闭图标复用 `@deepseek-ai/dsh-client-ui-primitives`,其余图标为 Lucide 内联 SVG(ISC License);面板容器自建 `<style>` 注入,颜色使用 `--dsw-*` 主题 token;插件卸载时随 fiber 清理
|
|
79
|
+
|
|
80
|
+
## 兼容性说明
|
|
81
|
+
|
|
82
|
+
- 目标平台:DSH Web 端(`dsh.client.platform: web`),依赖内核 seed 的 `react`、`slots`、`sessions` 服务与 `@deepseek-ai/dsh-client-ui-primitives`,以及 `dsh-client-runtime`、`dsh-client-ui-conversation` 提供的标准能力(`dsh.client.inject` 已声明 runtime 与 conversation)
|
|
83
|
+
- **版本敏感点**:`[data-chat-anchor-key]` / `[data-conversation-scroll]` 是当前 DSH 聊天视图的 DOM 锚点约定,DSH 升级后若锚点变化,只需调整 `lib/client.js` 中 `findAnchor` / `computeActiveKey` 两个函数
|
|
84
|
+
- 未声明 `timer` 硬依赖:客户端的 timer 服务存在则用于节流,不存在时自动退化为未节流模式
|
|
85
|
+
|
|
86
|
+
## 目录结构
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
lib/
|
|
90
|
+
index.js # 宿主侧空入口(纯浏览器插件)
|
|
91
|
+
client.js # 浏览器端完整实现(window.__ModuleLoader__ 模块格式)
|
|
92
|
+
assets/
|
|
93
|
+
screenshots/ # 截图(README 主图 + 市场截图墙)
|
|
94
|
+
cordis.patch.yml # 组合包补丁层(插入插件行)
|
|
95
|
+
example.patch.yml # 手动安装时的补丁示例
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## License
|
|
99
|
+
|
|
100
|
+
MIT
|