dsh-vscode-mode 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "DSH 上的类 VSCode 编码体验：Monaco 编辑器（文件页签/QuickOpen/状态栏，可驻 DSH 0.1.5+ 官方右侧 Sidebar 与对话同屏）+ 命令栏（Ctrl+Shift+P）与可扩展指令系统 + VS Code 兼容代码片段（.code-snippets 全局/项目，IntelliSense 展开）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚）+ SVN 集成（侧栏变更面板/日志弹窗/并排差异）+ 语言服务器（LSP）智能（跳转定义/引用/hover/大纲 + VSIX 扩展市场安装），状态持久化到工作区旁车",
   "keywords": [
     "dsh",

package/src/client/compat.ts

@@ -12,7 +12,7 @@ export const SIDEBAR_PLUGIN = 'dsh-better-sidebar'
 
 /** 设置 scope 的跨组件上下文形状（与官方 settingsScope 绑定的最小面）。 */
 export interface SettingsScopeLike {
-  getSnapshot: () => { status?: string; value?: { fileOpenTool?: unknown; keybindings?: Record<string, string>; sidebarMinWidth?: unknown }; writable?: boolean }
+  getSnapshot: () => { status?: string; value?: { fileOpenTool?: unknown; keybindings?: Record<string, string>; sidebarMinWidth?: unknown; maxOpenEditors?: unknown }; writable?: boolean }
   subscribe: (listener: () => void) => () => void
   set: (field: string, value: unknown) => Promise<void>
 }

package/src/client/dap/BpWidget.ts

@@ -0,0 +1,262 @@
+/**
+ * dsh-vscode-mode client — 断点行内编辑浮层（逐项对齐 VS Code/CodeBuddy breakpointWidget）。
+ *
+ * 权威结构（CodeBuddy workbench.desktop.main.js）：
+ * - **View Zone**（`changeViewZones(z => z.addZone({ afterLineNumber, heightInLines, domNode, afterColumnAffinity:1 }))`）
+ *   → 占据**整个编辑区宽度**并把下方内容推开（不是 content widget：后者宽度受限且不推挤）：
+ *   `_getWidth(i) = i.width - i.minimap.minimapWidth - i.verticalScrollbarWidth`。
+ * - 左侧「模式下拉」四项（表达式 / 命中次数 / 日志消息 / 等待断点）+ 右侧**单行输入框**；
+ *   切换模式时各模式内容独立记忆（rememberInput/getInputValue），「等待断点」模式隐藏输入框。
+ * - 无「确定」按钮（仅「等待断点」模式有）：`Enter` 提交（primary:3）、`Escape` 取消（primary:9），
+ *   提示写进输入框占位。
+ * - 打开期间给**目标行**挂高亮装饰（`edrv-dap-bp-editing`），关闭时移除。
+ * 文案逐字取自 CodeBuddy 官方中文语言包（索引 7259/7262~7265）。
+ * 作者 ddj 2026年09月29号
+ */
+import { setEditingLine } from './decorate.js'
+
+/** 模式索引（与权威实现 context 一致：0 表达式 / 1 命中次数 / 2 日志消息 / 3 等待断点）。 */
+export const BP_MODE = { EXPRESSION: 0, HIT_COUNT: 1, LOG_MESSAGE: 2, WAIT: 3 } as const
+
+/** 模式 → 字段键（等待断点无输入字段）。 */
+export type BpFieldKey = 'condition' | 'hitCondition' | 'logMessage'
+
+/** 浮层输入。 */
+export interface BpWidgetInput {
+  line: number
+  entry: { condition?: string; hitCondition?: string; logMessage?: string }
+  /** 打开时选中的模式（「添加条件断点…」→ 表达式、「添加记录点…」→ 日志消息）。 */
+  mode?: number
+  onSave: (fields: { condition: string; hitCondition: string; logMessage: string }) => void
+  onClose: () => void
+}
+
+/** 浮层宿主（编辑器 + zone 句柄），由调用方持有用于关闭。 */
+export interface BpWidgetHost {
+  close: () => void
+}
+
+/** 模式项（顺序与权威实现一致）。 */
+const MODES: readonly { mode: number; label: string; placeholder: string }[] = [
+  { mode: BP_MODE.EXPRESSION, label: '表达式', placeholder: '在表达式结果为真时中断。按 "Enter" 键确认，"Escape" 键取消。' },
+  { mode: BP_MODE.HIT_COUNT, label: '命中次数', placeholder: '在满足命中次数条件时中断。按 "Enter" 键确认，"Escape" 键取消。' },
+  { mode: BP_MODE.LOG_MESSAGE, label: '日志消息', placeholder: '断点命中时记录的消息。{} 内的表达式将被替换。按 "Enter" 键确认，"Escape" 键取消。' },
+  { mode: BP_MODE.WAIT, label: '等待断点', placeholder: '选择此断点命中前必须先命中的断点。' },
+]
+/** 模式清单（调试面板行内编辑器同源复用：标签与占位文案一致）。 */
+export { MODES }
+
+/** 模式 → 字段键映射（等待断点返回 null）；调试面板行内编辑器同源复用。 */
+export function fieldOfMode(mode: number): BpFieldKey | null {
+  if (mode === BP_MODE.EXPRESSION) return 'condition'
+  if (mode === BP_MODE.HIT_COUNT) return 'hitCondition'
+  if (mode === BP_MODE.LOG_MESSAGE) return 'logMessage'
+  return null
+}
+
+/**
+ * 打开断点行内编辑浮层（View Zone：整编辑区宽 + 推开内容 + 目标行高亮）。
+ * @author ddj 2026年09月29号
+ * @param editor Monaco 编辑器
+ * @param input 目标行、初始值、初始模式、保存/取消回调
+ * @returns 宿主句柄（close 关闭浮层）
+ */
+export function createBpWidget(editor: unknown, input: BpWidgetInput): BpWidgetHost {
+  const ed = editor as {
+    changeViewZones?: (cb: (accessor: { addZone: (zone: unknown) => string; removeZone: (id: string) => void }) => void) => void
+  } | null
+  let zoneId: string | null = null
+  let closed = false
+
+  // 各模式独立记忆（对齐 rememberInput / getInputValue）
+  const remembered: Record<BpFieldKey, string> = {
+    condition: input.entry?.condition ?? '',
+    hitCondition: input.entry?.hitCondition ?? '',
+    logMessage: input.entry?.logMessage ?? '',
+  }
+  let mode = typeof input.mode === 'number' ? input.mode : BP_MODE.EXPRESSION
+
+  const root = document.createElement('div')
+  root.className = 'edrv-bpwidget'
+  root.setAttribute('data-edrv-view', '1')
+
+  // 左侧模式下拉
+  const select = document.createElement('select')
+  select.className = 'edrv-bpwidget-mode'
+  select.title = '断点类型'
+  for (const item of MODES) {
+    const opt = document.createElement('option')
+    opt.value = String(item.mode)
+    opt.textContent = item.label
+    select.appendChild(opt)
+  }
+  select.value = String(mode)
+
+  // 右侧单行输入
+  const field = document.createElement('input')
+  field.className = 'edrv-bpwidget-input'
+  field.spellcheck = false
+
+  root.appendChild(select)
+  root.appendChild(field)
+
+  /** 当前模式正文（等待断点模式无正文）。 */
+  const currentText = (): string => {
+    const key = fieldOfMode(mode)
+    return key ? remembered[key] : ''
+  }
+
+  /** 模式切换：先记忆当前，再套用新模式的正文与占位。 */
+  const applyMode = (): void => {
+    const key = fieldOfMode(mode)
+    const item = MODES.find((m) => m.mode === mode)
+    field.value = currentText()
+    field.placeholder = item?.placeholder ?? ''
+    field.hidden = key === null
+    select.value = String(mode)
+    if (key !== null) { try { field.focus(); field.select() } catch { /* 忽略 */ } }
+  }
+
+  /** 记忆当前正文。 */
+  const remember = (): void => {
+    const key = fieldOfMode(mode)
+    if (!key) return
+    remembered[key] = field.value
+  }
+
+  /** 提交：记忆全部字段并回调。 */
+  const save = (): void => {
+    remember()
+    input.onSave({ ...remembered })
+  }
+
+  select.addEventListener('change', () => {
+    remember()
+    mode = Number(select.value)
+    applyMode()
+  })
+  // 输入框/下拉内点击：preventDefault 阻止 Monaco 抢焦（浏览器默认聚焦被取消后由
+  // 显式 focus 补上），保证"点进去一定能输入"。
+  const keepFocus = (ev: MouseEvent): void => {
+    ev.preventDefault()
+    ev.stopPropagation()
+    const el = ev.currentTarget === select ? select : field
+    try { el.focus() } catch { /* 忽略 */ }
+  }
+  field.addEventListener('mousedown', keepFocus)
+  select.addEventListener('mousedown', keepFocus)
+
+  const onKeyDown = (ev: KeyboardEvent): void => {
+    ev.stopPropagation()
+    if (ev.key === 'Enter') { ev.preventDefault(); save(); return }
+    if (ev.key === 'Escape') { ev.preventDefault(); input.onClose() }
+  }
+  field.addEventListener('keydown', onKeyDown)
+  select.addEventListener('keydown', onKeyDown)
+
+  // ---- 全局接管（浮层存活期间）----
+  // ① window 级 Enter/Esc：焦点被编辑器抢走后仍可确认/取消（对齐 VS Code 的
+  //    acceptInput primary:Enter 与 closeBreakpointWidget primary:Escape 全局命令）。
+  // ② 编辑器内点击浮层之外 → 关闭浮层（对齐 VS Code：点击别处即收起，想改重新右键）。
+  // ③ document 级 mousedown 捕获：浮层内点击阻断 Monaco 抢焦；输入框/下拉点进去可控。
+  const onWindowKey = (ev: KeyboardEvent): void => {
+    if (ev.key === 'Enter') { ev.preventDefault(); ev.stopPropagation(); save(); return }
+    if (ev.key === 'Escape') { ev.preventDefault(); ev.stopPropagation(); input.onClose() }
+  }
+  const onEditorMouseDown = (ev: MouseEvent): void => {
+    const target = ev.target as Node | null
+    if (target && root.contains(target)) return
+    input.onClose()
+  }
+  const onDocMouseDownCapture = (ev: MouseEvent): void => {
+    const target = ev.target as HTMLElement | null
+    if (!target) return
+    if (root.contains(target)) {
+      if (target !== field && target !== select) {
+        ev.preventDefault()
+        ev.stopPropagation()
+        try { field.focus() } catch { /* 忽略 */ }
+      }
+      return
+    }
+    // 浮层之外的点击（含编辑器正文/行号/glyph）→ 关闭（对齐 VS Code）
+    if ((editor as { getDomNode?: () => HTMLElement | null })?.getDomNode?.()?.contains(target)) input.onClose()
+  }
+  window.addEventListener('keydown', onWindowKey, true)
+  document.addEventListener('mousedown', onDocMouseDownCapture, true)
+  const editorDom = (editor as { getDomNode?: () => HTMLElement | null })?.getDomNode?.()
+  editorDom?.addEventListener('mousedown', onEditorMouseDown)
+  applyMode()
+
+  /** 关闭时解除全局接管（close 内调用）。 */
+  const detachGlobal = (): void => {
+    window.removeEventListener('keydown', onWindowKey, true)
+    document.removeEventListener('mousedown', onDocMouseDownCapture, true)
+    editorDom?.removeEventListener('mousedown', onEditorMouseDown)
+  }
+
+  // 挂 View Zone（推开内容）并把浮层铺满整个编辑区宽度。
+  // ⚠️ Monaco 的 .view-zones 容器宽度只有内容区（contentWidth，从 contentLeft 起），
+  //    而 VS Code 的 zone-widget 整宽 = width - minimapWidth - verticalScrollbarWidth
+  //    （见其 `_getWidth`）。这里用负 left + 显式宽度补偿 contentLeft 与右侧滚动条。
+  const syncWidth = (): void => {
+    const layout = (editor as { getLayoutInfo?: () => Record<string, unknown> } | null)?.getLayoutInfo?.()
+    if (!layout) return
+    const contentLeft = Number(layout.contentLeft) || 0
+    const scrollbarWidth = Number((layout as { verticalScrollbarWidth?: number }).verticalScrollbarWidth) || 0
+    const width = contentLeft + (Number(layout.contentWidth) || 0) + scrollbarWidth
+    // 用 important 覆盖 Monaco addZone 写入的内联 `width:100%` / `left:0` / `display:block`。
+    // display 必须是 flex，否则子项不参与 flex 布局、输入框只剩默认宽度（用户反馈"输入框太短"）。
+    // 注意：Monaco 在 addZone 之后仍可能重写内联样式，故此处由 onComputedHeight 反复调用兜住。
+    root.style.setProperty('left', -contentLeft + 'px', 'important')
+    root.style.setProperty('width', width + 'px', 'important')
+    root.style.setProperty('display', 'flex', 'important')
+    root.style.setProperty('align-items', 'center', 'important')
+    // 行内元素从编辑器最左（行号列）开始，右侧留出滚动条宽度（对齐 VS Code zone-widget 起始位）
+    root.style.setProperty('padding-left', '4px', 'important')
+    root.style.setProperty('padding-right', (scrollbarWidth + 6) + 'px', 'important')
+  }
+  // 挂 View Zone（推开内容）并把浮层铺满整个编辑区宽度。
+  // ⚠️ Monaco 的 addZone 会用内联样式强制 `width: 100%`（= .view-zones 内容区宽，不含
+  //    glyph/行号/装饰列与右侧滚动条），直接设宽度会被覆盖。对齐 VS Code：在其
+  //    `onComputedHeight`（每次布局回调）里重新套用整宽 = width - minimapWidth - scrollbarWidth。
+  ed?.changeViewZones?.((accessor) => {
+    zoneId = accessor.addZone({
+      afterLineNumber: input.line,
+      heightInLines: 1.6,
+      domNode: root,
+      afterColumnAffinity: 1,
+      onComputedHeight: () => syncWidth(),
+    })
+  })
+  setEditingLine(ed, input.line)
+  // addZone 首次布局晚于本行；且 Monaco 之后仍可能重写内联样式（display/width），
+  // 故布局回调 + 首帧 + 短周期守卫（浮层存活期间，关闭即停）三处兜住。
+  setTimeout(() => { if (!closed) syncWidth() }, 0)
+  const guard = setInterval(() => {
+    if (closed) { clearInterval(guard); return }
+    syncWidth()
+  }, 250)
+  setTimeout(() => clearInterval(guard), 3000).unref?.()
+
+  const close = (): void => {
+    if (closed) return
+    closed = true
+    detachGlobal()
+    setEditingLine(ed, null)
+    if (zoneId) {
+      const id = zoneId
+      zoneId = null
+      try { ed?.changeViewZones?.((accessor) => accessor.removeZone(id)) } catch { /* 编辑器可能已销毁 */ }
+    }
+    try { root.remove() } catch { /* 忽略 */ }
+  }
+
+  // 首帧后聚焦（有输入框时聚焦输入框，否则聚焦下拉）
+  setTimeout(() => {
+    if (closed) return
+    try { (fieldOfMode(mode) ? field : select).focus?.() } catch { /* 忽略 */ }
+  }, 0)
+
+  return { close }
+}

package/src/client/dap/bpMenu.ts

@@ -0,0 +1,91 @@
+/**
+ * dsh-vscode-mode client — 断点 gutter 右键菜单条目（纯函数，可单测）。
+ * 逐条对齐 CodeBuddy（VS Code 内核）breakpointEditorContribution.getContextMenuActions
+ * 与其官方中文语言包译文：
+ * - 无断点：添加断点 / 添加条件断点... / 添加记录点... / 添加触发的断点...
+ * - 有断点：删除 {noun}（右侧 Delete）/ 编辑 {noun}… / 禁用{noun} 或 启用 {noun}
+ *   noun 随类型切换：普通断点 =「断点」，记录点（带日志消息）=「记录点」
+ * - 暂停且支持时：前置分隔线 + 运行到行
+ *
+ * 文案逐字取自语言包（**空格与省略号形态不可改**）：
+ *   removeBreakpoint「删除 {0}」/ editBreakpoint「编辑 {0}…」/
+ *   disableBreakpoint「禁用{0}」/ enableBreakpoint「启用 {0}」/ runToLine「运行到行」
+ * 本模块只产出条目数据，onClick 由 EditorView 装配（无副作用）。
+ * 作者 ddj 2026年09月29号
+ */
+
+/** 菜单动作 id。 */
+export type BpMenuAction =
+  | 'add'
+  | 'add-conditional'
+  | 'add-logpoint'
+  | 'add-triggered'
+  | 'delete'
+  | 'edit'
+  | 'disable'
+  | 'enable'
+  | 'run-to-line'
+
+/** 一条菜单条目。 */
+export interface BpMenuEntry {
+  id: BpMenuAction
+  label: string
+  /** 前置分隔线（运行到行与断点条目之间，对齐 CodeBuddy）。 */
+  separator?: boolean
+  /** 右侧键位提示（CodeBuddy 仅删除项带 Delete）。 */
+  hint?: string
+  /** 显示但当前调试器不支持：点击给出明确提示而非静默失败。 */
+  unsupported?: boolean
+}
+
+/** 菜单构造输入。 */
+export interface BpMenuState {
+  /** 命中行是否已有断点。 */
+  hasBreakpoint: boolean
+  /** 已有断点是否启用（无断点时忽略）。 */
+  enabled?: boolean
+  /** 已有断点是否为记录点（带日志消息）→ 名词用「记录点」。 */
+  isLogpoint?: boolean
+  /** 调试器是否暂停中（运行到行仅在暂停时出现）。 */
+  paused?: boolean
+  /** 调试器是否支持运行到行。 */
+  canRunTo?: boolean
+  /** 调试器是否支持触发的断点。 */
+  canTriggered?: boolean
+}
+
+/**
+ * 构造断点右键菜单条目。
+ * @author ddj 2026年09月29号
+ * @param state 命中行与调试器状态
+ * @returns 菜单条目列表（顺序即展示顺序）
+ */
+export function buildBpMenu(state: BpMenuState): BpMenuEntry[] {
+  const entries = state.hasBreakpoint ? ownedEntries(state) : addEntries(state.canTriggered === true)
+  // CodeBuddy 在 if/else 链之后无条件追加：空行同样支持运行到行（仅在暂停时）
+  if (state.paused === true && state.canRunTo === true) {
+    entries.push({ id: 'run-to-line', label: '运行到行', separator: true })
+  }
+  return entries
+}
+
+/** 无断点：四个添加类条目（对齐 CodeBuddy 无条件四项）。 */
+function addEntries(canTriggered: boolean): BpMenuEntry[] {
+  return [
+    { id: 'add', label: '添加断点' },
+    { id: 'add-conditional', label: '添加条件断点...' },
+    { id: 'add-logpoint', label: '添加记录点...' },
+    { id: 'add-triggered', label: '添加触发的断点...', unsupported: !canTriggered },
+  ]
+}
+
+/** 已有断点：删除 / 编辑 / 启停（名词随记录点切换）。 */
+function ownedEntries(state: BpMenuState): BpMenuEntry[] {
+  const noun = state.isLogpoint === true ? '记录点' : '断点'
+  const enabled = state.enabled !== false
+  return [
+    { id: 'delete', label: '删除 ' + noun, hint: 'Delete' },
+    { id: 'edit', label: '编辑 ' + noun + '…' },
+    enabled ? { id: 'disable', label: '禁用' + noun } : { id: 'enable', label: '启用 ' + noun },
+  ]
+}

package/src/client/dap/bpRowMenu.ts

@@ -0,0 +1,53 @@
+/**
+ * dsh-vscode-mode client — 调试面板断点行右键菜单条目（纯函数，可单测）。
+ * 对齐 CodeBuddy（VS Code 内核）断点视图行上下文菜单：
+ * 编辑断点… / 编辑条件… / 编辑命中次数… / 编辑记录点… / 启用|禁用断点 / 删除断点。
+ * 四个编辑条目都打开面板行内编辑器，仅初始模式不同
+ * （0 表达式 / 1 命中次数 / 2 日志消息；"编辑断点…"按现有字段自动判定）。
+ * 本模块只产出条目数据，onClick 由 DebugPanel 装配（无副作用）。
+ * 作者 ddj 2026年09月21号
+ */
+
+/** 菜单动作 id。 */
+export type BpRowMenuAction =
+  | 'edit'
+  | 'edit-condition'
+  | 'edit-hit-count'
+  | 'edit-logpoint'
+  | 'enable'
+  | 'disable'
+  | 'remove'
+
+/** 一条菜单条目。 */
+export interface BpRowMenuEntry {
+  id: BpRowMenuAction
+  label: string
+  /** 前置分隔线（编辑组与启停/删除组之间，对齐 CodeBuddy）。 */
+  separator?: boolean
+}
+
+/** 菜单构造输入。 */
+export interface BpRowMenuState {
+  /** 当前断点是否启用（禁用态显示「启用断点」）。 */
+  enabled?: boolean
+}
+
+/**
+ * 构造调试面板断点行右键菜单条目。
+ * @author ddj 2026年09月21号
+ * @param state 行内断点状态
+ * @returns 菜单条目列表（顺序即展示顺序）
+ */
+export function buildBpRowMenu(state: BpRowMenuState): BpRowMenuEntry[] {
+  const enabled = state.enabled !== false
+  return [
+    { id: 'edit', label: '编辑断点…' },
+    { id: 'edit-condition', label: '编辑条件…' },
+    { id: 'edit-hit-count', label: '编辑命中次数…' },
+    { id: 'edit-logpoint', label: '编辑记录点…' },
+    enabled
+      ? { id: 'disable', label: '禁用断点', separator: true }
+      : { id: 'enable', label: '启用断点', separator: true },
+    { id: 'remove', label: '删除断点' },
+  ]
+}

package/src/client/dap/breakpoints.ts

@@ -0,0 +1,222 @@
+/**
+ * dsh-vscode-mode client — 调试断点集合（纯函数 + localStorage 持久）。
+ * 存储：`edrv.dap.bp.<scope>` → Record<relPath, BpEntry[]>（行升序）。
+ * scope 与编辑器状态作用域一致（workspaceScopeOf 产物），跨刷新保留。
+ * 作者 ddj 2026年09月29号
+ */
+
+/** 单条断点。 */
+export interface BpEntry {
+  line: number
+  enabled: boolean
+  /** 命中条件表达式（Lua，如 count % 10 == 0；空=无条件）。 */
+  condition?: string
+  /** 命中次数条件（适配器 hitCondition，如 >=5）。 */
+  hitCondition?: string
+  /** 日志断点消息（适配器 logMessage；存在时命中不打断仅打日志）。 */
+  logMessage?: string
+}
+
+/** 断点表：relPath → 条目列表。 */
+export type BpMap = Record<string, BpEntry[]>
+
+/** localStorage key 前缀。 */
+const KEY_PREFIX = 'edrv.dap.bp.'
+
+/**
+ * 读断点表（缺失/损坏返回空表）。
+ * @author ddj 2026年09月29号
+ * @param scope 状态作用域
+ */
+export function loadBpMap(scope: string): BpMap {
+  try {
+    const raw = localStorage.getItem(KEY_PREFIX + scope)
+    if (!raw) return {}
+    const data = JSON.parse(raw)
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return {}
+    const out: BpMap = {}
+    for (const [path, list] of Object.entries(data as Record<string, unknown>)) {
+      if (!Array.isArray(list)) continue
+      const entries: BpEntry[] = []
+      for (const item of list) {
+        if (!item || typeof item !== 'object') continue
+        const line = (item as BpEntry).line
+        if (typeof line !== 'number' || line < 1) continue
+        const entry: BpEntry = { line, enabled: (item as BpEntry).enabled !== false }
+        if (typeof (item as BpEntry).condition === 'string') entry.condition = (item as BpEntry).condition
+        if (typeof (item as BpEntry).hitCondition === 'string') entry.hitCondition = (item as BpEntry).hitCondition
+        if (typeof (item as BpEntry).logMessage === 'string') entry.logMessage = (item as BpEntry).logMessage
+        entries.push(entry)
+      }
+      if (entries.length) out[path] = entries.sort((a, b) => a.line - b.line)
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * 写断点表（空表时清 key；写失败静默）。
+ * @author ddj 2026年09月29号
+ * @param scope 状态作用域
+ * @param map 断点表
+ */
+export function saveBpMap(scope: string, map: BpMap): void {
+  try {
+    const keys = Object.keys(map)
+    if (!keys.length) localStorage.removeItem(KEY_PREFIX + scope)
+    else localStorage.setItem(KEY_PREFIX + scope, JSON.stringify(map))
+  } catch { /* 无 localStorage 环境：仅内存生效 */ }
+}
+
+/**
+ * 切换某文件某行断点（纯函数，返回新表与是否新增）。
+ * @author ddj 2026年09月29号
+ * @param map 原表
+ * @param path 文件相对路径
+ * @param line 行号
+ */
+export function toggleBp(map: BpMap, path: string, line: number): { map: BpMap; added: boolean } {
+  const list = map[path] ?? []
+  const hit = list.find((item) => item.line === line)
+  let nextList: BpEntry[]
+  let added: boolean
+  if (hit) {
+    nextList = list.filter((item) => item.line !== line)
+    added = false
+  } else {
+    nextList = [...list, { line, enabled: true }].sort((a, b) => a.line - b.line)
+    added = true
+  }
+  const next: BpMap = { ...map }
+  if (nextList.length) next[path] = nextList
+  else delete next[path]
+  return { map: next, added }
+}
+
+/**
+ * 取某文件启用的断点行（升序）。
+ * @author ddj 2026年09月29号
+ * @param map 断点表
+ * @param path 文件相对路径
+ */
+export function bpLinesOf(map: BpMap, path: string): number[] {
+  return (map[path] ?? []).filter((item) => item.enabled).map((item) => item.line)
+}
+
+/**
+ * 取某文件禁用的断点行（升序；灰点展示用）。
+ * @author ddj 2026年09月29号
+ * @param map 断点表
+ * @param path 文件相对路径
+ */
+export function bpDisabledLinesOf(map: BpMap, path: string): number[] {
+  return (map[path] ?? []).filter((item) => !item.enabled).map((item) => item.line)
+}
+
+/**
+ * 断点表规模（跨文件总数；版本指纹用）。
+ * @author ddj 2026年09月29号
+ * @param map 断点表
+ */
+export function bpTotalOf(map: BpMap): number {
+  let total = 0
+  for (const list of Object.values(map)) total += list.length
+  return total
+}
+
+/**
+ * 全量启停所有断点（不删条目，只改 enabled；纯函数）。
+ * @author ddj 2026年09月21号
+ * @param map 原表
+ * @param enabled 目标启用态
+ */
+export function setAllEnabled(map: BpMap, enabled: boolean): BpMap {
+  const next: BpMap = {}
+  for (const [path, list] of Object.entries(map)) {
+    if (!list.length) continue
+    next[path] = list.map((item) => (item.enabled === enabled ? item : { ...item, enabled }))
+  }
+  return next
+}
+
+/**
+ * 清空所有断点（纯函数；不修改原表）。
+ * 同时返回曾有条目的文件清单（store 逐文件 syncPoints 空载荷用）。
+ * @author ddj 2026年09月21号
+ * @param map 原表
+ */
+export function removeAll(map: BpMap): { map: BpMap; files: string[] } {
+  return { map: {}, files: Object.keys(map).filter((path) => (map[path] ?? []).length > 0) }
+}
+
+/**
+ * 更新某行断点的编辑字段（条件/命中次数/日志；纯函数）。
+ * 空串视为清除该字段。
+ * @author ddj 2026年09月29号
+ * @param map 原表
+ * @param path 文件相对路径
+ * @param line 行号
+ * @param fields 要写入的字段（undefined = 不变）
+ */
+export function updateBpFields(
+  map: BpMap,
+  path: string,
+  line: number,
+  fields: { condition?: string; hitCondition?: string; logMessage?: string },
+): BpMap {
+  const clean = (value?: string): string | undefined => {
+    const trimmed = typeof value === 'string' ? value.trim() : undefined
+    return trimmed ? trimmed : undefined
+  }
+  const list = (map[path] ?? []).map((item) => {
+    if (item.line !== line) return item
+    const next: BpEntry = { ...item }
+    if (fields.condition !== undefined) next.condition = clean(fields.condition)
+    if (fields.hitCondition !== undefined) next.hitCondition = clean(fields.hitCondition)
+    if (fields.logMessage !== undefined) next.logMessage = clean(fields.logMessage)
+    return next
+  })
+  return { ...map, [path]: list }
+}
+
+/** 断点行跳转入参（调试面板行视图：文件路径 + 条目）。 */
+export interface BpJumpRowLike {
+  path?: string
+  entry?: { line?: number }
+}
+
+/** 断点行跳转目标（1-based；列固定 1，与搜索面板命中跳转同口径）。 */
+export interface BpJumpTarget {
+  path: string
+  line: number
+  column: number
+}
+
+/**
+ * 推导断点行的跳转目标（调试面板点击断点项 → 打开文件并定位到断点行）。
+ * 路径缺失或行号非 ≥1 的有限数时返回 null（提前返回，不发起无效导航）。
+ * @author ddj 2026年09月21号
+ * @param row 面板行视图（文件路径 + 断点条目）
+ * @returns 跳转目标；入参不合法时返回 null
+ */
+export function bpJumpTargetOf(row: BpJumpRowLike | null | undefined): BpJumpTarget | null {
+  const path = typeof row?.path === 'string' ? row.path : ''
+  const line = row?.entry?.line
+  if (!path || typeof line !== 'number' || !Number.isFinite(line) || line < 1) return null
+  return { path, line: Math.floor(line), column: 1 }
+}
+
+/**
+ * 路径是否为可下断点的调试目标（当前调试器为 Lua；按扩展名后缀匹配，
+ * 支持 '.lua' 与 '.lua.bytes' 这类带尾缀的 Unity 资产形态）。
+ * @author ddj 2026年09月29号
+ * @param path 文件路径（相对/绝对均可）
+ * @param exts 允许的扩展名列表（默认 ['.lua']；大小写不敏感）
+ */
+export function isDebuggablePath(path: string, exts: readonly string[] = ['.lua']): boolean {
+  const lower = String(path || '').toLowerCase()
+  if (!lower) return false
+  return exts.some((ext) => lower.endsWith(String(ext).toLowerCase()))
+}