# dsh-chat-toc (DSH 对话目录与原生小地图增强)

[English](README.en.md) · [Español](README.es.md)

DSH Web GUI 的对话导航与大纲增强插件：**深度赋能官方原生 Turn Rail 导航轨**，告别冗余平行的第二条轨道，100% 融入原生界面。提供悬停卡片双向预览（用户提问 + AI 核心回答）、单条收藏与金光高亮、跨会话持久化、右上角原生扁平小工具栏（搜索 / 收藏过滤 / Markdown 大纲导出）。

## 功能特性

- **100% 原生融合与零视觉负担**：
  - 彻底移除冗余并排的彩色指示条，不破坏界面原有留白；
  - 深度赋能 DSH 官方自带的右侧消息刻度轨道，使原生小地图具备旗舰级功能。

- **自主稳定悬停卡片（带防抖，绝不闪退）**：
  - **双向内容呈现**：鼠标滑过官方轨道上的任意刻度，优雅弹出自研高质量预览卡片，清晰呈现 **👤 用户提问** 与 **🤖 AI 核心回答**；
  - **300ms 黄金防抖**：鼠标从轨道向左平移移入卡片时，卡片保持稳定悬浮，可从容选中文字或点击操作按钮，彻底解决原生卡片离开即闪退的痛点；
  - **一键收藏（⭐）与复制（📋）**：每张卡片右下角直接内嵌操作区，点击一键收藏该轮对话，或一键复制该轮问答全部正文。

- **跨会话永久持久化（Session-Scoped Storage）**：
  - 基于稳定的 **会话 ID (Session ID) + 消息全局唯一指纹 (chatAnchorKey)** 进行隔离持久化；
  - 刷新页面、关掉浏览器重新打开，收藏状态永远不丢；只有在会话被主动删除或归档时才清除。

- **右上角扁平极简工具条（原生排版流）**：
  - 优雅内嵌于右上角操作区（紧邻 Session 日志按钮），与界面浑然天成，绝不遮挡任何侧边面板或产生双滚动条；
  - **🔍 关键词即时与深度全会话搜索**：点击展开搜索框，输入即时模糊高亮当前页匹配；**长对话支持按 Enter 键触发全会话深度回溯搜索**，系统自动联动官方「加载更早」向上递归翻页拉取，直到精准命中并平滑定位至历史目标气泡，彻底告别盲翻！
  - **💻 代码与工具专属过滤胶囊**：搜索栏下方配备 `全部` · `仅代码 💻` · `仅工具 ⚙️` 快捷胶囊，长对话中一键精准过滤出代码变更或工具调用的轮次，告别低效盲翻；
  - **⭐ 仅看收藏过滤**：点击一键开启收藏过滤模式，未收藏刻度自动半透明淡化，已收藏刻度呈现 **22px 醒目金黄加宽长条 + 金色粒子微光晕**，全轨重要结论一览无余；
  - **📋 复制 Markdown 结构大纲**：一键将整场对话的所有提问与角色大纲导出为格式化 Markdown 树，便于快速归档与分享。

- **多语言与明暗主题自适应**：
  - 自动跟随 DSH Web 界面语言（中文 / 英文 / 西班牙语）；
  - 100% 完美适配 DSH Web 的浅色（Light）与深色（Dark）主题模式。

## 界面预览

**1. 悬停卡片（提问 + AI 核心回复预览，内嵌收藏与复制，右上角扁平工具条）：**

![悬停卡片预览](docs/toc-pop.png?v=0.4.10)

**2. 开启顶部 ⭐ 收藏过滤（已收藏刻度呈金色粒子长条高亮闪耀，未收藏线条淡化）：**

![全轨收藏高亮](docs/toc-bar.png?v=0.4.10)

## 环境要求

- **最低版本要求：DSH 宿主 ≥ `0.1.5-rc.2`**（`@deepseek-ai/dsh-client-runtime` / `dsh-client-locale` / `dsh-client-ui-chat` ≥ `0.1.5-rc.2`）。`peerDependencies` 已声明为 `>=0.1.5-rc.2 <0.3.0`。
  本插件依赖以下官方 DOM 契约，它们自 `0.1.5-rc.2` 起才齐备：
  - `data-chat-flow-kind` / `data-chat-turn` / `data-chat-anchor-key`（轮次与消息行的权威判据）
  - `data-chat-flow-kind="text"` 与 `"reasoning"` 的区分（用于只取**回答正文**、跳过思考过程）
  - 刻度按钮 `aria-label` 内的轮次号（`chat.turnNavigation.jump`）
  - `*_bubble` / `*_previewPrompt` / `*_previewResponse`（提问文本与官方预览兜底）
- **已验证版本**：`0.1.5-rc.2`、`0.1.6-alpha.1/2`、**`0.2.0-rc.1`**（当前最新）。
- **兼容官方 `0.2.0-rc.1` 的破坏性改版**：官方在该版**删除了 `markPosition` 类名**并把刻度改为**虚拟化渲染**。本插件已改为以**刻度按钮自身**为锚点，新旧两代通用；并因虚拟化改为每次重新读取，绝不缓存刻度元素引用。
- **接入方式**：以官方**数据属性**（`data-chat-*`）与 `aria-label` 为主要判据，**不依赖易变的 CSS Module 哈希**；仅在确有必要时使用「哈希前缀 + 下划线」形式的类名子串。
- **依赖**：纯前端增强，**无需任何其它插件**，无宿主侧服务，无需额外配置。

## 安装方式

```sh
dsh plugin --profile web add dsh-chat-toc
```

安装或更新后，刷新 `dsh web` 页面即可无缝体验。

> 本地开发时可用 `dsh plugin --profile web add link:/path/to/dsh-chat-toc` 以链接方式安装，修改源码后 `npm run build` 并刷新页面即可生效。

## 反馈

使用中遇到问题或有功能建议？欢迎到 [GitHub Issues](https://github.com/a792883583/dsh-chat-toc/issues) 提交反馈，感谢支持！

## License

MIT