dsh-quick-toc

English | 中文

DeepSeek Harness（DSH）对话大纲插件：把 AI 回复中的 Markdown 标题（H1–H6）提取成可导航的大纲面板，按对话回合分组、覆盖整段会话（含尚未加载进窗口的回合），支持标题/全文搜索、悬停预览与阅读位置自动跟随。

功能

• 按回合分组 —— 每条用户消息 + 其后续 AI 回复为一组，组头显示回合时间与首行预览，点击跳到该回合模型回答的开头
• 覆盖整段会话 —— 未加载进对话窗口的回合也在列表里（带「未加载」标记与预览）；点击即加载该回合并跳过去
• 失败回合的报错 —— 请求超时 / 上游报错这类没有回复的回合显示 请求失败 与报错原文，点击跳到对话中的报错位置
• 中英双语 —— 界面语言可设为跟随宿主、中文或 English；中文时间戳用 昨天 / 前天，英文昨天用 yesterday、更早用 YY-MM-DD HH:MM 日期
• 插件配置卡片 —— 设置 → 插件 → 插件配置里的「对话大纲」卡片：语言、默认停靠边缘、显示的标题层级、模糊搜索、悬停预览与诊断开关；改过的字段标「已自定义」并可单独重置，卡片与面板实时同步
• 回合时间带日期 —— 昨天 昨天 15:04、前天 前天 15:04、更早 25-09-11 15:04，跨天的会话里时间不再重影
• 标题行副标题 —— 每行标题下方显示该节正文的第一句，同名标题一眼可辨
• 悬停预览 —— 悬停标题行显示该节开头、回合时间与层级路径
• 搜索 —— 标题 / 全文两种范围，结果列表点击定位并高亮，n/N 回车逐处跳，Esc 关闭
• 搜索容错 —— 大小写、全角半角、连续空白自动视为同一匹配；「模糊」开关可放宽到关键字中间夹字
• 对话内高亮 —— 命中的关键字在对话中高亮，当前命中单独标亮
• 组头吸顶 —— 滚动大纲时，当前回合的组头固定在面板顶部
• 层级筛选 —— 标题栏的圆形层级按钮弹出 H1–H6 开关，任意组合显示
• 自动跟随 —— 滚动对话时正在阅读的回合自动点亮（封闭蓝框），大纲自动跟随
• 跳转 —— 点击标题跳到对话中该标题的位置（滚动动画由插件逐帧绘制，不依赖浏览器的「平滑滚动」——部分环境会把它直接执行成瞬移；每帧重瞄目标实时位置，宿主翻页改变偏移也能落准，跨页远跳不会半途停下）；面板与对话双向定位
• 回到底部 —— 往上翻远之后，列表右下角的浮动按钮一步回到最新一条（不在底部时出现、到底后消失）
• 可停靠、可缩放 —— 拖顶部横条移动，◀ / ▶ 切换左右停靠，拖边缘调宽高，收起后成为边缘把手；位置与尺寸按浏览器记住（顶边距、宽度、高度只通过拖拽调整）
• 分页 —— 默认显示最近的若干组，向上滚动既展开索引也加载更早的对话
• 边界提示 —— 滚到最早或最新再继续滚动时，面板底部短暂提示
• Markdown 感知 —— 标题中的行内标记会被剥离；围栏代码块里的 # 行不算标题
• 主题适配 —— 深色 / 浅色主题自适应；仅对话视图显示，切到其他视图渐隐
• 对话中没有标题也没有可识别时间时面板自动隐藏

兼容性

| 插件版本 | 支持的 DSH 版本 | | --- | --- | | 0.6.x（最新，0.6.0） | 0.1.5-rc.1、0.1.5-rc.2 | | 0.5.x（0.5.1） | 0.1.5-rc.1、0.1.5-rc.2 | | 0.4.x（0.4.1） | 0.1.5-rc.1、0.1.5-rc.2 | | 0.3.x（0.3.3） | 0.1.5-rc.1 | | 0.2.x（0.2.2） | = 0.1.2-rc.1 |

每个大版本只列该系列最新的一个补丁版本（新功能引入的缺陷都在其后的补丁里修掉了，所以同一个大版本内直接用最新补丁即可；旧补丁仍可继续用，插件不破坏既有接口）。

engines.dsh 下限为 0.1.5-rc.1（>=，该版本起插件改用会话级槽位注入的宿主接口）。0.6.0 在 0.1.5-rc.2 上实测通过（含宿主半的设置命名空间注册）；0.1.5-rc.1 上实测了插件加载与客户端模块下发（宿主启动正常、boot graph 中 dsh-quick-toc/client.js 的 rev 与本仓库 lib/client.js 逐字节一致），它依赖的宿主接口——turnOutline 投影、会话级槽位的 useProjection、客户端 sessions 服务与 loadThrough 跳转加载器（0.5.0 起）、失败回合所用的 turn-error 节点（0.5.1 起）、以及 0.6.0 新增的宿主 settings 服务（installSection）、客户端 settingsScope 与 settings.plugin.item 配置卡片槽位——在 0.1.5-rc.1 与 0.1.5-rc.2 的安装包中逐个核对存在（这些宿主包的代码在两版之间逐字节相同，dsh-client-ui-chat 仅差一条与本插件无关的 CSS 声明），因此两版都声明兼容。更早或更新的 DSH 版本未经验证，不作声明；在更早的 DSH 上可安装的最新插件版本是 0.3.2。安装或更新时，DSH 市场会依据 package.json 中的 engines.dsh、dsh.compatibility.dshReleases 与 peerDependencies 做宿主兼容预检。

安装

通过 DSH CLI 安装：

dsh plugin --profile web add dsh-quick-toc

也可以从 GitHub 安装：

dsh plugin --profile web add github:LyaxZ/dsh-quick-toc

或以本地目录安装：

dsh plugin --profile web add <插件目录路径>

安装后重启 DSH 并打开 Web UI。面板默认收起，点击对话区边缘的把手即可展开。

使用

• 跳转：点击大纲标题或组头跳到对应位置；带「未加载」标记的条目会先把该回合加载进来再跳；失败回合点报错行跳到对话中的报错位置
• 搜索：放大镜打开搜索框，输入后点结果定位并高亮，回车逐处跳，Esc 关闭
• 搜索容错：全角/半角、大小写、空格差异会自动匹配；需要更宽松时点搜索框右侧的「模糊」开关
• 层级筛选：点标题栏的圆形层级按钮弹出 H1–H6 开关，选择显示的层级
• 移动与停靠：拖顶部横条移动，◀ / ▶ 切换左右停靠
• 调整大小：拖右边缘、下边缘或右下角
• 加载更早：在大纲中向上滚动（既展开索引，也加载更早的对话）
• 回到底部：翻远了之后点列表右下角的浮动按钮回到最新一条
• 阅读位置：滚动对话，正在阅读的回合会以蓝框标出；大纲会自动跟随
• 设置：在 设置 → 插件 → 插件配置 里展开「对话大纲」卡片，可改语言、默认停靠边缘、显示的标题层级与模糊/悬停/诊断开关；改过的字段可单独重置。卡片与面板实时同步，不需要刷新；偏好保存在 DSH 的设置里，跟随配置走

诊断

面板挂载时默认不打印任何日志。需要排查宿主能力时，在 设置 → 插件 → 插件配置 里展开「对话大纲」卡片、勾选「在控制台打印诊断日志」——打开后当下就会打印一行（无需刷新）：

[dsh-quick-toc] panel mounted · turnOutline=… · jumpLoader=… · lang=… · prefs=…

turnOutline 缺失说明宿主没有该投影，jumpLoader 的分阶段措辞（no-sessions-service / no-binding-api / no-binding-for-session / no-loadThrough / binding-threw）可直接定位跳转桥断在哪一环。

开发

• lib/client.js —— 全部 UI 逻辑（浏览器端）
• lib/index.js —— 宿主半：注册 dsh-quick-toc 设置命名空间（schemastery schema，含取值范围校验），让偏好进入 DSH 的设置文档并提供插件配置卡片的入口
• cordis.patch.yml —— loader patch（符合官方 bundle 规范）
• 面板注册进会话级 conversation.input.overlay 槽以取得会话级 hook（useChat、useSession、sessionId 等），面板本体通过 createPortal 渲染到 document.body 成为固定浮层；对话数据来自 props.useChat（ChatSnapshot.order 与 nodes，节点形状：kind: user/assistant-step、location.turn、data.blocks）
• 「未加载回合」能力依赖宿主的两样东西：turnOutline 投影（整段会话的回合索引，每条含 turn/start 的 seq）与会话跳转加载器（客户端 sessions 服务的 binding(sessionId).session.loadThrough(seq)，通过客户端 ctx 的 ctx.get("sessions") 免声明查找取得）。两者各自独立降级：没有投影时只列已加载回合，没有加载器时未加载条目只展示、不跳转，面板其余功能不受影响。
• 失败回合的报错行读的是宿主的 turn-error 会话节点（宿主在 turn/end 的原因为 error 时发布，含 message 与可选的 code）；宿主不提供该节点时只是不显示这一行，其余功能不受影响。
• 界面文字来自 lib/client.js 顶部的一张字符串表（DICTS，中英各一份），语言设置决定用哪一份：跟随宿主 时优先问宿主的翻译函数（ctx.locale.bind("dsh-quick-toc")，注册的表就来自 DICTS），拿不到才回退到内置表。中英两份表的键必须对齐（仅 time.beforeYesterday（前天）是中文独有——英文对更早的时间直接用日期；time.yesterday 两语言都有，英文作 yesterday）。
• 偏好存储分两层，由一个模块级 store 统一读出：宿主设置文档（ctx.settingsScope.bind({ namespace: "dsh-quick-toc" })，语言/停靠边/层级/模糊/悬停/诊断六项，回环页面上是权威层）与 localStorage（镜像 + 顶边距/宽度/高度三项的正式存储——它们描述"这一块屏幕"，按浏览器保存）。写入按字段路由：宿主字段走 scope.mutate（本地同步折叠、宿主应答后对账），其余写 localStorage。非回环页面 DSH 将设置标记为只读，此时六项偏好退回本地镜像，行为与 0.5.x 一致；0.5.x 留下的本地值会在宿主层首次应答时导入一次（仅当用户层为空）。
• 插件配置卡片注册进 settings.plugin.item 槽（key 为插件命名空间；该槽按宿主实际提供的命名空间派发，宿主半未加载时卡片自然不出现，面板不受影响）；卡片与面板共享上面那个 store，因此两边实时互通。
• 修改 lib/client.js 后刷新页面即可看到变化（客户端模块按内容哈希发版，DSH 的客户端 HMR 也会推送重载）；改 lib/index.js（宿主半）需重启 DSH

License

MIT © 2026 LyaxZ