dsh-vscode-mode 0.12.0 → 0.13.1

package/src/client/monaco/loader.ts

@@ -6,7 +6,9 @@
  */
 import { applyOfficial, registerThemes } from './theme.js'
 
-export const MONACO_BASE = '/edrv/vendor/monaco/vs'
+import { appUrl } from '../../shared/appUrl.js'
+
+export const MONACO_BASE = appUrl('/edrv/vendor/monaco/vs')
 let monacoPromise = null
 let monacoStage = { phase: 'idle', progress: 0, message: '准备加载 Monaco…' }
 const stageListeners = new Set()

package/src/client/openFlow.ts

@@ -8,7 +8,7 @@
  */
 import { rpc } from './rpc.js'
 import { chooseWorkspace } from './chooseDialog.js'
-import { emitOpenAt, openEditorView } from './events.js'
+import { requestOpen } from './openReceipt.js'
 import { toastDom } from './externalOpen.js'
 import { createAddToConversation } from './addToConversation.js'
 import type { AddOutcome, CtxLike } from './addToConversation.js'
@@ -47,7 +47,7 @@ export interface OpenDeps {
   openSession(id: string): void
   reference(sessionId: string, path: string, appearance: 'file' | 'folder'): Promise<boolean>
   choose(title: string, folder: string): Promise<'recent' | 'create' | null>
-  openEditor(path: string | null, line?: number, column?: number): void
+  openEditor(path: string | null, line?: number, column?: number, sessionId?: string): Promise<boolean>
   schedule(fn: () => void, ms: number): void
   notify(text: string): void
 }
@@ -57,8 +57,6 @@ const READY_TIMEOUT_MS = 15000
 const READY_TICK_MS = 300
 const REF_RETRY_MAX = 20
 const REF_RETRY_MS = 300
-const REST_STEP_MS = 150
-const LINE_AT_DELAY_MS = 200
 
 /**
  * 路径规范化：`\→/`、小写、去尾分隔符（Windows 大小写不敏感前缀匹配用）。
@@ -124,11 +122,11 @@ export function pickRule(kind: PathKind, matched: boolean, hasSession: boolean):
  * @param params 深链参数（首路径驱动规则）
  * @param overrides 依赖覆盖（测试注入）
  */
-export async function openDeepLink(ctx: unknown, params: OpenParams, overrides: Partial<OpenDeps> = {}): Promise<void> {
+export async function openDeepLink(ctx: unknown, params: OpenParams, overrides: Partial<OpenDeps> = {}): Promise<boolean> {
   const deps = realDeps(ctx, overrides)
   if (!(await waitListsReady(deps))) {
     deps.notify('DSH 会话列表未就绪，请稍后重试')
-    return
+    return false
   }
   const primary = params.paths[0]
   const kind = await deps.stat(primary).catch(() => 'missing' as PathKind)
@@ -137,14 +135,16 @@ export async function openDeepLink(ctx: unknown, params: OpenParams, overrides:
   try {
     if (rule === 'abort') {
       deps.notify('路径不存在：' + primary)
-      return
+      return false
     }
-    if (rule === 'choose') return await runChoose(deps, primary, params)
-    if (rule === 'folderNew') return await runFolderNew(deps, primary, params)
-    if (rule === 'fileRecent') return await runFileRecent(deps, primary, params)
-    return await runFileBootstrap(deps, primary, params)
+    if (rule === 'choose') await runChoose(deps, primary, params)
+    else if (rule === 'folderNew') await runFolderNew(deps, primary, params)
+    else if (rule === 'fileRecent') await runFileRecent(deps, primary, params)
+    else await runFileBootstrap(deps, primary, params)
+    return true
   } catch (error) {
     deps.notify('打开失败：' + String((error as Error)?.message ?? error))
+    return false
   }
 }
 
@@ -162,12 +162,12 @@ async function runChoose(deps: OpenDeps, folder: string, params: OpenParams): Pr
   const matches = matchWorkspaces(deps.workspaces().items, folder)
   const best = bestMatch(deps, matches)
   const choice = await deps.choose(best?.title ?? '工作区', folder)
-  if (choice === null) return
+  if (choice === null) throw new Error('用户取消打开')
   if (choice === 'create') return runFolderNew(deps, folder, params)
   const ws = best ?? deps.workspaces().items[0]
   const sessionId = await spawnInWorkspace(deps, ws.workspaceId, undefined)
   await settleRef(deps, sessionId, folder, 'folder')
-  deps.openEditor(null)
+  await openChecked(deps, sessionId, null)
   await openRest(deps, sessionId, params, 1)
 }
 
@@ -178,21 +178,21 @@ async function runFileRecent(deps: OpenDeps, file: string, params: OpenParams):
     const anchor = recentSessionIn(deps, ws)
     if (anchor) {
       deps.openSession(anchor.id)
-      deps.openEditor(file, params.line, params.column)
+      await openChecked(deps, anchor.id, file, params.line, params.column)
       await openRest(deps, anchor.id, params, 1)
       return
     }
     // 文件所属工作区存在但无会话 → 在该工作区新建对话 + 文件引用
     const sessionId = await spawnInWorkspace(deps, ws.workspaceId, undefined)
     await settleRef(deps, sessionId, file, 'file')
-    deps.openEditor(file, params.line, params.column)
+    await openChecked(deps, sessionId, file, params.line, params.column)
     await openRest(deps, sessionId, params, 1)
     return
   }
   const anchor = recentSession(deps.sessions().byId, deps.sessions().ids)
   if (!anchor) return runFileBootstrap(deps, file, params)
   deps.openSession(anchor.id)
-  deps.openEditor(file, params.line, params.column)
+  await openChecked(deps, anchor.id, file, params.line, params.column)
   await openRest(deps, anchor.id, params, 1)
 }
 
@@ -228,7 +228,7 @@ async function runFileBootstrap(deps: OpenDeps, file: string, params: OpenParams
   const ws = await deps.createWorkspace(dirnameOf(file))
   const sessionId = await spawnInWorkspace(deps, ws.workspaceId, undefined)
   await settleRef(deps, sessionId, file, 'file')
-  deps.openEditor(file, params.line, params.column)
+  await openChecked(deps, sessionId, file, params.line, params.column)
   await openRest(deps, sessionId, params, 1)
 }
 
@@ -237,7 +237,7 @@ async function runFolderNew(deps: OpenDeps, folder: string, params: OpenParams):
   const ws = await deps.createWorkspace(folder)
   const sessionId = await spawnInWorkspace(deps, ws.workspaceId, undefined)
   await settleRef(deps, sessionId, folder, 'folder')
-  deps.openEditor(null)
+  await openChecked(deps, sessionId, null)
   await openRest(deps, sessionId, params, 1)
 }
 
@@ -264,17 +264,20 @@ async function settleRef(deps: OpenDeps, sessionId: string, path: string, appear
     if (await deps.reference(sessionId, path, appearance)) return
     await sleep(deps, REF_RETRY_MS)
   }
+  throw new Error('引用插入未完成')
 }
 
 /** 其余路径：文件进编辑器（步进），文件夹补文件夹引用。 */
 async function openRest(deps: OpenDeps, sessionId: string | null, params: OpenParams, from: number): Promise<void> {
   const rest = params.paths.slice(from)
-  for (const [index, path] of rest.entries()) {
+  for (const path of rest) {
     const kind = await deps.stat(path).catch(() => 'missing' as PathKind)
     if (kind === 'file') {
-      deps.schedule(() => deps.openEditor(path), REST_STEP_MS * (index + 1))
+      await openChecked(deps, sessionId ?? undefined, path)
     } else if (kind === 'directory' && sessionId) {
       await settleRef(deps, sessionId, path, 'folder')
+    } else {
+      throw new Error('路径不存在：' + path)
     }
   }
 }
@@ -316,16 +319,21 @@ function realDeps(ctx: unknown, overrides: Partial<OpenDeps> = {}): OpenDeps {
       return outcome === 'ok' || outcome === 'busy'
     },
     choose: (title, folder) => chooseWorkspace(title, folder),
-    openEditor: (path, line, column) => {
-      if (path == null) {
-        openEditorView(null)
-        return
-      }
-      openEditorView(path)
-      if (line != null) setTimeout(() => emitOpenAt(path, line, column), LINE_AT_DELAY_MS)
-    },
+    openEditor: requestOpen,
     schedule: (fn, ms) => setTimeout(fn, ms),
     notify: (text) => toastDom(text),
   }
   return { ...base, ...overrides }
 }
+
+/** @private @author ddj 2026年09月28号
+ * Await actual editor completion and propagate failure to the request result.
+ * @param deps Open dependencies.
+ * @param sessionId Target session.
+ * @param path Target file or editor mount.
+ * @param line Optional line.
+ * @param column Optional column.
+ */
+async function openChecked(deps: OpenDeps, sessionId: string | undefined, path: string | null, line?: number, column?: number): Promise<void> {
+  if (!(await deps.openEditor(path, line, column, sessionId))) throw new Error('编辑器打开未完成：' + (path ?? '工作区'))
+}

package/src/client/openReceipt.ts

@@ -0,0 +1,64 @@
+import { openEditorView } from './events.js'
+
+export interface EditorRequest { requestId: string; sessionId: string; path: string | null; line?: number; column?: number }
+interface Waiter { request: EditorRequest; finish: (success: boolean) => void; claimed?: boolean }
+const waiters = new Map<string, Waiter>()
+
+/** @public @author ddj 2026年09月28号
+ * Atomically claim the pending request for this editor's session on mount.
+ * @param sessionId Owning session.
+ * @returns Unclaimed request, if any.
+ */
+export function peekOpen(sessionId: string): EditorRequest | undefined {
+  const row = [...waiters.values()].find((item) => item.request.sessionId === sessionId && !item.claimed)
+  if (!row) return undefined
+  row.claimed = true
+  return row.request
+}
+
+/** @public @author ddj 2026年09月28号
+ * Complete an actual editor open by its unguessable local request ID.
+ * @param requestId Claimed request identity.
+ * @param success Whether content and navigation are ready.
+ * @param error Optional diagnostic for the caller.
+ */
+export function finishOpen(requestId: string, success: boolean, error?: string): void {
+  const row = waiters.get(requestId)
+  if (row?.claimed) row.finish(success === true)
+}
+
+/** @public @author ddj 2026年09月28号
+ * Route an editor open and await a correlated model-ready completion.
+ * @param path File path, or null to mount the editor.
+ * @param line Optional target line.
+ * @param column Optional target column.
+ * @param sessionId Owning session, required for routing.
+ * @returns Actual completion; timeout and disposal are false.
+ */
+export function requestOpen(path: string | null, line?: number, column?: number, sessionId = ''): Promise<boolean> {
+  if (typeof window === 'undefined' || !sessionId) return Promise.resolve(false)
+  const request: EditorRequest = { requestId: crypto.randomUUID(), sessionId, path, line, column }
+  return new Promise((resolve) => {
+    let timer: ReturnType<typeof setTimeout>
+    /** @private @author ddj 2026年09月28号 Complete once and release the deadline. */
+    function finish(success: boolean): void {
+      clearTimeout(timer)
+      waiters.delete(request.requestId)
+      resolve(success)
+    }
+    waiters.set(request.requestId, { request, finish })
+    timer = setTimeout(() => finish(false), 20_000)
+    openEditorView(null)
+    window.dispatchEvent(new CustomEvent('edrv:open-request', { detail: request }))
+  })
+}
+
+/** @public @author ddj 2026年09月28号
+ * Check that an editor receipt is still awaited after timeout or disposal.
+ * @param requestId Local request identity.
+ * @returns Whether this request may still be completed.
+ */
+export function hasOpen(requestId: string): boolean { return waiters.has(requestId) }
+
+/** @public @author ddj 2026年09月28号 Cancel outstanding receipts when the client plugin unloads. */
+export function disposeOpenWait(): void { for (const waiter of [...waiters.values()]) waiter.finish(false) }

package/src/client/panelCommands.ts

@@ -0,0 +1,101 @@
+import type { SessionScope } from './sessionScope.js'
+
+export type PanelAction = 'quickOpen' | 'searchInFiles'
+export interface PanelRoute {
+  readScope(): SessionScope
+  canOpen(): boolean
+  open(): boolean
+}
+interface PendingPanel extends SessionScope { action: PanelAction; expires: number }
+interface PanelHost { action: PanelAction; scope: SessionScope; run(): void }
+let route: PanelRoute | null = null
+const hosts = new Set<PanelHost>()
+const storage = globalThis as typeof globalThis & { __edrvPanelCommand__?: PendingPanel }
+
+/**
+ * Compare the command's session and workspace identity.
+ * @author ddj 2026年09月28号
+ * @param left Requested scope.
+ * @param right Mounted scope.
+ * @returns Whether both refer to the same session and known workspace.
+ */
+function sameScope(left: SessionScope, right: SessionScope): boolean {
+  return Boolean(left.sessionId && left.sessionId === right.sessionId
+    && (!left.cwd || !right.cwd || left.cwd === right.cwd))
+}
+
+/**
+ * Find the most recently mounted matching command receiver.
+ * @author ddj 2026年09月28号
+ * @param action Panel action.
+ * @param scope Active session scope.
+ * @returns Receiver if mounted.
+ */
+function panelHost(action: PanelAction, scope: SessionScope): PanelHost | undefined {
+  return [...hosts].reverse().find((host) => host.action === action && sameScope(scope, host.scope))
+}
+
+/**
+ * Install the existing sidebar route and current-session reader.
+ * @author ddj 2026年09月28号
+ * @param next Route capabilities; no side effects during availability checks.
+ * @returns Identity-safe disposal; pending intent survives plugin reload.
+ */
+export function setPanelRoute(next: PanelRoute): () => void {
+  route = next
+  return () => { if (route === next) route = null }
+}
+
+/**
+ * Check that a command has a mounted receiver or a usable editor route.
+ * @author ddj 2026年09月28号
+ * @param action Panel action.
+ * @returns False when genuinely unavailable, allowing official key dispatch to pass.
+ */
+export function panelAvailable(action: PanelAction): boolean {
+  const scope = route?.readScope()
+  if (!scope?.sessionId) return false
+  return Boolean(panelHost(action, scope) || route?.canOpen())
+}
+
+/**
+ * Deliver now or preserve an intent until the editor mounts.
+ * @author ddj 2026年09月28号
+ * @param action Panel action.
+ * @returns Whether the mounted host or sidebar accepted the request.
+ */
+export function runPanelCommand(action: PanelAction): boolean {
+  const scope = route?.readScope()
+  if (!scope?.sessionId) return false
+  const host = panelHost(action, scope)
+  if (host) { host.run(); return true }
+  if (!route?.canOpen()) return false
+  const pending = { ...scope, action, expires: Date.now() + 30_000 }
+  storage.__edrvPanelCommand__ = pending
+  try {
+    if (route.open()) return true
+  } catch { /* A disappearing sidebar leaves the command unhandled. */ }
+  if (storage.__edrvPanelCommand__ === pending) delete storage.__edrvPanelCommand__
+  return false
+}
+
+/**
+ * Attach one scoped receiver and consume a still-current pending intent once.
+ * @author ddj 2026年09月28号
+ * @param action Panel action.
+ * @param scope Mounted session/workspace.
+ * @param run Action using the mounted component's state.
+ * @returns Receiver disposal.
+ */
+export function bindPanelCommand(action: PanelAction, scope: SessionScope, run: () => void): () => void {
+  const host = { action, scope, run }
+  hosts.add(host)
+  const pending = storage.__edrvPanelCommand__
+  if (pending && (pending.expires < Date.now() || !sameScope(pending, route?.readScope() ?? {}))) {
+    delete storage.__edrvPanelCommand__
+  } else if (pending?.action === action && sameScope(pending, scope)) {
+    delete storage.__edrvPanelCommand__
+    run()
+  }
+  return () => { hosts.delete(host) }
+}

package/src/client/pdf/pdfLoader.ts

@@ -7,8 +7,10 @@
  * 作者 ddj 2026-09-22
  */
 
-/** vendor 根（routes.ts /edrv/vendor 前缀路由分发 assets/vendor/*）。 */
-export const PDFJS_BASE = '/edrv/vendor/pdfjs'
+import { appUrl } from '../../shared/appUrl.js'
+
+/** vendor 根，保留官方桌面协议及反向代理前缀。 */
+export const PDFJS_BASE = appUrl('/edrv/vendor/pdfjs')
 /** pdf.js Worker 地址（GlobalWorkerOptions.workerSrc）。 */
 export const PDFJS_WORKER_SRC = PDFJS_BASE + '/build/pdf.worker.mjs'
 /** CJK 字符映射目录（中文 PDF 渲染必需，尾斜杠固定）。 */

package/src/client/receiptState.ts

@@ -0,0 +1,120 @@
+import { absoluteOf } from './tabActions.js'
+import type { EditorRequest } from './openReceipt.js'
+
+/** Identity of one load, committed together with its text or preview state. */
+export interface ReceiptLoad {
+  sessionId: string
+  cwd: string | null
+  path: string
+  sequence: number
+  status: 'loading' | 'ready' | 'error'
+  error?: string
+}
+
+/** Current rendered facts; generic save/SVN errors intentionally have no receipt field. */
+export interface ReceiptView {
+  sessionId: string
+  cwd?: string | null
+  active: string | null
+  sequence: number
+  load: ReceiptLoad | null
+  mounted: boolean
+  blocked: boolean
+  kind: 'text' | 'image' | 'pdf' | 'markdown'
+  contentPath: string | null
+  contentReady: boolean
+  modelMatches: boolean
+  positionMatches: boolean
+  imageLoaded: boolean
+  pdfLoaded: boolean
+  engineError?: string | null
+}
+
+/**
+ * Normalize identity using the workspace's path syntax, never the browser OS.
+ * @public @author ddj 2026年09月28号
+ * @param path File path.
+ * @param cwd Workspace root, including remote POSIX roots on Windows clients.
+ * @returns Absolute normalized identity, case folded only for Windows paths.
+ */
+export function receiptPath(path: string, cwd?: string | null): string {
+  const value = absoluteOf(path, cwd)
+  return /^(?:[a-z]:\/|\/\/)/i.test(value) ? value.toLowerCase() : value
+}
+
+/**
+ * Preserve POSIX case when converting an external path into a tab path.
+ * @public @author ddj 2026年09月28号
+ * @param path External file path.
+ * @param cwd Workspace root.
+ * @returns Relative path only when it is inside the same correctly cased root.
+ */
+export function receiptTabPath(path: string, cwd?: string | null): string {
+  const value = path.replace(/\\/g, '/')
+  const base = (cwd ?? '').replace(/\\/g, '/').replace(/\/+$/, '')
+  if (base && receiptPath(value).startsWith(receiptPath(base) + '/')) return value.slice(base.length + 1)
+  return value
+}
+
+/**
+ * Match a load to the current request, rendered path, and live load sequence.
+ * @private @author ddj 2026年09月28号
+ * @param request Claimed request.
+ * @param view Current render and load metadata.
+ * @returns Whether load facts belong to this exact target and generation.
+ */
+function ownsLoad(request: EditorRequest, view: ReceiptView): boolean {
+  const load = view.load
+  if (!request.path || !view.active || !load) return false
+  const wanted = receiptPath(request.path, view.cwd)
+  return request.sessionId === view.sessionId && load.sessionId === view.sessionId
+    && load.sequence === view.sequence && receiptPath(load.path, load.cwd) === wanted
+    && receiptPath(view.active, view.cwd) === wanted
+}
+
+/**
+ * Confirm actual content/preview/navigation readiness for a correlated generation.
+ * @public @author ddj 2026年09月28号
+ * @param request Claimed external open.
+ * @param view Rendered state, including model identity and DOM readiness.
+ * @returns True only when the requested target is genuinely presented.
+ */
+export function receiptReadyFor(request: EditorRequest, view: ReceiptView): boolean {
+  if (request.sessionId !== view.sessionId) return false
+  if (!request.path) return view.mounted
+  if (!ownsLoad(request, view) || view.load?.status !== 'ready' || view.blocked || view.engineError) return false
+  if (view.kind === 'image') return view.imageLoaded
+  if (view.kind === 'pdf') return view.pdfLoaded
+  if (!view.contentReady || !view.contentPath || receiptPath(view.contentPath, view.cwd) !== receiptPath(request.path, view.cwd)) return false
+  const positioned = request.line != null || request.column != null
+  if (view.kind === 'markdown') return !positioned
+  return view.modelMatches && (!positioned || view.positionMatches)
+}
+
+/**
+ * Return only errors from this target's current load/render generation.
+ * @public @author ddj 2026年09月28号
+ * @param request Claimed request.
+ * @param view Rendered metadata and editor-engine startup failure.
+ * @returns Correlated error, otherwise null; prior files and save errors are ignored.
+ */
+export function receiptErrorFor(request: EditorRequest, view: ReceiptView): string | null {
+  if (!ownsLoad(request, view)) return null
+  if (view.engineError) return view.engineError
+  return view.load?.status === 'error' ? view.load.error ?? '文件加载失败' : null
+}
+
+/**
+ * Guard delayed load/render callbacks against a replacement generation.
+ * @public @author ddj 2026年09月28号
+ * @param load Current committed metadata.
+ * @param sessionId Callback owner.
+ * @param path Callback target, already normalized as a tab path.
+ * @param sequence Callback load sequence.
+ * @param currentSequence Live loader sequence.
+ * @returns Whether this callback may update the receipt status.
+ */
+export function acceptsLoad(load: ReceiptLoad | null, sessionId: string, path: string, sequence: number, currentSequence: number): boolean {
+  return Boolean(load && load.sessionId === sessionId && load.path === path
+    && load.sequence === sequence && sequence === currentSequence)
+}

package/src/client/rpc.ts

@@ -4,6 +4,7 @@
  * 诊断开关运行时化：内存缓存 + localStorage 持久（日志弹窗开关即改即生效，免刷新）。
  * 作者 ddj 2026-08-20 / 2026-09-17
  */
+import { appUrl } from '../shared/appUrl.js'
 import { RPC_PATH } from '../shared/rpc.js'
 import type { RpcMethod, RpcRequestMap, RpcResult } from '../shared/rpc.js'
 import type { LoggerLevel } from '../shared/logger.js'
@@ -35,13 +36,38 @@ export function setDebugEnabled(on: boolean): void {
   } catch (e) { /* 无 localStorage 环境：仅内存生效 */ }
 }
 
-/** 同源 RPC 调用（host /edrv/rpc 精确路由）。 */
-export function rpc<M extends RpcMethod>(method: M, args: RpcRequestMap[M]): Promise<RpcResult<M>> {
-  return fetch(RPC_PATH, {
+/**
+ * Call the authenticated RPC route using the current application base.
+ * @author ddj 2026年09月28号
+ * @param method Typed business method.
+ * @param args Business arguments.
+ * @param signal Optional cancellation signal.
+ * @returns A validated business result; transport failures reject with a readable error.
+ */
+export async function rpc<M extends RpcMethod>(method: M, args: RpcRequestMap[M], signal?: AbortSignal): Promise<RpcResult<M>> {
+  const res = await fetch(appUrl(RPC_PATH), {
     method: 'POST',
+    credentials: 'same-origin',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ method, args }),
-  }).then((res) => res.json()) as Promise<RpcResult<M>>
+    signal,
+  })
+  if (!res.ok) {
+    const message = res.status === 401 ? 'DSH 登录已失效，请重新打开已登录的应用页面'
+      : res.status === 403 ? 'DSH 拒绝了当前页面的访问'
+      : res.status === 413 ? '请求超过支持的文件大小'
+      : res.status === 503 ? 'DSH 认证服务尚未就绪'
+      : 'DSH 请求失败（HTTP ' + res.status + '）'
+    throw new Error(message)
+  }
+  if (!/^application\/json(?:\s*;|\s*$)/i.test(res.headers.get('content-type') ?? '')) {
+    throw new Error('DSH 返回了非 JSON 响应，请检查应用地址和代理配置')
+  }
+  const value: unknown = await res.json()
+  if (!value || typeof value !== 'object' || typeof (value as { ok?: unknown }).ok !== 'boolean') {
+    throw new Error('DSH RPC 响应格式不正确')
+  }
+  return value as RpcResult<M>
 }
 
 /**

package/src/client/shortcutsOfficial.ts

@@ -8,7 +8,7 @@
  * 作者 ddj 2026年10月
  */
 import { bindingToChord, chordToBinding, defaultKeybindings, normalizeKeybindings } from '../shared/keybindings.js'
-import { matchEvent, parseChords } from './keybindings.js'
+import { applyKeyAria, matchEvent, parseChords } from './keybindings.js'
 import type { OfficialBinding, ShortcutProfileKey } from '../shared/keybindings.js'
 import { log } from './log.js'
 
@@ -193,7 +193,9 @@ export function installLegacyKeys(
 ): () => void {
   if (!target) return () => {}
   const cache = new Map<string, ReturnType<typeof parseChords>>()
+  let disposed = false
   const onKey = (event: Event): void => {
+    if (disposed) return
     const key = event as KeyboardEvent
     const current = chords()
     for (const def of defs) {
@@ -211,8 +213,12 @@ export function installLegacyKeys(
       return
     }
   }
-  target.addEventListener('keydown', onKey, true)
-  return () => target.removeEventListener('keydown', onKey, true)
+  target.addEventListener('keydown', onKey, { capture: true })
+  return () => {
+    if (disposed) return
+    disposed = true
+    target.removeEventListener('keydown', onKey, { capture: true })
+  }
 }
 
 /**
@@ -283,22 +289,51 @@ export function registerOfficialShortcuts(
 export function bindCatalogChords(service: ShortcutsServiceLike, onChange: (chords: Readonly<Record<string, string>>) => void): () => void {
   const sync = (): void => {
     const chords: Record<string, string> = {}
+    const aria: Record<string, string | undefined> = {}
     try {
       for (const row of service.catalog.getSnapshot()) {
         if (!row.id.startsWith('edrv.') || row.binding === null) continue
         if (row.issue !== null) continue
-        const chord = bindingToChord(row.binding)
+        const chord = row.keys.length ? row.keys.join(' ') : bindingToChord(row.binding)
         if (chord !== null) chords[row.id] = chord
+        aria[row.id] = row.aria
       }
     } catch (error) {
       bridgeLog.warn('官方目录弦表重建失败：' + String(error))
     }
+    applyKeyAria(aria)
     onChange(chords)
   }
   sync()
   return service.catalog.subscribe(sync)
 }
 
+/**
+ * 唤起官方快捷键弹窗（VSCodeMode 通用页的跳转入口用；插件不再自建录键界面）。
+ * 官方入口不可用（旧版 DSH / registry 缺失）或唤起失败时返回可读说明，
+ * 供设置页原样展示：不抛错、不阻断设置渲染。
+ * @author ddj 2026年09月28号
+ * @param service 官方 shortcuts 服务（可为 null：运行时探测未就绪）
+ * @returns 空串 = 已成功唤起；否则为给用户看的失败说明
+ */
+export function openOfficialShortcuts(service: ShortcutsServiceLike | null): string {
+  const manual = '可按 Ctrl+/ 或到 DSH 设置 → 通用 → 快捷键 打开'
+  if (!service || !service.registry || typeof service.registry.invoke !== 'function') {
+    return '官方快捷键弹窗入口不可用（当前 DSH 版本或外壳未提供）：' + manual
+  }
+  try {
+    service.registry.invoke('shortcuts.open', {
+      region: 'page',
+      modal: null,
+      target: typeof document === 'undefined' ? null : document.activeElement,
+    })
+    return ''
+  } catch (error) {
+    bridgeLog.warn('打开官方快捷键弹窗失败：' + String(error))
+    return '打开官方快捷键弹窗失败：' + String(error) + '；' + manual
+  }
+}
+
 //#region 旧设置迁移
 
 /** 旧设置 scope 最小形状（compat settingsBridge 绑定产物的最小面，结构与 SettingsScopeLike 兼容）。 */

package/src/client/sidebarBridge.ts

@@ -133,6 +133,13 @@ export function takePendingSideOpen(sessionId?: string): { path: string | null;
  * @param focusDiff 是否聚焦首个差异
  * @returns 是否路由成功
  */
+/**
+ * Check the installed editor route without opening any UI.
+ * @author ddj 2026年09月28号
+ * @returns Whether a mounted sidebar adapter owns editor navigation.
+ */
+export function hasSideRoute(): boolean { return ensureSideEditor !== null }
+
 export function routeSideEditor(path: string | null, focusDiff: boolean): boolean {
   if (typeof ensureSideEditor !== 'function') return false
   try {

package/src/client/styles/mcp.css

@@ -18,7 +18,7 @@
 .vsm-mcp-subtabs button.active{color:var(--dsw-alias-label-primary,#fff);font-weight:500}
 .vsm-mcp-subtabs button.active::after{content:"";position:absolute;left:0;right:0;bottom:-1px;height:2px;background:var(--dsw-alias-brand-primary,#6d55ff);border-radius:2px}
 
-/* 顶层 Tab：通用 / 快捷键 / MCP 管理 / 语言服务器 / 性能优化 / 兼容性 */
+/* 顶层 Tab：通用 / MCP 管理 / 语言服务器 / AI 补全 / 性能优化 / 兼容性 */
 .vsm-mcp-tabs{display:flex;gap:24px;border-bottom:1px solid var(--dsw-alias-border-l2,#3a3a3a)}
 .vsm-mcp-tabs button{border:0;background:none;color:var(--dsw-alias-label-tertiary,#9aa5b1);padding:9px 2px 11px;cursor:pointer;font-size:14px;position:relative}
 .vsm-mcp-tabs button:hover{color:var(--dsw-alias-label-secondary,#c8c8c8)}
@@ -128,24 +128,6 @@
 .vsm-general-row button:disabled{opacity:.55;cursor:default}
 .vsm-general-row button.vsm-devform-close{color:var(--dsw-alias-state-error-primary,#f07878);border-color:var(--dsw-alias-state-error-secondary,#d9534f55)}
 
-/* keyboard shortcuts page */
-.vsm-kb-list{display:flex;flex-direction:column;gap:6px;margin-top:8px}
-.vsm-kb-row{display:flex;align-items:center;gap:10px;padding:8px 10px;border:1px solid var(--dsw-alias-border-l2,#555);border-radius:8px;background:var(--dsw-alias-bg-layer-1,#161616)}
-.vsm-kb-row.rec{border-color:var(--dsw-alias-brand-primary,#4f8cff)}
-.vsm-kb-label{flex:1;min-width:0;display:flex;flex-direction:column;gap:2px;color:var(--dsw-alias-label-primary,#eee);font-size:13px}
-.vsm-kb-warn{color:var(--dsw-alias-state-warn-primary,#e5b93f);font-size:11px}
-.vsm-kb-key{min-width:96px;text-align:center;padding:3px 10px;border:1px solid var(--dsw-alias-border-l2,#555);border-radius:6px;background:var(--dsw-alias-bg-base,#111);color:var(--dsw-alias-label-primary,#eee);font-size:12px;font-family:var(--ds-font-family-code,ui-monospace,monospace)}
-.vsm-kb-key.warn{border-color:var(--dsw-alias-state-warn-primary,#e5b93f);color:var(--dsw-alias-state-warn-primary,#e5b93f)}
-.vsm-kb-key.invalid{border-color:var(--dsw-alias-state-error-primary,#d9534f);color:var(--dsw-alias-state-error-primary,#d9534f)}
-.vsm-kb-rec{font-size:12px;color:var(--dsw-alias-label-secondary,#9aa5b1)}
-.vsm-kb-actions{display:flex;gap:6px}
-.vsm-kb-actions button{border:1px solid var(--dsw-alias-border-l2,#555);border-radius:6px;padding:4px 10px;background:none;color:var(--dsw-alias-label-primary,#eee);cursor:pointer;font-size:12px;white-space:nowrap}
-.vsm-kb-actions button:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover,#ffffff14)}
-.vsm-kb-actions button:disabled{opacity:.55;cursor:default}
-.vsm-kb-actionsbar{display:flex;align-items:center;gap:10px;margin-top:12px}
-.vsm-kb-dirty{flex:1;font-size:12px;color:var(--dsw-alias-state-warn-primary,#e5b93f)}
-.vsm-kb-message{font-size:12px;color:var(--dsw-alias-brand-primary,#4f8cff);margin-top:8px}
-
 /* 语言服务器（LSP）设置子 Tab */
 .vsm-lsp-form{display:flex;flex-direction:column;gap:6px;margin-top:8px}
 .vsm-lsp-form label{display:flex;flex-direction:column;gap:4px;font-size:12px;color:var(--dsw-alias-label-secondary,#9aa5b1)}