dsh-vscode-mode 0.1.19 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "DSH 上的类 VSCode 编码体验：Monaco 中央编辑器（文件页签/QuickOpen/状态栏）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚），状态持久化到工作区旁车",
   "keywords": [
     "dsh",

package/src/client/diffDock.ts

@@ -0,0 +1,52 @@
+/**
+ * dsh-vscode-mode client — 对话差异 dock 纯函数。
+ * 只负责差异文件轮转和文案，状态查询仍由组件复用现有 edrv.list/summarize。
+ * 作者 ddj 2026-08-26
+ */
+
+/**
+ * 从稳定差异文件列表中取下一个路径，并返回下一次索引。
+ * @author ddj 2026年08月26号
+ * @param paths 待处理差异文件路径
+ * @param index 当前轮转索引
+ * @returns 下一个路径与归一化后的下一索引
+ */
+export function nextDiffPath(paths: string[], index: number): { path: string | null; index: number } {
+  if (!paths.length) return { path: null, index: 0 }
+  const current = Number.isFinite(index) ? Math.max(0, Math.floor(index)) : 0
+  const at = current % paths.length
+  return { path: paths[at] ?? null, index: (at + 1) % paths.length }
+}
+
+/**
+ * 生成对话差异 dock 的单按钮文案。
+ * @author ddj 2026年08月26号
+ * @param count 待处理差异文件数量
+ * @returns 展示文案
+ */
+export function diffDockText(count: number): string {
+  return '差异 ' + Math.max(0, Math.floor(count)) + ' 个文件 · 查看下一个'
+}
+
+/**
+ * 根据活动文件决定编辑页 dock 形态，加载期间保持 editor 结构稳定。
+ * @author ddj 2026年08月26号
+ * @param activePath 当前活动文件路径
+ * @returns 编辑态或无文件空态
+ */
+export function editorDockMode(activePath: string | null | undefined): 'editor' | 'editor-empty' {
+  return activePath ? 'editor' : 'editor-empty'
+}
+
+/**
+ * 获取切换文件期间稳定展示的文件内差异数量。
+ * @author ddj 2026年08月26号
+ * @param ready 当前文件内容是否已加载完成
+ * @param actualTotal 内容就绪后的精确差异数
+ * @param fallbackTotal 内容加载期间的文件摘要差异数
+ * @returns 非负整数差异数
+ */
+export function displayDiffTotal(ready: boolean, actualTotal: number, fallbackTotal: number): number {
+  const value = ready ? actualTotal : fallbackTotal
+  return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0
+}

package/src/client/diffDockStore.ts

@@ -0,0 +1,87 @@
+/**
+ * dsh-vscode-mode client — 会话级差异 dock store。
+ * EditorView 发布当前编辑上下文，conversation.input.dock 唯一读取并渲染。
+ * 作者 ddj 2026年08月26号
+ */
+
+/** 差异 dock 的显示形态。 */
+export type DiffDockMode = 'chat' | 'editor' | 'editor-empty'
+
+/**
+ * 跨 slot 传递的差异 dock 快照。
+ * 操作回调随快照一起更新，避免 dock 持有已卸载编辑器的旧闭包。
+ */
+export interface DiffDockSnapshot {
+  mode: DiffDockMode
+  [key: string]: unknown
+}
+
+type DiffDockListener = () => void
+type DiffDockSource = object
+
+const values = new Map<string, DiffDockSnapshot>()
+const sources = new Map<string, DiffDockSource>()
+const listeners = new Map<string, Set<DiffDockListener>>()
+
+/** 通知指定会话的 dock 订阅者。 */
+function notifyDiff(sessionId: string): void {
+  for (const listener of listeners.get(sessionId) ?? []) listener()
+}
+
+/**
+ * 发布指定会话的最新编辑器差异上下文。
+ * @author ddj 2026年08月26号
+ * @param sessionId 会话 id
+ * @param snapshot 完整 DiffBox 操作上下文
+ * @param source 发布者令牌，用于卸载时防止误清理新实例
+ */
+export function publishDiffDock(sessionId: string, snapshot: DiffDockSnapshot, source?: DiffDockSource): void {
+  values.set(sessionId, snapshot)
+  if (source) sources.set(sessionId, source)
+  else sources.delete(sessionId)
+  notifyDiff(sessionId)
+}
+
+/**
+ * 清除指定会话的差异上下文。
+ * @author ddj 2026年08月26号
+ * @param sessionId 会话 id
+ * @param source 可选发布者令牌；不匹配时忽略清理
+ */
+export function clearDiffDock(sessionId: string, source?: DiffDockSource): void {
+  if (source && sources.get(sessionId) !== source) return
+  values.delete(sessionId)
+  sources.delete(sessionId)
+  notifyDiff(sessionId)
+}
+
+/**
+ * 读取指定会话的最新上下文。
+ * @author ddj 2026年08月26号
+ * @param sessionId 会话 id
+ * @returns 最新上下文或 null
+ */
+export function readDiffDock(sessionId?: string): DiffDockSnapshot | null {
+  if (!sessionId) return null
+  return values.get(sessionId) ?? null
+}
+
+/**
+ * 订阅指定会话的上下文变化。
+ * @author ddj 2026年08月26号
+ * @param sessionId 会话 id
+ * @param listener 变化回调
+ * @returns 取消订阅函数
+ */
+export function subscribeDiffDock(sessionId: string, listener: DiffDockListener): () => void {
+  let bucket = listeners.get(sessionId)
+  if (!bucket) {
+    bucket = new Set()
+    listeners.set(sessionId, bucket)
+  }
+  bucket.add(listener)
+  return () => {
+    bucket!.delete(listener)
+    if (!bucket!.size) listeners.delete(sessionId)
+  }
+}

package/src/client/editorLayout.ts

@@ -0,0 +1,19 @@
+/**
+ * dsh-vscode-mode client — 编辑区与原生 composer 的几何边界计算。
+ * @author ddj 2026年08月26号
+ */
+
+/**
+ * 计算编辑根节点在当前会话滚动区内、composer 上方可使用的高度。
+ * @author ddj 2026年08月26号
+ * @param rootTop 编辑根节点顶边
+ * @param scrollBottom 会话滚动区可视底边
+ * @param composerTop composer 顶边；缺失时回退滚动区底边
+ * @returns 非负可用高度
+ */
+export function editorHeight(rootTop: number, scrollBottom: number, composerTop?: number): number {
+  const root = Number.isFinite(rootTop) ? rootTop : 0
+  const scroll = Number.isFinite(scrollBottom) ? scrollBottom : root
+  const composer = Number.isFinite(composerTop) ? composerTop as number : scroll
+  return Math.max(0, Math.min(scroll, composer) - root)
+}

package/src/client/events.ts

@@ -5,18 +5,43 @@
  */
 
 /**
- * 打开中央「文件编辑」页签：点击 shell 会话头部的视图页签（DOM 级，无需 store actions）。
- * @author ddj 2026年08月20号
- * @param path 要打开的路径（可空）
+ * 选择中央「文件编辑」页签（DOM 级，无需 store actions）。
+ * @author ddj 2026年08月26号
  */
-export function openEditorView(path: string | null): void {
+function selectEditorTab(): void {
   const tabs = Array.from(document.querySelectorAll('div[role="tablist"] button[role="tab"]'))
-  for (const b of tabs) {
-    if (b.textContent && b.textContent.includes('文件编辑')) { (b as HTMLButtonElement).click(); break }
+  for (const tab of tabs) {
+    if (tab.textContent && tab.textContent.includes('文件编辑')) {
+      (tab as HTMLButtonElement).click()
+      break
+    }
   }
-  const p = path ?? null
+}
+
+/**
+ * 打开中央「文件编辑」页签。
+ * @author ddj 2026年08月26号
+ * @param path 要打开的路径（可空）
+ */
+export function openEditorView(path: string | null): void {
+  selectEditorTab()
+  const target = path ?? null
   setTimeout(() => {
-    window.dispatchEvent(new CustomEvent('edrv:open-editor', { detail: { path: p } }))
+    window.dispatchEvent(new CustomEvent('edrv:open-editor', { detail: { path: target } }))
+  }, 80)
+}
+
+/**
+ * 打开文件编辑页并聚焦指定文件的首个差异。
+ * @author ddj 2026年08月26号
+ * @param path 待聚焦的差异文件路径
+ */
+export function openDiffView(path: string): void {
+  selectEditorTab()
+  setTimeout(() => {
+    window.dispatchEvent(new CustomEvent('edrv:open-editor', {
+      detail: { path, focusDiff: true },
+    }))
   }, 80)
 }
 
@@ -30,7 +55,11 @@ export function emitOpenEditor(path: string): void {
   window.dispatchEvent(new CustomEvent('edrv:open-editor', { detail: { path } }))
 }
 
-/** 拉起 DiffLauncher。 */
-export function emitShowLauncher(): void {
-  window.dispatchEvent(new CustomEvent('edrv:show-launcher'))
+/**
+ * 拉起 DiffLauncher。
+ * @author ddj 2026年08月26号
+ * @param tab 可选的目标页签
+ */
+export function emitShowLauncher(tab?: 'pending' | 'archive'): void {
+  window.dispatchEvent(new CustomEvent('edrv:show-launcher', { detail: { tab } }))
 }

package/src/client/index.ts

@@ -1,6 +1,6 @@
 /**
  * dsh-vscode-mode client — 浏览器半入口：slot 注册 + 装配。
- * 挂点：conversation.view「文件编辑」页签（中央 Monaco 编辑器）+ header 差异角标。
+ * 挂点：conversation.view「文件编辑」页签（中央 Monaco 编辑器）+ conversation.input.dock 差异条 + header 差异角标。
  * 与 Host 通信：同源 fetch('/edrv/rpc')（shared/rpc 契约）。
  *
  * ⚠️ 跨版本 slot 装配（2026-08-21）：新版 DSH 的 slots 系统要求 slot 必须由父 entry
@@ -8,13 +8,15 @@
  * 声明未就绪时抛 `slot ... is not declared (a parent entry's children table must declare it)`。
  * 正确写法 = `ctx.slots.inject(name, () => ctx.slots.register(...))`：声明存在时同步
  * 执行，否则等待声明（官方 ui-conversation 自身即此模式）；旧版（rc.8 及更早）同样支持，
- * 故跨版本兼容。slot 名未变：conversation.view / conversation.session.header.utilities。
+ * 故跨版本兼容。slot 名：conversation.view / conversation.session.header.utilities /
+ * conversation.input.dock。
  * 作者 ddj 2026-08-20
  */
 import React from 'react'
 import './styles/editor.css'
 import { EditorView } from './ui/EditorView.js'
 import { DiffBadge } from './ui/DiffBadge.js'
+import { ConversationDiffDock } from './ui/ConversationDiffDock.js'
 import { McpSettings } from './ui/McpSettings.js'
 import { rpc } from './rpc.js'
 import { loadMonaco } from './monaco/loader.js'
@@ -24,6 +26,8 @@ import { installOpenPathRouter, vscodeOpener, autoValue } from './openPathRouter
 import { SettingsContext } from './settingsContext.js'
 import { SIDEBAR_PLUGIN, pickSettingsBinder, registerSlotSafely } from './compat.js'
 import { createAddToConversation } from './addToConversation.js'
+import { createSidebarPanelRegistry } from './sidebar/registry.js'
+import { createFilePanel } from './sidebar/panels/index.js'
 import type { CompatAdapter } from '../shared/compat.js'
 
 export const inject = ['slots', 'timer', 'locale', 'connection', 'remote', 'workspaces', 'sessions', 'conversation', 'settingsScope', 'webUiSettings']
@@ -37,18 +41,29 @@ export const inject = ['slots', 'timer', 'locale', 'connection', 'remote', 'work
 export function apply(ctx: any): void {
   const schedule = (fn: () => void, ms: number) => ctx.timeout(fn, ms)
 
-  // Monaco 预热：DSH 启动后后台加载编辑器核心（模块级 promise 去重），用户点开「文件编辑」页签即用，
-  // 不再等页签挂载后才首次拉取 /edrv/vendor/*。requestIdleCallback 让出首屏带宽，缺省回退延时调度；
-  // 预热失败静默吞掉（loader 失败会重置 promise，页签打开时仍走原有加载/重试路径）。
-  if (typeof window !== 'undefined') {
-    const preloadMonaco = () => loadMonaco(() => {}).catch(() => {})
-    if (typeof window.requestIdleCallback === 'function') window.requestIdleCallback(preloadMonaco, { timeout: 2000 })
-    else schedule(preloadMonaco, 300)
-  }
-
   const registry: FileOpenerRegistry = createFileOpenerRegistry()
   const workspaces = ctx.get('workspaces')
   const sessions = ctx.get('sessions')
+
+  // Monaco 加载时机：不再 DSH 启动即预热，改为进入会话界面（sessions.list.current 出现）后再后台加载，
+  // 用户点开「文件编辑」页签即用；空闲时仍由 EditorView 挂载兜底加载。
+  // 模块级 promise 去重，重复触发只首次真正加载；requestIdleCallback 让出会话首屏带宽，缺省回退延时调度；
+  // 预热失败静默吞掉（loader 失败会重置 promise，页签打开时仍走原有加载/重试路径）。
+  const monacoList = sessions?.list
+  if (typeof window !== 'undefined' && monacoList && typeof monacoList.subscribe === 'function') {
+    const list = monacoList as { getSnapshot: () => { current?: unknown }; subscribe: (listener: () => void) => () => void }
+    const schedulePreload = () => {
+      const preload = () => loadMonaco(() => {}).catch(() => {})
+      if (typeof window.requestIdleCallback === 'function') window.requestIdleCallback(preload, { timeout: 2000 })
+      else schedule(preload, 300)
+    }
+    const onSessionEnter = () => {
+      if (!list.getSnapshot()?.current) return
+      schedulePreload()
+    }
+    ctx.effect(() => list.subscribe(onSessionEnter), 'vscode-mode: monaco session trigger')
+    onSessionEnter()
+  }
   const originalOpenPath = workspaces?.openPath
   const binder = pickSettingsBinder(ctx)
   const settings = binder.scope
@@ -65,6 +80,11 @@ export function apply(ctx: any): void {
 
   ctx.provide('fileOpeners', registry)
   ctx.effect(() => registry.register(vscodeOpener()), 'vscode-mode: file opener')
+
+  // 侧边栏面板注册表（对外 provide，供本插件/第三方注册面板；文件管理为面板 #1）
+  const sidebarPanels = createSidebarPanelRegistry()
+  ctx.provide('edrvSidebarPanels', sidebarPanels)
+  ctx.effect(() => sidebarPanels.register(createFilePanel()), 'vscode-mode: sidebar panel')
   ctx.effect(() => registry.register({
     id: 'system', label: '系统默认应用', priority: 0,
     open: (path: string) => originalOpenPath.call(workspaces, path),
@@ -99,14 +119,23 @@ export function apply(ctx: any): void {
     }), 'vscode-mode: file link routing')
   }
 
-  // 中央「文件编辑」页签：类 VSCode 编辑器（顶部=文件页签+搜索框，差异 UI=文件底部圆角悬浮框）
+  // 中央「文件编辑」页签：类 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 })))
+  }, (props: unknown) => React.createElement(EditorView, Object.assign({}, props, { schedule, addToConversation, sidebarPanels })))
+
+  // 对话输入框上方差异 dock：普通对话显示单文案按钮，文件编辑页由 EditorView 隐藏
+  registerSlotSafely(ctx, {
+    name: 'conversation.input.dock',
+    id: 'edrv-diff-dock',
+    order: 30,
+    label: '差异',
+    inject: (sessionId: string) => ({ sessionId }),
+  }, (props: unknown) => React.createElement(ConversationDiffDock, Object.assign({}, props)))
 
   // header 差异角标：仅当前工作区存在差异时渲染
   registerSlotSafely(ctx, { name: 'conversation.session.header.utilities', id: 'edrv-diff-badge', order: 90, label: '差异' },

package/src/client/sidebar/SidebarView.ts

@@ -0,0 +1,73 @@
+// @ts-nocheck
+/**
+ * dsh-vscode-mode client — 侧边栏容器（活动栏 + 面板区 + 拖拽调宽）。
+ * 面板列表来自注册表（活动栏图标/徽标/激活态），渲染当前激活面板的 render(ctx)；
+ * 右侧手柄拖拽调宽（clamp 180–560），底部按钮收起侧边栏。
+ * 作者 ddj 2026-08-26
+ */
+import React from 'react'
+import type { SidebarCtx } from './types.js'
+
+const W_MIN = 180
+const W_MAX = 560
+
+/**
+ * 侧边栏容器。
+ * @param props.registry 面板注册表（list() 提供面板顺序）
+ * @param props.ctx 面板共享上下文
+ * @param props.activePanel 当前激活面板 id
+ * @param props.onActive 激活面板变化回调
+ * @param props.width 面板区宽度
+ * @param props.onWidth 宽度变化回调
+ * @param props.onHide 收起侧边栏回调
+ */
+export function SidebarView(props) {
+  const panels = props.registry?.list?.() ?? []
+  const ctx = props.ctx
+  const activePanel = props.activePanel
+  const onActive = props.onActive
+  const width = props.width
+  const onWidth = props.onWidth
+  const onHide = props.onHide
+
+  const active = panels.find((p) => p.id === activePanel) || panels[0]
+
+  const onPointerDown = (e) => {
+    e.preventDefault()
+    const startX = e.clientX
+    const startW = width
+    const onMove = (ev) => {
+      const w = Math.max(W_MIN, Math.min(W_MAX, startW + (ev.clientX - startX)))
+      onWidth(w)
+    }
+    const onUp = () => {
+      window.removeEventListener('pointermove', onMove)
+      window.removeEventListener('pointerup', onUp)
+    }
+    window.addEventListener('pointermove', onMove)
+    window.addEventListener('pointerup', onUp)
+  }
+
+  const rail = React.createElement('div', { className: 'edrv-rail' },
+    React.createElement('div', { style: { flex: 1, display: 'flex', flexDirection: 'column', gap: 2 } },
+      panels.map((p) => {
+        const count = typeof p.badge === 'function' ? p.badge(ctx) : null
+        return React.createElement('button', {
+          key: p.id,
+          className: 'edrv-rail-btn' + (active && p.id === active.id ? ' edrv-rail-on' : ''),
+          title: p.title,
+          onClick: () => onActive(p.id),
+        },
+          React.createElement('span', { className: 'edrv-rail-icon' }, p.icon),
+          count > 0
+            ? React.createElement('span', { className: 'edrv-rail-badge' }, String(count))
+            : null)
+      })),
+    React.createElement('button', { className: 'edrv-rail-btn', title: '隐藏侧边栏 (Ctrl+B)', onClick: onHide }, '◀'))
+
+  return React.createElement('div', { className: 'edrv-sidebar', style: { width } },
+    rail,
+    React.createElement('div', { className: 'edrv-side-body' },
+      active ? active.render(ctx) : null),
+    React.createElement('div', { className: 'edrv-side-resize', onPointerDown: onPointerDown }))
+}

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

@@ -0,0 +1,161 @@
+// @ts-nocheck
+/**
+ * dsh-vscode-mode client — 侧边栏「文件管理」面板（懒加载目录树）。
+ * 点目录展开/收起（首次经 edrv.listDir 拉取并缓存），点文件经 ctx.openFile 打开；
+ * 差异角标取 pendingByPath，活动文件高亮；edrv:refresh 事件与手动刷新重载树。
+ * 作者 ddj 2026-08-26
+ */
+import React from 'react'
+import { rpc } from '../../rpc.js'
+import type { SidebarCtx } from '../types.js'
+
+const DIR_CAP = 4000
+
+/**
+ * 目录树面板主体。
+ * @param props.ctx 面板共享上下文（sessionId/openFile/activePath/pendingByPath）
+ */
+export function FileExplorer(props) {
+  const ctx = props?.ctx
+  const sessionId = ctx?.sessionId
+  const openFile = ctx?.openFile
+  const activePath = ctx?.activePath ?? null
+  const pendingByPath = ctx?.pendingByPath ?? {}
+  const [root, setRoot] = React.useState(null)
+  const [dirs, setDirs] = React.useState({})
+  const [expanded, setExpanded] = React.useState({})
+  const [loading, setLoading] = React.useState({})
+  const [error, setError] = React.useState(null)
+  const tokensRef = React.useRef({})
+  // expanded 的 ref 镜像：edrv:refresh 监听用首次渲染闭包，但需读到最新展开态
+  const expandedRef = React.useRef({})
+  expandedRef.current = expanded
+
+  const loadDir = (rel) => {
+    const token = (tokensRef.current[rel] || 0) + 1
+    tokensRef.current[rel] = token
+    setLoading((prev) => Object.assign({}, prev, { [rel]: true }))
+    setError(null)
+    rpc('edrv.listDir', { sessionId, path: rel }).then((res) => {
+      if (tokensRef.current[rel] !== token) return
+      if (res && res.ok && Array.isArray(res.entries)) {
+        setDirs((prev) => Object.assign({}, prev, { [rel]: res.entries }))
+        if (res.root && !root) setRoot(res.root)
+      } else {
+        setError(res?.error ? String(res.error) : '读取目录失败')
+      }
+    }).catch((e) => {
+      if (tokensRef.current[rel] !== token) return
+      setError('读取目录异常:' + String(e))
+    }).finally(() => {
+      if (tokensRef.current[rel] !== token) return
+      setLoading((prev) => {
+        const next = Object.assign({}, prev)
+        delete next[rel]
+        return next
+      })
+    })
+  }
+
+  const toggle = (rel) => {
+    if (expanded[rel] === true) {
+      setExpanded((prev) => Object.assign({}, prev, { [rel]: false }))
+      return
+    }
+    if (!dirs[rel]) void loadDir(rel)
+    setExpanded((prev) => Object.assign({}, prev, { [rel]: true }))
+  }
+
+  const refresh = () => {
+    const keep = Object.keys(expandedRef.current).filter((k) => expandedRef.current[k] === true)
+    tokensRef.current = {}
+    setDirs({})
+    setLoading({})
+    setError(null)
+    if (keep.length) {
+      const next = {}
+      for (const rel of keep) next[rel] = true
+      setExpanded(next)
+      for (const rel of keep) void loadDir(rel)
+    } else {
+      setExpanded({})
+    }
+    void loadDir('')
+  }
+
+  React.useEffect(() => {
+    tokensRef.current = {}
+    setDirs({})
+    setExpanded({})
+    setLoading({})
+    setError(null)
+    setRoot(null)
+    void loadDir('')
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sessionId])
+
+  React.useEffect(() => {
+    const onRefresh = () => refresh()
+    window.addEventListener('edrv:refresh', onRefresh)
+    return () => window.removeEventListener('edrv:refresh', onRefresh)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const rootName = root ? String(root).split(/[\\/]/).pop() || root : ''
+
+  const rowEl = (e, depth, isDir, isOpen) => {
+    const pending = isDir ? 0 : (pendingByPath[e.path] ?? 0)
+    const active = !isDir && e.path === activePath
+    const dim = e.type === 'other'
+    return React.createElement('div', {
+      key: e.path,
+      className: 'edrv-tree-row' + (active ? ' edrv-tree-active' : ''),
+      title: e.path,
+      style: { paddingLeft: 6 + depth * 14 },
+      onClick: () => { if (isDir) toggle(e.path); else openFile(e.path) },
+    },
+      React.createElement('span', { className: 'edrv-tree-chev' },
+        isDir ? (isOpen ? '▾' : '▸') : ''),
+      React.createElement('span', { className: 'edrv-tree-name' + (dim ? ' edrv-tree-dim' : '') },
+        isDir ? (isOpen ? '📂' : '📁') : '📄', ' ', e.name),
+      (pending > 0
+        ? React.createElement('span', { className: 'edrv-tree-badge' }, String(pending))
+        : null))
+  }
+
+  const rowsOf = (rel, depth) => {
+    const entries = dirs[rel]
+    if (!entries) {
+      return [React.createElement('div', { key: rel + ':loading', className: 'edrv-tree-loading', style: { paddingLeft: 6 + depth * 14 } },
+        loading[rel] ? '加载中…' : '无法加载')]
+    }
+    const rows = []
+    const cap = entries.length
+    for (let i = 0; i < cap; i++) {
+      const e = entries[i]
+      const isDir = e.type === 'directory'
+      const isOpen = expanded[e.path] === true
+      rows.push(rowEl(e, depth, isDir, isOpen))
+      if (isDir && isOpen) rows.push(...rowsOf(e.path, depth + 1))
+    }
+    if (cap >= DIR_CAP) {
+      rows.push(React.createElement('div', { key: rel + ':cap', className: 'edrv-tree-loading', style: { paddingLeft: 6 + depth * 14 } },
+        '目录条目过多，仅显示前 ' + DIR_CAP + ' 项'))
+    }
+    return rows
+  }
+
+  return React.createElement('div', { className: 'edrv-side-panel' },
+    React.createElement('div', { className: 'edrv-side-head' },
+      React.createElement('span', { className: 'edrv-side-title' }, '资源管理器'),
+      React.createElement('span', { className: 'edrv-side-root', title: root || '' }, rootName),
+      React.createElement('span', { style: { flex: 1 } }),
+      React.createElement('button', { className: 'edrv-side-btn', title: '刷新目录树', onClick: refresh }, '⟳')),
+    React.createElement('div', { className: 'edrv-tree' },
+      (error
+        ? React.createElement('div', { className: 'edrv-tree-error' },
+            React.createElement('span', null, String(error)),
+            React.createElement('button', { className: 'edrv-side-btn', onClick: () => refresh() }, '重试'))
+        : null),
+      rowsOf('', 0)))
+}

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

@@ -0,0 +1,24 @@
+// @ts-nocheck
+/**
+ * dsh-vscode-mode client — 「文件管理」面板定义（注册表一项）。
+ * 作者 ddj 2026-08-26
+ */
+import React from 'react'
+import { FileExplorer } from './FileExplorer.js'
+import type { SidebarPanelDef, SidebarCtx } from '../types.js'
+
+/**
+ * 构造文件管理面板定义。
+ * @author ddj 2026年08月26号
+ * @returns 面板定义（含活动栏徽标 = 差异文件总数）
+ */
+export function createFilePanel(): SidebarPanelDef {
+  return {
+    id: 'explorer',
+    title: '文件管理',
+    icon: '📁',
+    order: 10,
+    badge: (ctx: SidebarCtx) => (ctx.sum && ctx.sum.totalFiles > 0 ? ctx.sum.totalFiles : null),
+    render: (ctx: SidebarCtx) => React.createElement(FileExplorer, { ctx }),
+  }
+}

package/src/client/sidebar/registry.ts

@@ -0,0 +1,52 @@
+/**
+ * dsh-vscode-mode client — 侧边栏面板注册表。
+ * 镜像 fileOpeners.ts 的注册表模式：create + register(返回注销) + list + subscribe，
+ * 由 client/index.ts `ctx.provide('edrvSidebarPanels', registry)` 对外暴露（第三方可注册）。
+ * 作者 ddj 2026-08-26
+ */
+import type { SidebarPanelDef } from './types.js'
+
+export interface SidebarPanelRegistry {
+  register(panel: SidebarPanelDef): () => void
+  list(): readonly SidebarPanelDef[]
+  subscribe(listener: () => void): () => void
+  get(id: string): SidebarPanelDef | undefined
+}
+
+/** 校验面板定义并写入注册表（缺 id/render 抛 TypeError）。 */
+function panelRegister(entries: Map<string, SidebarPanelDef>, notify: () => void, panel: SidebarPanelDef): void {
+  if (!panel.id || typeof panel.render !== 'function') throw new TypeError('侧边栏面板必须提供 id 和 render')
+  entries.set(panel.id, panel)
+  notify()
+}
+
+/**
+ * 创建生命周期独立的面板注册表。
+ * @author ddj 2026年08月26号
+ * @returns 面板注册表
+ */
+export function createSidebarPanelRegistry(): SidebarPanelRegistry {
+  const entries = new Map<string, SidebarPanelDef>()
+  const listeners = new Set<() => void>()
+  const notify = (): void => {
+    for (const listener of listeners) listener()
+  }
+  const list = (): readonly SidebarPanelDef[] =>
+    [...entries.values()].sort((a, b) => (a.order ?? 100) - (b.order ?? 100))
+  return {
+    register(panel: SidebarPanelDef): () => void {
+      panelRegister(entries, notify, panel)
+      return () => {
+        if (entries.get(panel.id) !== panel) return
+        entries.delete(panel.id)
+        notify()
+      }
+    },
+    list,
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    get: (id: string) => entries.get(id),
+  }
+}