会话快切 Yporcupine/dsh-session-switcher

Session Switcher

英文概览见下 · 完整详细文档为简体中文，见 中文说明

Session Switcher（dsh-session-switcher）是 DSH Desktop 的插件，为最近查看的会话带来「按住切换」导航。按住 Ctrl 再点按 Tab，会打开一个浮动的最近会话列表，并高亮下一个目标；再点按 Tab 向下移动，然后松开修饰键即可打开高亮的会话（Ctrl+Shift+Tab 反向移动，Esc 取消）。按住修饰键期间高亮会持续移动，所以你可以在松手确认前跳过若干会话。它专为 DSH Desktop 打造：在浏览器标签页里 Ctrl+Tab 归浏览器所有，插件不会在那里触发。

| 按键 | 操作 |
| 按住 Ctrl，点按 Tab | 打开列表并高亮下一个最近查看的会话；再点按向下移动 |
| Ctrl + Shift + Tab | 反向移动高亮 |
| 松开修饰键 | 打开高亮的会话并关闭列表 |
| Esc | 取消，不切换 |
| Enter / 点击某一行 | 立即打开该会话 |
| ↑ / ↓ | 列表打开时移动高亮 |
| 点击外部 / 窗口失焦 | 取消 |

安装 / Installation

从插件管理器安装（推荐）/ Install from the plugin manager

插件是普通的 DSH bundle，DSH 自带的插件管理器就能安装并启用它：

1. 在 DSH 中打开 Plugins 页面（侧边栏里的插件管理器页面；中文界面为「插件」）。
2. 选择 Add plugin → Install a third-party plugin（「添加插件」→「安装第三方插件」）。
3. 输入仓库地址，然后选择 Install：

https://github.com/Yporcupine/dsh-session-switcher

4. 如果 DSH 要求重启，就重启 DSH Desktop。安装器会把依赖加到你的配置档并为你启用 bundle，无需手动配置。

之后要禁用或卸载插件，用同一个 Plugins 页面即可。

命令行安装 / Install with the CLI

用 dsh 命令行也能完成同样的安装：

dsh plugin add https://github.com/Yporcupine/dsh-session-switcher

用 --profile <name> 指定某个配置档（例如 dsh plugin --profile desktop add ...）。命令行之后可能提示你重启 DSH。你也可以安装发布版 tarball —— 把 Releases 页面 里 dsh-session-switcher-1.3.0.tgz 资源的下载链接粘贴到同一个对话框或命令中。

本地开发安装 / Local checkout (development)

想改插件代码，就把本地检出作为链接 bundle 运行。优先用 DSH 自带的安装器 —— 它会写入 link: 依赖并运行配置档的包安装，从而把检出链接进配置档；只手动改 manifest 会跳过这一步，启动时 bundle 会被跳过。

1. 把仓库克隆到你的 DSH bundles 目录（~/.dsh/bundles/；Windows：%USERPROFILE%\.dsh\bundles\）：

macOS / Linuxbash
git clone https://github.com/Yporcupine/dsh-session-switcher.git ~/.dsh/bundles/session-switcher

powershell

Windows (PowerShell)

git clone https://github.com/Yporcupine/dsh-session-switcher.git "$env:USERPROFILE\.dsh\bundles\session-switcher"

2. 走同一套添加插件流程安装这份检出，把目标指向本地目录：Plugins 页面 → Add plugin → Install a third-party plugin → 填入检出的绝对路径（/home/<you>/.dsh/bundles/session-switcher、/Users/<you>/.dsh/bundles/session-switcher 或 C:/Users/<you>/.dsh/bundles/session-switcher）。也可以用命令行：

bash
dsh plugin --profile desktop add /home/<you>/.dsh/bundles/session-switcher

DSH 会记录一条 link: 依赖，把它装进配置档，并启用该 bundle。

3. 重启 DSH Desktop。之后每次改动检出，都要重启 DSH Desktop（或在 Plugins 页面先禁用再启用该 bundle），才能重新挂载客户端模块。

手动回退：手改配置档清单

只在安装器用不了的时候这么做。编辑 DSH Desktop 的配置档清单 ~/.dsh/profiles/desktop/package.json（Windows：%USERPROFILE%\.dsh\profiles\desktop\package.json），加上依赖和 bundle 选择： json {
"dependencies": {
"dsh-session-switcher": "link:/home/<you>/.dsh/bundles/session-switcher"
},
"dsh": {
"profile": {
"bundles": ["...", "dsh-session-switcher"]
}
}
}

路径用你克隆位置的绝对路径：Linux 上是 /home/<you>/...，macOS 上是 /Users/<you>/...，Windows 上是 C:/Users/<you>/...（JSON 路径在所有系统上都用正斜杠）；从配置档目录出发，相对写法 link:../../bundles/session-switcher 指向同一位置。然后重新链接并重装配置档——少了这一步，链接的包永远进不了 node_modules，bundle 会被跳过： bash
dsh plugin --profile desktop install

之后重启 DSH Desktop。

浏览器 / Browser： 快捷键只针对 DSH Desktop。浏览器标签页里 Ctrl+Tab 归浏览器所有，插件不会触发。

中文说明

DSH Desktop 插件：按住 Ctrl 敲 Tab，弹出「最近会话」浮动小窗，高亮待切换的会话；松开修饰键即打开高亮会话并收起小窗。

| 操作 | 效果 |
| Ctrl+Tab（按住 Ctrl 连按 Tab） | 打开浮动窗，高亮「下一个最近查看的会话」；继续按 Tab 依次下移 |
| Ctrl+Shift+Tab | 反向移动高亮 |
| 松开修饰键 | 打开高亮会话，关闭小窗 |
| Esc | 取消，不切换 |
| Enter / 鼠标点击某一行 | 立即打开该会话 |
| ↑ / ↓ | 移动高亮（小窗打开时） |
| 点击小窗外 / 窗口失焦 | 取消 |

- 插件按 DSH Desktop 设计：浏览器里 Ctrl+Tab 归浏览器所有，插件不会被触发。
- macOS 同样使用 Ctrl+Tab / Ctrl+Shift+Tab（Cmd+Tab 是系统应用切换，应用收不到）。

实现要点：为什么用 fixed 输入而不是可编辑快捷键

DSH Desktop 的原生键盘桥会先于页面拦截「可编辑快捷键」的按键组合，然后 Electron 会吞掉随后的修饰键 keyup（DSH 官方 shortcuts 文档的 “Understand the implementation” 一节也说明：Electron 在原生拦截之后可能省略 keyup）。一旦 Ctrl 的 keyup 到不了页面，浮动窗就无法知道「Ctrl 已松开」，只能等下一次按键——这正是早期版本「松开 Ctrl 无反应、要再按一次 Ctrl 才切换」的根因（已用合成按键 + UI Automation 实测复现：Ctrl+Tab、Ctrl+B 等任何可编辑快捷键之后都收不到 keyup）。
因此 Ctrl+Tab / Ctrl+Shift+Tab 注册为 fixed 输入动作（ctx.shortcuts.registerFixed
+ ctx.shortcuts.observeFixedInput）：fixed 动作不走原生桥拦截，留在正常的 DOM 输入路径，修饰键 keyup 可以正常收到，于是「松手提交」可靠。代价是这两行在 Settings → Keyboard shortcuts（Mod+/）里显示为只读条目（Application 分组，键帽 Ctrl + Tab / Ctrl + Shift + Tab），不能改键；不想要时停用/卸载插件即可。

为什么点击行曾「只关窗、不切换」（已修复）

DSH 的 shortcuts 服务在每个 pointerdown 上都会给 fixed 输入观察者发一次 { type: "reset" }（用于中断多键序列）。早期版本把 reset 一律当作取消：鼠标按下瞬间小窗就被卸载，行的 React click 永远来不及触发——于是「点一下小窗消失，但会话没切换」。
现在的做法是：在 window 捕获阶段（早于 shortcuts 服务的 document 捕获 reset）先判断这次按下是否落在小窗内；落在窗内的按下不算取消，只吞掉紧接着的 reset，让行正常收到 click 并切换；点到窗外仍然立即取消。松开指针（pointerup/pointercancel）后恢复常规 reset 行为。

参考实现

当前 ChatGPT / Codex 桌面端（2026，版本 26）把 Ctrl+Tab 定义为 “Next recently viewed chat”， Ctrl+Shift+Tab 为 “Previous recently viewed chat”（另有 Ctrl+PageDown/PageUp、 Ctrl+Shift+]/ 等别名）；Codex 应用更新日志也提到加入了「跳转到最近线程的键盘快捷键」。
本插件按这个语义实现：

- 列表 = 最近查看顺序（MRU）：当前会话 → 查看历史（最近查看的在前）→ 其余会话按侧边栏最近更新排序；每次查看会话都会更新查看历史；
- 按住修饰键时只移动高亮，松开才切换（VS Code / Alt-Tab 式 hold-modifier switcher）；
- 列表跳过已归档会话和子代理（subagent）会话；当前未开始的新会话排在最前。

参考链接：

- <https://defkey.com/chatgpt-windows-app-2026-shortcuts>（ChatGPT Windows App 26.x 快捷键表）
- <https://learn.chatgpt.com/docs/changelog?type=codex-app>（Codex app 更新日志）

样式

面板沿用 DSH 菜单样式：--dsw-specific-menu 表面、--dsw-elevation-prominent 阴影、 --dsw-radius-xl 圆角、--dsw-alias-state-business-primary 选中强调色，跟随明暗主题；行内显示会话标题、所属工作区与相对时间，当前会话带「当前」标记。

某一行的会话正在运行（active turn）时，行右侧显示一个 14px 的旋转圆圈，复用 DSH 侧边栏 StateDot 的 ongoing 外观：1.5s 线性旋转 + 1.5s 虚线弧动画，描边继承 --dsw-alias-label-tertiary；prefers-reduced-motion 下两段动画停止、弧固定。运行状态来自 frame 槽作用域提供的 useSessionStatus 钩子（实时订阅），取不到时回退到会话列表快照里的 running 提示；它会和「当前」标记并排显示，但始终位于最右侧。

文件

| 文件 | 作用 |
| package.json | 包清单：dsh.bundle.patch 声明 bundle 补丁，dsh.client 声明浏览器半体 |
| cordis.patch.yml | 向 profile 配置树插入 Host 行 session-switcher |
| index.js | Host 半体（无需挂载任何服务，空 apply） |
| client.js | 浏览器半体：fixed 输入动作 + shell.overlay 浮动窗 + 页面级 keyup/keydown 负责「松手提交 / Esc 取消」，并订阅会话列表维护最近查看顺序；window 捕获阶段区分「点中面板」与「点外取消」；运行中的会话行右侧渲染 useSessionStatus 旋转圆圈；内置中英文运行时文案 |
| locale/*.json | 插件市场/设置页里的标题与描述（中英文） |
| icon.svg | 插件图标 |
| verify-client.cjs | 本地校验脚本（不参与运行时）：用桩 React/DOM/服务执行真实 client.js，验证 fixed 注册、最近查看排序、浮动窗状态机、松手提交、修饰键顺序、Esc/Enter/方向键、点击（含 shortcuts 服务 pointerdown reset 之后仍能点击）、运行中转圈及其回退、reset/失焦取消、过滤与样式令牌 |
| LICENSE | MIT 许可证（Copyright (c) 2026 Yporcupine） |
| .gitignore / .gitattributes | 仓库辅助文件：忽略依赖、日志与系统文件，统一文本换行为 LF |

运行校验（需要 Node.js；脚本只读取 client.js，不会创建任何文件）： bash
node verify-client.cjs

License

MIT — see [LICENSE. Copyright (c) 2026 Yporcupine.