前言¶

在 DSH desktop 里长时间并行多个工作区与会话时，左侧会话区的层级、顺序和状态往往决定切换成本。官方 sidebar.workspaces 提供基础能力，但若你更习惯 Codex 式分区（置顶 / 项目分组、三级缩进、表头定格）并在不改动 Harness 源码的前提下替换整块左侧会话 UI，就需要一个只占位、不接管数据真相源的客户端插件。dsh-session-manager（npm 包名 @pianner/dsh-session-manager）由维护者 NianjunZou 发布，在官方 slot 上渲染可逆 overlay，会话与顺序仍由 DSH 宿主服务读写。

这是什么¶

dsh-session-manager 是面向 DSH desktop web client 的本地插件：在 sidebar.workspaces 单占位 cell 上渲染 Codex 风格的左侧会话管理界面，包含置顶区、按工作区分组的项目会话、状态点与多种排序/筛选视图。它不修改 DSH/Harness 源码，不成为会话数据的第二真相源；禁用或卸载后 slot 注册随插件生命周期消失，官方会话区自动恢复。仓库与说明见 GitHub，社区目录页见 SkillHub。当前 npm 版本为 0.1.7，许可证 MIT。

核心功能¶

下面介绍 README 与插件契约中已明确的能力；未列出的能力不要假设已实现。

布局与分区¶

结构为一级标题「工作区」→「置顶会话」标题带（顺序来自宿主 pinnedSessionIds，与工作区分组去重）→「项目会话」标题带 → 各工作区分组（文件夹图标 + 展开/折叠）。置顶会话与项目会话各自可折叠；滚动时表头钉在顶部，进入某个工作区分组时由该分组表头接管。工作区为缩进一级的目录行，会话再缩进一级；直接挂在分区标题下的行（置顶区、搜索结果）用浅缩进，对齐 Codex 会话列表习惯。

顺序与置顶¶

• 会话顺序：拖动行（指针手势，非 HTML5 拖放）、Alt+↑/↓、或行菜单「上移 / 下移」，统一调用宿主 workspaces.insertSessionBefore，顺序写入宿主耐久存储。
• 置顶区重排：置顶顺序由宿主 pin 集合决定；插件在拖动时按最小后缀改写 pin 顺序，拖动过程中直接显示目标顺序。
• 工作区排序：拖标题，调用 workspaces.insertBefore，与官方目录行行为一致。

状态与优先级¶

每行一个状态点，使用官方 StateDot 词表（等待 / 执行中 / 已完成未读 / 空闲）；子会话、后台任务等信息并入主点悬停说明与读屏文案，不额外画标记。0.1.7 起不显示失败态：客户端 SessionStatus 无失败位，早期代理在实测中会误报，详见仓库「状态取舍」说明。

优先级 P1–P4 以行尾数字胶囊展示，经官方 dsh-client-store 持久化（键 dsh-session-manager.priority）。头部 P 徽标可进入优先级视图，勾选后批量改/清优先级（一次存储写入）。

搜索、分页与视图¶

• 会话搜索：标题 / 工作区名本地匹配 + 宿主消息索引（sessions.search），结果按最近活跃排序并显示匹配片段。
• 分页：每区块默认 5 行，超出可「展开其余 N 个会话 / 收起」；前 50 行内带运行中、等待或未读状态的会话会自动抬升，不被折叠隐藏。
• 视图选项：手动顺序 / 最近活跃；隐藏 / 显示 / 只看归档。

行操作与图标¶

行菜单与官方能力对齐的方向包括：置顶 / 取消置顶、重命名、分叉、归档 / 取消归档、上移 / 下移、复制 Session ID、复制工作目录。图标均来自 dsh-client-ui-primitives，不用文字符号顶替。

安装与启用¶

前置条件（资料原文）：macOS 上的 DSH desktop；开发与测试对齐目标版本 dsh-v0.2.1-alpha.5（client-ui-slots 等契约）。其它 DSH 版本可能需适配。

1、从 npm 安装插件（将 <profile> 换成你的 profile 名）：

dsh plugin --profile <profile> add @pianner/dsh-session-manager

2、在 dsh.profile.bundles 中加入 @pianner/dsh-session-manager。

3、重启 DSH。完整部署、卸载与回滚见仓库 docs/DEPLOY.md。

安装前建议自行查看插件源码与 MIT 许可证；插件在 当前 DSH 进程权限 下运行，与任何 DSH 插件一样，只安装你信任的来源。

典型用法¶

日常操作大多在左侧 overlay 内完成，无需额外 CLI。

调整会话顺序：在目标行前按住拖动，或使用 Alt+↑/↓、行菜单「上移 / 下移」。

整理置顶：在「置顶会话」区内拖动重排；与工作区内的会话通过置顶 / 取消置顶菜单项切换。

按优先级批量处理：点击头部 P 徽标进入优先级视图，勾选会话后一次修改或清除 P1–P4。

查找会话：使用搜索框；本地匹配标题与工作区名，并调用宿主 sessions.search 检索消息内容。

切换列表视图：在视图选项中选择手动顺序或最近活跃，以及是否显示归档会话。

更细的操作说明见仓库 docs/USAGE.md。

适用场景与注意¶

适合谁：已在 macOS 上使用 DSH desktop、希望左侧会话区接近 Codex 分区与交互、且接受「整块替换官方 sidebar.workspaces 渲染」的开发者。

与官方 UI 的取舍（启用插件期间）：sidebar.workspaces 为排他占位，官方 WorkspaceBrowser 不再渲染；官方 5 个子槽（如第三方注册的会话菜单项、行内按钮、ui-schedule 定时任务标记等）在占位期间不会出现——插件自实现了等价菜单，但 暂无 定时任务标记的等价实现。停用或卸载后这些贡献立即恢复。

明确未提供或受宿主 API 限制：永久删除会话、跨工作区移动、原生「未读」状态的持久化写入等，在目标 DSH 版本缺少可调用的公开写接口，插件暂未提供。

开发与验证（维护者或二次开发者）：仓库内 npm run verify 含 build、测试与插件契约检查；对齐宿主源码时需 DSH_SOURCE=~/deepseek-harness npm run verify:align（无源码时该 lane 自跳过）。

结尾¶

dsh-session-manager 把 Codex 式左侧会话列表做成可逆的 DSH 客户端插件：数据与顺序仍归宿主，UI 与手势在 slot 内完成投影。若你要核对分类与简介，可看社区目录 dsh-session-manager；源码、契约与 0.1.7 验收记录见 GitHub 仓库。