dsh-vscode-mode 0.1.30 → 0.1.35

package/src/lsp/server.ts

@@ -0,0 +1,346 @@
+/**
+ * dsh-vscode-mode host — 单语言服务器会话（绑定 工作区根 + 语言）。
+ * 负责：启动传输 + LSP 客户端握手、文档同步（didOpen/didChange/didSave/didClose）、
+ * 请求封装（definition/references/documentSymbol/workspaceSymbol/hover）、状态上报。
+ * 作者 ddj 2026-08-27
+ */
+import { spawnServer, type Transport } from './transport.js'
+import { createLspClient, type LspClient } from './client.js'
+import { pathToFileUri } from './uri.js'
+import type { LspProviderSpec } from './providers.js'
+import type {
+  LspLocation,
+  LspServerCapabilities,
+  LspServerPhase,
+  LspServerStatus,
+  LspSymbol,
+} from '../shared/lsp.js'
+
+export interface LspServer {
+  readonly languageId: string
+  readonly root: string
+  readonly phase: LspServerPhase
+  readonly capabilities: LspServerCapabilities
+  onStateChange: ((status: LspServerStatus) => void) | null
+  status(): LspServerStatus
+  start(): Promise<boolean>
+  sync(path: string, text: string, version: number): void
+  close(path: string): void
+  definition(path: string, line: number, character: number): Promise<LspLocation[]>
+  references(path: string, line: number, character: number, includeDeclaration: boolean): Promise<LspLocation[]>
+  documentSymbol(path: string): Promise<LspSymbol[]>
+  workspaceSymbol(query: string): Promise<LspSymbol[]>
+  hover(path: string, line: number, character: number): Promise<{ contents: string[] } | null>
+  dispose(): Promise<void>
+}
+
+/** 文档注册表：path(工作区相对) → { version, text, uri }。 */
+interface OpenDoc {
+  path: string
+  uri: string
+  version: number
+  text: string
+}
+
+const RESTARTABLE = true
+
+/**
+ * 创建语言服务器会话。
+ * @author ddj 2026年08月27号
+ * @param spec provider 规格（argv/cwd）
+ * @param root 工作区根（绝对路径）
+ * @param languageId 语言 id
+ * @param logger 诊断日志
+ * @returns 会话句柄
+ */
+export function createLspServer(spec: LspProviderSpec, root: string, languageId: string, logger?: (line: string) => void): LspServer {
+  const rootUri = pathToFileUri(root)
+  const docs = new Map<string, OpenDoc>()
+  let phase: LspServerPhase = 'idle'
+  let transport: Transport | null = null
+  let client: LspClient | null = null
+  let capabilities: LspServerCapabilities = { definition: false, references: false, documentSymbol: false, workspaceSymbol: false, hover: false }
+  let disposed = false
+  let readyWait: Promise<boolean> = Promise.resolve(false)
+  let resolveReady: ((ready: boolean) => void) | null = null
+  let lastProgress: { value?: number; message?: string } = {}
+  let lastStatus: LspServerStatus = { languageId, source: spec.kind, phase: 'idle', reason: spec.ready ? undefined : spec.reason, root }
+
+  const log = (line: string): void => logger?.('[' + languageId + '@' + root + '] ' + line)
+
+  const setPhase = (next: LspServerPhase, reason?: string): void => {
+    phase = next
+    lastStatus = { languageId, source: spec.kind, phase: next, reason, root, ...progressFields() }
+    server.onStateChange?.(lastStatus)
+  }
+
+  /** 返回当前进度字段，避免空进度污染状态载荷。 */
+  const progressFields = (): Pick<LspServerStatus, 'progress' | 'progressMessage'> => ({
+    progress: lastProgress.value,
+    progressMessage: lastProgress.message,
+  })
+
+  /** 处理 LSP $/progress 通知并映射为编辑器状态。 */
+  const applyProgress = (params: unknown): void => {
+    const value = params as { value?: unknown }
+    const report = value?.value as { kind?: unknown; percentage?: unknown; message?: unknown } | undefined
+    if (report?.kind === 'begin') {
+      lastProgress = { value: 0, message: typeof report.message === 'string' ? report.message : '正在解析工作区' }
+      if (phase === 'ready') phase = 'indexing'
+    } else if (report?.kind === 'end') {
+      lastProgress = { value: 100, message: typeof report.message === 'string' ? report.message : '解析完成' }
+      if (phase === 'indexing') phase = 'ready'
+    } else if (typeof report?.percentage === 'number') {
+      lastProgress = { value: Math.max(0, Math.min(100, report.percentage)), message: typeof report.message === 'string' ? report.message : lastProgress.message }
+      if (phase === 'ready') phase = 'indexing'
+    } else if (typeof report?.message === 'string') {
+      lastProgress = { ...lastProgress, message: report.message }
+    }
+    lastStatus = { ...lastStatus, phase, ...progressFields() }
+    server.onStateChange?.(lastStatus)
+  }
+
+  const ensureClient = (): LspClient => {
+    if (!client) throw new Error('LSP 服务器未启动')
+    return client
+  }
+
+  const server: LspServer = {
+    languageId,
+    root,
+    get phase() {
+      return phase
+    },
+    get capabilities() {
+      return capabilities
+    },
+    status(): LspServerStatus {
+      return lastStatus
+    },
+    onStateChange: null,
+
+    async start(): Promise<boolean> {
+      if (disposed) return false
+      if (phase === 'starting') return readyWait
+      if (phase === 'ready' || phase === 'indexing') return true
+      readyWait = new Promise((resolve) => { resolveReady = resolve })
+      lastProgress = {}
+      setPhase('starting')
+      try {
+        transport = spawnServer(
+          { argv: spec.argv, cwd: spec.cwd ?? root },
+          (message) => { /* 由 client 接管 */ },
+          (line) => log('stderr: ' + line),
+        )
+        client = createLspClient(transport, {
+          onReady: (caps) => {
+            capabilities = caps
+            // 重放已打开文档（崩溃重启后恢复服务器侧状态）
+            for (const doc of docs.values()) {
+              client?.notify('textDocument/didOpen', {
+                textDocument: { uri: doc.uri, languageId, version: doc.version, text: doc.text },
+              })
+            }
+            setPhase('ready')
+            resolveReady?.(true)
+            resolveReady = null
+            log('ready: definition=' + caps.definition + ' references=' + caps.references + ' symbols=' + caps.documentSymbol)
+          },
+          onProgress: (params) => applyProgress(params),
+          onExit: (code, signal) => {
+            if (disposed) return
+            resolveReady?.(false)
+            resolveReady = null
+            log('server exited (' + String(code) + '/' + String(signal) + ')')
+            client = null
+            transport = null
+            if (RESTARTABLE) setPhase('idle', '服务器已退出（' + String(code) + '/' + String(signal) + '），等待重启')
+            else setPhase('stopped', '服务器已退出')
+          },
+          onLog: (line) => log('lsp: ' + line),
+        })
+        // 让 client 接管 stdout 消息
+        const caps = await client.initialize(rootUri, [rootUri])
+        capabilities = caps
+        return true
+      } catch (error) {
+        log('start failed: ' + String(error))
+        setPhase('unavailable', '启动失败：' + String(error))
+        resolveReady?.(false)
+        resolveReady = null
+        try { await server.dispose() } catch { /* 忽略 */ }
+        return false
+      }
+    },
+
+    sync(path: string, text: string, version: number): void {
+      const existing = docs.get(path)
+      const uri = existing?.uri ?? pathToFileUri(root + '/' + path.split('/').join('/'))
+      if (existing) {
+        existing.version = version
+        existing.text = text
+        if (phase === 'ready' || phase === 'indexing') {
+          client?.notify('textDocument/didChange', {
+            textDocument: { uri, version },
+            contentChanges: [{ text }],
+          })
+        }
+        return
+      }
+      docs.set(path, { path, uri, version, text })
+      if (phase === 'ready' || phase === 'indexing') {
+        client?.notify('textDocument/didOpen', {
+          textDocument: { uri, languageId, version, text },
+        })
+      }
+    },
+
+    close(path: string): void {
+      const doc = docs.get(path)
+      if (!doc) return
+      docs.delete(path)
+      if (phase === 'ready' || phase === 'indexing') {
+        client?.notify('textDocument/didClose', { textDocument: { uri: doc.uri } })
+      }
+    },
+
+    async definition(path: string, line: number, character: number): Promise<LspLocation[]> {
+      const doc = docs.get(path)
+      if (!doc || !(await readyWait)) return []
+      const result = await ensureClient().request<unknown>(
+        'textDocument/definition',
+        { textDocument: { uri: doc.uri }, position: { line, character } },
+      )
+      return normalizeLocations(result)
+    },
+
+    async references(path: string, line: number, character: number, includeDeclaration: boolean): Promise<LspLocation[]> {
+      const doc = docs.get(path)
+      if (!doc || !(await readyWait)) return []
+      const result = await ensureClient().request<unknown>(
+        'textDocument/references',
+        {
+          textDocument: { uri: doc.uri },
+          position: { line, character },
+          context: { includeDeclaration },
+        },
+      )
+      return normalizeLocations(result)
+    },
+
+    async documentSymbol(path: string): Promise<LspSymbol[]> {
+      const doc = docs.get(path)
+      if (!doc || !(await readyWait)) return []
+      const result = await ensureClient().request<unknown>('textDocument/documentSymbol', { textDocument: { uri: doc.uri } })
+      if (!Array.isArray(result)) return []
+      return (result as unknown[]).map(normalizeSymbol).filter((s): s is LspSymbol => s !== null)
+    },
+
+    async workspaceSymbol(query: string): Promise<LspSymbol[]> {
+      if (!(await readyWait)) return []
+      const result = await ensureClient().request<unknown>('workspace/symbol', { query })
+      if (!Array.isArray(result)) return []
+      return (result as unknown[]).map(normalizeSymbol).filter((s): s is LspSymbol => s !== null)
+    },
+
+    async hover(path: string, line: number, character: number): Promise<{ contents: string[] } | null> {
+      const doc = docs.get(path)
+      if (!doc || !(await readyWait)) return null
+      const result = await ensureClient().request<{ contents?: unknown; range?: unknown } | null>(
+        'textDocument/hover',
+        { textDocument: { uri: doc.uri }, position: { line, character } },
+      )
+      if (!result || !result.contents) return null
+      return { contents: stringifyHoverContents(result.contents) }
+    },
+
+    async dispose(): Promise<void> {
+      disposed = true
+      resolveReady?.(false)
+      resolveReady = null
+      if (client) {
+        await client.shutdown().catch(() => {})
+        client = null
+      }
+      if (transport) {
+        transport.dispose()
+        transport = null
+      }
+      setPhase('stopped')
+    },
+  }
+  return server
+}
+
+/** 归一化 definition/references 结果（Location | Location[] | LocationLink[]）。 */
+function normalizeLocations(result: unknown): LspLocation[] {
+  if (!Array.isArray(result)) return []
+  const out: LspLocation[] = []
+  for (const item of result) {
+    if (!item || typeof item !== 'object') continue
+    const obj = item as { uri?: unknown; range?: unknown; targetUri?: unknown; targetRange?: unknown; targetSelectionRange?: unknown }
+    const uri = typeof obj.targetUri === 'string' ? obj.targetUri : typeof obj.uri === 'string' ? obj.uri : ''
+    const range = (obj.targetRange ?? obj.range) as { start?: { line?: unknown; character?: unknown }; end?: { line?: unknown; character?: unknown } } | undefined
+    if (!uri || !range || !range.start || !range.end) continue
+    out.push({
+      uri,
+      range: {
+        start: { line: toInt(range.start.line), character: toInt(range.start.character) },
+        end: { line: toInt(range.end.line), character: toInt(range.end.character) },
+      },
+    })
+  }
+  return out
+}
+
+/** 归一化 documentSymbol/workspaceSymbol 结果（DocumentSymbol | SymbolInformation）。 */
+function normalizeSymbol(item: unknown): LspSymbol | null {
+  if (!item || typeof item !== 'object') return null
+  const obj = item as {
+    name?: unknown
+    kind?: unknown
+    detail?: unknown
+    containerName?: unknown
+    range?: { start?: unknown; end?: unknown }
+    selectionRange?: { start?: unknown; end?: unknown }
+    children?: unknown
+    location?: { uri?: unknown; range?: unknown }
+  }
+  if (typeof obj.name !== 'string') return null
+  const selection = obj.selectionRange ?? (obj.location && (obj.location as { range?: unknown }).range)
+  const range = obj.range ?? selection
+  if (!range || typeof range !== 'object') return null
+  const r = range as { start?: { line?: unknown; character?: unknown }; end?: { line?: unknown; character?: unknown } }
+  if (!r.start || !r.end) return null
+  const symbol: LspSymbol = {
+    name: obj.name,
+    kind: toInt(obj.kind),
+    range: { start: { line: toInt((r.start as { line?: unknown }).line), character: toInt((r.start as { character?: unknown }).character) }, end: { line: toInt((r.end as { line?: unknown }).line), character: toInt((r.end as { character?: unknown }).character) } },
+    selectionRange: selection
+      ? { start: { line: toInt(((selection as { start?: { line?: unknown } }).start as { line?: unknown } | undefined)?.line ?? toInt((r.start as { line?: unknown }).line)), character: toInt(((selection as { start?: { character?: unknown } }).start as { character?: unknown } | undefined)?.character ?? toInt((r.start as { character?: unknown }).character)) }, end: { line: toInt(((selection as { end?: { line?: unknown } }).end as { line?: unknown } | undefined)?.line ?? toInt((r.end as { line?: unknown }).line)), character: toInt(((selection as { end?: { character?: unknown } }).end as { character?: unknown } | undefined)?.character ?? toInt((r.end as { character?: unknown }).character)) } }
+      : { start: { line: toInt((r.start as { line?: unknown }).line), character: toInt((r.start as { character?: unknown }).character) }, end: { line: toInt((r.end as { line?: unknown }).line), character: toInt((r.end as { character?: unknown }).character) } },
+  }
+  if (typeof obj.detail === 'string' && obj.detail) symbol.detail = obj.detail
+  if (typeof obj.containerName === 'string' && obj.containerName) symbol.containerName = obj.containerName
+  if (Array.isArray(obj.children)) {
+    const kids = obj.children.map(normalizeSymbol).filter((s): s is LspSymbol => s !== null)
+    if (kids.length) symbol.children = kids
+  }
+  return symbol
+}
+
+/** hover contents → 文本行（MarkupContent | MarkedString | MarkedString[]）。 */
+function stringifyHoverContents(contents: unknown): string[] {
+  if (typeof contents === 'string') return [contents]
+  if (Array.isArray(contents)) return contents.map(stringifyHoverContents).flat().filter(Boolean)
+  if (contents && typeof contents === 'object') {
+    const value = (contents as { value?: unknown }).value
+    if (typeof value === 'string') return [value]
+  }
+  return []
+}
+
+function toInt(value: unknown): number {
+  const n = Number(value)
+  return Number.isFinite(n) ? Math.max(0, Math.floor(n)) : 0
+}

package/src/lsp/settings.ts

@@ -0,0 +1,44 @@
+/**
+ * dsh-vscode-mode host — LSP 配置设置 section 安装（动态依赖，缺失不抛错）。
+ * ns：dsh-vscode-mode.languageServers；每语言 { enabled, command, path }。
+ * 作者 ddj 2026-08-27
+ */
+import type { Ctx } from '../store.js'
+import { LSP_LANGUAGES, LSP_SETTINGS_NS, type LspConfig } from './config.js'
+import { loadSettingsDeps, type SettingsDeps } from '../fileOpenSettings.js'
+
+/**
+ * 安装 LSP 设置 section。
+ * @author ddj 2026年08月27号
+ * @param ctx DSH 上下文
+ * @param entry 初始配置
+ * @returns 是否成功安装
+ */
+export async function installLspSettingsSection(ctx: Ctx, entry: LspConfig): Promise<boolean> {
+  const deps = await loadSettingsDeps()
+  if (!deps) return false
+  try {
+    // schemastery 无 .optional()，对象字段默认即可选；.default 必给避免 undefined 覆盖
+    const z = deps.z
+    const langShape: Record<string, unknown> = {}
+    for (const lang of LSP_LANGUAGES) {
+      langShape[lang] = z.object({
+        enabled: z.boolean(),
+        command: z.string(),
+        path: z.string(),
+      }).default({})
+    }
+    const schema = z.object(langShape).default({})
+    deps.installSettingsSection(ctx, LSP_SETTINGS_NS, schema, entry, {
+      setSource: () => {},
+      onChange: () => {},
+    })
+    return true
+  } catch (error) {
+    // 设置 section 安装失败不致命：降级为无设置 UI，LSP 核心功能不受影响
+    console.error('[dsh-vscode-mode] LSP 设置 section 安装失败：' + String(error))
+    return false
+  }
+}
+
+export type { SettingsDeps }

package/src/lsp/transport.ts

@@ -0,0 +1,143 @@
+/**
+ * dsh-vscode-mode host — LSP 语言服务器进程传输层。
+ * 基于 node:child_process.spawn（stdio pipe 双向流）。刻意不用 DSH ctx.subprocess
+ * 抽象：LSP 需要持续写 stdin + 流式读 stdout，而该抽象 stdin 不可写、输出为一次性收集。
+ * 作者 ddj 2026-08-27
+ */
+import { spawn, type ChildProcess } from 'node:child_process'
+import { createFrameParser } from './jsonrpc.js'
+
+const STDERR_CAP = 256 << 10
+
+export interface TransportSpec {
+  argv: string[]
+  cwd?: string
+  env?: Record<string, string>
+}
+
+export interface Transport {
+  /** 写一行帧到 stdin（自动加换行）。 */
+  write(chunk: Buffer): boolean
+  /** 推送 stdout 解析出的原始消息（内部由帧解析器调用）。 */
+  onMessage: ((message: unknown) => void) | null
+  /** stderr 收集缓冲（有界，供诊断）。 */
+  stderr(): string
+  /** 进程退出/崩溃回调（code/signal）。 */
+  onExit: ((code: number | null, signal: string | null) => void) | null
+  /** 优雅关闭后强杀（Windows 下连带进程树）。 */
+  dispose(): void
+  /** 是否仍存活。 */
+  readonly alive: boolean
+  readonly pid: number | undefined
+}
+
+const running = new Set<ChildProcess>()
+
+/** 当前仍在运行的 LSP 子进程（供 disposeAll / 诊断）。 */
+export function liveChildren(): ReadonlySet<ChildProcess> {
+  return running
+}
+
+/**
+ * 启动语言服务器进程。
+ * @author ddj 2026年08月27号
+ * @param spec 启动参数（argv 数组，不经 shell，Windows 引号安全）
+ * @param onMessage stdout 消息回调
+ * @param logger 诊断日志（可选）
+ * @returns 传输句柄
+ */
+export function spawnServer(spec: TransportSpec, onMessage: (message: unknown) => void, logger?: (line: string) => void): Transport {
+  const { argv, cwd, env } = spec
+  const child = spawn(argv[0], argv.slice(1), {
+    cwd,
+    env: { ...process.env, ...env },
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+  })
+  running.add(child)
+  let stderrBuf = Buffer.alloc(0)
+  let alive = true
+  const parser = createFrameParser()
+
+  child.stderr.on('data', (chunk: Buffer) => {
+    if (stderrBuf.length < STDERR_CAP) {
+      stderrBuf = Buffer.concat([stderrBuf, chunk], Math.min(stderrBuf.length + chunk.length, STDERR_CAP))
+    }
+    logger?.(chunk.toString('utf8'))
+  })
+
+  let exited = false
+  const emitExit = (code: number | null, signal: string | null): void => {
+    if (exited) return
+    exited = true
+    alive = false
+    running.delete(child)
+    transport.onExit?.(code, signal)
+  }
+  child.on('error', (error) => {
+    logger?.('spawn error: ' + String(error))
+    emitExit(null, null)
+  })
+  child.on('exit', (code, signal) => emitExit(code, signal))
+  child.on('close', (code, signal) => emitExit(code, signal))
+
+  const transport: Transport = {
+    write(chunk: Buffer): boolean {
+      if (!alive || !child.stdin.writable) return false
+      child.stdin.write(chunk)
+      return true
+    },
+    onMessage,
+    stderr(): string {
+      return stderrBuf.toString('utf8')
+    },
+    onExit: null,
+    dispose(): void {
+      if (!alive) return
+      // 先 SIGTERM 让服务器有机会清理，1.5s 后强杀进程树
+      child.kill()
+      const timer = setTimeout(() => {
+        if (!alive) return
+        alive = false
+        running.delete(child)
+        try {
+          if (process.platform === 'win32') {
+            spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' })
+          } else {
+            child.kill('SIGKILL')
+          }
+        } catch (error) {
+          logger?.('force kill error: ' + String(error))
+        }
+      }, 1500)
+      timer.unref?.()
+    },
+    get alive() {
+      return alive
+    },
+    get pid() {
+      return child.pid
+    },
+  }
+  // stdout 帧解析 → onMessage（LSP 响应/通知；onMessage 由 client 接管后动态生效）
+  child.stdout.on('data', (chunk: Buffer) => {
+    for (const message of parser.push(chunk)) transport.onMessage?.(message)
+  })
+  return transport
+}
+
+/** 强杀全部运行中的 LSP 子进程（插件卸载/退出用）。 */
+export function disposeAllServers(): void {
+  for (const child of running) {
+    try {
+      if (process.platform === 'win32' && child.pid) {
+        spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' })
+      } else {
+        child.kill('SIGKILL')
+      }
+    } catch (error) {
+      /* 忽略单个清理失败 */
+    }
+  }
+  running.clear()
+}

package/src/lsp/uri.ts

@@ -0,0 +1,62 @@
+/**
+ * dsh-vscode-mode host — 路径 ↔ file:// URI 转换（纯函数，node 可测）。
+ * LSP 的 uri 字段必须是 file:// 绝对 URI；客户端 Monaco 用 edrv:///<encodeURI(path)>。
+ * 作者 ddj 2026-08-27
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { isAbsolute, resolve as resolvePath } from 'node:path'
+
+/**
+ * 绝对路径 → file:// URI（Windows 盘符保留：D:/x → file:///D:/x）。
+ * @author ddj 2026年08月27号
+ * @param absPath 绝对路径（正/反斜杠均可）
+ * @returns file:// URI
+ */
+export function pathToFileUri(absPath: string): string {
+  const normalized = absPath.replace(/\\/g, '/')
+  const drive = /^([A-Za-z]:)(?:\/(.*))?$/.exec(normalized)
+  if (drive) {
+    const tail = drive[2] ? '/' + drive[2].split('/').map(encodeURIComponent).join('/') : ''
+    return 'file:///' + drive[1] + tail
+  }
+  return pathToFileURL(normalized).toString()
+}
+
+/**
+ * file:// URI → 绝对路径（Windows file:///C:/x → C:\x）。
+ * @author ddj 2026年08月27号
+ * @param uri file:// URI
+ * @returns 绝对路径
+ */
+export function fileUriToPath(fileUri: string): string {
+  try {
+    return fileURLToPath(fileUri)
+  } catch (error) {
+    return String(error)
+  }
+}
+
+/**
+ * 将（可能相对的）路径解析为绝对路径后转 file:// URI。
+ * @author ddj 2026年08月27号
+ * @param path 相对或绝对路径
+ * @param cwd 解析相对路径的基准（可选）
+ * @returns file:// URI
+ */
+export function resolveToFileUri(path: string, cwd?: string): string {
+  const abs = isAbsolute(path) ? path : cwd ? resolvePath(cwd, path) : resolvePath(path)
+  return pathToFileUri(abs)
+}
+
+/**
+ * 判定绝对路径是否在给定根目录（含）内。
+ * @author ddj 2026年08月27号
+ * @param root 根目录绝对路径
+ * @param target 目标绝对路径
+ * @returns 是否在根内
+ */
+export function isInside(root: string, target: string): boolean {
+  const r = root.replace(/\\/g, '/').replace(/\/+$/, '') + '/'
+  const t = target.replace(/\\/g, '/')
+  return t === r.slice(0, -1) || t.startsWith(r)
+}

package/src/lsp/zip.ts

@@ -0,0 +1,82 @@
+/**
+ * dsh-vscode-mode host — 纯 Node ZIP 解压（零依赖，跨平台）。
+ * 供 extmgr 解包 VSIX 使用；只实现 VSIX 需要的子集：
+ * 读取 EOCD + 中央目录，支持 stored(0)/deflate(8)，忽略 zip64（VSIX < 4GB）。
+ * 作者 ddj 2026-08-27
+ */
+import { inflateRawSync } from 'node:zlib'
+
+/** 单条解压结果：相对路径 + 内容（目录条目 path 以 / 结尾）。 */
+export interface ZipEntry {
+  path: string
+  data: Buffer
+  isDirectory: boolean
+}
+
+const EOCD_SIG = 0x06054b50
+const CDIR_SIG = 0x02014b50
+const LHDR_SIG = 0x04034b50
+
+/**
+ * 解析 ZIP 缓冲区 → 条目列表（不解压内容，仅元数据）。
+ * @author ddj 2026年08月27号
+ * @param buf zip 字节
+ * @returns 条目元数据
+ */
+export function zipEntries(buf: Buffer): { name: string; method: number; compressed: number; uncompressed: number; localOffset: number }[] {
+  const eocd = findEocd(buf)
+  if (eocd < 0) throw new Error('不是有效的 ZIP 文件（找不到 EOCD）')
+  const total = buf.readUInt16LE(eocd + 10)
+  let offset = buf.readUInt32LE(eocd + 16)
+  const out: { name: string; method: number; compressed: number; uncompressed: number; localOffset: number }[] = []
+  for (let i = 0; i < total; i++) {
+    if (buf.readUInt32LE(offset) !== CDIR_SIG) throw new Error('ZIP 中央目录损坏')
+    const method = buf.readUInt16LE(offset + 10)
+    const compressed = buf.readUInt32LE(offset + 20)
+    const uncompressed = buf.readUInt32LE(offset + 24)
+    const nameLen = buf.readUInt16LE(offset + 28)
+    const extraLen = buf.readUInt16LE(offset + 30)
+    const commentLen = buf.readUInt16LE(offset + 32)
+    const localOffset = buf.readUInt32LE(offset + 42)
+    const name = buf.subarray(offset + 46, offset + 46 + nameLen).toString('utf8')
+    out.push({ name, method, compressed, uncompressed, localOffset })
+    offset += 46 + nameLen + extraLen + commentLen
+  }
+  return out
+}
+
+/**
+ * 解压 ZIP → 条目列表（目录条目含尾部 /）。
+ * @author ddj 2026年08月27号
+ * @param buf zip 字节
+ * @returns 条目（含内容）
+ */
+export function unzip(buf: Buffer): ZipEntry[] {
+  const metas = zipEntries(buf)
+  const out: ZipEntry[] = []
+  for (const meta of metas) {
+    const lh = meta.localOffset
+    if (buf.readUInt32LE(lh) !== LHDR_SIG) throw new Error('ZIP 本地头损坏：' + meta.name)
+    const nameLen = buf.readUInt16LE(lh + 26)
+    const extraLen = buf.readUInt16LE(lh + 28)
+    const dataStart = lh + 30 + nameLen + extraLen
+    const isDir = /\/$/.test(meta.name)
+    let data: Buffer = Buffer.alloc(0)
+    if (!isDir && meta.compressed > 0) {
+      const raw = buf.subarray(dataStart, dataStart + meta.compressed)
+      data = meta.method === 8 ? Buffer.from(inflateRawSync(raw)) : meta.method === 0 ? Buffer.from(raw) : Buffer.alloc(0)
+    }
+    out.push({ path: meta.name, data, isDirectory: isDir })
+  }
+  return out
+}
+
+/** 定位 EOCD（从尾部向前扫，容忍尾部注释）。 */
+function findEocd(buf: Buffer): number {
+  const maxScan = Math.min(buf.length, 65557)
+  for (let i = buf.length - 22; i >= buf.length - maxScan; i--) {
+    if (i < 0) break
+    if (buf.readUInt32LE(i) === EOCD_SIG) return i
+  }
+  return -1
+}