前言¶

在 DSH Web 里用多个 workspace 跑智能体时，侧栏 Session 列表会随 workspace 分组变长。正在运行的任务、已完成但你还没打开的 Session、以及当前主视图里还开着的 Session，混在各自分组里时，很容易漏看或找错行。

社区插件 dsh-pinned-sessions（维护者 TianYa-DAO）在侧栏 workspace 列表顶部增加 Pinned 区域，按状态自动汇总这些 Session，并支持从 Session 或 workspace 的「…」菜单全局固定。下面介绍它的能力、安装方式与使用注意。

这是什么¶

dsh-pinned-sessions 是 客户端 类 DSH 插件（当前版本 0.2.1，MIT 许可证）。它不改服务端逻辑，只在 Web 客户端侧栏的 workspace 列表上方插入一块固定区域，把「不能丢视线」的 Session 和可选的全局固定 workspace 集中展示。

目录页：SkillHub - dsh-pinned-sessions
源码与说明：GitHub - TianYa-DAO/dsh-pinned-sessions

侧栏里会出现什么¶

仅在侧栏按 workspace 分组时显示（By workspace、Workspace tree）；切换到 In one list、侧栏收起到 rail、或正在显示搜索结果时，整块 Pinned 会隐藏，且不会把下方列表里的 Session 藏起来。

区域结构（自上而下，空块会省略；全部为空时不渲染）大致如下：

sidebar
├─ Workspaces            ← 原有区域头（搜索 / 视图 / 添加 workspace）
├─ Pinned                ← 本插件插入
│   ├─ Pinned N          ← 从 Session「…」菜单全局固定的 Session
│   ├─ Running N         ← 状态推导：running === true（蓝色脉冲点）
│   ├─ Unread N          ← completionUnread === true（绿点）
│   ├─ Open now N        ← retainedBy.mainView > 0（空心环）
│   └─ Pinned workspaces ← 从 workspace「…」菜单固定的 workspace
├─ Workspace group A
└─ Workspace group B

要点：

1. 全局固定的 Session 仍保留在下方对应 workspace 分组里；Pinned 区展开时，它们不会重复出现在 Running / Unread / Open now 里，行上的状态点与真实状态一致。折叠 Pinned 子块后，这些 Session 会重新按状态出现在对应分组中，避免折叠后看不见仍在跑或未读的 Session。
2. Running / Unread / Open now 互斥，优先级为 Running → Unread → Open now；每个 Session 只进其中一组。
3. 全局固定的 workspace 在 Pinned 里以可折叠分组展示，可直接展开打开 Session；固定期间，下方列表里该 workspace 的原分组会被隐藏。
4. 已归档 Session、subagent 子 Session 不会出现；行按最近更新时间排序；点击行会打开该 Session。

固定与取消固定¶

1. Session：在 Session 的「…」菜单中使用 Pin globally / Unpin globally（占用官方槽位 sidebar.workspaces.session.menu.item，与 rename、fork、archive 等并列）。
2. Workspace：workspace 的「…」菜单提供同样操作；DSH 未声明该菜单槽位，插件通过 portal 注入到已打开的 popup，并根据 data-row-key="workspace:<key>" 定位行。
3. Pinned 区里的 Session 行与 workspace 头在 hover 时显示取消固定控件（workspace 固定后原行被隐藏，这一点尤其需要）。

设置与持久化¶

在 Settings → General → Pinned sessions 可开关整块区域。开关、已固定的 Session / workspace、以及哪些固定的 workspace 处于折叠状态，保存在客户端 shared store，localStorage 键为 dsh.pinned-sessions.prefs.v1。

安装与启用¶

宿主要求（package 声明）：DSH >=0.2.0-rc.2 <0.3.0。README 注明在 0.2.1-rc.1 上做过测试。

从 npm 安装：

dsh plugin add dsh-pinned-sessions

从 release 包安装：

dsh plugin add https://github.com/TianYa-DAO/dsh-pinned-sessions/releases/latest/download/dsh-pinned-sessions-0.2.1.tgz

桌面版可在 Plugins 页面安装。包声明 dsh.bundle，会挂载 cordis.patch.yml，客户端通过 registry 加载 ./client.js。

安装后，在 General 里打开 Pinned sessions，侧栏保持 workspace 分组视图即可看到 Pinned 区域。

典型用法¶

1. 长时间跑任务时，依赖 Running 分组和蓝色脉冲点，在列表顶部看到仍在执行的 Session。
2. 任务在后台完成、你尚未打开时，Unread 分组用绿点标出 completionUnread 的 Session。
3. 主视图仍保留的 Session 出现在 Open now（空心环）。
4. 需要长期盯住的 Session 或整个 workspace：打开该行「…」→ Pin globally；不需要时用 Unpin globally 或 Pinned 区 hover 取消固定。

实现要点（便于排查）¶

插件仅客户端：client.js 经 window.__ModuleLoader__.load 加载，向 shell.overlay 注册；在 div[data-slot="sidebar.workspaces"] 内、带 list 类的滚动容器顶部插入 host，卸载时移除。数据来自 useSessions、useSessionStatus、useWorkspaces；打开 Session 走 ctx.get("uiWorkspace").openSession(id)。样式使用 dshps-* 与 --dsw-alias-* 主题 token。

维护者提供的自检：

npm test

适用场景与注意¶

适合：经常在 DSH Web 多 workspace 间切换、需要一眼看到运行中、未读完成和当前打开 Session 的开发者；希望把少数 Session 或整个 workspace 钉在侧栏顶部的人。

注意：

1. 插件以当前 DSH 客户端进程权限运行，安装前建议阅读 源码 与 MIT 许可证，确认符合你的安全策略。
2. 布局依赖官方侧栏 DOM 与类名（如 listArea、projectRow、searchResultRow、rail、list）；侧栏大改可能需要插件更新选择器。
3. workspace 菜单项为注入实现，popup 结构变化可能需要改 client.js。
4. 客户端 API 更名可能导致注册或 hook 失效；uiWorkspace 不可用时会 warn，但仍可能需要跟进 DSH 版本升级。

SkillHub 等社区目录独立于 DeepSeek / 幻方，并非官方应用商店；DSH 生态强调「一切皆插件」，本插件是其中一项客户端增强。

结尾¶

dsh-pinned-sessions 在 workspace 分组视图的侧栏顶部汇总 Running、Unread、Open now 与手动固定的 Session / workspace，减少在长列表里漏看关键任务。需要时可从 npm 或 release 包安装，并在 General 中启用 Pinned sessions。

• 目录页：https://www.skillhub.cn/plugins/TianYa-DAO/dsh-pinned-sessions
• GitHub：https://github.com/TianYa-DAO/dsh-pinned-sessions
• 问题反馈：https://github.com/TianYa-DAO/dsh-pinned-sessions/issues