timsok-shit/dsh-conversation-tracker

dsh-conversation-tracker

DSH Web 对话导航器（纯客户端插件，v0.4）。

导航轨道用于定位对话中的历史消息：每条 user 消息映射为一个导航节点，而 assistant 消息不创建节点。它不是滚动条，不是任务进度条，不是思维链，也不是智能体工作流。

节点数据源（v0.3：数据层驱动）

节点直接来自当前对话的完整消息数据，即 messages.filter(kind user/steering).map(message => node)：

- 数据入口：ctx.sessions.list.getSnapshot().current → ctx.sessions.binding(id).session（SessionFace = ObservableSnapshot）→ chat.order + chat.nodes.get(key) 遍历每个节点。
- 不依赖 DOM 扫描来统计消息数量，不依赖 DOM 索引，也不仅在挂载时初始化一次：session.subscribe() 实时推送更新；sessions.list.subscribe() 监听会话切换并重新绑定当前会话的节点（绝不混入其他会话）。
- 即使历史消息当前不在 DOM 中（虚拟化 / 历史分页尚未加载），导航器仍保留相应节点（位置根据已渲染行线性插值）。
- DOM 仅承载“节点 ↔ 已渲染行”的映射：数据层节点的 key 等于已渲染行的 data-chat-anchor-key（官方持久锚点，而非 DOM 索引），用于跳转 / 活动同步。
- messageId 绑定真实消息身份：steering 节点使用其 messageId；user 节点使用其持久事件序列 seq（数据层 user 节点没有单独的 messageId 字段；seq 即其稳定 ID）。

交互模型

- 容器折叠 / 展开：节点轨道默认紧凑折叠（水平占用最小）；当用户查看（悬停 / 聚焦 / 触摸 / 拖拽）时，轨道展开并显示节点及摘要，查看结束后重新折叠。折叠 / 展开仅影响容器层——节点圆点样式保持不变。
- 固定等距：节点在轨道中等距排列（仅由序号决定），完全独立于消息内容高度或对话间距；滚动、流式回复增长和消息折叠都不会移动任何节点。节点列仅表达“第 N 条用户消息的顺序”。
- 默认仅显示节点：一列小圆点（稀疏）/ 细条（密集），没有始终可见的文本。
- 按需预览：仅当用户主动悬停 / 聚焦 / 触摸 / 拖拽到某个节点时，才显示该节点的摘要卡片（直接显示 / 隐藏 + 轻量淡入，无胶囊变形，无细线残留）。默认不显示任何节点文本。
- 预览内容 = 原始用户文本：完全本地生成（结构化内容块的文本拼接 + 本地 markdown 控制字符剥离）。无 AI 摘要、无 LLM 调用、无自动标题、无语义改写、无重排序。 处理规则：
1. 提取用户的实际输入内容（文本块原始文本；兼容 DSH 的 type 字段和旧版 kind 字段；图片/附件按块类型计数）；
2. 剥离 markdown 控制字符，同时保留实际文本（本地 stripMarkdown：整块代码块、反引号、图片/链接语法、标题/列表/引用标记、粗体/斜体标记等，不重排序）；
3. 不显示完整代码块；
4. 仅图片 → [图片]；
5. 仅附件（工具调用/其他块）→ [附件]；
6. 方括号语法中的 URL 保留链接文本，并限制视觉宽度（overflow-wrap: anywhere）；
7. 保留 Emoji；
8. 空消息 → [无文本内容]；
9. 文本 + 附件共存 → 优先显示用户文本，可选前缀 [图片] / [附件]。
- 点击节点：通过 messageId/key 定位对应 user 消息的渲染行（若未渲染则回退到最近的行），平滑滚动使目标消息位于视口顶部约 30% 处（不贴顶，保留下方回复上下文），并立即更新活动节点；跳转后锁定活动状态约 700ms，使 IO 无法抢占高亮。
- 正常滚动：IntersectionObserver（root = 滚动容器，rootMargin 中间带）自动同步活动节点；不会在每次滚动事件时重新扫描整个对话。
- 拖拽导航：pointerdown 捕获 → 拖拽期间按等距序号实时映射节点并实时预览（无需释放），可快速遍历大量节点；释放后定位到目标消息。点击 = 无位移的拖拽。
- 设置页 / 模态层：当设置（或任何全屏模态层）打开时，跟踪器完全隐藏（覆盖检测 + 模态信号双重检查），绝不显示在设置界面之上；关闭后恢复。
- 移动端触摸：pointer 事件统一处理触摸；触摸按下展开容器，拖拽提供实时预览，触摸结束延迟后折叠并定位。视觉节点较小，但每个都带有 24px 的命中区域（::after），确保易用性。
- 键盘可访问：节点可通过 Tab 聚焦（聚焦时展开容器并显示预览，失焦时重新折叠）。

状态（完全本地化，无级联聊天页面重渲染）

activeNodeId、hoveredNodeId（包含 focusedNodeId 语义）、previewNodeId、dragging、targetNodeId —— 全部为本插件的内部模块状态，仅影响其自身的 DOM。

节点模型

node = { id, key, messageId, index, el, top, previewText }

- id：唯一的导航器节点 ID（dct-）。
- key：数据层节点键 == 渲染行的 data-chat-anchor-key（官方持久锚点）。
- messageId：真实消息标识（steering.messageId / user.seq 字符串化）。
- index：该用户消息在当前会话中的序号（与消息顺序一致）。
- el：已渲染的行元素（在虚拟化窗口之外时为 null；节点仍保留）。
- previewText：本地生成的原文纯文本预览。
- 一条用户消息 = 一个节点；相邻的短消息（“ok / why? / continue / yes”）各自保持独立。

大量节点 / 长会话

- 节点轻量（单个 div，无独立事件监听器；所有事件委托在导轨上）。
- 节点位置 = 等间距槽位（仅由序号决定，与布局无关）→ 滚动/流式输出永不移动节点；滚动仅切换类，永不重新渲染节点；布局仅在数据/结构变化时重建，通过 requestAnimationFrame 节流（diff 复用现有节点）。
- 流式输出期间数据快照变化迅速，但当用户节点签名（key+messageId）未变时，仅执行 DOM 关联刷新（render('dom')），不重建预览 / 不重新计算文本。
- 拖拽/悬停映射按等间距序号为 O(1)；dotMap 缓存避免逐帧 DOM 查询。
- 预览单例卡片按需填充（显示 show/隐藏 hide，无细条中间状态）。
- 当节点 > 160 时，激活密集模式（节点压缩为细条，非关键权重降低），不破坏顺序或定位。
- 兼容消息虚拟化 / 分页 / 动态追加 / 会话切换 / 节点删除。

DOM 契约（与官方会话客户端一致）

滚动容器  → [data-conversation-scroll]
消息行       → [data-chat-flow-kind] + [data-chat-anchor-key] + [data-chat-flow-key]
节点 key          → 已渲染行的 data-chat-anchor-key（== Conversation 节点 key）
focus-chat 回退 → [data-focus-flow] / [data-focus-anchor-key]
flowTop(row) = row.getBoundingClientRect().top - scrollport.getBoundingClientRect().top

技术说明

- 纯客户端插件：dsh.client.platform: "web"，window.__ModuleLoader__.load 注入，不放入 bundles；inject: ['slots', 'sessions']。
- 纯 DOM 自渲染，零构建，无 @deepseek-ai 值导入（符合 bundle 纯净性门禁）。
- 仅注入 UI，仅读取 DOM，绝不触碰会话数据文件；数据读取通过公共运行时 API。
- 样式完全复用 DSW 主题变量（--dsw-*），自动适配浅色/深色，无独立设计系统。
- 在数据层不可用的极端环境下，自动回退到 DOM 扫描基线。

布局
侧边栏 | 导航器 | 主聊天：导航器是位于文档根节点（布局根 / 视口层）的 position: fixed 覆盖层，不是 Sidebar 的子元素，不会被 Sidebar 的 overflow / transform / contain 裁剪。水平定位直接从 AppFrame 的网格 gridTemplateColumns 读取侧边栏列宽：轨道放置在侧边栏右边缘加上向聊天区域内侧 6px 的内边距凹槽处，默认状态下不与侧边栏重叠；当 Sidebar 宽度 / 折叠状态变化时，ResizeObserver 会自动跟随。预览也是一个绝对定位覆盖层，默认向聊天区域右侧展开：它不会改变轨道尺寸，也不会推挤聊天 / 侧边栏，因此锚点稳定，不会发生布局跳动。

目录结构

dsh-conversation-tracker/
├── package.json   # dsh.client.platform: "web"; exports ./client
├── index.js       # host-side empty apply (loader entry placeholder)
├── client.js      # Conversation Navigator full UI logic (pure DOM self-rendering)
└── README.md

安装

dsh plugin --profile web add github:timsok-shit/dsh-conversation-tracker

卸载

dsh plugin --profile web remove dsh-conversation-tracker

配置

纯客户端 DOM 插件，没有可配置的外部项；可调常量集中放在 client.js 的顶部 / 局部常量区域：

| 名称 | 位置 | 默认值 | 描述 |
| --- | --- | --- | --- |
| SLOT_PX | render() | 12 | 每个节点的等距槽位距离（轨道自适应 = N×SLOT_PX+8，上限为视口高度） |
| maxTrackH 下界 | render() | 40 | 最小轨道高度 |
| activeLockUntil 时长 | jumpTo() | 700 ms | 程序化滚动期间锁定 active，防止 IO 抢占高亮 |
| 折叠延迟 | scheduleCollapse | 220 / 触摸 900 ms | 离开容器后重新折叠前的缓冲时间 |
| 预览宽度上限 | showPreview() | 320 px | 摘要卡片最大宽度 |
| 层级探测 | checkLayerCover() | 900 ms 间隔 | 当模态信号与跟踪器重叠时隐藏 |

API

对外暴露（ModuleLoader 契约，inject: ['slots', 'sessions']）：

- apply(ctx)：插件入口。ctx.sessions 是数据层入口（list.getSnapshot().current → binding(id).session → getSnapshot() 读取 ConversationSnapshot）；ctx.get('slots') 用于 shell.overlay 占位注册。副作用：注入 #dsh-conversation-tracker-style 样式，在 body 上挂载 [data-dsh-conv-tracker] 容器，订阅会话快照和列表，启动 MutationObserver / ResizeObserver / 周期性层级探测。
- inject：声明对 slots 和 sessions 服务的依赖。
- 内部（不导出）：collectDomRows（行关联）、buildDataNodes（数据 → 节点）、render(mode)（full/dom）、showPreview / hidePreview、jumpTo、checkLayerCover 等，均只读写本插件的 DOM 和只读会话快照，无外部副作用。

维护

- 修改 client.js 后：用 node --check 检查语法 → 刷新 GUI 页面以重新注入 client-modules → 按“验收”逐项验证。
- 数据来源：节点来自运行时 ConversationSnapshot（只读）；绝不写入会话数据文件。
- 已知注意事项：导轨高度随节点数量自适应；层级检测基于模态信号相交检查（不依赖 elementsFromPoint，避免聊天区域凹槽误检导致跟踪器消失）。
- 性能契约：节点等距排列（由序号决定）→ 滚动/流式输出时节点永不移动；预览卡片对同一节点幂等（不重建、不重放动画）。

验收

1. 打开一个包含多轮问答的会话：出现导航导轨，节点数 = 该会话的用户消息总数（包括历史记录，包括不在 DOM 中的消息），助手消息不产生节点。
2. 默认仅显示节点；悬停/聚焦/触摸某个节点时显示该节点的原文预览；移开后隐藏。
3. 预览显示用户的原文（无 AI 摘要迹象）；图片消息显示 [图片]，附件显示 [附件]，空消息显示 [无文本内容]。
4. 点击某个节点会平滑滚动到对应问题；该消息位于视口顶部，回复上下文在下方可见；活动节点同步高亮。
5. 正常滚动过程中，活动节点自动跟随当前阅读位置（高亮沿节点列移动）。
6. 按住并拖动导航器：实时预览目标问题，松开后定位；快速遍历大量节点无卡顿。
7. 发送新消息：节点数实时增加 1；切换到另一个会话：节点数变为该会话的用户消息数，不会混入上一个会话。
8. 长对话（数百个节点及以上）滚动/拖动流畅；节点进入密集模式且仍可定位。
9. 浅色和深色主题均显示正常，不影响现有界面、文本选择或滚动。