dsh-vscode-mode 0.1.32 → 0.1.35

package/src/lsp/client.ts

@@ -0,0 +1,205 @@
+/**
+ * dsh-vscode-mode host — LSP 客户端（JSON-RPC over stdio）。
+ * 职责：请求/通知/握手/超时/服务器端请求处理/生命周期。transport 无关性：
+ * 只依赖 write/onMessage 契约，便于单测时注入假传输。
+ * 作者 ddj 2026-08-27
+ */
+import { createFrameParser, encodeMessage, requestMessage, notifyMessage } from './jsonrpc.js'
+import type { LspServerCapabilities } from '../shared/lsp.js'
+
+export interface LspClientEvents {
+  onReady?: (capabilities: LspServerCapabilities) => void
+  onExit?: (code: number | null, signal: string | null) => void
+  onLog?: (line: string) => void
+  onProgress?: (params: unknown) => void
+}
+
+const DEFAULT_TIMEOUT_MS = 20_000
+
+export class LspError extends Error {
+  code: number
+  constructor(code: number, message: string) {
+    super(message)
+    this.code = code
+  }
+}
+
+export interface LspClientTransport {
+  write(chunk: Buffer): boolean
+  dispose(): void
+  readonly alive: boolean
+  onMessage: ((message: unknown) => void) | null
+  onExit: ((code: number | null, signal: string | null) => void) | null
+}
+
+export interface LspClient {
+  request<T>(method: string, params: unknown, timeoutMs?: number): Promise<T>
+  notify(method: string, params: unknown): void
+  initialize(rootUri: string, workspaceFolders: string[]): Promise<LspServerCapabilities>
+  shutdown(): Promise<void>
+  readonly alive: boolean
+}
+
+/**
+ * 创建 LSP 客户端。
+ * @author ddj 2026年08月27号
+ * @param transport 传输句柄（write/onMessage/alive/dispose）
+ * @param events 事件回调
+ * @returns LSP 客户端
+ */
+export function createLspClient(
+  transport: LspClientTransport,
+  events: LspClientEvents = {},
+): LspClient {
+  let nextId = 1
+  let alive = transport.alive
+  const pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>()
+  let serverCapabilities: LspServerCapabilities = { definition: false, references: false, documentSymbol: false, workspaceSymbol: false, hover: false }
+
+  const log = (line: string): void => events.onLog?.(line)
+  const parser = createFrameParser()
+
+  transport.onMessage = (message: unknown): void => {
+    const msg = message as { id?: unknown; method?: unknown; params?: unknown; result?: unknown; error?: unknown }
+    // 服务器端请求/通知带 method（请求还带 id）；响应带 id + result/error、无 method。先判 method 再判 id。
+    if (typeof msg.method === 'string') {
+      if (msg.method === '$/progress') events.onProgress?.(msg.params)
+      void handleServerRequest(msg as { method: string; params?: unknown; id?: unknown })
+      return
+    }
+    if (typeof msg.id === 'number' || typeof msg.id === 'string') {
+      const entry = pending.get(Number(msg.id))
+      if (!entry) return
+      pending.delete(Number(msg.id))
+      clearTimeout(entry.timer)
+      if (msg.error) {
+        const err = msg.error as { code?: number; message?: string }
+        entry.reject(new LspError(err.code ?? -32000, err.message ?? 'LSP error'))
+      } else {
+        entry.resolve(msg.result)
+      }
+    }
+  }
+
+  /** 服务器端请求：消息/日志类打日志，配置/能力类回 result:null，其余回 method not found。 */
+  const handleServerRequest = async (msg: { method: string; params?: unknown; id?: unknown }): Promise<void> => {
+    const { method, params, id } = msg
+    const respond = (payload: Record<string, unknown>): void => {
+      transport.write(encodeMessage(payload))
+    }
+    try {
+      if (method === 'window/logMessage' || method === 'window/showMessage' || method === 'window/showMessageRequest') {
+        const p = params as { type?: number; message?: string }
+        log('[server ' + (p?.type ?? '') + '] ' + String(p?.message ?? ''))
+        if (id !== undefined) respond({ jsonrpc: '2.0', id, result: null })
+        return
+      }
+      if (method === 'workspace/configuration') {
+        const p = params as { items?: unknown[] }
+        const items = Array.isArray(p?.items) ? p.items.map(() => null) : []
+        if (id !== undefined) respond({ jsonrpc: '2.0', id, result: items })
+        return
+      }
+      // 客户端能力协商类：标准行为是确认（result:null），否则部分服务器（如 LuaLS）会中断工作区初始化
+      if (method === 'window/workDoneProgress/create' || method === 'client/registerCapability' || method === 'workspace/workspaceFolders') {
+        if (id !== undefined) respond({ jsonrpc: '2.0', id, result: null })
+        return
+      }
+      if (id !== undefined) {
+        respond({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found: ' + method } })
+      }
+    } catch (error) {
+      log('server request handler error: ' + String(error))
+      if (id !== undefined) {
+        respond({ jsonrpc: '2.0', id, error: { code: -32603, message: String(error) } })
+      }
+    }
+  }
+
+  const transportExit = transport.onExit
+  transport.onExit = (code, signal): void => {
+    alive = false
+    for (const entry of pending.values()) {
+      clearTimeout(entry.timer)
+      entry.reject(new Error('LSP 服务器已退出（' + String(code) + '/' + String(signal) + '）'))
+    }
+    pending.clear()
+    events.onExit?.(code, signal)
+    transportExit?.(code, signal)
+  }
+
+  const client: LspClient = {
+    async request<T>(method: string, params: unknown, timeoutMs = DEFAULT_TIMEOUT_MS): Promise<T> {
+      if (!alive) throw new Error('LSP 服务器未运行')
+      const id = nextId++
+      return new Promise<T>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id)
+          reject(new Error('LSP 请求超时：' + method + '（' + timeoutMs + 'ms）'))
+        }, timeoutMs)
+        pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer })
+        transport.write(encodeMessage(requestMessage(id, method, params)))
+      })
+    },
+    notify(method: string, params: unknown): void {
+      if (!alive) return
+      transport.write(encodeMessage(notifyMessage(method, params)))
+    },
+    async initialize(rootUri: string, workspaceFolders: string[]): Promise<LspServerCapabilities> {
+      const init = await client.request<{
+        capabilities?: {
+          definitionProvider?: unknown
+          referencesProvider?: unknown
+          documentSymbolProvider?: unknown
+          workspaceSymbolProvider?: unknown
+          hoverProvider?: unknown
+        }
+      }>('initialize', {
+        processId: process.pid,
+        rootUri: rootUri || null,
+        rootPath: null,
+        workspaceFolders: workspaceFolders.length
+          ? workspaceFolders.map((uri) => ({ uri, name: uri }))
+          : null,
+        capabilities: {
+          window: { workDoneProgress: true },
+          workspace: { configuration: true },
+          textDocument: {
+            synchronization: { dynamicRegistration: false, willSave: false, didSave: true },
+            definition: { dynamicRegistration: false },
+            references: { dynamicRegistration: false },
+            documentSymbol: { dynamicRegistration: false },
+            hover: { dynamicRegistration: false },
+          },
+        },
+      })
+      const caps = init?.capabilities ?? {}
+      serverCapabilities = {
+        definition: Boolean(caps.definitionProvider),
+        references: Boolean(caps.referencesProvider),
+        documentSymbol: Boolean(caps.documentSymbolProvider),
+        workspaceSymbol: Boolean(caps.workspaceSymbolProvider),
+        hover: Boolean(caps.hoverProvider),
+      }
+      client.notify('initialized', {})
+      events.onReady?.(serverCapabilities)
+      return serverCapabilities
+    },
+    async shutdown(): Promise<void> {
+      try {
+        await client.request<unknown>('shutdown', null, 3000)
+      } catch (error) {
+        log('shutdown: ' + String(error))
+      }
+      try {
+        client.notify('exit', null)
+      } catch (error) {
+        log('exit: ' + String(error))
+      }
+    },
+    get alive() {
+      return alive
+    },
+  }
+  return client
+}

package/src/lsp/config.ts

@@ -0,0 +1,107 @@
+/**
+ * dsh-vscode-mode host — LSP 配置读取与 provider 解析装配。
+ * 配置来源优先级：settings 持久化（ns dsh-vscode-mode.languageServers）> 插件组合配置 > 默认。
+ * 作者 ddj 2026-08-27
+ */
+import type { Ctx } from '../store.js'
+import { PROVIDER_RESOLVERS, type LspProviderSpec } from './providers.js'
+
+/** 单语言配置。 */
+export interface LspLangConfig {
+  enabled?: boolean
+  command?: string
+  path?: string
+}
+
+/** LSP 配置（按语言）。 */
+export interface LspConfig {
+  lua?: LspLangConfig
+  csharp?: LspLangConfig
+  [languageId: string]: LspLangConfig | undefined
+}
+
+export const LSP_SETTINGS_NS = 'dsh-vscode-mode.languageServers'
+export const LSP_LANGUAGES = ['lua', 'csharp'] as const
+
+function sanitizeLang(raw: unknown): LspLangConfig | undefined {
+  if (!raw || typeof raw !== 'object') return undefined
+  const obj = raw as Record<string, unknown>
+  const out: LspLangConfig = {}
+  if (typeof obj.enabled === 'boolean') out.enabled = obj.enabled
+  if (typeof obj.command === 'string') out.command = obj.command
+  if (typeof obj.path === 'string') out.path = obj.path
+  return out
+}
+
+/** 从插件组合配置读取。 */
+export function configFromPlugin(config: unknown): LspConfig {
+  const raw = (config as { languageServers?: unknown } | undefined)?.languageServers
+  if (!raw || typeof raw !== 'object') return {}
+  const out: LspConfig = {}
+  for (const lang of LSP_LANGUAGES) {
+    const v = sanitizeLang((raw as Record<string, unknown>)[lang])
+    if (v) out[lang] = v
+  }
+  return out
+}
+
+/** 从 settings 描述符读取（无 settings 服务/无该 section → {}）。 */
+export function configFromSettings(ctx: Ctx): LspConfig {
+  try {
+    const settings = ctx.get('settings')
+    const descriptor = settings?.describe?.({ redactSecrets: true })?.find((item: { ns?: string }) => item.ns === LSP_SETTINGS_NS)
+    const value = descriptor?.value
+    if (!value || typeof value !== 'object') return {}
+    const out: LspConfig = {}
+    for (const lang of LSP_LANGUAGES) {
+      const v = sanitizeLang((value as Record<string, unknown>)[lang])
+      if (v) out[lang] = v
+    }
+    return out
+  } catch (error) {
+    return {}
+  }
+}
+
+/** 合并配置：settings 覆盖插件配置。 */
+export function mergeConfig(a: LspConfig, b: LspConfig): LspConfig {
+  const out: LspConfig = { ...a }
+  for (const lang of LSP_LANGUAGES) {
+    const av = a[lang]
+    const bv = b[lang]
+    if (bv) out[lang] = { ...av, ...bv }
+    else if (av) out[lang] = av
+  }
+  return out
+}
+
+/**
+ * 解析某语言的 provider spec（合并配置后）。
+ * @author ddj 2026年08月27号
+ * @param ctx DSH 上下文
+ * @param pluginConfig 插件组合配置
+ * @param languageId 语言 id
+ * @returns provider 规格
+ */
+export function resolveProviderSpec(ctx: Ctx, pluginConfig: unknown, languageId: string): LspProviderSpec {
+  const resolver = PROVIDER_RESOLVERS[languageId]
+  if (!resolver) return { languageId, kind: 'none', argv: [], ready: false, reason: '不支持的语言：' + languageId }
+  const merged = mergeConfig(configFromPlugin(pluginConfig), configFromSettings(ctx))
+  const lang = merged[languageId]
+  if (lang && lang.enabled === false) {
+    return { languageId, kind: 'none', argv: [], ready: false, reason: '已在设置中禁用' }
+  }
+  return resolver({ command: lang?.command, path: lang?.path })
+}
+
+/** 语言 → 扩展名（供客户端判断是否触发 LSP）。 */
+export function langOfPath(path: string): string | null {
+  const base = String(path || '').split(/[\\/]/).pop() || ''
+  const dot = base.lastIndexOf('.')
+  if (dot <= 0) return null
+  const ext = base.slice(dot + 1).toLowerCase()
+  for (const [lang, exts] of Object.entries({ lua: ['lua'], csharp: ['cs', 'csx'] })) {
+    if (exts.includes(ext)) return lang
+  }
+  return null
+}

package/src/lsp/extmgr.ts

@@ -0,0 +1,208 @@
+/**
+ * dsh-vscode-mode host — VSIX 扩展管理器（extmgr）。
+ * 管理 DSH 专属扩展目录（~/.dsh/dsh-vscode-mode/extensions/），支持：
+ * 本地 .vsix 安装、Open VSX 市场搜索/下载安装、卸载、更新检测与安装。
+ * 已装扩展作为 LSP provider 的"扩展源"（kind=extension），见 providers.ts。
+ * 作者 ddj 2026-08-27
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { unzip } from './zip.js'
+import { dshHome, PLUGIN_ID } from '../paths.js'
+
+/** 单个已装扩展信息（edrv.lsp.ext.list 载荷元素）。 */
+export interface ExtInfo {
+  id: string        // publisher.name
+  namespace: string
+  name: string
+  version: string
+  displayName?: string
+  description?: string
+  dirName: string   // 目录名 publisher.name-version
+  dir: string       // 绝对路径
+}
+
+/** Open VSX 市场搜索结果（edrv.lsp.ext.market 载荷元素）。 */
+export interface MarketItem {
+  namespace: string
+  name: string
+  id: string
+  version: string
+  displayName?: string
+  description?: string
+  download?: string
+}
+
+const OPEN_VSX = 'https://open-vsx.org'
+const META_FILE = 'package.json'
+/** 当前平台（与 VSCode platform 命名对齐：win32-x64/darwin-arm64/linux-x64）。 */
+const PLATFORM = (() => {
+  if (process.platform === 'win32') return process.arch === 'arm64' ? 'win32-arm64' : 'win32-x64'
+  if (process.platform === 'darwin') return process.arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64'
+  return process.arch === 'arm64' ? 'linux-arm64' : 'linux-x64'
+})()
+
+/** DSH 专属扩展目录。 */
+export function extensionsRoot(home = dshHome()): string {
+  return join(home, PLUGIN_ID, 'extensions')
+}
+
+/** 从 VSIX 字节里读 extension/package.json 清单。 */
+export function vsixManifest(vsix: Buffer): Record<string, unknown> {
+  for (const entry of unzip(vsix)) {
+    if (entry.path === 'extension/package.json' || entry.path === 'extension\\package.json') {
+      return JSON.parse(entry.data.toString('utf8')) as Record<string, unknown>
+    }
+  }
+  throw new Error('VSIX 缺少 extension/package.json')
+}
+
+/**
+ * 解包 VSIX 到目录（仅取 extension/ 子树，剥前缀；返回清单）。
+ * @author ddj 2026年08月27号
+ * @param vsix vsix 字节
+ * @param dest 目标目录（已存在则先清空）
+ * @returns 清单对象
+ */
+export function unpackVsix(vsix: Buffer, dest: string): Record<string, unknown> {
+  rmSync(dest, { recursive: true, force: true })
+  mkdirSync(dest, { recursive: true })
+  let manifest: Record<string, unknown> | null = null
+  for (const entry of unzip(vsix)) {
+    const rel = entry.path.replace(/^extension[\\/]/, '')
+    if (!rel || entry.path.startsWith('..')) continue
+    const safe = rel.split(/[\\/]/).filter((part) => part && part !== '..' && part !== '.').join('/')
+    if (!safe) continue
+    const target = join(dest, ...safe.split('/'))
+    if (entry.isDirectory) {
+      mkdirSync(target, { recursive: true })
+      continue
+    }
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, entry.data)
+    if (rel === 'package.json') manifest = JSON.parse(entry.data.toString('utf8')) as Record<string, unknown>
+  }
+  if (!manifest) throw new Error('VSIX 解包后缺少 package.json')
+  return manifest
+}
+
+/** 扩展信息（清单 + 目录）。 */
+export function extInfoOf(manifest: Record<string, unknown>, dir: string): ExtInfo {
+  const namespace = String(manifest.publisher ?? 'unknown')
+  const name = String(manifest.name ?? 'unknown')
+  const version = String(manifest.version ?? '0.0.0')
+  return {
+    id: namespace + '.' + name,
+    namespace,
+    name,
+    version,
+    displayName: typeof manifest.displayName === 'string' ? manifest.displayName : undefined,
+    description: typeof manifest.description === 'string' ? manifest.description : undefined,
+    dirName: basename(dir),
+    dir,
+  }
+}
+
+/** 安装本地 .vsix 文件（已存在同 id 则升级替换）。 */
+export async function installVsixFile(vsixPath: string, home = dshHome()): Promise<ExtInfo> {
+  const vsix = readFileSync(vsixPath)
+  return installVsixBuffer(vsix, home)
+}
+
+/** 安装 VSIX 字节（解包进 extensionsRoot；同名旧版本先清）。 */
+export function installVsixBuffer(vsix: Buffer, home = dshHome()): ExtInfo {
+  const manifest = vsixManifest(vsix)
+  const info = extInfoOf(manifest, '')
+  const target = join(extensionsRoot(home), info.id + '-' + info.version)
+  const unpacked = unpackVsix(vsix, target)
+  return extInfoOf(unpacked, target)
+}
+/** 扫描已装扩展目录。 */
+export function listInstalled(home = dshHome()): ExtInfo[] {
+  const root = extensionsRoot(home)
+  if (!existsSync(root)) return []
+  const out: ExtInfo[] = []
+  for (const dir of readdirSync(root)) {
+    const full = join(root, dir)
+    const meta = join(full, META_FILE)
+    if (!existsSync(meta)) continue
+    try {
+      const manifest = JSON.parse(readFileSync(meta, 'utf8')) as Record<string, unknown>
+      out.push(extInfoOf(manifest, full))
+    } catch (error) {
+      /* 坏清单目录跳过 */
+    }
+  }
+  return out
+}
+
+/** 卸载扩展（按 id）。 */
+export function uninstall(id: string, home = dshHome()): boolean {
+  const target = listInstalled(home).find((e) => e.id === id)?.dir
+  if (!target) return false
+  rmSync(target, { recursive: true, force: true })
+  return true
+}
+
+/** Open VSX 单扩展元数据（latest + 下载 URL）。 */
+export async function marketGet(namespace: string, name: string, version?: string): Promise<Record<string, unknown> | null> {
+  const path = version ? namespace + '/' + name + '/' + version : namespace + '/' + name
+  const res = await fetch(OPEN_VSX + '/api/' + path, { headers: { accept: 'application/json' } })
+  if (!res.ok) return null
+  return (await res.json()) as Record<string, unknown>
+}
+
+/** Open VSX 搜索。 */
+export async function marketSearch(query: string, size = 12): Promise<MarketItem[]> {
+  const url = OPEN_VSX + '/api/-/search?query=' + encodeURIComponent(query) + '&size=' + size
+  const res = await fetch(url, { headers: { accept: 'application/json' } })
+  if (!res.ok) throw new Error('市场搜索失败：HTTP ' + res.status)
+  const data = (await res.json()) as { extensions?: unknown[] }
+  return ((data.extensions ?? []) as Record<string, unknown>[]).map((item) => ({
+    namespace: String(item.namespace ?? ''),
+    name: String(item.name ?? ''),
+    id: String(item.namespace ?? '') + '.' + String(item.name ?? ''),
+    version: String(item.version ?? ''),
+    displayName: typeof item.displayName === 'string' ? item.displayName : undefined,
+    description: typeof item.description === 'string' ? item.description : undefined,
+    download: typeof (item.files as { download?: unknown } | undefined)?.download === 'string' ? (item.files as { download: string }).download : undefined,
+  }))
+}
+
+/** 平台匹配的 VSIX 下载 URL（探测平台变体，失败回退 API 默认）。 */
+export async function resolveDownload(namespace: string, name: string, version: string): Promise<string> {
+  const candidate = OPEN_VSX + '/api/' + namespace + '/' + name + '/' + PLATFORM + '/' + version +
+    '/file/' + namespace + '.' + name + '-' + version + '@' + PLATFORM + '.vsix'
+  try {
+    const head = await fetch(candidate, { method: 'HEAD' })
+    if (head.ok) return candidate
+  } catch (error) {
+    /* 探测失败走默认 */
+  }
+  const meta = await marketGet(namespace, name, version)
+  const download = (meta?.files as { download?: unknown } | undefined)?.download
+  if (typeof download === 'string') return download
+  throw new Error('市场未提供 ' + namespace + '.' + name + '@' + version + ' 的下载地址')
+}
+
+/** 从 Open VSX 安装/更新扩展。 */
+export async function installFromMarket(namespace: string, name: string, version?: string): Promise<ExtInfo> {
+  const meta = await marketGet(namespace, name, version)
+  if (!meta) throw new Error('市场找不到 ' + namespace + '.' + name + (version ? '@' + version : ''))
+  const ver = version ?? String(meta.version ?? '')
+  const url = await resolveDownload(namespace, name, ver)
+  const res = await fetch(url)
+  if (!res.ok) throw new Error('下载失败：HTTP ' + res.status)
+  const vsix = Buffer.from(await res.arrayBuffer())
+  return installVsixBuffer(vsix)
+}
+
+/** 更新已装扩展（对比市场最新版；返回 null 表示已最新）。 */
+export async function updateExtension(id: string): Promise<ExtInfo | null> {
+  const installed = listInstalled().find((e) => e.id === id)
+  if (!installed) throw new Error('扩展未安装：' + id)
+  const meta = await marketGet(installed.namespace, installed.name)
+  const latest = String(meta?.version ?? '')
+  if (!latest || latest === installed.version) return null
+  return installFromMarket(installed.namespace, installed.name, latest)
+}

package/src/lsp/jsonrpc.ts

@@ -0,0 +1,86 @@
+/**
+ * dsh-vscode-mode host — LSP JSON-RPC 帧编解码（纯函数，node 可测）。
+ * LSP over stdio 用 Content-Length 帧：
+ *   Content-Length: <n>\r\n\r\n<恰好 n 字节 JSON>
+ * 导出：encodeMessage（对象→帧 Buffer）、createFrameParser（流式粘包/拆包）、parseFrame（单帧）。
+ * 作者 ddj 2026-08-27
+ */
+
+const HEADER_END = '\r\n\r\n'
+
+/** 消息头正则（仅取 Content-Length；其它头忽略）。 */
+const HEADER_RE = /^Content-Length:\s*(\d+)\s*$/im
+
+/** 将对象编码为带 Content-Length 头的帧。 */
+export function encodeMessage(message: unknown): Buffer {
+  const body = JSON.stringify(message)
+  const head = 'Content-Length: ' + Buffer.byteLength(body, 'utf8') + '\r\n\r\n'
+  return Buffer.from(head + body, 'utf8')
+}
+
+/**
+ * 尝试从 buffer 解析单个帧；成功返回 { body, rest }，数据不足返回 null。
+ * @author ddj 2026年08月27号
+ * @param buffer 已累积的字节
+ * @returns 解析结果（rest 为剩余未消费字节）
+ */
+export function parseFrame(buffer: Buffer): { body: string; rest: Buffer } | null {
+  const headEnd = buffer.indexOf(HEADER_END)
+  if (headEnd < 0) return null
+  const header = buffer.subarray(0, headEnd).toString('utf8')
+  const m = HEADER_RE.exec(header)
+  if (!m) {
+    // 非法头：丢弃直到下一个帧头，避免死循环
+    const next = buffer.indexOf('Content-Length:')
+    return next >= 0 ? parseFrame(buffer.subarray(next)) : null
+  }
+  const length = Number(m[1])
+  const bodyStart = headEnd + HEADER_END.length
+  if (buffer.length < bodyStart + length) return null
+  const body = buffer.subarray(bodyStart, bodyStart + length).toString('utf8')
+  return { body, rest: buffer.subarray(bodyStart + length) }
+}
+
+/** 帧解析器：push 数据块，吐出完整消息（可能拆包后重组、也可能一包多帧）。 */
+export function createFrameParser(): {
+  push(chunk: Buffer): unknown[]
+  clear(): void
+} {
+  let buffer: Buffer = Buffer.alloc(0)
+  return {
+    push(chunk: Buffer): unknown[] {
+      if (chunk.length) buffer = Buffer.concat([buffer, chunk]) as Buffer
+      const out: unknown[] = []
+      for (;;) {
+        const parsed = parseFrame(buffer)
+        if (!parsed) break
+        buffer = parsed.rest
+        try {
+          out.push(JSON.parse(parsed.body))
+        } catch (error) {
+          out.push({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse error: ' + String(error) }, id: null })
+        }
+      }
+      return out
+    },
+    clear(): void {
+      buffer = Buffer.alloc(0)
+    },
+  }
+}
+
+/** 构造标准 JSON-RPC 请求消息。 */
+export function requestMessage(id: number, method: string, params: unknown): Record<string, unknown> {
+  return { jsonrpc: '2.0', id, method, params }
+}
+
+/** 构造标准 JSON-RPC 通知消息（无 id，fire-and-forget）。 */
+export function notifyMessage(method: string, params: unknown): Record<string, unknown> {
+  return { jsonrpc: '2.0', method, params }
+}
+
+/** 构造标准 JSON-RPC 响应消息。 */
+export function responseMessage(id: number | string | null, result: unknown, error?: unknown): Record<string, unknown> {
+  if (error !== undefined) return { jsonrpc: '2.0', id, error }
+  return { jsonrpc: '2.0', id, result }
+}