dsh-session-toc

dsh-session-toc

右侧会话目录（Table of Contents）插件，为 DeepSeek Harness Web UI 的每个会话页加一个右侧中间常驻、可折叠的目录栏：把会话里的每个「用户提问」作为一条目录项列出，点一下尽量把会话滚动到对应消息，并高亮当前条目。

对应 DeepSeek 官网网页版里"右侧目录索引，点一下跳转到对应内容"的能力。

特性

• 常驻右侧：shell.overlay 浮动层，垂直居中靠右，默认 click-through，条目可交互。
• 每问一条：目录条目来自完整会话日志（host 端 sessionQuery.readSession），覆盖整段会话（含早期未加载进内存的消息）。
• 点击跳转：点目录项用 DSH 节点稳定 key（data-chat-anchor-key）精确定位并滚动；早期消息自动 loadOlder 补加载后定位；定位不可靠时降级为"仅高亮当前条目"。
• 可折叠：可收起成右侧一个窄条按钮，再点展开。
• 样式自切换（data-dsh-toc-theme）：卡片顶部控制条可切换目录栏自身的明/暗皮肤，并可拖动滑杆调节背景不透明度（只影响背景、文字始终不透明可读）。选择持久化到 localStorage（dsh-session-toc.theme / dsh-session-toc.bgAlpha），跨会话、刷新保留，且独立于 DSH 全局主题。
• 自动隐藏：当前会话的用户提问不足阈值（默认 3 条）时目录栏不显示，避免噪音。
• 长会话友好：目录列表超过 200 条时启用固定行高虚拟列表，只渲染可见窗口 ± 缓冲，避免长会话撑大 DOM 内存；条目数据全量保留，点击定位不受影响。
• 切换不卡顿：宿主侧做「进程内 LRU 缓存 + 落盘索引」双层降频，切换会话不再反复触发全量 readSession（磁盘读 + 深拷贝 + 全量 replay）；persisted 会话按 revision 失效、live 会话按消息序号增量失效。
• 重启秒开：落盘索引（$DSH_HOME/storages/session-toc/）跨进程/重启保留，重启后切换会话也能秒开。
• 零侵入：不改动任何 @deepseek-ai/* 内置包，仅以 bundle 插件方式挂载。

安装

需要本机已安装 pnpm，且 DSH 的 web profile 存在（如 ~/.dsh/profiles/web）。

方式一：从 GitHub 克隆后以 link 方式安装（推荐）

git clone https://github.com/notload/dsh-session-toc.git
cd dsh-session-toc
dsh plugin --profile web add link:$(pwd)

如果 $(pwd) 在你的 shell 里不生效，直接写完整的绝对路径即可，例如 Windows： dsh plugin --profile web add link:C:\Users\<你的用户名>\dsh-session-toc

方式二：安装已发布版本（若已发布到 npm）

dsh plugin --profile web add dsh-session-toc

安装后会写入 profile 的 package.json 的 dependencies，并自动进入 dsh.profile.bundles 层栈（dsh plugin 会自动 reconcile）。

确认进入层栈：

dsh plugin --profile web list

然后重启 dsh web，浏览器访问同一 URL，即可在会话页右侧看到目录栏。

配置

目录参数通过 cordis.patch.yml 传给 host 半侧（apply 的 config）。注意：DSH 客户端配置管线当前尚未打通，浏览器半侧收到的 config 是空对象，因此以下参数目前以代码默认值为准（与 dsh-pet 同样的限制）。

配置项（对照 lib/client.js 的默认值）：

key	默认值	说明
minEntries	1	当前会话用户提问少于该值时隐藏目录栏
maxChars	48	单条目录文案的最大字符数（超出加省略号）
collapsed	false	初始是否折叠

当前这些值在 client 里不可被用户覆盖。若需要可配置，需等 DSH 打通客户端配置管线，或改为硬编码默认值。

行为与限制

目录条目来源

• 条目来自完整会话日志：浏览器侧请求 host 端 /session-toc/questions?sessionId=…，host 用 ctx.sessionQuery.readSession 读取整个会话日志并提取全部 user/message 事件，再返回给浏览器生成目录。
• 覆盖整段会话：不依赖浏览器"已加载到内存"的节点。DSH 会话视图是按需加载的（有"加载更早"按钮，早期消息默认不在内存），但目录仍能列出全部历史提问。
• 图片/文件配文字时用文字：如果一条用户消息带有文字说明，目录文案直接用文字（忽略图片/文件名）；只有纯图片/文件、无任何文字时，才用文件名代替（🖼 文件名，无文件名用媒体类型兜底）。这样就不会出现"文字说明 + 文件名"混杂的目录条目。
• 排除上下文注入：只保留 source.kind === 'user' 的事件，session-reference、workspace 等注入式上下文不会进目录。

加载失败降级（长会话 / 格式不兼容）

• host 读取失败（如会话日志含本 harness 不认识的 background-agents/* 新事件类型，报 SessionFormatUnsupportedError）时，返回结构化错误码（SESSION_FORMAT_UNSUPPORTED / SESSION_READ_FAILED）。
• 前端收到失败后不再静默清空：会降级为"浏览器已加载节点"的目录（部分可用），并在目录里显示"目录加载失败（已显示部分已加载内容）+ 重试"提示条。
• host 对读取结果做「进程内 LRU 缓存 + 落盘索引」双层降频：
  • 进程内 LRU 缓存（上限 64 会话 + 8MB 总字节预算）命中直接返回已序列化 JSON；长对话多个大缓存共存时按字节预算再多淘汰，兜住进程堆内存；
  • 落盘索引（$DSH_HOME/storages/session-toc/<id>.json）跨进程/重启保留，仅对 persisted 会话生效；
  • 失效信号：persisted 会话按 revision（sessionPersistence 的 stat 级变更 token），live 会话按消息序号（lastSeq）零 IO 增量校验。
  • 这样切换会话 / 重启后都不再反复触发 readSession（磁盘读 + 多次深拷贝 + 全量 replay 校验）；失败结果不缓存。
• 安全：路由不携带 CORS 头（由浏览器同源策略拦截跨源读取）；并校验请求携带浏览器来源信号（sec-fetch-site 或同源 Origin），curl/脚本/局域网主机等裸请求一律 403；sessionId 还需属于当前 host 可见会话（live 或 persisted），否则拒绝；错误响应不回显内部错误详情。

滚动定位

• DSH 会话视图的每个 chat 节点在 DOM 上有稳定属性 data-chat-anchor-key（= 节点的 engine 稳定 key）。本插件优先用它来精确定位：点击条目时 document.querySelector('[data-chat-anchor-key="<key>"]') 找到节点并 scrollIntoView({block:'center'})。这比文本/图片匹配可靠得多，图片消息也能准确定位（图片节点同样有该属性）。
• 节点 key = conversationContextKey("input-message", userMessageId) = "13:input-message" + id，其中 id 是 host 从会话日志取出的用户消息 id。
• 早期消息自动补加载（渐进、不卡顿）：DSH 会话是虚拟列表（每页约 50 条），早期消息默认不在 DOM。点击条目时若目标已加载则立即定位（秒回）；若需补加载，插件先把视图滚到当前已加载的最早边界给即时反馈，再逐页调用 session.loadOlder()，每页之间用 requestAnimationFrame 让出主线程（不再用 requestIdleCallback 排队叠加，避免浏览器忙碌时越卡）；guard 按目标距离估算（estimateLoadOlderPages，封顶 40 页）。浏览器 console 会打印 [dsh-session-toc] jump {targetSeq,pages,ms} 供量化。
• 回退：节点始终未找到（如会话正在运行、loadOlder 不可用）或拿不到 id 时，降级为文本匹配；仍失败则仅高亮条目。

目录结构

dsh-session-toc
├── package.json          # bundle + client 声明
├── cordis.patch.yml      # 挂载声明（insert 行）
├── lib
│   ├── index.js          # host 半侧占位插件
│   ├── client.js         # 浏览器半侧：右侧目录栏 UI + 滚动定位
│   └── types
│       ├── index.d.ts    # host 侧类型
│       └── client
│           └── index.d.ts # 浏览器侧类型
└── README.md

License

MIT © notload

如果这个插件对你有帮助，欢迎点个 ⭐ Star 支持一下～