dsh-vscode-mode 0.1.21 → 0.1.23

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.1.21",
-  "description": "DSH 上的类 VSCode 编码体验：Monaco 中央编辑器（文件页签/QuickOpen/状态栏）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚），状态持久化到工作区旁车",
+  "version": "0.1.23",
+  "description": "DSH 上的类 VSCode 编码体验：Monaco 编辑器（文件页签/QuickOpen/状态栏，可驻 dsh-better-sidebar 侧边栏与对话同屏）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚），状态持久化到工作区旁车",
   "keywords": [
     "dsh",
     "dsh-plugin",

package/src/client/events.ts

@@ -1,11 +1,13 @@
 /**
  * dsh-vscode-mode client — 跨组件/跨 slot 的窗口事件助手。
- * 迁移自原 src/client/index.ts 的 openEditorView 与事件派发，语义不改。
+ * 迁移自原 src/client/index.ts 的 openEditorView 与事件派发，语义不改；
+ * 侧边栏形态（sidebarBridge 已注册路由）优先，否则回退 DOM 页签点击。
  * 作者 ddj 2026-08-20
  */
+import { routeSideEditor } from './sidebarBridge.js'
 
 /**
- * 选择中央「文件编辑」页签（DOM 级，无需 store actions）。
+ * 选择中央「文件编辑」页签（DOM 级，无需 store actions）。仅旧页签形态使用。
  * @author ddj 2026年08月26号
  */
 function selectEditorTab(): void {
@@ -19,11 +21,12 @@ function selectEditorTab(): void {
 }
 
 /**
- * 打开中央「文件编辑」页签。
+ * 打开「文件编辑」：侧边栏形态路由优先，旧形态回退中央页签。
  * @author ddj 2026年08月26号
  * @param path 要打开的路径（可空）
  */
 export function openEditorView(path: string | null): void {
+  if (routeSideEditor(path ?? null, false)) return
   selectEditorTab()
   const target = path ?? null
   setTimeout(() => {
@@ -32,11 +35,12 @@ export function openEditorView(path: string | null): void {
 }
 
 /**
- * 打开文件编辑页并聚焦指定文件的首个差异。
+ * 打开文件编辑页并聚焦指定文件的首个差异（侧边栏形态自动展开面板）。
  * @author ddj 2026年08月26号
  * @param path 待聚焦的差异文件路径
  */
 export function openDiffView(path: string): void {
+  if (routeSideEditor(path, true)) return
   selectEditorTab()
   setTimeout(() => {
     window.dispatchEvent(new CustomEvent('edrv:open-editor', {

package/src/client/fileReveal.ts

@@ -0,0 +1,28 @@
+/**
+ * dsh-vscode-mode client — 「在文件浏览器中打开」RPC 包装（树菜单与 Monaco 右键共用）。
+ * 归一化为 { ok, error? }，不抛异常；无会话/异常降级返回错误文案。
+ * 作者 ddj 2026-08-27
+ */
+import { rpc } from './rpc.js'
+
+export interface RevealOutcome {
+  ok: boolean
+  error?: string
+}
+
+/**
+ * 请求 host 在 OS 文件浏览器中打开/定位路径。
+ * @author ddj 2026年08月27号
+ * @param sessionId 会话 id（可空）
+ * @param path 工作区相对路径（'' = 根目录）
+ * @returns 成功或失败原因
+ */
+export async function revealInExplorer(sessionId: string | undefined, path: string): Promise<RevealOutcome> {
+  if (!sessionId) return { ok: false, error: '无活动会话' }
+  try {
+    const res = await rpc('edrv.revealInExplorer', { sessionId, path })
+    return res.ok ? { ok: true } : { ok: false, error: res.error }
+  } catch (error) {
+    return { ok: false, error: '打开异常:' + String(error) }
+  }
+}

package/src/client/index.ts

@@ -1,6 +1,7 @@
 /**
  * dsh-vscode-mode client — 浏览器半入口：slot 注册 + 装配。
- * 挂点：conversation.view「文件编辑」页签（中央 Monaco 编辑器）+ conversation.input.dock 差异条 + header 差异角标。
+ * 挂点：betterSidebar「文件编辑」Tab（侧边栏形态，对话+编辑同屏；未装 dsh-better-sidebar 时
+ * 回退 conversation.view 中央页签）+ conversation.input.dock 差异条 + header 差异角标。
  * 与 Host 通信：同源 fetch('/edrv/rpc')（shared/rpc 契约）。
  *
  * ⚠️ 跨版本 slot 装配（2026-08-21）：新版 DSH 的 slots 系统要求 slot 必须由父 entry
@@ -25,9 +26,13 @@ import type { FileOpenerRegistry } from './fileOpeners.js'
 import { installOpenPathRouter, vscodeOpener, autoValue } from './openPathRouter.js'
 import { SettingsContext } from './settingsContext.js'
 import { SIDEBAR_PLUGIN, pickSettingsBinder, registerSlotSafely } from './compat.js'
+import { detectSidebarService, installSideEditor, setEnsureSideEditor, SIDEBAR_INSTALL_CMD } from './sidebarBridge.js'
+import { SideEditorTab } from './ui/SideEditorTab.js'
 import { createAddToConversation } from './addToConversation.js'
 import { createSidebarPanelRegistry } from './sidebar/registry.js'
 import { createFilePanel } from './sidebar/panels/index.js'
+import { createTreeMenuRegistry } from './sidebar/contextMenu.js'
+import { createDefaultFileMenuItems } from './sidebar/menuItems.js'
 import { createOutlinePanel } from './outline/index.js'
 import { createOutlineSourceRegistry, registerBuiltinOutlineSources } from './outline/sources.js'
 import type { CompatAdapter } from '../shared/compat.js'
@@ -70,6 +75,8 @@ export function apply(ctx: any): void {
   const binder = pickSettingsBinder(ctx)
   const settings = binder.scope
   let selected = autoValue('auto')
+  /** 可选探测 betterSidebar 服务（不进 inject：缺失会让插件停靠等待，杀死回退路径）。 */
+  const sideService = detectSidebarService(ctx)
   /** 「添加到对话」动作集：编辑区/Tab 右键菜单注入文件引用与代码块（conversation 服务缺失时各动作安全降级）。 */
   const addToConversation = createAddToConversation(ctx)
 
@@ -78,6 +85,7 @@ export function apply(ctx: any): void {
     { name: '设置桥', active: settings !== undefined, note: settings !== undefined ? '使用 ' + binder.service + ' 桥' : '未绑定设置服务（fileOpenTool 持久化不可用）' },
     { name: '文件打开路由（workspaces.openPath）', active: Boolean(workspaces?.openPath), note: 'vscode 打开器优先，失败回退系统打开' },
     { name: '侧边栏打开器（' + SIDEBAR_PLUGIN + '）', active: registry.get(SIDEBAR_PLUGIN) !== undefined, note: registry.get(SIDEBAR_PLUGIN) !== undefined ? '已注册（优先级 80）' : '未检测到侧边栏打开能力' },
+    { name: '侧边栏编辑区（' + SIDEBAR_PLUGIN + '）', active: sideService !== undefined, note: sideService !== undefined ? '编辑区=侧边栏 Tab（对话+编辑同屏）' : '未检测到；安装 dsh-better-sidebar 后刷新启用侧边栏形态（' + SIDEBAR_INSTALL_CMD + '）' },
   ]
 
   ctx.provide('fileOpeners', registry)
@@ -87,6 +95,12 @@ export function apply(ctx: any): void {
   const sidebarPanels = createSidebarPanelRegistry()
   ctx.provide('edrvSidebarPanels', sidebarPanels)
   ctx.effect(() => sidebarPanels.register(createFilePanel()), 'vscode-mode: sidebar panel')
+  // 文件右键菜单项注册表（对外 provide，供本插件/第三方注册；内置「在文件浏览器中打开」）
+  const fileMenuItems = createTreeMenuRegistry()
+  ctx.provide('edrvFileContextMenuItems', fileMenuItems)
+  for (const item of createDefaultFileMenuItems()) {
+    ctx.effect(() => fileMenuItems.register(item), 'vscode-mode: file context menu item ' + item.id)
+  }
   // 大纲源注册表（公开预留口）：第三方语言插件（LSP/VSIX 等）注册更高优先级源即可覆盖兜底
   const outlineSources = createOutlineSourceRegistry()
   ctx.provide('edrvOutlineSources', outlineSources)
@@ -126,14 +140,35 @@ export function apply(ctx: any): void {
     }), 'vscode-mode: file link routing')
   }
 
-  // 中央「文件编辑」页签：类 VSCode 编辑器（顶部=文件页签+搜索框，左侧=侧边栏，差异 UI=文件底部圆角悬浮框）
-  registerSlotSafely(ctx, {
-    name: 'conversation.view',
-    id: 'edrv-editor',
-    order: 5,
-    label: '文件编辑',
-    inject: (sessionId: string) => ({ sessionId }),
-  }, (props: unknown) => React.createElement(EditorView, Object.assign({}, props, { schedule, addToConversation, sidebarPanels, outlineSources })))
+  // 中央「文件编辑」页签（旧形态回退）：类 VSCode 编辑器；侧边栏形态可用时编辑器住 betterSidebar Tab，
+  // 本页签不注册（避免双实例：Monaco×2 + diff dock 每会话单源抢占）。
+  const registerLegacyTab = (): void => {
+    registerSlotSafely(ctx, {
+      name: 'conversation.view',
+      id: 'edrv-editor',
+      order: 5,
+      label: '文件编辑',
+      inject: (sessionId: string) => ({ sessionId }),
+    }, (props: unknown) => React.createElement(EditorView, Object.assign({}, props, { layout: 'tab', sideHint: SIDEBAR_INSTALL_CMD, schedule, addToConversation, sidebarPanels, outlineSources, fileMenuItems })))
+  }
+
+  if (sideService) {
+    // 侧边栏形态：注册「文件编辑」Tab（单实例、可按会话持久化、内容打开自动展开面板）
+    ctx.effect(() => installSideEditor({
+      service: sideService,
+      renderTab: (props: Record<string, unknown>) => React.createElement(SideEditorTab, Object.assign({}, props, { schedule, addToConversation, sidebarPanels, outlineSources, fileMenuItems })),
+      activeSession: () => {
+        const snapshot = sessions?.list?.getSnapshot?.() as { current?: string; byId?: Record<string, { cwd?: string }> } | undefined
+        const sessionId = snapshot?.current
+        if (!sessionId) return undefined
+        return { sessionId, cwd: snapshot?.byId?.[sessionId]?.cwd }
+      },
+      registerLegacyFallback: registerLegacyTab,
+    }), 'vscode-mode: sidebar editor tab')
+  } else {
+    setEnsureSideEditor(null)
+    registerLegacyTab()
+  }
 
   // 对话输入框上方差异 dock：普通对话显示单文案按钮，文件编辑页由 EditorView 隐藏
   registerSlotSafely(ctx, {

package/src/client/sidebar/contextMenu.ts

@@ -0,0 +1,99 @@
+/**
+ * dsh-vscode-mode client — 文件管理右键菜单框架（类型 + 注册表 + 纯构建函数）。
+ * 镜像 sidebar/registry.ts 的注册表模式：create + register(返回注销) + list + subscribe，
+ * 由 client/index.ts `ctx.provide('edrvFileContextMenuItems', registry)` 对外暴露（第三方可注册）。
+ * 新增菜单项只需 register 一条 TreeMenuItem，面板在右键打开时经 buildTreeMenu 过滤/排序。
+ * 本模块不触 React/浏览器，可单测。
+ * 作者 ddj 2026-08-27
+ */
+import type { TreeEntry } from '../../shared/rpc.js'
+import type { SidebarCtx } from './types.js'
+
+/** 右键目标（树行/面板空白区，path 相对工作区根，'' 表示根目录）。 */
+export interface TreeMenuTarget {
+  path: string
+  type: TreeEntry['type']
+}
+
+/** 一条右键菜单项定义。 */
+export interface TreeMenuItem {
+  id: string
+  label: string
+  /** 排序：数值越小越靠前（缺省 100）。 */
+  order?: number
+  /** 红色警示样式（如删除类操作）。 */
+  danger?: boolean
+  /** 置灰不可点（如无权限/目标不支持时）。 */
+  disabled?: boolean
+  /** 前置分隔线。 */
+  separator?: boolean
+  /** 显隐守卫：返回 false 则不显示。 */
+  visible?: (target: TreeMenuTarget, ctx: SidebarCtx) => boolean
+  run: (target: TreeMenuTarget, ctx: SidebarCtx) => void
+}
+
+/** 右键菜单项注册表（生命周期独立，可注册/注销/订阅）。 */
+export interface TreeMenuRegistry {
+  register(item: TreeMenuItem): () => void
+  list(): readonly TreeMenuItem[]
+  subscribe(listener: () => void): () => void
+  get(id: string): TreeMenuItem | undefined
+}
+
+/** 校验菜单项并写入注册表（缺 id/run/label 抛 TypeError）。 */
+function itemRegister(entries: Map<string, TreeMenuItem>, notify: () => void, item: TreeMenuItem): void {
+  if (!item.id || typeof item.run !== 'function' || !item.label) {
+    throw new TypeError('文件右键菜单项必须提供 id、label 和 run')
+  }
+  entries.set(item.id, item)
+  notify()
+}
+
+/**
+ * 创建生命周期独立的右键菜单项注册表。
+ * @author ddj 2026年08月27号
+ * @returns 菜单项注册表
+ */
+export function createTreeMenuRegistry(): TreeMenuRegistry {
+  const entries = new Map<string, TreeMenuItem>()
+  const listeners = new Set<() => void>()
+  const notify = (): void => {
+    for (const listener of listeners) listener()
+  }
+  const list = (): readonly TreeMenuItem[] =>
+    [...entries.values()].sort((a, b) => (a.order ?? 100) - (b.order ?? 100))
+  return {
+    register(item: TreeMenuItem): () => void {
+      itemRegister(entries, notify, item)
+      return () => {
+        if (entries.get(item.id) !== item) return
+        entries.delete(item.id)
+        notify()
+      }
+    },
+    list,
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    get: (id: string) => entries.get(id),
+  }
+}
+
+/**
+ * 按目标构建当前可见菜单项（visible 过滤 + order 排序）。
+ * @author ddj 2026年08月27号
+ * @param registry 菜单项注册表
+ * @param target 右键目标
+ * @param ctx 面板共享上下文
+ * @returns 可见菜单项（已排序）
+ */
+export function buildTreeMenu(registry: TreeMenuRegistry | undefined, target: TreeMenuTarget, ctx: SidebarCtx): TreeMenuItem[] {
+  if (!registry) return []
+  const out: TreeMenuItem[] = []
+  for (const item of registry.list()) {
+    if (typeof item.visible === 'function' && !item.visible(target, ctx)) continue
+    out.push(item)
+  }
+  return out
+}

package/src/client/sidebar/menuItems.ts

@@ -0,0 +1,28 @@
+/**
+ * dsh-vscode-mode client — 文件管理右键菜单内置项。
+ * 首个内置项：「在文件浏览器中打开」（文件→OS Explorer 定位选中、目录→打开目录）。
+ * 反馈统一走 ctx.notify（由 EditorView 提供，落到编辑区路径栏状态）。
+ * 作者 ddj 2026-08-27
+ */
+import { revealInExplorer } from '../fileReveal.js'
+import type { TreeMenuItem } from './contextMenu.js'
+
+/**
+ * 构造内置右键菜单项列表（后续内置项直接追加）。
+ * @author ddj 2026年08月27号
+ * @returns 内置菜单项数组
+ */
+export function createDefaultFileMenuItems(): TreeMenuItem[] {
+  return [
+    {
+      id: 'reveal-in-explorer',
+      label: '在文件浏览器中打开',
+      order: 0,
+      run: (target, ctx) => {
+        void revealInExplorer(ctx.sessionId, target.path).then((outcome) => {
+          ctx.notify?.(outcome.ok ? '已在文件浏览器中打开' : '打开失败：' + (outcome.error ?? '未知错误'))
+        })
+      },
+    },
+  ]
+}

package/src/client/sidebar/panels/FileExplorer.ts

@@ -3,17 +3,21 @@
  * dsh-vscode-mode client — 侧边栏「文件管理」面板（懒加载目录树）。
  * 点目录展开/收起（首次经 edrv.listDir 拉取并缓存），点文件经 ctx.openFile 打开；
  * 差异角标取 pendingByPath，活动文件高亮；edrv:refresh 事件与手动刷新重载树。
- * 作者 ddj 2026-08-26
+ * 右键行/空白弹出菜单：项来自 ctx.fileMenuItems 注册表（可拓展），
+ * 内置「在文件浏览器中打开」经 edrv.revealInExplorer 定位/打开。
+ * 作者 ddj 2026-08-26 / 2026-08-27
  */
 import React from 'react'
 import { rpc } from '../../rpc.js'
+import { ContextMenu } from '../../ui/ContextMenu.js'
+import { buildTreeMenu } from '../contextMenu.js'
 import type { SidebarCtx } from '../types.js'
 
 const DIR_CAP = 4000
 
 /**
  * 目录树面板主体。
- * @param props.ctx 面板共享上下文（sessionId/openFile/activePath/pendingByPath）
+ * @param props.ctx 面板共享上下文（sessionId/openFile/activePath/pendingByPath/fileMenuItems/notify）
  */
 export function FileExplorer(props) {
   const ctx = props?.ctx
@@ -26,6 +30,7 @@ export function FileExplorer(props) {
   const [expanded, setExpanded] = React.useState({})
   const [loading, setLoading] = React.useState({})
   const [error, setError] = React.useState(null)
+  const [menu, setMenu] = React.useState(null) // 右键菜单 { x, y, target }
   const tokensRef = React.useRef({})
   // expanded 的 ref 镜像：edrv:refresh 监听用首次渲染闭包，但需读到最新展开态
   const expandedRef = React.useRef({})
@@ -113,6 +118,11 @@ export function FileExplorer(props) {
       title: e.path,
       style: { paddingLeft: 6 + depth * 14 },
       onClick: () => { if (isDir) toggle(e.path); else openFile(e.path) },
+      onContextMenu: (ev) => {
+        ev.preventDefault()
+        ev.stopPropagation()
+        setMenu({ x: ev.clientX, y: ev.clientY, target: { path: e.path, type: e.type } })
+      },
     },
       React.createElement('span', { className: 'edrv-tree-chev' },
         isDir ? (isOpen ? '▾' : '▸') : ''),
@@ -145,7 +155,24 @@ export function FileExplorer(props) {
     return rows
   }
 
-  return React.createElement('div', { className: 'edrv-side-panel' },
+  // 面板区右键（空白处）→ 工作区根目录菜单；行内右键已在 rowEl 阻止冒泡。
+  const onPanelContext = (ev) => {
+    ev.preventDefault()
+    setMenu({ x: ev.clientX, y: ev.clientY, target: { path: '', type: 'directory' } })
+  }
+  // 当前右键目标的可视菜单项（构建时过滤/排序，registry 变化下次打开生效）。
+  const menuEntries = menu
+    ? buildTreeMenu(ctx?.fileMenuItems, menu.target, ctx).map((item) => ({
+        id: item.id,
+        label: item.label,
+        danger: item.danger,
+        disabled: item.disabled,
+        separator: item.separator,
+        onClick: () => item.run(menu.target, ctx),
+      }))
+    : []
+
+  return React.createElement('div', { className: 'edrv-side-panel', onContextMenu: onPanelContext },
     React.createElement('div', { className: 'edrv-side-head' },
       React.createElement('span', { className: 'edrv-side-title' }, '资源管理器'),
       React.createElement('span', { className: 'edrv-side-root', title: root || '' }, rootName),
@@ -157,5 +184,8 @@ export function FileExplorer(props) {
             React.createElement('span', null, String(error)),
             React.createElement('button', { className: 'edrv-side-btn', onClick: () => refresh() }, '重试'))
         : null),
-      rowsOf('', 0)))
+      rowsOf('', 0)),
+    (menu && menuEntries.length
+      ? React.createElement(ContextMenu, { x: menu.x, y: menu.y, entries: menuEntries, onClose: () => setMenu(null) })
+      : null))
 }

package/src/client/sidebar/types.ts

@@ -4,6 +4,7 @@
  * 作者 ddj 2026-08-26
  */
 import type { OutlineSourceRegistry } from '../outline/types.js'
+import type { TreeMenuRegistry } from './contextMenu.js'
 
 /** 面板可用的共享上下文（由 SidebarView 从 EditorView 注入，面板不直碰其内部）。 */
 export interface SidebarCtx {
@@ -20,6 +21,10 @@ export interface SidebarCtx {
   editor?: () => unknown | null
   /** 大纲源注册表（公开 provide 为 edrvOutlineSources；大纲面板解析符号用）。 */
   outlineSources?: OutlineSourceRegistry
+  /** 文件右键菜单项注册表（公开 provide 为 edrvFileContextMenuItems；文件管理面板构建菜单用）。 */
+  fileMenuItems?: TreeMenuRegistry
+  /** 面板动作反馈（如右键菜单操作结果 → 编辑区路径栏状态）。 */
+  notify?: (message: string) => void
 }
 
 /** 单个侧边栏面板定义。 */

package/src/client/sidebarBridge.ts

@@ -0,0 +1,247 @@
+/**
+ * dsh-vscode-mode client — 侧边栏编辑区桥：可选探测 dsh-better-sidebar 的
+ * ctx.betterSidebar 服务，并注册「文件编辑」Tab（单实例）。
+ * 可选依赖模式：服务缺失时调用方回退到中央页签形态；本模块不注册任何东西。
+ * 纯逻辑（探测/初始打开解析/角标计数）可单测，DOM/事件仅存在于 install 路径。
+ * 作者 ddj 2026年08月25号
+ */
+
+import React from 'react'
+
+/** betterSidebar 服务名（ctx.get 用；不要加进 inject——缺失会让插件停靠等待）。 */
+export const BETTER_SIDEBAR_SERVICE = 'betterSidebar'
+/** 本插件在侧边栏注册的 Tab 类型 id（亦是 SidebarTab.type）。 */
+export const SIDE_TAB_ID = 'edrv-editor'
+/** 侧边栏 Tab 标题。 */
+export const SIDE_TAB_TITLE = '文件编辑'
+/** 推荐安装命令（提示条/兼容性报告共用）。 */
+export const SIDEBAR_INSTALL_CMD = 'dsh plugin --profile web add dsh-better-sidebar'
+
+/** Tab 元数据（openTab 种子随 Tab 持久化，创建路径用它恢复初始打开）。 */
+export interface SideEditorMeta {
+  /** 待打开的工作区相对/绝对路径。 */
+  openPath?: string
+  /** 打开后聚焦首个差异。 */
+  focusDiff?: boolean
+}
+
+/**
+ * betterSidebar 服务的最小结构面（结构性探测，不 import 第三方类型）。
+ */
+export interface SidebarServiceLike {
+  registerTab: (descriptor: unknown) => () => void
+  openTab: (seed: { type: string; title?: string; path?: string; meta?: unknown }, scope?: { sessionId: string; cwd?: string }) => void
+  isTabEnabled?: (id: string) => boolean
+  features?: readonly string[]
+}
+
+/**
+ * 解析 Tab 挂载时的初始打开请求（创建路径读 tab.path/meta，聚焦路径走窗口事件）。
+ * @author ddj 2026年08月25号
+ * @param tab 侧边栏 Tab（path/meta 为可选字段）
+ * @returns 待打开路径与是否聚焦差异
+ */
+export function resolveInitialOpen(tab: { path?: string; meta?: unknown } | null | undefined): { path: string | null; focusDiff: boolean } {
+  const meta = (tab?.meta ?? {}) as SideEditorMeta
+  const path = typeof tab?.path === 'string' && tab.path ? tab.path : (typeof meta?.openPath === 'string' ? meta.openPath : null)
+  return { path: path || null, focusDiff: meta?.focusDiff === true }
+}
+
+/** 会话级待处理差异文件数缓存（Tab 角标同步读取；EditorView 侧栏形态写入）。 */
+const sidePending = new Map<string, number>()
+
+/**
+ * 写入会话的待处理差异文件数（0 视为清除，不显示角标）。
+ * @author ddj 2026年08月25号
+ * @param sessionId 会话 id
+ * @param count 待处理差异文件数
+ */
+export function setSidePending(sessionId: string, count: number): void {
+  if (!sessionId) return
+  const value = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0
+  if (value > 0) sidePending.set(sessionId, value)
+  else sidePending.delete(sessionId)
+}
+
+/**
+ * 读取会话的待处理差异文件数（角标用）。
+ * @author ddj 2026年08月25号
+ * @param sessionId 会话 id
+ * @returns 非负计数
+ */
+export function getSidePending(sessionId?: string): number {
+  if (!sessionId) return 0
+  return sidePending.get(sessionId) ?? 0
+}
+
+/** 模块级侧栏打开路由（events.ts 优先走它；未注册 = 旧页签形态）。 */
+let ensureSideEditor: ((path: string | null, focusDiff: boolean) => boolean) | null = null
+
+/** 待消费的初始打开（Tab 组件尚未挂载时暂存；按会话匹配，挂载时取走）。 */
+let pendingOpen: { sessionId: string; path: string | null; focusDiff: boolean } | null = null
+/** Tab 组件当前是否有挂载实例（有则直接投递窗口事件，无则暂存待消费）。 */
+let sideEditorMounted = false
+
+/**
+ * 注册/撤销侧栏打开路由。
+ * @author ddj 2026年08月25号
+ * @param fn 路由函数或 null
+ */
+export function setEnsureSideEditor(fn: ((path: string | null, focusDiff: boolean) => boolean) | null): void {
+  ensureSideEditor = fn
+}
+
+/**
+ * 标记侧栏编辑器组件挂载状态（SideEditorTab 挂载/卸载时调用）。
+ * @author ddj 2026年08月25号
+ * @param mounted 是否已挂载
+ */
+export function setSideEditorMounted(mounted: boolean): void {
+  sideEditorMounted = mounted
+}
+
+/**
+ * 暂存指定会话的待消费初始打开（Tab 组件未挂载时由 install 路径调用）。
+ * @author ddj 2026年08月25号
+ * @param sessionId 会话 id
+ * @param path 待打开路径（可空）
+ * @param focusDiff 是否聚焦首个差异
+ */
+export function stagePendingSideOpen(sessionId: string, path: string | null, focusDiff: boolean): void {
+  if (!sessionId) return
+  pendingOpen = { sessionId, path: path || null, focusDiff: focusDiff === true }
+}
+
+/**
+ * 取走指定会话的待消费初始打开（SideEditorTab 挂载时读取；不存在返回 null）。
+ * @author ddj 2026年08月25号
+ * @param sessionId 会话 id
+ * @returns 待打开请求或 null
+ */
+export function takePendingSideOpen(sessionId?: string): { path: string | null; focusDiff: boolean } | null {
+  if (!pendingOpen || !sessionId || pendingOpen.sessionId !== sessionId) return null
+  const value = { path: pendingOpen.path, focusDiff: pendingOpen.focusDiff }
+  pendingOpen = null
+  return value
+}
+
+/**
+ * 打开/聚焦侧栏编辑器（打开路径可选；返回是否已被侧栏形态接管）。
+ * @author ddj 2026年08月25号
+ * @param path 待打开路径（可空）
+ * @param focusDiff 是否聚焦首个差异
+ * @returns 是否路由成功
+ */
+export function routeSideEditor(path: string | null, focusDiff: boolean): boolean {
+  if (typeof ensureSideEditor !== 'function') return false
+  try {
+    return ensureSideEditor(path, focusDiff) === true
+  } catch (error) {
+    console.warn('[dsh-vscode-mode] 侧栏编辑器打开失败（' + String(error) + '），已回退')
+    return false
+  }
+}
+
+/**
+ * 结构化探测 betterSidebar 服务（可选依赖：缺失/降级返回 undefined）。
+ * @author ddj 2026年08月25号
+ * @param ctx 客户端服务上下文
+ * @returns 服务结构面或 undefined
+ */
+export function detectSidebarService(ctx: { get: (name: string) => unknown }): SidebarServiceLike | undefined {
+  try {
+    const service = ctx.get(BETTER_SIDEBAR_SERVICE) as SidebarServiceLike | undefined
+    if (!service || typeof service.registerTab !== 'function' || typeof service.openTab !== 'function') return undefined
+    return service
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 注册侧边栏「文件编辑」Tab 并接管打开路由。
+ * Tab 被用户在 better-sidebar 设置里禁用时，打开路由降级为回退回调（中央页签）。
+ * @author ddj 2026年08月25号
+ * @param options 装配参数（组件依赖 + 活动会话解析 + 回退注册）
+ * @returns 卸载器（反注册 Tab + 撤销路由）
+ */
+export function installSideEditor(options: {
+  service: SidebarServiceLike
+  renderTab: (props: Record<string, unknown>) => unknown
+  activeSession: () => { sessionId?: string; cwd?: string } | undefined
+  registerLegacyFallback: () => void
+}): () => void {
+  const { service, renderTab, activeSession, registerLegacyFallback } = options
+  let fallbackInstalled = false
+  const open = (path: string | null, focusDiff: boolean): boolean => {
+    if (typeof service.isTabEnabled === 'function' && !service.isTabEnabled(SIDE_TAB_ID)) {
+      if (!fallbackInstalled) {
+        fallbackInstalled = true
+        try { registerLegacyFallback() } catch (error) { console.warn('[dsh-vscode-mode] 回退注册失败（' + String(error) + '）') }
+      }
+      return false
+    }
+    const scope = activeSession()
+    const sessionId = scope?.sessionId
+    if (!sessionId) return false
+    try {
+      service.openTab({
+        type: SIDE_TAB_ID,
+        title: SIDE_TAB_TITLE,
+        ...(path ? { path } : {}),
+        meta: { openPath: path || undefined, focusDiff },
+      }, { sessionId, cwd: scope?.cwd })
+    } catch (error) {
+      console.warn('[dsh-vscode-mode] openTab 失败（' + String(error) + '）')
+      return false
+    }
+    if (sideEditorMounted) {
+      // 已挂载：窗口事件直达 EditorView 监听器
+      window.dispatchEvent(new CustomEvent('edrv:open-editor', { detail: { path, focusDiff } }))
+    } else {
+      // 未挂载（面板折叠卸载/首次创建）：暂存待消费，挂载时由 SideEditorTab 取走
+      stagePendingSideOpen(sessionId, path, focusDiff)
+    }
+    return true
+  }
+  let tabDisposer: (() => void) | null = null
+  try {
+    tabDisposer = service.registerTab({
+      id: SIDE_TAB_ID,
+      title: SIDE_TAB_TITLE,
+      icon: codeIcon,
+      single: true,
+      badge: (_ctx: unknown, scope: { sessionId?: string }) => getSidePending(scope?.sessionId) || null,
+      component: renderTab,
+    })
+  } catch (error) {
+    console.warn('[dsh-vscode-mode] 侧边栏 Tab 注册失败（' + String(error) + '）')
+    // 注册失败 = 侧栏形态不可用：立即回退中央页签，不接管打开路由
+    if (!fallbackInstalled) {
+      fallbackInstalled = true
+      try { registerLegacyFallback() } catch (inner) { console.warn('[dsh-vscode-mode] 回退注册失败（' + String(inner) + '）') }
+    }
+    return () => {}
+  }
+  setEnsureSideEditor(open)
+  return () => {
+    if (typeof tabDisposer === 'function') tabDisposer()
+    setEnsureSideEditor(null)
+  }
+}
+
+/**
+ * 侧边栏 Tab 图标（内联 SVG 代码括号，不依赖图标包）。
+ * @author ddj 2026年08月25号
+ * @param size 边长（px）
+ * @returns 图标元素
+ */
+function codeIcon(size: number): unknown {
+  return React.createElement('svg', {
+    width: size, height: size, viewBox: '0 0 16 16', fill: 'none', 'aria-hidden': true, focusable: false,
+  },
+    React.createElement('path', {
+      d: 'M5.5 4.5 2.5 8l3 3.5M10.5 4.5 13.5 8l-3 3.5',
+      stroke: 'currentColor', strokeWidth: 1.4, strokeLinecap: 'round', strokeLinejoin: 'round',
+    }))
+}