feat(workspace): 模式按钮双击收展侧栏

图标栏的「终端工作区 / SSH 工作区」按钮新增双击手势：双击当前工作区按钮展开/收起侧栏；单击（含双击另一个按钮）只切换工作区，侧栏不动。判定逻辑抽成零 import 纯模块 modeRailGesture.ts，用浏览器原生 MouseEvent.detail 连击计数识别手势——detail=2 到达时 store 已被第一击更新，故在 detail=1 时把「手势前模式」存入 ref 再比对。新增 tests/mode-rail-gesture.mjs 表驱动测试（10 例），测试数 35→36。
2026-10-20 23:59:28 +08:00
6 changed files with 321 additions and 9 deletions
@@ -7,10 +7,10 @@ Electron + electron-vite + React 终端工具（本地终端 / SSH / SFTP）。
 - 开发：`npm run dev`（主进程改动不热重建，需重启）
 - dev 实例使用独立用户数据目录 `%APPDATA%\OpenTerminal-dev` 与独立单实例锁（`src/main/index.ts` 顶部 `!app.isPackaged` 分支），窗口标题带 `(dev)`：**可与已安装的正式版同时运行，互不干扰**，也不会把测试设置/会话写进真实配置
 - 类型检查：`npm run typecheck`（tsconfig.node.json + tsconfig.web.json；只看渲染层可单跑 `npx tsc --noEmit -p tsconfig.web.json`）
- 测试：`npm test`（**npm 生命周期先自动跑 `pretest` 做类型检查**，再 `node tests/build-bundles.cjs` 重建 esbuild bundle，然后依次跑可离线运行的 35 个测试：ssh-loopback、commands-store、connections-store、settings-store、local-path-grants、lock-store、lock-controller、lock-shortcuts、reserved-accelerators、terminal-title、ipc-guard、updater-fallback、log-sanitizer、app-log、sftp-timeout、hl-split-smoke、hl-rules、redos-probes、rule-validation、redos-validator、perf-diagnostics、zmodem-e2e、ssh-session-e2e、sysinfo-e2e、terminal-cwd、terminal-links、broadcast-store、write-batcher、refit-throttle、semantic-theme、theme-contrast、css-theme-vars、ot-var-names、font-stack、link-rules；真实服务器测试需 JD_* 凭据，不在此列）。其中渲染层纯函数测试（semantic-theme、theme-contrast、ot-var-names、font-stack、write-batcher、refit-throttle、perf-diagnostics、redos-probes、rule-validation、broadcast-store、terminal-cwd、terminal-links、terminal-title、hl-split-smoke、hl-rules、link-rules 等）用 Node 22.18+ 的原生 TS 类型剥离**直接 import `.ts` 源文件**（不经 esbuild bundle），Node 20/22.17 以下会 `ERR_UNKNOWN_FILE_EXTENSION`
+- 测试：`npm test`（**npm 生命周期先自动跑 `pretest` 做类型检查**，再 `node tests/build-bundles.cjs` 重建 esbuild bundle，然后依次跑可离线运行的 36 个测试：ssh-loopback、commands-store、connections-store、settings-store、local-path-grants、lock-store、lock-controller、lock-shortcuts、reserved-accelerators、terminal-title、ipc-guard、updater-fallback、log-sanitizer、app-log、sftp-timeout、hl-split-smoke、hl-rules、redos-probes、rule-validation、redos-validator、perf-diagnostics、zmodem-e2e、ssh-session-e2e、sysinfo-e2e、terminal-cwd、terminal-links、broadcast-store、write-batcher、refit-throttle、semantic-theme、theme-contrast、css-theme-vars、ot-var-names、font-stack、link-rules、mode-rail-gesture；真实服务器测试需 JD_* 凭据，不在此列）。其中渲染层纯函数测试（semantic-theme、theme-contrast、ot-var-names、font-stack、write-batcher、refit-throttle、perf-diagnostics、redos-probes、rule-validation、broadcast-store、terminal-cwd、terminal-links、terminal-title、hl-split-smoke、hl-rules、link-rules、mode-rail-gesture 等）用 Node 22.18+ 的原生 TS 类型剥离**直接 import `.ts` 源文件**（不经 esbuild bundle），Node 20/22.17 以下会 `ERR_UNKNOWN_FILE_EXTENSION`
 - 依赖分类规则：**只有 `src/main/`/`src/preload/` 实际 import 的包才能进 `dependencies`**（node-pty/ssh2/zmodem.js/font-list/electron-updater）；纯渲染层依赖一律 devDependencies（Vite 全量打包进 out/renderer，`externalizeDepsPlugin` 不作用渲染层）——这条让 asar 从 98MB 瘦到 8.1MB，加新依赖时别放错边
 - 下载量统计：`node scripts/download-stats.cjs`（Gitea + GitHub release 资产的 download_count 汇总；GitHub 优先直连、失败自动回退 `HTTPS_PROXY`/本地 7897；更新通道无计数接口不计入）
- 打包：`npm run dist`（**生命周期先自动跑 `predist` → `npm test`，即类型检查 + 35 个离线测试全部通过后才 build/package**，typecheck 全程只跑一次；`electron-vite build` 之后、electron-builder 之前会跑 `node tests/worker-artifact.mjs`——真实加载 `out/main/redosProbeWorker-*.js` 并回包，防止 `?nodeWorker` 产物静默丢失；predist 末尾的 `npm install --package-lock-only` 会把 `package-lock.json` 根版本号对齐 `package.json`，**发布提交必须带上 package-lock.json**），产物在 `release/`（exe + latest.yml + blockmap）
+- 打包：`npm run dist`（**生命周期先自动跑 `predist` → `npm test`，即类型检查 + 36 个离线测试全部通过后才 build/package**，typecheck 全程只跑一次；`electron-vite build` 之后、electron-builder 之前会跑 `node tests/worker-artifact.mjs`——真实加载 `out/main/redosProbeWorker-*.js` 并回包，防止 `?nodeWorker` 产物静默丢失；predist 末尾的 `npm install --package-lock-only` 会把 `package-lock.json` 根版本号对齐 `package.json`，**发布提交必须带上 package-lock.json**），产物在 `release/`（exe + latest.yml + blockmap）
  - GitHub Actions：`.github/workflows/ci.yml` 在 windows-latest + Node 22 上跑 `npm ci` / `npm test`（含 pretest typecheck）/ `npm run build`，只做验证，不打包安装器、不发布
  - 国内网络需镜像：`ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ npm run dist`
 - 依赖一致性闸门：`predist` 开头跑 `node scripts/verify-deps.cjs`（逐条比对 `node_modules` 与 `package-lock.json` 的版本，跨平台 optional 依赖缺失跳过；不一致就 exit 1）——`npm install --package-lock-only` **只重算 lockfile、不碰 node_modules**（本版 npm 还会把 `node_modules/.package-lock.json` 一并重写成理想树，制造「已经装好了」的假象），所以**改动依赖版本后必须真实 `npm install` 或 `npm ci` 再构建**，别指望 lockfile 对齐就等于树里换了包；v1.0.21 的中文输入法回归正是这个坑（`@xterm/xterm` 锁 6.1.0-beta.304，树里还是 6.0.0，打进去的是旧代码）
@@ -0,0 +1,237 @@
+# 侧栏模式按钮双击收展侧栏 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 图标栏的「终端工作区 / SSH 工作区」模式按钮新增双击手势：双击当前工作区按钮 = 展开/收起侧栏；单击（含双击另一个按钮）只切换工作区。
+
+**Architecture:** 不挂 `onDoubleClick`，直接在按钮 `onClick` 里用浏览器原生 `MouseEvent.detail` 连击计数判定手势。关键约束：双击时序是 `click(detail=1) → click(detail=2) → dblclick`，detail=2 到达时 zustand store 已被第一击更新，因此「手势前模式」必须在 detail===1 时存进 ref。判定逻辑抽成零 import 纯模块（仓库惯例，Node 原生类型剥离直连测试）。
+
+**Tech Stack:** React 19.2.8 / zustand 5.0.15 / TypeScript strict / Node ≥22.18 原生 TS 剥离测试。
+
+**已核实前提**（子代理两轮核实，全部属实）：
+- `ModeRailButtons`（Workspace.tsx:1545）与 `IconRail`（:1506）全链路无条件渲染、无 key、无 StrictMode —— ref 生命周期 = 应用生命周期
+- antd Tooltip（6.6.2）只代理 8 种事件，不含 click 之外的干扰；`e.detail` 在合成事件上可靠
+- zustand v5 选择器走 `Object.is`，同值 set 不重渲染（双击当前按钮的第二击零副作用）
+- `toggleSidebar`（Workspace.tsx:341，useCallback 稳定引用）已作为 `onToggleSidebar` 传入 `IconRail`（:1274），透传即可，Workspace 自身 props 接线不动
+- `WorkspaceMode` 类型已在 Workspace.tsx:42 导入；`useRef` 已在用
+- 渲染层无全局 click 监听、无既有 `e.detail` 消费者，无双击手势冲突
+
+## Global Constraints
+
+- **不执行任何 git commit / push** —— 改动留在工作区由用户审查（仓库 owner 惯例）
+- 新纯模块 `modeRailGesture.ts` **零 import**（Node 原生类型剥离直连的硬约束，同 semantic.ts / workspaceMode.ts）
+- 不改 CSS、不改 i18n 词典、不动现有收展按钮（rail 顶部 MenuFold/MenuUnfold）
+- 行为语义锁定：detail 0/1 → 切换；detail 2 且手势前模式=本按钮 → 翻侧栏；detail 2 其余 → 无操作
+- 测试脚手架照 `tests/semantic-theme.mjs`：`ok(cond, msg)` 计数器 + 末尾 `process.exit(failed ? 1 : 0)`
+
+---
+
+### Task 1: 纯手势判定模块 + 表驱动测试（TDD）
+
+**Files:**
+- Test: `tests/mode-rail-gesture.mjs`（新建）
+- Create: `src/renderer/src/workspace/modeRailGesture.ts`（新建）
+- Modify: `package.json:16`（test 链尾追加）
+- Modify: `AGENTS.md`（测试计数 35→36 + 两处清单）
+
+**Interfaces:**
+- Produces: `decideModeClick(detail: number, preGestureMode: RailMode | null, buttonMode: RailMode): ModeClickAction`，`RailMode = 'terminal' | 'ssh'`，`ModeClickAction = 'switch' | 'toggle-sidebar' | 'noop'` —— Task 2 的 `ModeRailButtons` 消费此签名。
+
+- [ ] **Step 1: 先写测试 `tests/mode-rail-gesture.mjs`**
+
+```js
+/**
+ * modeRailGesture.ts self-test。零 import 纯模块，Node 原生类型剥离直连 .ts。
+ * 锁定双击手势语义：
+ *  1) 单击 / 键盘触发（detail 1 / 0）一律 switch；
+ *  2) detail 2 只有「手势前模式 === 本按钮模式」才 toggle-sidebar（双击当前工作区按钮）；
+ *  3) detail 2 其余情况 noop（双击另一个按钮时第一击已完成切换，侧栏不动）。
+ * Run: node tests/mode-rail-gesture.mjs  (must exit 0)
+ */
+import { decideModeClick } from '../src/renderer/src/workspace/modeRailGesture.ts'
+
+let failed = 0
+const ok = (cond, msg) => {
+  console.log(`  ${cond ? 'ok' : 'FAIL'}: ${msg}`)
+  if (!cond) failed += 1
+}
+
+console.log('single click / keyboard always switch:')
+ok(decideModeClick(1, null, 'terminal') === 'switch', 'detail=1 preMode=null → switch')
+ok(decideModeClick(1, 'terminal', 'terminal') === 'switch', 'detail=1 same mode → switch')
+ok(decideModeClick(1, 'terminal', 'ssh') === 'switch', 'detail=1 other mode → switch')
+ok(decideModeClick(0, 'terminal', 'ssh') === 'switch', 'detail=0 keyboard → switch')
+
+console.log('double click toggles sidebar only on the already-active button:')
+ok(decideModeClick(2, 'terminal', 'terminal') === 'toggle-sidebar', 'detail=2 active terminal → toggle-sidebar')
+ok(decideModeClick(2, 'ssh', 'ssh') === 'toggle-sidebar', 'detail=2 active ssh → toggle-sidebar')
+ok(decideModeClick(2, 'terminal', 'ssh') === 'noop', 'detail=2 inactive ssh → noop（第一击已切换）')
+ok(decideModeClick(2, 'ssh', 'terminal') === 'noop', 'detail=2 inactive terminal → noop')
+ok(decideModeClick(2, null, 'terminal') === 'noop', 'detail=2 preMode=null → noop（防御）')
+
+console.log('click streaks beyond 2 fall back to switch semantics:')
+ok(decideModeClick(3, 'terminal', 'terminal') === 'switch', 'detail=3 → switch（不产生第二次翻转）')
+
+if (failed > 0) {
+  console.error(`${failed} check(s) failed`)
+  process.exit(1)
+}
+console.log('mode-rail-gesture: all ok')
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `node tests/mode-rail-gesture.mjs`
+Expected: FAIL —— `ERR_MODULE_NOT_FOUND`（模块尚不存在）
+
+- [ ] **Step 3: 实现 `src/renderer/src/workspace/modeRailGesture.ts`**
+
+```ts
+/**
+ * 图标栏模式按钮（终端工作区 / SSH 工作区）的单击·双击手势判定。
+ * 零 import 纯模块 —— tests/mode-rail-gesture.mjs 经 Node 原生类型剥离直连本文件。
+ *
+ * 浏览器双击时序是 click(detail=1) → click(detail=2) → dblclick，且 detail=2 到达时
+ * store 里的模式已被第一击更新，所以调用方必须在 detail===1 时把「手势前模式」存进 ref、
+ * detail===2 时传入本函数比对 —— 绝不能在第二击时读当前 store 值。
+ */
+export type RailMode = 'terminal' | 'ssh'
+
+export type ModeClickAction = 'switch' | 'toggle-sidebar' | 'noop'
+
+/**
+ * 判定一次 click 属于哪种动作：
+ * - detail 1（单击或双击的第一击）→ 'switch'：记录手势前模式并切换工作区
+ * - detail 2 且手势前模式 === 本按钮模式 → 'toggle-sidebar'：双击的是当前工作区按钮
+ * - detail 2 且不等 → 'noop'：第一击已完成切换，侧栏不动
+ * - detail 0（键盘 Enter/Space 触发）→ 'switch'：无障碍路径保持单击语义
+ */
+export function decideModeClick(detail: number, preGestureMode: RailMode | null, buttonMode: RailMode): ModeClickAction {
+  if (detail === 2) return preGestureMode === buttonMode ? 'toggle-sidebar' : 'noop'
+  return 'switch'
+}
+```
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `node tests/mode-rail-gesture.mjs`
+Expected: PASS —— 10 行 `ok`，末尾 `mode-rail-gesture: all ok`，exit 0
+
+- [ ] **Step 5: 登记测试到 package.json**
+
+`package.json:16` 的 `"test"` 链尾，在 `node tests/link-rules.mjs` 之后追加：
+
+```
+ && node tests/mode-rail-gesture.mjs
+```
+
+（新测试是零 import 直连型，不依赖 bundle，位置在链尾即可。）
+
+- [ ] **Step 6: 同步 AGENTS.md 测试清单（项目规则：改 AGENTS.md 所载内容须同步）**
+
+两处编辑：
+1. 「测试」条目里 `可离线运行的 35 个测试` → `36 个测试`，枚举末尾 `font-stack、link-rules；` → `font-stack、link-rules、mode-rail-gesture；`
+2. 同条目括号内的渲染层纯函数测试枚举 `…hl-rules、link-rules 等）` → `…hl-rules、link-rules、mode-rail-gesture 等）`
+
+### Task 2: Workspace.tsx 接线
+
+**Files:**
+- Modify: `src/renderer/src/workspace/Workspace.tsx`（import 一处、ModeRailButtons :1545、IconRail JSX :1532）
+
+**Interfaces:**
+- Consumes: Task 1 的 `decideModeClick` / `ModeClickAction`；既有 `useWorkspaceModeStore`（含 `.getState()`）、`WorkspaceMode` 类型（已在 :42 导入）、`useRef`（已在用）、IconRail 已有的 `onToggleSidebar` prop。
+
+- [ ] **Step 1: 加 import**
+
+在 Workspace.tsx:43 `import { useWorkspaceModeStore } from './workspaceModeStore'` 之后加：
+
+```ts
+import { decideModeClick } from './modeRailGesture'
+```
+
+- [ ] **Step 2: 替换 ModeRailButtons（:1545–1564 整段）**
+
+旧代码（原样，供 Edit 的 old_string）：
+
+```tsx
+/** M6.1: terminal / SSH workspace entries in the icon rail. */
+function ModeRailButtons(): React.JSX.Element {
+  const mode = useWorkspaceModeStore((s) => s.mode)
+  const setMode = useWorkspaceModeStore((s) => s.setMode)
+  return (
+    <>
+      <RailButton
+        title={t('workspace.rail.terminalWorkspace')}
+        icon={<CodeOutlined />}
+        active={mode === 'terminal'}
+        onClick={() => setMode('terminal')}
+      />
+      <RailButton
+        title={t('workspace.rail.sshWorkspace')}
+        icon={<CloudServerOutlined />}
+        active={mode === 'ssh'}
+        onClick={() => setMode('ssh')}
+      />
+    </>
+  )
+}
+```
+
+新代码：
+
+```tsx
+/** M6.1: terminal / SSH workspace entries in the icon rail. 双击当前工作区按钮 = 收展侧栏。 */
+function ModeRailButtons({ onToggleSidebar }: { onToggleSidebar: () => void }): React.JSX.Element {
+  const mode = useWorkspaceModeStore((s) => s.mode)
+  const setMode = useWorkspaceModeStore((s) => s.setMode)
+  /** 手势开始前的模式。detail===2 到达时 store 已被第一击更新，判定「双击的是不是当前工作区」只能用这里存的值。 */
+  const preGestureModeRef = useRef<WorkspaceMode | null>(null)
+
+  const handleModeClick = (buttonMode: WorkspaceMode) => (e: React.MouseEvent<HTMLButtonElement>): void => {
+    const action = decideModeClick(e.detail, preGestureModeRef.current, buttonMode)
+    if (action === 'toggle-sidebar') {
+      onToggleSidebar()
+      return
+    }
+    if (action === 'noop') return
+    preGestureModeRef.current = useWorkspaceModeStore.getState().mode
+    setMode(buttonMode)
+  }
+
+  return (
+    <>
+      <RailButton
+        title={t('workspace.rail.terminalWorkspace')}
+        icon={<CodeOutlined />}
+        active={mode === 'terminal'}
+        onClick={handleModeClick('terminal')}
+      />
+      <RailButton
+        title={t('workspace.rail.sshWorkspace')}
+        icon={<CloudServerOutlined />}
+        active={mode === 'ssh'}
+        onClick={handleModeClick('ssh')}
+      />
+    </>
+  )
+}
+```
+
+- [ ] **Step 3: IconRail 内透传（:1532）**
+
+`<ModeRailButtons />` → `<ModeRailButtons onToggleSidebar={onToggleSidebar} />`
+
+- [ ] **Step 4: 渲染层类型检查**
+
+Run: `npx tsc --noEmit -p tsconfig.web.json`
+Expected: 无输出，exit 0
+
+- [ ] **Step 5: 全量测试**
+
+Run: `npm test`
+Expected: pretest 类型检查 + 36 个离线测试全部通过，exit 0
+
+- [ ] **Step 6: 自审 diff**
+
+Run: `git diff --stat` + `git status`
+Expected: 恰好 3 改 2 新：`Workspace.tsx`、`package.json`、`AGENTS.md` 修改；`modeRailGesture.ts`、`tests/mode-rail-gesture.mjs` 新增（共 5 个路径；本计划文档自身 untracked 属预期，无其它文件）；无 CSS / i18n 词典改动
@@ -13,7 +13,7 @@
    "preview": "electron-vite preview",
    "typecheck": "tsc --noEmit -p tsconfig.node.json && tsc --noEmit -p tsconfig.web.json",
    "pretest": "npm run typecheck",
-    "test": "node tests/build-bundles.cjs && node tests/ssh-loopback.mjs && node tests/commands-store.mjs && node tests/connections-store.mjs && node tests/settings-store.mjs && node tests/local-path-grants.mjs && node tests/lock-store.mjs && node tests/lock-controller.mjs && node tests/lock-shortcuts.mjs && node tests/reserved-accelerators.mjs && node tests/.terminal-title.cjs && node tests/ipc-guard.mjs && node tests/updater-fallback.mjs && node tests/log-sanitizer.mjs && node tests/app-log.mjs && node tests/sftp-timeout.mjs && node tests/.hl-split-smoke.cjs && node tests/.hl-rules.cjs && node tests/redos-probes.mjs && node tests/rule-validation.mjs && node tests/redos-validator.mjs && node tests/perf-diagnostics.mjs && node tests/zmodem-e2e.mjs && node tests/ssh-session-e2e.mjs && node tests/sysinfo-e2e.mjs && node tests/terminal-cwd.mjs && node tests/terminal-links.mjs && node tests/broadcast-store.mjs && node tests/write-batcher.mjs && node tests/refit-throttle.mjs && node tests/semantic-theme.mjs && node tests/theme-contrast.mjs && node tests/css-theme-vars.mjs && node tests/ot-var-names.mjs && node tests/font-stack.mjs && node tests/link-rules.mjs",
+    "test": "node tests/build-bundles.cjs && node tests/ssh-loopback.mjs && node tests/commands-store.mjs && node tests/connections-store.mjs && node tests/settings-store.mjs && node tests/local-path-grants.mjs && node tests/lock-store.mjs && node tests/lock-controller.mjs && node tests/lock-shortcuts.mjs && node tests/reserved-accelerators.mjs && node tests/.terminal-title.cjs && node tests/ipc-guard.mjs && node tests/updater-fallback.mjs && node tests/log-sanitizer.mjs && node tests/app-log.mjs && node tests/sftp-timeout.mjs && node tests/.hl-split-smoke.cjs && node tests/.hl-rules.cjs && node tests/redos-probes.mjs && node tests/rule-validation.mjs && node tests/redos-validator.mjs && node tests/perf-diagnostics.mjs && node tests/zmodem-e2e.mjs && node tests/ssh-session-e2e.mjs && node tests/sysinfo-e2e.mjs && node tests/terminal-cwd.mjs && node tests/terminal-links.mjs && node tests/broadcast-store.mjs && node tests/write-batcher.mjs && node tests/refit-throttle.mjs && node tests/semantic-theme.mjs && node tests/theme-contrast.mjs && node tests/css-theme-vars.mjs && node tests/ot-var-names.mjs && node tests/font-stack.mjs && node tests/link-rules.mjs && node tests/mode-rail-gesture.mjs",
    "predist": "node scripts/verify-deps.cjs && npm test && npm install --package-lock-only",
    "dist": "electron-vite build && node tests/worker-artifact.mjs && electron-builder --win nsis",
    "dist:dir": "electron-vite build && node tests/worker-artifact.mjs && electron-builder --win --dir"
@@ -41,6 +41,7 @@ import { useSettingsStore } from '@renderer/settings/store'
 import type { SessionSnapshot, SessionPanelState } from '@shared/ipc'
 import type { WorkspaceMode } from './workspaceMode'
 import { useWorkspaceModeStore } from './workspaceModeStore'
+import { decideModeClick } from './modeRailGesture'
 import './workspace.css'

 export interface WorkspaceProps {
@@ -1529,7 +1530,7 @@ const IconRail = memo(function IconRail({
      <RailButton title={t('workspace.newTerminal')} icon={<PlusOutlined />} onClick={onNewTerminal} />
      <LayoutFlyout menu={layoutMenu} />
      <div className="workspace-rail-divider" />
-      <ModeRailButtons />
+      <ModeRailButtons onToggleSidebar={onToggleSidebar} />
      <div className="workspace-rail-spacer" />
      {connecting && (
        <Tooltip title={t('workspace.rail.connecting')} placement="right">
@@ -1541,23 +1542,37 @@ const IconRail = memo(function IconRail({
  )
 })

-/** M6.1: terminal / SSH workspace entries in the icon rail. */
-function ModeRailButtons(): React.JSX.Element {
+/** M6.1: terminal / SSH workspace entries in the icon rail. 双击当前工作区按钮 = 收展侧栏。 */
+function ModeRailButtons({ onToggleSidebar }: { onToggleSidebar: () => void }): React.JSX.Element {
  const mode = useWorkspaceModeStore((s) => s.mode)
  const setMode = useWorkspaceModeStore((s) => s.setMode)
+  /** 手势开始前的模式。detail===2 到达时 store 已被第一击更新，判定「双击的是不是当前工作区」只能用这里存的值。 */
+  const preGestureModeRef = useRef<WorkspaceMode | null>(null)
+
+  const handleModeClick = (buttonMode: WorkspaceMode) => (e: React.MouseEvent<HTMLButtonElement>): void => {
+    const action = decideModeClick(e.detail, preGestureModeRef.current, buttonMode)
+    if (action === 'toggle-sidebar') {
+      onToggleSidebar()
+      return
+    }
+    if (action === 'noop') return
+    preGestureModeRef.current = useWorkspaceModeStore.getState().mode
+    setMode(buttonMode)
+  }
+
  return (
    <>
      <RailButton
        title={t('workspace.rail.terminalWorkspace')}
        icon={<CodeOutlined />}
        active={mode === 'terminal'}
-        onClick={() => setMode('terminal')}
+        onClick={handleModeClick('terminal')}
      />
      <RailButton
        title={t('workspace.rail.sshWorkspace')}
        icon={<CloudServerOutlined />}
        active={mode === 'ssh'}
-        onClick={() => setMode('ssh')}
+        onClick={handleModeClick('ssh')}
      />
    </>
  )
@@ -1644,7 +1659,7 @@ function RailButton({
 }: {
  title: string
  icon: ReactNode
-  onClick?: () => void
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void
  active?: boolean
  hideTooltip?: boolean
 }): React.JSX.Element {
@@ -0,0 +1,23 @@
+/**
+ * 图标栏模式按钮（终端工作区 / SSH 工作区）的单击·双击手势判定。
+ * 零 import 纯模块 —— tests/mode-rail-gesture.mjs 经 Node 原生类型剥离直连本文件。
+ *
+ * 浏览器双击时序是 click(detail=1) → click(detail=2) → dblclick，且 detail=2 到达时
+ * store 里的模式已被第一击更新，所以调用方必须在 detail===1 时把「手势前模式」存进 ref、
+ * detail===2 时传入本函数比对 —— 绝不能在第二击时读当前 store 值。
+ */
+export type RailMode = 'terminal' | 'ssh'
+
+export type ModeClickAction = 'switch' | 'toggle-sidebar' | 'noop'
+
+/**
+ * 判定一次 click 属于哪种动作：
+ * - detail 1（单击或双击的第一击）→ 'switch'：记录手势前模式并切换工作区
+ * - detail 2 且手势前模式 === 本按钮模式 → 'toggle-sidebar'：双击的是当前工作区按钮
+ * - detail 2 且不等 → 'noop'：第一击已完成切换，侧栏不动
+ * - detail 0（键盘 Enter/Space 触发）→ 'switch'：无障碍路径保持单击语义
+ */
+export function decideModeClick(detail: number, preGestureMode: RailMode | null, buttonMode: RailMode): ModeClickAction {
+  if (detail === 2) return preGestureMode === buttonMode ? 'toggle-sidebar' : 'noop'
+  return 'switch'
+}
@@ -0,0 +1,37 @@
+/**
+ * modeRailGesture.ts self-test。零 import 纯模块，Node 原生类型剥离直连 .ts。
+ * 锁定双击手势语义：
+ *  1) 单击 / 键盘触发（detail 1 / 0）一律 switch；
+ *  2) detail 2 只有「手势前模式 === 本按钮模式」才 toggle-sidebar（双击当前工作区按钮）；
+ *  3) detail 2 其余情况 noop（双击另一个按钮时第一击已完成切换，侧栏不动）。
+ * Run: node tests/mode-rail-gesture.mjs  (must exit 0)
+ */
+import { decideModeClick } from '../src/renderer/src/workspace/modeRailGesture.ts'
+
+let failed = 0
+const ok = (cond, msg) => {
+  console.log(`  ${cond ? 'ok' : 'FAIL'}: ${msg}`)
+  if (!cond) failed += 1
+}
+
+console.log('single click / keyboard always switch:')
+ok(decideModeClick(1, null, 'terminal') === 'switch', 'detail=1 preMode=null → switch')
+ok(decideModeClick(1, 'terminal', 'terminal') === 'switch', 'detail=1 same mode → switch')
+ok(decideModeClick(1, 'terminal', 'ssh') === 'switch', 'detail=1 other mode → switch')
+ok(decideModeClick(0, 'terminal', 'ssh') === 'switch', 'detail=0 keyboard → switch')
+
+console.log('double click toggles sidebar only on the already-active button:')
+ok(decideModeClick(2, 'terminal', 'terminal') === 'toggle-sidebar', 'detail=2 active terminal → toggle-sidebar')
+ok(decideModeClick(2, 'ssh', 'ssh') === 'toggle-sidebar', 'detail=2 active ssh → toggle-sidebar')
+ok(decideModeClick(2, 'terminal', 'ssh') === 'noop', 'detail=2 inactive ssh → noop（第一击已切换）')
+ok(decideModeClick(2, 'ssh', 'terminal') === 'noop', 'detail=2 inactive terminal → noop')
+ok(decideModeClick(2, null, 'terminal') === 'noop', 'detail=2 preMode=null → noop（防御）')
+
+console.log('click streaks beyond 2 fall back to switch semantics:')
+ok(decideModeClick(3, 'terminal', 'terminal') === 'switch', 'detail=3 → switch（不产生第二次翻转）')
+
+if (failed > 0) {
+  console.error(`${failed} check(s) failed`)
+  process.exit(1)
+}
+console.log('mode-rail-gesture: all ok')