dsh-plugin-session-outline

English: README.md

dsh-plugin-session-outline

DeepSeek Harness cordis 插件：右侧浮动「会话大纲」导航面板。

• 面板入口是对话区右侧中部的圆形按钮（☰），点击展开/收起（Esc 或 × 收起）。
• 大纲只保留用户消息（user / steering 节点 = 一轮对话的开头，一级条目、带编号），点击任一条目平滑滚动到该轮对话开头。
• 面板可拖动（按住头部），位置记忆在 localStorage。

交互细节

• 当前位置指示：当前可见（最靠上）的用户消息在大纲里高亮；标题显示「会话大纲 · N」条目计数。
• 上/下一轮快速导航：面板底部「↑ 上一轮 / 下一轮 ↓」按钮，从当前位置逐轮跳转（未定位时上一轮=最后一条、下一轮=第一条）；面板内聚焦时也可用 ↑/↓ 方向键（不劫持输入框按键）。
• 跳转反馈：命中后目标条目短暂高亮闪烁，提示当前跳到哪。
• 历史懒加载兜底：重开 DSH 时旧会话消息可能尚未渲染（或已被虚拟列表卸载），此时点击条目会显示「⏳ 加载中…」，自动按方向滚到会话顶部/底部触发加载，轮询等待目标消息出现后自动跳转（最多约 10s）。
• 刷新防抖：MutationObserver 合并为 150ms 一次 + 2s 定时兜底；且只对结构变化与 user 行内文本变化敏感 —— assistant 流式输出期间不再高频全量扫描。
• 空会话不打扰：会话里还没有用户消息时，连 ☰ 入口按钮都不显示。
• 双语文案：走 DSH locale 系统（session.outline namespace，zh/en），跟随界面语言切换。
• 条目文本自动剥掉消息尾部的时间戳（HH:MM / 相对时间 / 日期等）。

实现机制

• 注册点：shell.overlay（list/root）——layout 预留的空白浮动层扩展点，不与右侧 details 栏冲突；order: 100 排在既有浮动条目之后。
• 数据来源：对话区消息节点的稳定 DOM 锚点 data-chat-anchor-key / data-chat-flow-kind（user / steering）。
• 跳转：手动计算 scrollTop + scrollTo({ behavior: 'smooth' })，450ms 后校验强制落位（不依赖 scrollIntoView，避免被页面滚动守卫/虚拟列表吞掉）。
• 性能：面板收起时只做廉价的存在性探测；展开时才全量扫描 + IntersectionObserver；插件自身 DOM 的 mutation 被过滤，assistant 流式文本变化不触发扫描（只对结构变化与 user 行内文本敏感）；扫描结果无变化时不重渲染。
• 样式：全部使用 DSH 设计 token（--dsw-alias-*），自动适配深浅主题；<style> 注入带 data-plugin 去重守卫，HMR 重载不会重复挂样式。

兼容性

• 平台：DSH web（dsh web），dsh.client.platform = "web"。
• peerDependencies：
  • @deepseek-ai/cordis ^4.0.1
  • @deepseek-ai/dsh-client-ui-slots ^0.1.0-rc.6（类型/槽位契约）
• client 声明：inject: ['slots', 'locale']（服务级依赖），包级 dsh.client.inject 指向 @deepseek-ai/dsh-client-ui-slots（模块表静态词）。
• 对 DSH Web UI 内部结构的依赖仅限上述 DOM 锚点与 shell.overlay 槽位，均为上游公开契约。

安装

方式一：从 npm 安装（发布后）

npm install -g dsh-plugin-session-outline   # 或装进 profile 的 node_modules

方式二：手动拷贝

构建后把整个插件目录复制到 profile node_modules：

cp -r dsh-plugin-session-outline ~/.dsh/profiles/node_modules/

然后在 cordis.patch.yml 追加：

- insert:
    - id: session-outline
      name: dsh-plugin-session-outline

重启 DSH，打开一个会话，右侧中部出现 ☰ 按钮即加载成功。

开发与构建

client half 必须打包成 window.__ModuleLoader__.load({ id, factory }) 形式才能被 web 前端加载（dsh-client-modules 的 Node half 会扫描 loader 树里 enabled 插件， resolve exports["./client"] 并 serve 进 /plugins boot graph）。

npm install            # 仅需 devDependency: esbuild
npm run bundle         # scripts/bundle.mjs：esbuild 打包 → lib/client.js
npm test               # node --test：bundle 契约测试 + internals 单元测试（时间戳清洗/等价判定/导航推导）
npm run preflight       # 发布/部署预检（陈旧 bundle 守卫 + 契约检查）
npm run check          # node --check lib/client.js 语法校验
# npm publish 时 prepublishOnly 会自动执行 preflight

测试通过 internals 导出（官方惯例，见 dsh-web-app）覆盖纯函数；lib/client.js 的 apply/inject 契约在 vm 沙箱中黑盒验证。

本地验证（改完即见）

构建后用原子同步脚本把产物部署到运行中的 DSH profile（先写临时文件再 逐个 rename 替换，bundle 最后落盘，避免服务器在半更新状态被请求）：

npm run bundle && npm run sync        # 默认 ~/.dsh/profiles/node_modules/<name>
# 可选：DSH_WEB_URL=http://127.0.0.1:PORT npm run sync   # 顺带打印新旧 boot rev

刷新浏览器后 boot manifest 的 rev 变化即说明新 bundle 已被 serve。

发布

当前状态：测试期私密发布。 package.json 标记了 "private": true， 不会（也不应）发布到公共 npm。测试期请用本地路径或 git 依赖安装：

dsh plugin --profile web add file:<本仓库路径>          # 本地路径安装
# 或作为 git 依赖（私有仓库需 npm 凭证）：
npm install git+https://<私有仓库地址>.git

插件转入稳定后：移除 "private": true，再执行 npm publish （prepublishOnly 会自动跑 preflight + 全量测试，未通过会中止）。

发布内容由 files 字段控制：index.js、lib/client.js、README.md、LICENSE （源码与构建脚本不随包发布）。

文件

index.js                 host half（最小，仅让 loader entry 可被发现）
src/client.jsx           client 源码（React 组件 + shell.overlay 注册）
lib/client.js            client bundle（构建产物，勿手改）
scripts/bundle.mjs       本地构建脚本（esbuild）
test/                    bundle 契约测试（node --test）
LICENSE                  MIT