dsh-vscode-mode 0.1.19 → 0.1.21

package/src/client/outline/parse.ts

@@ -0,0 +1,271 @@
+/**
+ * dsh-vscode-mode client — 大纲兜底解析器（纯函数，无 DOM/Monaco 依赖，node 可测）。
+ * 覆盖无内置 document symbol provider 的语言：markdown/mdx、python、shell、powershell、
+ * lua、go、rust、yaml、ini(toml)、花括号语言（c/cpp/csharp/java/php/ruby/kotlin/swift/dart）。
+ * TS/JS/JSON/CSS/HTML 有 Monaco 原生 provider，不走这里。
+ * 作者 ddj 2026-08-27
+ */
+import type { OutlineSymbol } from './types.js'
+
+/** monaco SymbolKind 数值常量（与 LSP SymbolKind 一致，面板渲染按此分组）。 */
+export const SK = {
+  File: 0, Module: 1, Namespace: 2, Package: 3, Class: 4, Method: 5,
+  Property: 6, Field: 7, Constructor: 8, Enum: 9, Interface: 10,
+  Function: 11, Variable: 12, Constant: 13, String: 14, Number: 15,
+  Boolean: 16, Array: 17, Object: 18, Key: 19, Null: 20, EnumMember: 21,
+  Struct: 22, Event: 23, Operator: 24, TypeParameter: 25,
+} as const
+
+/** 花括号语言的泛型函数名排除集（避免误把控制流/关键字当符号）。 */
+const BRACE_KW = new Set([
+  'if', 'for', 'while', 'switch', 'catch', 'foreach', 'using', 'with', 'when',
+  'match', 'return', 'new', 'in', 'of', 'do', 'else', 'elif', 'then', 'yield',
+  'await', 'typeof', 'instanceof', 'case', 'default', 'try', 'finally', 'throw',
+])
+
+/** 花括号语言的类型关键字 → SymbolKind。 */
+const BRACE_TYPE_KIND: Record<string, number> = {
+  class: SK.Class, struct: SK.Struct, interface: SK.Interface, enum: SK.Enum,
+  namespace: SK.Namespace, module: SK.Module, trait: SK.Interface, record: SK.Class,
+}
+
+/** 按文档序（先序）补齐每个符号的 endLine：叶子取“下一个符号起行 - 1”，容器取末子 endLine。 */
+function computeEnds(symbols: OutlineSymbol[], lastLine: number): void {
+  const order: OutlineSymbol[] = []
+  const collect = (list: OutlineSymbol[]): void => {
+    for (const s of list) {
+      order.push(s)
+      if (s.children && s.children.length) collect(s.children)
+    }
+  }
+  collect(symbols)
+  for (let i = order.length - 1; i >= 0; i--) {
+    const s = order[i]
+    const kids = s.children ?? []
+    if (kids.length) {
+      s.endLine = Math.max(s.startLine, kids[kids.length - 1].endLine)
+    } else {
+      const next = order[i + 1]
+      const end = next ? Math.max(s.startLine, next.startLine - 1) : lastLine
+      s.endLine = Math.max(s.startLine, Math.min(end, lastLine))
+    }
+  }
+}
+
+/** 构造单行符号（起始行=跳转行=所在行；detail 为截断后的声明文本）。 */
+function mk(lineIndex: number, name: string, kind: number, raw: string): OutlineSymbol {
+  const detail = raw.trim().replace(/\s+/g, ' ').slice(0, 80)
+  const line = lineIndex + 1
+  const out: OutlineSymbol = { name, kind, startLine: line, endLine: line, selectLine: line }
+  if (detail && detail !== name) out.detail = detail
+  return out
+}
+
+/** Markdown/mdx：`#` 级标题，层级嵌套。 */
+function parseMarkdown(text: string): OutlineSymbol[] {
+  const roots: OutlineSymbol[] = []
+  const stack: Array<{ level: number; item: OutlineSymbol }> = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^(\#{1,6})\s+(.+?)\s*#*\s*$/.exec(lines[i])
+    if (!m) continue
+    const item: OutlineSymbol = {
+      name: m[2].trim(), kind: SK.Namespace,
+      startLine: i + 1, endLine: i + 1, selectLine: i + 1, children: [],
+    }
+    while (stack.length && stack[stack.length - 1].level >= m[1].length) stack.pop()
+    const parent = stack.length ? stack[stack.length - 1].item : null
+    ;(parent ? parent.children : roots)!.push(item)
+    stack.push({ level: m[1].length, item })
+  }
+  computeEnds(roots, lines.length)
+  return roots
+}
+
+/** Python：def/class 按缩进栈嵌套。 */
+function parsePython(text: string): OutlineSymbol[] {
+  const roots: OutlineSymbol[] = []
+  const stack: Array<{ indent: number; item: OutlineSymbol }> = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^([ \t]*)(?:class|def)\s+([A-Za-z_]\w*)\s*[(:]/.exec(lines[i])
+    if (!m) continue
+    const indent = m[1].replace(/\t/g, '  ').length
+    const isClass = /class\s/.test(lines[i])
+    const item: OutlineSymbol = {
+      name: m[2], kind: isClass ? SK.Class : SK.Function,
+      startLine: i + 1, endLine: i + 1, selectLine: i + 1, children: [],
+    }
+    while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop()
+    const parent = stack.length ? stack[stack.length - 1].item : null
+    ;(parent ? parent.children : roots)!.push(item)
+    stack.push({ indent, item })
+  }
+  computeEnds(roots, lines.length)
+  return roots
+}
+
+/** Shell：`name() {` 函数。 */
+function parseShell(text: string): OutlineSymbol[] {
+  const out: OutlineSymbol[] = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^[ \t]*([A-Za-z_][A-Za-z0-9_]*)[ \t]*\(\)[ \t]*\{/.exec(lines[i])
+    if (m) out.push(mk(i, m[1], SK.Function, lines[i]))
+  }
+  computeEnds(out, lines.length)
+  return out
+}
+
+/** PowerShell：`function Name {` / `filter Name {`。 */
+function parsePwsh(text: string): OutlineSymbol[] {
+  const out: OutlineSymbol[] = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^[ \t]*(?:function|filter)[ \t]+([\w.-]+)/.exec(lines[i])
+    if (m) out.push(mk(i, m[1], SK.Function, lines[i]))
+  }
+  computeEnds(out, lines.length)
+  return out
+}
+
+/** Lua：`function Foo:bar` / `M.bar = class|function`。 */
+function parseLua(text: string): OutlineSymbol[] {
+  const out: OutlineSymbol[] = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (/^\s*--/.test(line)) continue
+    const fm = /^[ \t]*(?:local[ \t]+)?function[ \t]+([A-Za-z_][\w.:]*)/.exec(line)
+    if (fm) { out.push(mk(i, fm[1], SK.Function, line)); continue }
+    const cm = /^[ \t]*([A-Za-z_][\w.]*)[ \t]*=[ \t]*(?:class|function)\b/.exec(line)
+    if (cm) out.push(mk(i, cm[1], /class\b/.test(line) ? SK.Class : SK.Function, line))
+  }
+  computeEnds(out, lines.length)
+  return out
+}
+
+/** Go：func（含 receiver）/ type。 */
+function parseGo(text: string): OutlineSymbol[] {
+  const out: OutlineSymbol[] = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const fm = /^[ \t]*func[ \t]+(?:\([^)]*\)[ \t]*)?([A-Za-z_]\w*)/.exec(lines[i])
+    if (fm) { out.push(mk(i, fm[1], SK.Function, lines[i])); continue }
+    const tm = /^[ \t]*type[ \t]+([A-Za-z_]\w*)/.exec(lines[i])
+    if (tm) out.push(mk(i, tm[1], SK.Struct, lines[i]))
+  }
+  computeEnds(out, lines.length)
+  return out
+}
+
+/** Rust：fn/struct/enum/trait/impl/mod/type。 */
+function parseRust(text: string): OutlineSymbol[] {
+  const out: OutlineSymbol[] = []
+  const lines = text.split('\n')
+  const kindOf: Record<string, number> = {
+    fn: SK.Function, struct: SK.Struct, enum: SK.Enum, trait: SK.Interface,
+    impl: SK.Module, mod: SK.Module, type: SK.TypeParameter,
+  }
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^[ \t]*(?:pub(?:\([^)]*\))?[ \t]+)?(fn|struct|enum|trait|impl|mod|type)[ \t]+([A-Za-z_]\w*)/.exec(lines[i])
+    if (m && kindOf[m[1]]) out.push(mk(i, m[2], kindOf[m[1]], lines[i]))
+  }
+  computeEnds(out, lines.length)
+  return out
+}
+
+/** YAML：仅顶层键。 */
+function parseYaml(text: string): OutlineSymbol[] {
+  const out: OutlineSymbol[] = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line.trim() || /^\s/.test(line) || /^\s*[#-]/.test(line)) continue
+    const m = /^([A-Za-z0-9_.\-]+)\s*:/.exec(line)
+    if (m) out.push(mk(i, m[1], SK.Key, line))
+  }
+  computeEnds(out, lines.length)
+  return out
+}
+
+/** INI/TOML：`[section]` + `key=value`。 */
+function parseIni(text: string): OutlineSymbol[] {
+  const out: OutlineSymbol[] = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line.trim() || /^\s*[;#]/.test(line)) continue
+    const sm = /^\[([^\]]+)\]/.exec(line)
+    if (sm) { out.push(mk(i, sm[1], SK.Namespace, line)); continue }
+    const km = /^([A-Za-z0-9_.\-]+)\s*[=:]/.exec(line.trim())
+    if (km) out.push(mk(i, km[1], SK.Key, line))
+  }
+  computeEnds(out, lines.length)
+  return out
+}
+
+/** 花括号语言（C 族/JVM/.NET）：类型声明 + 泛型函数扫描（扁平，best-effort）。 */
+function parseBrace(text: string): OutlineSymbol[] {
+  const out: OutlineSymbol[] = []
+  const lines = text.split('\n')
+  const typeRe = /^[ \t]*(?:(?:public|private|protected|internal|static|final|abstract|sealed|readonly|export|declare|async|open|extern|virtual|override|const|global|pub|local)\s+)*(class|struct|interface|enum|namespace|module|trait|record)\s+([A-Za-z_]\w*)/
+  // 泛型函数：允许任意“字词型”返回类型/修饰符前缀（含 :: 限定名），名字后跟 ( 且不以 ; 结尾
+  const funcRe = /^[ \t]*(?:[\w<>,*&\[\].:]+\s+)*([A-Za-z_]\w*)\s*(?:<[^>]*>)?\s*\(/
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const t = line.trim()
+    if (!t || /^\s*\*/.test(line)) continue
+    const tm = typeRe.exec(line)
+    if (tm) { out.push(mk(i, tm[2], BRACE_TYPE_KIND[tm[1]] ?? SK.Class, line)); continue }
+    const fm = funcRe.exec(line)
+    if (!fm) continue
+    if (BRACE_KW.has(fm[1]) || /;\s*$/.test(t)) continue
+    out.push(mk(i, fm[1], SK.Function, line))
+  }
+  computeEnds(out, lines.length)
+  return out
+}
+
+/**
+ * 按 Monaco languageId 解析大纲符号（纯函数）。
+ * @author ddj 2026年08月27号
+ * @param languageId Monaco 语言 id
+ * @param text 文件全文
+ * @returns 归一化大纲符号树
+ */
+export function parseOutline(languageId: string, text: string): OutlineSymbol[] {
+  switch (languageId) {
+    case 'markdown':
+    case 'mdx':
+      return parseMarkdown(text)
+    case 'python':
+      return parsePython(text)
+    case 'shell':
+      return parseShell(text)
+    case 'powershell':
+      return parsePwsh(text)
+    case 'lua':
+      return parseLua(text)
+    case 'go':
+      return parseGo(text)
+    case 'rust':
+      return parseRust(text)
+    case 'yaml':
+      return parseYaml(text)
+    case 'ini':
+      return parseIni(text)
+    case 'c':
+    case 'cpp':
+    case 'csharp':
+    case 'java':
+    case 'php':
+    case 'ruby':
+    case 'kotlin':
+    case 'swift':
+    case 'dart':
+      return parseBrace(text)
+    default:
+      return []
+  }
+}

package/src/client/outline/sources.ts

@@ -0,0 +1,134 @@
+// @ts-nocheck
+/**
+ * dsh-vscode-mode client — 大纲源注册表 + 内置数据源（monaco / fallback）。
+ * 解析规则：按优先级降序遍历源，首个非空结果生效；全空 → 空态。
+ * monaco 源吃 Monaco 原生 document symbol provider（ts/json/css/html 与未来
+ * 第三方注册的 provider）；fallback 源兜底无内置提供方的语言（parse.ts）。
+ * 注册表对外 provide 为 edrvOutlineSources，第三方语言插件可注册更高优先级源。
+ * 作者 ddj 2026-08-27
+ */
+import type { OutlineSourceRegistry, OutlineSource, OutlineSourceInput, OutlineSymbol } from './types.js'
+import { parseOutline } from './parse.js'
+
+/** Monaco 原生有 document symbol provider 的语言（无需 fallback）。 */
+export const OUTLINE_MONACO_LANGS = new Set([
+  'typescript', 'javascript', 'json', 'jsonc', 'css', 'scss', 'less', 'html',
+])
+
+/** 无内置 provider、由 parse.ts 兜底的语言。 */
+export const OUTLINE_FALLBACK_LANGS = new Set([
+  'markdown', 'mdx', 'python', 'shell', 'powershell', 'lua', 'go', 'rust',
+  'yaml', 'ini', 'c', 'cpp', 'csharp', 'java', 'php', 'ruby', 'kotlin',
+  'swift', 'dart',
+])
+
+/**
+ * 创建生命周期独立的大纲源注册表。
+ * @author ddj 2026年08月27号
+ * @returns 大纲源注册表
+ */
+export function createOutlineSourceRegistry(): OutlineSourceRegistry {
+  const entries = new Map<string, OutlineSource>()
+  const listeners = new Set<() => void>()
+  const notify = (): void => {
+    for (const listener of listeners) listener()
+  }
+  const list = (): readonly OutlineSource[] =>
+    [...entries.values()].sort((a, b) => (b.priority - a.priority) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  return {
+    register(source: OutlineSource): () => void {
+      if (!source || !source.id || typeof source.get !== 'function') throw new TypeError('大纲源必须提供 id 与 get')
+      entries.set(source.id, source)
+      notify()
+      return () => {
+        if (entries.get(source.id) !== source) return
+        entries.delete(source.id)
+        notify()
+      }
+    },
+    list,
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    get: (id: string) => entries.get(id),
+  }
+}
+
+/** 归一化 Monaco OutlineElement（getTopLevelSymbols 产物）→ OutlineSymbol。 */
+function normalizeMonaco(el): OutlineSymbol | null {
+  if (!el || typeof el.name !== 'string') return null
+  const range = el.range || {}
+  const sel = el.selectionRange || range
+  const startLine = Math.max(1, Number(sel.startLineNumber ?? range.startLineNumber ?? 1))
+  const endLine = Math.max(1, Number(range.endLineNumber ?? startLine))
+  const out: OutlineSymbol = {
+    name: el.name,
+    kind: typeof el.kind === 'number' ? el.kind : 0,
+    startLine: Math.max(1, Number(range.startLineNumber ?? startLine)),
+    endLine,
+    selectLine: startLine,
+  }
+  if (typeof el.detail === 'string' && el.detail) out.detail = el.detail
+  if (Array.isArray(el.children) && el.children.length) {
+    const kids = el.children.map(normalizeMonaco).filter(Boolean)
+    if (kids.length) out.children = kids
+  }
+  return out
+}
+
+/**
+ * 按优先级解析大纲符号：首个非空结果生效（出错源跳过，落入下一优先级）。
+ * @author ddj 2026年08月27号
+ * @param sources 大纲源注册表
+ * @param input 当前快照（languageId/model/editor/monaco）
+ * @returns 归一化符号树（无符号时为空数组）
+ */
+export async function resolveOutline(sources: OutlineSourceRegistry, input: OutlineSourceInput): Promise<OutlineSymbol[]> {
+  for (const source of sources.list()) {
+    let supports = false
+    try { supports = source.provides(input.languageId) } catch { supports = false }
+    if (!supports) continue
+    let items: OutlineSymbol[] | null = null
+    try { items = await source.get(input) } catch { items = null }
+    if (items && items.length) return items
+  }
+  return []
+}
+
+/**
+ * 注册内置大纲源（monaco=50 / fallback=30）。
+ * @author ddj 2026年08月27号
+ * @param registry 目标注册表
+ * @returns 注销函数（同时注销全部内置源）
+ */
+export function registerBuiltinOutlineSources(registry: OutlineSourceRegistry): () => void {
+  const disposers = [
+    registry.register({
+      id: 'monaco',
+      priority: 50,
+      provides: () => true,
+      async get(input: OutlineSourceInput): Promise<OutlineSymbol[]> {
+        const ed = input.editor
+        const model = input.model
+        const cmd = ed?._commandService
+        if (!cmd || typeof cmd.executeCommand !== 'function') return []
+        const uri = model?.uri
+        if (!uri) return []
+        const list = await cmd.executeCommand('_executeDocumentSymbolProvider', uri)
+        return Array.isArray(list) ? list.map(normalizeMonaco).filter(Boolean) : []
+      },
+    }),
+    registry.register({
+      id: 'fallback',
+      priority: 30,
+      provides: (languageId: string) => OUTLINE_FALLBACK_LANGS.has(languageId),
+      async get(input: OutlineSourceInput): Promise<OutlineSymbol[]> {
+        const model = input.model
+        if (!model || typeof model.getValue !== 'function') return []
+        return parseOutline(input.languageId, model.getValue())
+      },
+    }),
+  ]
+  return () => { for (const dispose of disposers) dispose() }
+}

package/src/client/outline/types.ts

@@ -0,0 +1,51 @@
+/**
+ * dsh-vscode-mode client — 大纲契约（归一化符号模型 + 数据源接口）。
+ * 面板只消费 OutlineSymbol[]，与 Monaco 解耦；未来语言插件（LSP/VSIX 风格，
+ * 如 EmmyLua/C#）注册高优先级 OutlineSource 即可接入，无需改动面板。
+ * kind 取 monaco SymbolKind 数值（0–25，与 LSP SymbolKind 一致）。
+ * 作者 ddj 2026-08-27
+ */
+
+/** 归一化大纲符号（面板唯一渲染契约）。 */
+export interface OutlineSymbol {
+  name: string
+  /** monaco SymbolKind 数值：File0/Module1/Namespace2/Package3/Class4/Method5/Property6/Field7/Constructor8/Enum9/Interface10/Function11/Variable12/Constant13/String14/Number15/Boolean16/Array17/Object18/Key19/Null20/EnumMember21/Struct22/Event23/Operator24/TypeParameter25。 */
+  kind: number
+  detail?: string
+  /** 符号整体起始行（1-based）。 */
+  startLine: number
+  /** 符号整体结束行（1-based）。 */
+  endLine: number
+  /** 跳转行（符号名所在行，1-based）。 */
+  selectLine: number
+  children?: OutlineSymbol[]
+}
+
+/** 大纲数据源输入（面板解析时注入当前快照；字段均为弱类型，源自行 duck-typing）。 */
+export interface OutlineSourceInput {
+  languageId: string
+  /** Monaco 文本模型（源可用 model.getValue() 自行解析）。 */
+  model?: unknown
+  /** 当前 Monaco 编辑器实例（供 _commandService 等内部调用）。 */
+  editor?: unknown
+  /** 全局 monaco 对象。 */
+  monaco?: unknown
+}
+
+/** 大纲数据源：按优先级降序解析，首个非空结果生效。 */
+export interface OutlineSource {
+  id: string
+  /** 数值越大越优先（内置：monaco=50、fallback=30；第三方语言插件建议 60–90）。 */
+  priority: number
+  /** 是否可为该语言提供符号。 */
+  provides(languageId: string): boolean
+  get(input: OutlineSourceInput): Promise<OutlineSymbol[]>
+}
+
+/** 大纲源注册表（ctx.provide 为 edrvOutlineSources，供第三方注册）。 */
+export interface OutlineSourceRegistry {
+  register(source: OutlineSource): () => void
+  list(): readonly OutlineSource[]
+  subscribe(listener: () => void): () => void
+  get(id: string): OutlineSource | undefined
+}

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)))
+}