dsh-vscode-mode 0.5.3 → 0.7.0

package/src/client/ui/commandCatalog.ts

@@ -8,6 +8,7 @@
  */
 import { hasEditorModel, hasOpenTabs } from '../editorModelState.js'
 import { svnCurrentStatus } from '../svnStatus.js'
+import { dapStore } from '../dap/store.js'
 import { svnActionOn, svnActionsFor } from '../../shared/svnActions.js'
 import type { SvnActionDef } from '../../shared/svnActions.js'
 
@@ -79,6 +80,19 @@ function prevEditorRowDef(): CommandDef {
   }
 }
 
+/**
+ * 转到行（转发 Monaco 原生 gotoLine widget；补命令栏与快捷键设置页入口）。
+ * @author ddj 2026年09月22号
+ * @returns 命令定义
+ */
+function gotoLineDef(): CommandDef {
+  return {
+    id: 'edrv.goToLine', label: '转到行', category: '导航', order: 45,
+    keybinding: 'Ctrl+G', available: needsModel,
+    run: () => emit('goToLine'),
+  }
+}
+
 /**
  * 添加选中内容为引用（把当前选区追加进对话输入框；无选区则状态栏提示）。
  * 有活动编辑器模型才可用，保证对话框内按 Ctrl+U 不被本命令吞掉。
@@ -160,6 +174,8 @@ function svnEventOf(action: SvnActionDef): string {
     add: 'svnAdd',
     revert: 'svnRevertCli',
     log: 'svnLog',
+    'create-patch': 'svnCreatePatch',
+    'diff-summarize': 'svnDiffSum',
     cleanup: 'svnCleanup',
     'tortoise-commit': 'svnTortoiseCommit',
     'tortoise-log': 'svnTortoiseLog',
@@ -261,6 +277,51 @@ export const EDITOR_COMMANDS: readonly CommandDef[] = [
   ...svnPaletteDefs(),
 ]
 
+/**
+ * 调试（DAP）命令组：全部桥接派发，EditorView 统一接线调 dapStore。
+ * 可用性：步进类仅在暂停态可用（无编辑器时不吞键）；F5 需有配置或已暂停。
+ * @author ddj 2026年09月29号
+ * @returns 命令定义数组
+ */
+function debugPaletteDefs(): CommandDef[] {
+  const phase = () => dapStore.getSnapshot().phase
+  const paused = () => phase() === 'paused'
+  const canStart = () => paused() || dapStore.getSnapshot().configs.length > 0
+  const canStop = () => phase() !== 'idle' && phase() !== 'terminated'
+  return [
+    {
+      id: 'edrv.debugToggleBreakpoint', label: '调试：切换断点（光标行）', category: '调试', order: 10,
+      keybinding: 'F9', available: needsModel,
+      run: () => emit('debugToggleBreakpoint'),
+    },
+    {
+      id: 'edrv.debugStartContinue', label: '调试：启动 / 继续', category: '调试', order: 20,
+      keybinding: 'F5', available: canStart,
+      run: () => emit('debugStartContinue'),
+    },
+    {
+      id: 'edrv.debugStepOver', label: '调试：单步跳过', category: '调试', order: 30,
+      keybinding: 'F10', available: paused,
+      run: () => emit('debugStepOver'),
+    },
+    {
+      id: 'edrv.debugStepInto', label: '调试：单步步入', category: '调试', order: 40,
+      keybinding: 'F11', available: paused,
+      run: () => emit('debugStepInto'),
+    },
+    {
+      id: 'edrv.debugStepOut', label: '调试：单步步出', category: '调试', order: 50,
+      keybinding: 'Shift+F11', available: paused,
+      run: () => emit('debugStepOut'),
+    },
+    {
+      id: 'edrv.debugStop', label: '调试：停止', category: '调试', order: 60,
+      keybinding: 'Shift+F5', available: canStop,
+      run: () => emit('debugStop'),
+    },
+  ]
+}
+
 /**
  * 桥接派发指令（无原生监听，键位由 commandBridge 统一 capture 处理）。
  * 新增「只填目录、不写监听」的编辑器指令一律放这里：键位、命令栏、设置页自动可用。
@@ -269,8 +330,10 @@ export const EDITOR_COMMANDS: readonly CommandDef[] = [
 export const BRIDGE_COMMANDS: readonly CommandDef[] = [
   nextEditorRowDef(),
   prevEditorRowDef(),
+  gotoLineDef(),
   addSelectionRefDef(),
   closeTabDef(),
+  ...debugPaletteDefs(),
 ]
 
 /**

package/src/client/ui/svnExport.ts

@@ -0,0 +1,71 @@
+/**
+ * dsh-vscode-mode client — 前端导出工具（W1-4：变更列表/日志列表 → CSV/HTML 文件下载）。
+ *
+ * 纯前端拼装：Blob + 隐式 `<a download>` 触发，不经 host、不写工作副本；
+ * CSV 前置 UTF-8 BOM 保证 Excel 直开中文不乱码；导出物只在本地，不含凭据、不外发。
+ * 下载失败（无 Blob/下载权限等）静默返回 false，由调用方决定是否提示。
+ * 作者 ddj 2026年09月20号
+ */
+
+/**
+ * 二维表 → CSV 文本（RFC 4180：含逗号/引号/换行的字段加引号包裹、内部引号翻倍；行尾 CRLF）。
+ * @author ddj 2026年09月20号
+ * @param rows 二维字符串表（表头行由调用方一并传入）
+ * @returns CSV 文本（前置 UTF-8 BOM）
+ */
+export function csvOf(rows: unknown[][]): string {
+  const esc = (cell: unknown): string => {
+    const text = String(cell ?? '')
+    return /[",\r\n]/.test(text) ? '"' + text.replaceAll('"', '""') + '"' : text
+  }
+  const body = (rows || []).map((row) => (row || []).map(esc).join(',')).join('\r\n')
+  return '\uFEFF' + body + '\r\n'
+}
+
+/**
+ * 二维表 → 简单 HTML 报表（W1-4；全部经 HTML 转义防注入，UTF-8 声明 + 内联样式）。
+ * @author ddj 2026年09月20号
+ * @param headers 表头字符串数组
+ * @param rows 二维字符串表
+ * @param caption 页面标题（可空）
+ * @returns 完整 HTML 文档文本
+ */
+export function htmlTableOf(headers: unknown[], rows: unknown[][], caption?: string): string {
+  const esc = (value: unknown): string => String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+  const head = '<tr>' + (headers || []).map((cell) => '<th>' + esc(cell) + '</th>').join('') + '</tr>'
+  const body = (rows || []).map((row) => '<tr>' + (row || []).map((cell) => '<td>' + esc(cell) + '</td>').join('') + '</tr>').join('')
+  return '<!doctype html><html><head><meta charset="utf-8"><title>' + esc(caption || '导出') + '</title>'
+    + '<style>body{font-family:system-ui,sans-serif;font-size:13px;color:#1f2933;margin:16px}'
+    + 'table{border-collapse:collapse}th,td{border:1px solid #d5dbdb;padding:2px 8px;text-align:left;vertical-align:top}'
+    + 'th{background:#f0f4f4}h3{margin:0 0 10px}</style>'
+    + '</head><body><h3>' + esc(caption || '') + '</h3><table>' + head + body + '</table></body></html>'
+}
+
+/**
+ * 文本下载（Blob + `a[download]` 一次点击；异步 revoke 免内存泄漏）。
+ * @author ddj 2026年09月20号
+ * @param filename 下载文件名（建议带扩展名）
+ * @param text 文件内容（文本直接写入，CSV 已含 BOM 由 csvOf 负责）
+ * @param mime MIME 类型（不带 charset，函数内补 utf-8）
+ * @returns 是否触发成功（false = 浏览器能力缺失，调用方可提示）
+ */
+export function downloadText(filename: string, text: string, mime: string): boolean {
+  try {
+    const blob = new Blob([text], { type: mime + ';charset=utf-8' })
+    const url = URL.createObjectURL(blob)
+    const link = document.createElement('a')
+    link.href = url
+    link.download = filename
+    document.body.appendChild(link)
+    link.click()
+    link.remove()
+    setTimeout(() => URL.revokeObjectURL(url), 1000)
+    return true
+  } catch (error) {
+    return false
+  }
+}

package/src/dap/configSnippets.ts

@@ -0,0 +1,269 @@
+/**
+ * dsh-vscode-mode host — launch.json「添加配置」片段提取。
+ * 扫描 VSCode 扩展清单 contributes.debuggers[]：
+ * - configurationSnippets[]（label/description/body）优先；缺失时 initialConfigurations[] 兜底
+ *   （条目本身就是配置体，label 取 body.name → debugger.label → type）；
+ * - %key% 占位符按 package.nls.json → package.nls.zh-cn.json 合并表解析（zh 覆盖 base），
+ *   解析失败剥 %…% 外壳（避免裸占位符上屏）；
+ * - body 缺 type/name 时补齐（parseLaunchConfigs 要求两者，缺了插进去也不可见）。
+ * 与 discovery 各自独立缓存（片段随扩展安装变化；force 重扫，测试隔离）。
+ * 作者 ddj 2026年09月22号
+ */
+import { existsSync, readFileSync, readdirSync, type Dirent } from 'node:fs'
+import { join } from 'node:path'
+import { vscodeExtensionsDirs } from '../lsp/providers.js'
+import { dshHome } from '../paths.js'
+import type { DapAdapterDecl, DapConfigSnippet } from '../shared/dap.js'
+
+/** 清单 debuggers 条目（片段提取消费的子集）。 */
+interface SnippetDebuggerEntry {
+  type?: unknown
+  label?: unknown
+  configurationSnippets?: unknown
+  initialConfigurations?: unknown
+}
+
+/** 归一后的片段原料（nls 解析前）。 */
+interface RawSnippetItem {
+  label?: string
+  description?: string
+  body: Record<string, unknown>
+}
+
+/** nls 键值表（package.nls*.json 扁平结构）。 */
+type NlsTable = Record<string, string>
+
+/** 发现缓存（null = 未加载；按 home 隔离，测试用 force/clear 复位）。 */
+let cache: DapConfigSnippet[] | null = null
+let cacheHome = ''
+
+// --region 片段发现
+
+/**
+ * 全部可添加调试配置片段（按 label 字典序稳定输出，type+label 去重）。
+ * @author ddj 2026年09月22号
+ * @param force 强制重扫（扩展安装后 / 测试隔离用）
+ * @param home DSH home（缺省真实；测试可注入）
+ * @returns 片段列表
+ */
+export function dapConfigSnippets(force = false, home = dshHome()): DapConfigSnippet[] {
+  if (!force && cache !== null && home === cacheHome) return cache
+  cache = scanSnippets(home)
+  cacheHome = home
+  return cache
+}
+
+/** 清空片段缓存（扩展安装后 / 测试 afterEach 复位）。 */
+export function clearSnippetCache(): void {
+  cache = null
+  cacheHome = ''
+}
+
+/**
+ * 按适配器可用性标注片段（与调试工具条同源裁决 debuggerDecls）：
+ * type 命中 decl → 透传 available/reason；未命中（清单无该 type 的可用适配器声明）
+ * → available=false +「未发现该类型适配器」。下拉据此过滤「选得进、跑不了」的条目。
+ * @author ddj 2026年09月22号
+ * @param snippets 片段列表（dapConfigSnippets 产物）
+ * @param decls 适配器声明表（debuggerDecls()）
+ * @returns 带可用性标注的片段列表（新数组，不改入参）
+ */
+export function annotateSnippets(
+  snippets: readonly DapConfigSnippet[],
+  decls: readonly DapAdapterDecl[],
+): DapConfigSnippet[] {
+  const byType = new Map(decls.map((decl) => [decl.type, decl]))
+  return snippets.map((snip) => {
+    const decl = byType.get(snip.type)
+    if (!decl) {
+      return { ...snip, available: false, reason: '未发现该类型适配器' }
+    }
+    const annotated: DapConfigSnippet = { ...snip, available: decl.available }
+    if (!decl.available && decl.reason) annotated.reason = decl.reason
+    return annotated
+  })
+}
+
+/** 扫描全部扩展根收集片段（先到先得去重，输出按 label 排序）。 */
+function scanSnippets(home: string): DapConfigSnippet[] {
+  const out: DapConfigSnippet[] = []
+  const seen = new Set<string>()
+  for (const root of vscodeExtensionsDirs(home)) {
+    for (const extDir of subDirsOf(root)) {
+      collectExt(extDir, out, seen)
+    }
+  }
+  return out.sort((a, b) => a.label.localeCompare(b.label))
+}
+
+/** 单扩展处理：有产出原料才读 nls（多数扩展无调试片段，不白读两个小文件）。 */
+function collectExt(extDir: string, out: DapConfigSnippet[], seen: Set<string>): void {
+  const entries = debuggersOf(extDir)
+  const plans = entries
+    .map((entry) => ({ entry, type: strOf(entry.type), items: rawItemsOf(entry) }))
+    .filter((plan) => Boolean(plan.type) && plan.items.length > 0)
+  if (!plans.length) return
+  const nls = readNlsTable(extDir)
+  for (const plan of plans) {
+    for (const item of plan.items) {
+      const snippet = projectSnippet(plan.entry, plan.type, item, nls)
+      const key = plan.type + '\u0000' + snippet.label
+      if (seen.has(key)) continue
+      seen.add(key)
+      out.push(snippet)
+    }
+  }
+}
+
+/** 清单条目 → 片段投影（nls 解析 + type/name 补齐）。 */
+function projectSnippet(
+  entry: SnippetDebuggerEntry,
+  type: string,
+  item: RawSnippetItem,
+  nls: NlsTable,
+): DapConfigSnippet {
+  const body = resolveNlsDeep(item.body, nls) as Record<string, unknown>
+  if (!strOf(body.type)) body.type = type
+  const label = resolveNlsText(item.label ?? '', nls)
+    || strOf(body.name)
+    || resolveNlsText(strOf(entry.label), nls)
+    || type
+  if (!strOf(body.name)) body.name = label
+  const snippet: DapConfigSnippet = {
+    label,
+    type: strOf(body.type) || type,
+    bodyText: JSON.stringify(body, null, 2),
+  }
+  const description = resolveNlsText(item.description ?? '', nls)
+  if (description) snippet.description = description
+  return snippet
+}
+
+// --endregion
+
+// --region 清单与原料归一
+
+/** 读扩展根下的扩展子目录（根不存在返回空；与 discovery 同口径）。 */
+function subDirsOf(root: string): string[] {
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  return entries.filter((e) => e.isDirectory()).map((e) => join(root, e.name))
+}
+
+/** 读某扩展的 contributes.debuggers（无清单/无声明/解析失败返回空）。 */
+function debuggersOf(extDir: string): SnippetDebuggerEntry[] {
+  try {
+    const text = readFileSync(join(extDir, 'package.json'), 'utf8').replace(/^/, '')
+    const manifest = JSON.parse(text) as { contributes?: { debuggers?: unknown } }
+    const list = manifest.contributes?.debuggers
+    return Array.isArray(list) ? (list as SnippetDebuggerEntry[]) : []
+  } catch {
+    return []
+  }
+}
+
+/** 条目 → 原料列表：configurationSnippets 优先，initialConfigurations 兜底（条目即配置体）。 */
+function rawItemsOf(entry: SnippetDebuggerEntry): RawSnippetItem[] {
+  const out: RawSnippetItem[] = []
+  const snippets = asArray(entry.configurationSnippets)
+  for (const raw of snippets) {
+    const snippet = asRecord(raw)
+    if (!snippet) continue
+    const body = asRecord(snippet.body)
+    if (!body) continue
+    out.push({ label: strOf(snippet.label), description: strOf(snippet.description), body })
+  }
+  if (out.length) return out
+  for (const raw of asArray(entry.initialConfigurations)) {
+    const body = asRecord(raw)
+    if (body) out.push({ body })
+  }
+  return out
+}
+
+// --endregion
+
+// --region nls 占位符解析
+
+/**
+ * 读扩展 nls 表（base 先入，zh-cn 后入覆盖；文件缺失/解析失败按空跳过）。
+ * @author ddj 2026年09月22号
+ * @param extDir 扩展根目录
+ * @returns %key% → 文本 表
+ */
+function readNlsTable(extDir: string): NlsTable {
+  const table: NlsTable = {}
+  for (const file of ['package.nls.json', 'package.nls.zh-cn.json']) {
+    try {
+      const path = join(extDir, file)
+      if (!existsSync(path)) continue
+      const data = JSON.parse(readFileSync(path, 'utf8').replace(/^/, '')) as Record<string, unknown>
+      for (const [key, value] of Object.entries(data)) {
+        if (typeof value === 'string') table[key] = value
+      }
+    } catch {
+      /* 单个 nls 文件损坏按无表处理，不阻断提取 */
+    }
+  }
+  return table
+}
+
+/**
+ * 解析单串 %key% 占位（最多 3 轮：nls 值可再含占位；未命中剥 %…% 外壳）。
+ * @author ddj 2026年09月22号
+ * @param value 原文
+ * @param table nls 表
+ * @returns 解析后文本（无占位原样返回）
+ */
+function resolveNlsText(value: string, table: NlsTable): string {
+  if (!value.includes('%')) return value
+  let out = value
+  for (let round = 0; round < 3; round += 1) {
+    const next = out.replace(/%([A-Za-z0-9_.-]+)%/g, (_match, key: string) => table[key] ?? key)
+    if (next === out) break
+    out = next
+  }
+  return out
+}
+
+/** 深度解析任意值内的 %key%（字符串逐个过 resolveNlsText，对象/数组递归）。 */
+function resolveNlsDeep(value: unknown, table: NlsTable): unknown {
+  if (typeof value === 'string') return resolveNlsText(value, table)
+  if (Array.isArray(value)) return value.map((item) => resolveNlsDeep(item, table))
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = resolveNlsDeep(item, table)
+    }
+    return out
+  }
+  return value
+}
+
+// --endregion
+
+// --region 小工具
+
+/** unknown → 非空字符串（其余空串）。 */
+function strOf(value: unknown): string {
+  return typeof value === 'string' && value ? value : ''
+}
+
+/** unknown → 普通对象（数组/原始值返回 null）。 */
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+/** unknown → 数组（单对象包一层，兼容 initialConfigurations 单对象写法）。 */
+function asArray(value: unknown): unknown[] {
+  if (Array.isArray(value)) return value
+  return value && typeof value === 'object' ? [value] : []
+}
+
+// --endregion

package/src/dap/discovery.ts

@@ -0,0 +1,198 @@
+/**
+ * dsh-vscode-mode host — 调试适配器发现（清单驱动，VSCode contributes.debuggers 同源语义）。
+ * 扫描全部扩展根（复用 lsp 侧 vscodeExtensionsDirs：~/.vscode/extensions、
+ * ~/.vscode-server/extensions、插件扩展目录），读各扩展 package.json 的
+ * contributes.debuggers[] 声明，解析为 DapAdapterDecl：
+ * - program 按平台取 windows/linux/osx 覆盖，相对扩展根解析；
+ * - runtime='node' → 由 node 跑 js 入口；无 runtime → program 即可执行（args 为清单声明）；
+ * - 同 type 多扩展并存 → 按「清单版本降序(numeric) → 路径升序」取唯一（与 LSP 候选口径一致）；
+ * - 入口不存在 / runtime 不支持 → available=false + reason（如 DotRush 按需下载的 clrdbg，
+ *   诚实标注不假成功，调用方据此在下拉置灰并提示原因）。
+ * 作者 ddj 2026年09月21号
+ */
+import { existsSync, readdirSync, readFileSync, type Dirent } from 'node:fs'
+import { join } from 'node:path'
+import { LSP_LANG_EXT, manifestVersionOf, vscodeExtensionsDirs } from '../lsp/providers.js'
+import { dshHome } from '../paths.js'
+import type { DapAdapterDecl } from '../shared/dap.js'
+
+/** package.json contributes.debuggers 条目（本插件消费的子集）。 */
+interface DebuggerEntry {
+  type?: unknown
+  label?: unknown
+  program?: unknown
+  args?: unknown
+  runtime?: unknown
+  languages?: unknown
+  windows?: { program?: unknown }
+  linux?: { program?: unknown }
+  osx?: { program?: unknown }
+  darwin?: { program?: unknown }
+  configurationAttributes?: {
+    attach?: { properties?: { ext?: { default?: unknown } } }
+    launch?: { properties?: { ext?: { default?: unknown } } }
+  }
+}
+
+/** 发现缓存（扩展清单会话内基本不变；测试用 force 重扫）。 */
+let cacheReady = false
+let cacheHome = ''
+let cache: DapAdapterDecl[] = []
+
+/**
+ * 发现全部调试适配器声明（按 type 去重、type 字典序稳定输出）。
+ * @author ddj 2026年09月21号
+ * @param force 强制重扫（扩展安装后 / 测试隔离用）
+ * @param home DSH home（缺省真实；测试可注入）
+ */
+export function debuggerDecls(force = false, home = dshHome()): DapAdapterDecl[] {
+  if (cacheReady && !force && home === cacheHome) return cache
+  cache = scanDecls(home)
+  cacheHome = home
+  cacheReady = true
+  return cache
+}
+
+/** 清空发现缓存（扩展目录变更时；测试 afterEach 复位）。 */
+export function clearDiscoveryCache(): void {
+  cacheReady = false
+  cacheHome = ''
+  cache = []
+}
+
+/** 扫描全部扩展根并收集声明（同 type 去重后返回）。 */
+function scanDecls(home: string): DapAdapterDecl[] {
+  const hits: { decl: DapAdapterDecl; version: string }[] = []
+  for (const root of vscodeExtensionsDirs(home)) {
+    for (const extDir of subDirsOf(root)) {
+      for (const entry of debuggersOf(extDir)) {
+        const decl = declOf(extDir, entry)
+        if (decl) hits.push({ decl, version: manifestVersionOf(extDir) ?? '' })
+      }
+    }
+  }
+  return pickPerType(hits)
+}
+
+/** 同 type 去重：清单版本降序（numeric）→ 路径升序；输出按 type 字典序。 */
+function pickPerType(hits: { decl: DapAdapterDecl; version: string }[]): DapAdapterDecl[] {
+  const byType = new Map<string, { decl: DapAdapterDecl; version: string }>()
+  for (const hit of hits) {
+    const prev = byType.get(hit.decl.type)
+    if (!betterOf(hit, prev)) continue
+    byType.set(hit.decl.type, hit)
+  }
+  return [...byType.values()].map((h) => h.decl).sort((a, b) => a.type.localeCompare(b.type))
+}
+
+/** 候选比较：版本降序优先，平版本路径升序（无前任直接胜出）。 */
+function betterOf(hit: { decl: DapAdapterDecl; version: string }, prev?: { decl: DapAdapterDecl; version: string }): boolean {
+  if (!prev) return true
+  const byVersion = compareVersion(hit.version, prev.version)
+  if (byVersion !== 0) return byVersion > 0
+  return hit.decl.extensionPath.localeCompare(prev.decl.extensionPath) < 0
+}
+
+/** 清单版本比较（numeric 感知，与 LSP 候选排序同口径）：>0 表示 a 更新。 */
+function compareVersion(a: string, b: string): number {
+  return String(a || '').localeCompare(String(b || ''), undefined, { numeric: true })
+}
+
+/** 枚举扩展根下的扩展子目录（根不存在返回空）。 */
+function subDirsOf(root: string): string[] {
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  return entries.filter((e) => e.isDirectory()).map((e) => join(root, e.name))
+}
+
+/** 读某扩展的 contributes.debuggers 声明（无清单/无声明/解析失败返回空）。 */
+function debuggersOf(extDir: string): DebuggerEntry[] {
+  try {
+    const text = readFileSync(join(extDir, 'package.json'), 'utf8').replace(/^\uFEFF/, '')
+    const manifest = JSON.parse(text) as { contributes?: { debuggers?: unknown } }
+    const list = manifest.contributes?.debuggers
+    return Array.isArray(list) ? (list as DebuggerEntry[]) : []
+  } catch {
+    return []
+  }
+}
+
+/** 清单条目 → 声明（缺 type/program 视为无效条目跳过）。 */
+function declOf(extDir: string, entry: DebuggerEntry): DapAdapterDecl | null {
+  const type = typeof entry.type === 'string' ? entry.type : ''
+  if (!type || typeof entry.program !== 'string' || !entry.program) return null
+  const languages = stringsOf(entry.languages)
+  const resolved = resolveProgram(extDir, entry)
+  const runtime = typeof entry.runtime === 'string' && entry.runtime ? entry.runtime : undefined
+  const runtimeBad = runtime !== undefined && runtime !== 'node'
+  const available = resolved.available && !runtimeBad
+  const reason = !resolved.available
+    ? resolved.reason
+    : runtimeBad
+      ? '暂不支持运行时 "' + runtime + '"（仅支持 node 与原生可执行）'
+      : undefined
+  return {
+    type,
+    label: typeof entry.label === 'string' && entry.label ? entry.label : type,
+    extensionId: extensionIdOf(extDir),
+    extensionPath: extDir,
+    program: resolved.program,
+    args: stringsOf(entry.args),
+    runtime,
+    languages,
+    exts: extsOf(entry, languages),
+    available,
+    reason,
+  }
+}
+
+/** 平台 program 解析：windows/linux/osx(darwin) 覆盖优先，相对扩展根（剥 ./）。 */
+function resolveProgram(extDir: string, entry: DebuggerEntry): { program: string; available: boolean; reason?: string } {
+  const plat = process.platform
+  const override = plat === 'win32'
+    ? entry.windows?.program
+    : plat === 'darwin'
+      ? (entry.osx?.program ?? entry.darwin?.program)
+      : entry.linux?.program
+  const rel = typeof override === 'string' && override ? override : entry.program
+  if (typeof rel !== 'string' || !rel) return { program: '', available: false, reason: '清单未声明本平台 program' }
+  const program = join(extDir, ...rel.replace(/^\.\//, '').split(/[\\/]/))
+  if (!existsSync(program)) {
+    return { program, available: false, reason: '适配器入口不存在（扩展可能需按需下载）：' + rel }
+  }
+  return { program, available: true }
+}
+
+/** 来源扩展 id（目录名 publisher.name-version 取 version 前段；解析失败回退目录名）。 */
+function extensionIdOf(extDir: string): string {
+  const base = extDir.split(/[\\/]/).pop() ?? ''
+  const dot = base.lastIndexOf('-')
+  return dot > 0 ? base.slice(0, dot) : base
+}
+
+/** 可下断点扩展名：优先清单 configurationAttributes 的 ext 缺省（emmylua 的 .lua 家族），
+ * 否则按声明 languages 映射（LSP 侧同源）；两者皆空 = 不限（不过滤断点）。 */
+function extsOf(entry: DebuggerEntry, languages: string[]): string[] {
+  const attrs = entry.configurationAttributes
+  const declared = attrs?.attach?.properties?.ext?.default ?? attrs?.launch?.properties?.ext?.default
+  const fromManifest = stringsOf(declared)
+  if (fromManifest.length) return fromManifest
+  const out: string[] = []
+  for (const lang of languages) {
+    for (const ext of LSP_LANG_EXT[lang] ?? []) {
+      const dotted = '.' + ext.replace(/^\./, '')
+      if (!out.includes(dotted)) out.push(dotted)
+    }
+  }
+  return out
+}
+
+/** unknown → 字符串数组（非字符串元素剔除）。 */
+function stringsOf(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((v): v is string => typeof v === 'string' && v.length > 0)
+}