dsh-vscode-mode 0.17.0 → 0.19.0

package/package.json

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

package/skills/dsh-vscodemode-mcp/SKILL.md

@@ -14,8 +14,8 @@ whenToUse: 用户要求新增、修改、启停或排查 VSCodeMode MCP 配置
 |---|---|---|
 | 持久配置 | profile loader 树 | 已注册 workspace 根目录的 `.mcp.json` |
 | 生效范围 | profile 内所有工作区 | cwd 匹配该 workspace 的 agent |
-| 运行方式 | 原有全局 loader entry | `agent.ctx.plugin(officialMcp, config)` |
-| 连接实例 | 每个启用的全局 entry 一份 | 每个活动 agent、每个启用服务一份 |
+| 运行方式 | 原有全局 loader entry | 私有连接 scope + 会话授权代理，复用官方 MCP 插件 |
+| 连接实例 | 每个启用的全局 entry 一份 | 默认逐 agent 隔离；显式选择 workspace 后工作区复用 |
 | 没有活动 agent | 仍可运行 | 仅保存配置，`configured`、`instanceCount: 0` |
 | 团队共享 | 否 | `.mcp.json` 可以随仓库共享 |
 
@@ -25,7 +25,9 @@ whenToUse: 用户要求新增、修改、启停或排查 VSCodeMode MCP 配置
 
 设置 → VSCodeMode → MCP 管理，包含「我的 MCP」「项目 MCP」「MCP 市场」（占位）。项目服务在所选项目内管理。
 
-保存项目服务会写入 `.mcp.json` 并更新匹配的活动 agent；没有活动 agent 时保存为待挂载配置。启用不会凭空创建会话。每个新 agent 的串行 `agent/created` 监听会读取最新配置并等待其官方插件启动；插件装配时也会接入已经存在的 agent。
+保存项目服务会写入 `.mcp.json` 并更新匹配 agent 的能力目录与惰性资源入口。新建会话只等待配置准备和轻量入口，不等待任何项目 MCP 握手；默认 `on-demand`，未使用不启动。显式 `background` 后台预热也不阻塞创建。同一 Host 最多两个冷启动；同代次初始化 single-flight。配置写操作仍串行保护，但连接准备不占有跨会话全局锁。
+
+AI 先调用全局发现入口 `discover_project_mcp {action:"list"}`，仅返回执行 agent 工作区内的安全目录；需要时 `{action:"connect",serverName:"..."}` 连接并返回真实 schema。入口从工具执行上下文取 agent，不接受 sessionId、路径、命令、URL 或凭据。真实工具依然走官方审批、guard 和结果投影；Native 在下一次请求获得工具，PTC 必须结束当前程序后新建程序刷新 SDK，禁止 eval 或通用透传绕过权限。资源工具可通过所属工作区的惰性 provider 按需连接。
 
 禁用、删除、配置变更、刷新重连及 agent/插件卸载都会释放相应 fiber 和连接。仅刷新未变化的项目列表不会重复连接。主机代码更新需要重启 DSH 才能加载新实现。
 
@@ -33,6 +35,14 @@ whenToUse: 用户要求新增、修改、启停或排查 VSCodeMode MCP 配置
 
 表单 stdio 参数采用 JSON `string[]` 或每行一个完整参数，不按空格/引号做 shell 拆分；含空参数或内嵌换行使用 JSON。HTTP 请求头每行 `key=value`，保留值内的等号，拒绝非法/重复（忽略大小写）键。失败保存保持表单，忙时禁止重复动作。
 
+### 会话列表状态
+
+官方 `sidebar.session.row.leading` 插槽在会话标题前显示 16px 加载或异常图标；平稳完成不常驻绿色成功标。官方运行中、待审批、新消息状态优先覆盖 leading，归档行不展示 leading；`sidebar.session.row.hover` 悬浮详情仍可查看。
+
+详情只描述 VSCodeMode 管理的**项目 MCP**：待使用（不转圈）、读取配置、等待启动名额、加载插件模块、等待服务插件启动、复用已有连接、释放旧实例、完成或异常，展示完成数、耗时与安全错误摘要。共享显示会话本次等待，不将连接年龄冒充本次等待。超过 10 秒仅提示耗时较长，不判定失败。完成文案为「初始化完成，连接健康未验证」。无活跃 agent 文案为「当前无活跃 MCP 实例」，不是成功；不包含全局或 preset MCP。
+
+所有可见行共用一份 `mcp.sessionSnapshot` 订阅，在文档可见且有消费者时按 2.5 秒间隔查询；请求 10 秒截止、不重叠，隐藏/退订/卸载取消，过期响应丢弃。错误保留上次快照并标过期。查询只读内存，**不读配置、不 reconcile、不激活/保留历史会话、不建立连接**；旧 Host 或缺少插槽时安全降级。错误详情不返回 env、headers、完整配置或凭据 URL，仅返回安全类别提示，原始诊断看 Host 日志。
+
 ## 3. 项目配置
 
 `.mcp.json` 示例：
@@ -58,6 +68,8 @@ whenToUse: 用户要求新增、修改、启停或排查 VSCodeMode MCP 配置
 - stdio：`command` 必填；可填 `args`、`cwd`、`env`。未指定 `cwd` 时，以项目根作为进程工作目录。
 - HTTP：`url` 必须以 `http://` 或 `https://` 开头，可填 `headers`。
 - 高级参数：`toolCallTimeoutMs`、`failOnStartupError`、`maxInstructionBytes`、`reconnect`。
+- 项目扩展 `vscodeMode: { startup: "on-demand" | "background", sharing: "agent" | "workspace", startupTimeoutMs: 60000 }` 与官方传输配置分离，不透传；默认 on-demand + agent，旧文件不批量改写。初始化预算接受 1000–300000 整数，不是业务调用超时。全局配置不接受项目扩展。
+- workspace 共享必须显式确认服务适合共享内部状态；不会自动给 CodeGraph 开启。池键含工作区、有效配置和策略，凭据只做内存摘要身份。共享调用默认串行，最后租约释放保温 60 秒；agent 模式立即释放。禁用/删除/刷新/配置变化先失效与撤销再关闭，关闭未确认则阻止替代。超时显示释放阶段，失败冷却 5 秒后允许显式重试，不无限自动重试。
 - `disabled: true` 保持配置但不创建连接；保存表单会恢复启用。重启和 reconcile 都尊重 `disabled`。
 - 保存保留文档顶层、其他服务器及当前服务器的未知字段和未编辑高级参数；切换传输方式会移除旧传输专属字段。
 - `env` / `headers` 在返回值中使用 `••••••` 脱敏。原键的未修改掩码保存时恢复真实值；新键只有掩码而没有原值时会拒绝保存，需填写凭据。
@@ -85,12 +97,14 @@ whenToUse: 用户要求新增、修改、启停或排查 VSCodeMode MCP 配置
 |---|---|---|
 | `mcp.list` | `{}` | `servers` |
 | `mcp.snapshot` | `{}` | `servers`, `projects`（只读运行快照） |
+| `mcp.sessionSnapshot` | `{}` | `sessions`, `sampledAt`（按 sessionId 区分的活跃初始化状态，只读内存） |
 | `mcp.save` | `{ config }` | `server` |
 | `mcp.remove` | `{ id }` | 无 |
 | `mcp.toggle` | `{ id, enabled }` | `server` |
 | `mcp.refresh` | `{ id }` | `server` |
 | `mcp.projects` | `{}` | `projects` |
-| `mcp.projectSave` | `{ workspacePath, serverName, config }` | `project` |
+| `mcp.projectSave` | `{ workspacePath, serverName, config, policy? }` | `project` |
+| `mcp.projectConnect` | `{ sessionId, workspacePath, serverName }` | `project`（仅已活跃匹配会话，不激活历史会话） |
 | `mcp.projectRemove` | `{ workspacePath, serverName }` | `project` |
 | `mcp.projectToggle` | `{ workspacePath, serverName, enabled }` | `project` |
 | `mcp.projectRefresh` | `{ workspacePath, serverName }` | `project` |
@@ -109,7 +123,7 @@ whenToUse: 用户要求新增、修改、启停或排查 VSCodeMode MCP 配置
 
 ## 6. 工具、资源和指令隔离
 
-官方 0.1.7-rc.2 的 MCP Config 没有关闭资源/指令的开关；官方注册随 `scopeOf(ctx)` 归属。因此项目连接必须直接在 `agent.ctx` 挂载，不能全局连接后只隐藏工具。
+官方 0.1.7-rc.2 的 MCP Config 没有关闭资源/指令的开关；官方注册随 `scopeOf(ctx)` 归属。因此连接在独立 scope 中隔离 tools、mcpResources、systemPrompt，捕获注册后再给合法 agent 提供代理，绝不将原始项目注册暴露全局。创建私有 scope 后先等待 backing fiber 初始激活完成再 provide，防止依赖服务丢失；真实官方模块测试覆盖此边界。
 
 子 agent 会继承父 scope；跨 cwd 子会话还有三层处理：
 
@@ -126,7 +140,7 @@ whenToUse: 用户要求新增、修改、启停或排查 VSCodeMode MCP 配置
 
 | 状态/现象 | 含义与处理 |
 |---|---|
-| `configured` | 中性色；配置已保存，没有已挂载实例，打开匹配工作区会话后挂载 |
+| `configured` | 中性色；配置已保存，尚无连接实例，首次发现/资源访问或显式手动连接才启动（background 策略除外） |
 | `disabled` | 配置已停用，不建立项目连接 |
 | `connecting` | 官方插件还在等待启动完成；检查命令、cwd、URL 和握手 |
 | `unverified` | 中性色；fiber 已激活，但官方没有公开连接状态证据，不能宣称已连接；右侧绿色开关只表示启用 |
@@ -140,7 +154,10 @@ whenToUse: 用户要求新增、修改、启停或排查 VSCodeMode MCP 配置
 
 ## 8. 维护位置与验证
 
-- `src/mcpRuntime.ts`：agent → fibers 台账、官方插件加载、串行创建、迁移与卸载。
+- `src/mcpRuntime.ts`：会话租约/能力台账、官方模块加载、非阻塞接入、迁移与卸载。
+- `src/mcpPool.ts`：独立连接、single-flight、并发名额、取消/超时/保温和代次围栏。
+- `src/mcpBridge.ts`：私有服务隔离、真实工具代理、动态列表和撤销。
+- `src/mcpDiscover.ts`：统一发现入口与按 scope 输出的能力目录。
 - `src/mcpProject.ts`：源配置读取、保留字段、命名检查及 reconcile。
 - `src/mcpIsolation.ts`：继承工具限制、资源执行 guard、指令和资源列表覆盖。
 - `src/mcp.ts`：全局 loader CRUD、脱敏与诚实状态。

package/src/client/index.ts

@@ -20,6 +20,8 @@ import { DiffBadge } from './ui/DiffBadge.js'
 import { PerfSizeBadge } from './ui/PerfSizeBadge.js'
 import { ConversationDiffDock } from './ui/ConversationDiffDock.js'
 import { McpSettings } from './ui/McpSettings.js'
+import { mcpSessionState } from './mcpSessionState.js'
+import { McpSessionIcon, McpSessionDetail, type McpRowProps } from './ui/McpSessionStatus.js'
 import { PluginDetailSection } from './ui/PluginDetailSection.js'
 import { rpc } from './rpc.js'
 import { loadMonaco } from './monaco/loader.js'
@@ -74,6 +76,14 @@ import { flushPageState, flushUiState, hydrateUiState, installUiStatePersist, on
 import { workspaceScopeOf } from './state/scopeStore.js'
 import { dapStore } from './dap/store.js'
 import type { CompatAdapter } from '../shared/compat.js'
+import { setPanelImport } from './lazyPanel.js'
+import { dbg } from './rpc.js'
+import { BP_MODE, MODES, fieldOfMode } from './dap/BpWidget.js'
+import { ContextMenu } from './ui/ContextMenu.js'
+
+/** Root-owned live objects shared with independent panel chunks; no copied stores or transport state. */
+export const __lazyShared = { rpc, dbg, dapStore, BP_MODE, MODES, fieldOfMode, ContextMenu }
+export { setPanelImport as __setPanelImport }
 
 // ⚠️ inject 只列必需服务：webUiSettings 是 @linxin666/dsh-client-ui-web-ui-settings 提供的
 // 可选兼容桥（非官方服务），列入 inject 会让未装该桥的部署启动时 entry 永久 pending，
@@ -634,6 +644,18 @@ export async function apply(ctx: any): Promise<void> {
   }
   retrySideService()
 
+  // Root row slots receive only sessionId: no sessions.scope()/activation for historical rows.
+  ctx.effect(() => {
+    const store = mcpSessionState()
+    /** @author ddj 2026年10月20号 @param props Official root row identity. @returns Leading marker with shared polling. */
+    const renderIcon = (props: unknown) => React.createElement(McpSessionIcon, { ...(props as McpRowProps), store })
+    /** @author ddj 2026年10月20号 @param props Official hover identity. @returns Project-only initialization details. */
+    const renderDetail = (props: unknown) => React.createElement(McpSessionDetail, { ...(props as McpRowProps), store })
+    const leading = registerSlotSafely(ctx, { name: 'sidebar.session.row.leading', id: 'edrv-mcp-status', order: 20 }, renderIcon)
+    const hover = registerSlotSafely(ctx, { name: 'sidebar.session.row.hover', id: 'edrv-mcp-detail', order: 20 }, renderDetail)
+    return () => { leading?.(); hover?.(); store.dispose() }
+  }, 'vscode-mode: session MCP status')
+
   // 对话输入框上方差异 dock：普通对话显示单文案按钮，文件编辑页由 EditorView 隐藏
   registerSlotSafely(ctx, {
     name: 'conversation.input.dock',
@@ -659,6 +681,7 @@ export async function apply(ctx: any): Promise<void> {
     label: () => t('slot.settings'),
   }, () => React.createElement(SettingsContext.Provider, { value: bridge.scope() }, React.createElement(McpSettings, {
     openerRegistry: registry,
+    getMcpSession: () => readSessionScope(ctx).sessionId,
     compatSummary,
     // 快捷键统一走 DSH 官方配置：通用页只提供「打开官方快捷键配置」入口。
     // 服务运行时探测（自愈）：旧版 DSH 无该服务时按钮给出手动打开方式。
@@ -677,6 +700,7 @@ export async function apply(ctx: any): Promise<void> {
   // 注销挂在存活的 window.monaco 上的全部 Monaco provider 并复位模块状态。
   // 不做会导致重载后重复注册（补全/跳转/hover 各翻倍）与陈旧开关残留。
   ctx.effect(() => () => {
+    setPanelImport()
     try { disposeSnippets() } catch { /* 卸载异常不得阻断其余清理 */ }
     try { disposeLaunchJson() } catch { /* 同上 */ }
     try { disposeAiInline() } catch { /* 同上 */ }

package/src/client/lazyPanel.ts

@@ -0,0 +1,68 @@
+/** Package-local CJS panel loading; transport, revision URLs and HMR belong to DSH. @author ddj 2026年10月22号 */
+import React from 'react'
+import type { SidebarCtx } from './sidebar/types.js'
+
+type Panel = React.ComponentType<{ ctx: SidebarCtx }>
+type PanelKey = 'rules' | 'debug'
+type PanelImport = (file: string) => Promise<Record<string, unknown>>
+interface PanelLoad { pending?: Promise<Panel>; component?: Panel }
+const FILES = { rules: './client.rules.js', debug: './client.debug.js' } as const
+const EXPORTS = { rules: 'RulesPanel', debug: 'DebugPanel' } as const
+const loads = new Map<PanelKey, PanelLoad>()
+let generation = 0
+let importer: PanelImport | undefined
+
+/** @public @author ddj 2026年10月22号 @param transport Injected ModuleLoader require.async, never a global require. @description Start a new plugin generation and discard older results. */
+export function setPanelImport(transport?: PanelImport): void {
+  generation++
+  loads.clear()
+  importer = transport
+}
+
+/** @public @author ddj 2026年10月22号 @param key Fixed built-in panel key. @returns Shared pending load or cached component. @throws Unsupported loader or invalid chunk export. */
+export function loadPanel(key: PanelKey): Promise<Panel> {
+  const cached = loads.get(key)
+  if (cached?.component) return Promise.resolve(cached.component)
+  if (cached?.pending) return cached.pending
+  if (!importer) return Promise.reject(new Error('当前 DSH 不支持包内面板加载，请升级宿主'))
+
+  const epoch = generation
+  const transport = importer
+  const state: PanelLoad = {}
+  const pending = Promise.resolve().then(() => transport(FILES[key])).then((exports) => {
+    const component = exports[EXPORTS[key]]
+    if (typeof component !== 'function') throw new Error('面板脚本缺少组件导出')
+    if (epoch !== generation) throw new Error('面板加载已失效，请重试')
+    state.component = component as Panel
+    return state.component
+  }).catch((error) => {
+    if (loads.get(key) === state) loads.delete(key)
+    throw error
+  })
+  state.pending = pending
+  loads.set(key, state)
+  return pending
+}
+
+/** @public @author ddj 2026年10月22号 @param props Fixed panel and current context. @returns Loading, explicit retry, or the loaded panel subtree. */
+export function LazyPanel(props: { panel: PanelKey; ctx: SidebarCtx }): React.ReactElement {
+  const [attempt, retry] = React.useState(0)
+  const [view, setView] = React.useState<{ component?: Panel; error?: string }>({})
+  /** @private @author ddj 2026年10月22号 @returns Cleanup invalidating callbacks after switch or unmount. */
+  function loadEffect(): () => void {
+    let active = true
+    setView({})
+    /** @author ddj 2026年10月22号 @param component Loaded panel. */
+    function ready(component: Panel): void { if (active) setView({ component }) }
+    /** @author ddj 2026年10月22号 @param error Loader failure. */
+    function failed(error: unknown): void { if (active) setView({ error: String(error) }) }
+    void loadPanel(props.panel).then(ready, failed)
+    return () => { active = false }
+  }
+  React.useEffect(loadEffect, [props.panel, attempt])
+  /** @private @author ddj 2026年10月22号 @description Explicit retry; failures never loop automatically. */
+  function onRetry(): void { retry(attempt + 1) }
+  if (view.component) return React.createElement(view.component, { ctx: props.ctx })
+  return React.createElement('div', { className: 'edrv-empty', role: view.error ? 'alert' : 'status' },
+    view.error ?? '正在加载面板…', view.error && React.createElement('button', { onClick: onRetry }, '重试'))
+}

package/src/client/mcpSessionState.ts

@@ -0,0 +1,108 @@
+/** Shared, read-only sidebar MCP polling. @author ddj 2026年10月20号 */
+import { rpc } from './rpc.js'
+import type { McpSessionStatus } from '../shared/mcp.js'
+
+export interface SessionMcpView { status?: McpSessionStatus; stale: boolean }
+type Snapshot = { sessions: McpSessionStatus[]; sampledAt: number }
+type FetchStatus = (signal: AbortSignal) => Promise<Snapshot>
+const unavailable: SessionMcpView = { stale: true }
+const inactive: SessionMcpView = { stale: false }
+
+/** One poller for all mounted row/hover consumers; never retains or activates sessions. */
+export class McpSessionState {
+  private views = new Map<string, SessionMcpView>()
+  private listeners = new Map<string, Set<() => void>>()
+  private timer?: ReturnType<typeof setTimeout>
+  private request?: AbortController
+  private epoch = 0
+  private stale = true
+  private disposed = false
+
+  /** @public @author ddj 2026年10月20号 @param fetchStatus Authenticated read-only query. @param page Visibility boundary, omitted for server tests. */
+  constructor(private readonly fetchStatus: FetchStatus, private readonly page?: Document) {}
+
+  /** @public @author ddj 2026年10月20号 @param sessionId Row identity. @returns Stable view until the next observation. */
+  get(sessionId: string): SessionMcpView { return this.views.get(sessionId) ?? (this.stale ? unavailable : inactive) }
+
+  /** @public @author ddj 2026年10月20号 @param sessionId Row identity. @param listener React invalidation. @returns Idempotent unsubscribe; the last consumer stops polling. */
+  subscribe(sessionId: string, listener: () => void): () => void {
+    if (this.disposed) return () => undefined
+    const first = this.listeners.size === 0
+    const listeners = this.listeners.get(sessionId) ?? new Set()
+    listeners.add(listener)
+    this.listeners.set(sessionId, listeners)
+    if (first) {
+      this.page?.addEventListener('visibilitychange', this.visibility)
+      void this.poll()
+    }
+    return () => {
+      listeners.delete(listener)
+      if (listeners.size === 0) this.listeners.delete(sessionId)
+      if (this.listeners.size === 0) this.pause()
+    }
+  }
+
+  /** @private @author ddj 2026年10月20号 Stops pending work when hidden; resuming never accepts an old response. */
+  private visibility = (): void => {
+    if (this.page?.hidden) this.invalidate()
+    else void this.poll()
+  }
+
+  /** @private @author ddj 2026年10月20号 Invalidates responses without allowing overlapping transport requests. */
+  private invalidate(): void {
+    this.epoch += 1
+    clearTimeout(this.timer)
+    this.timer = undefined
+    this.request?.abort()
+    this.publish(undefined)
+  }
+
+  /** @private @author ddj 2026年10月20号 Cleans listener lifetime as well as timers. */
+  private pause(): void {
+    this.page?.removeEventListener('visibilitychange', this.visibility)
+    this.invalidate()
+  }
+
+  /** @public @author ddj 2026年10月20号 Permanently disposes HMR-owned polling. */
+  dispose(): void { this.disposed = true; this.pause(); this.listeners.clear(); this.views.clear() }
+
+  /** @private @author ddj 2026年10月20号 @param snapshot Fresh ledger, or undefined to mark all previous observations stale. */
+  private publish(snapshot?: Snapshot): void {
+    this.stale = snapshot === undefined
+    if (snapshot) this.views = new Map(snapshot.sessions.map((status) => [status.sessionId, { status, stale: false }]))
+    else for (const [id, view] of this.views) this.views.set(id, { ...view, stale: true })
+    for (const listeners of this.listeners.values()) for (const listener of listeners) listener()
+  }
+
+  /** @private @author ddj 2026年10月20号 Queries once, with a 10-second deadline and a 2.5-second gap after settlement. */
+  private async poll(): Promise<void> {
+    if (this.disposed || this.request || !this.listeners.size || this.page?.hidden) return
+    const request = new AbortController()
+    const epoch = this.epoch
+    this.request = request
+    /** @author ddj 2026年10月20号 Marks overdue responses unusable even if a transport ignores cancellation. */
+    const expire = (): void => { request.abort(); if (epoch === this.epoch) this.publish(undefined) }
+    const deadline = setTimeout(expire, 10000)
+    try {
+      const snapshot = await this.fetchStatus(request.signal)
+      if (epoch === this.epoch && !request.signal.aborted) this.publish(snapshot)
+    } catch {
+      if (epoch === this.epoch) this.publish(undefined)
+    } finally {
+      clearTimeout(deadline)
+      this.request = undefined
+      if (!this.disposed && this.listeners.size && !this.page?.hidden) this.timer = setTimeout(() => { void this.poll() }, 2500)
+    }
+  }
+}
+
+/** @public @author ddj 2026年10月20号 @returns Browser-owned singleton per plugin apply; legacy Hosts fail safely as stale. */
+export function mcpSessionState(): McpSessionState {
+  /** @author ddj 2026年10月20号 @param signal Fetch lifetime. @returns Current in-memory host ledger. @throws RPC errors. */
+  const fetchStatus = async (signal: AbortSignal): Promise<Snapshot> => {
+    const result = await rpc('mcp.sessionSnapshot', {}, signal)
+    if (!result.ok) throw new Error('MCP 状态暂不可用')
+    return result
+  }
+  return new McpSessionState(fetchStatus, document)
+}

package/src/client/monaco/lsp/providers.ts

@@ -5,7 +5,8 @@
  * 交互层：edrv.goToDefinition（F12）/ edrv.findReferences（Shift+F12 / 右键）均走 Monaco 原生命令；
  * Ctrl+点击使用处交给原生；Lua 表枚举字段声明处改为打开引用 Peek，
  * 数据经 host 的 LSP RPC 提供（registerEditorOpener 接管 edrv:// 点击跳转）。
- * 作者 ddj 2026-08-27 / 2026-09-11
+ * 定义结果返回前预热目标 model，避免 hover 定义链接预览抛 "Model not found"。
+ * 作者 ddj 2026-08-27 / 2026-09-11 / 2026-10-20
  */
 import {
   pathOfModel, syncDoc, closeDoc, findDefinition, findReferences,
@@ -19,6 +20,7 @@ import {
   LSP_COMPLETION_KIND_NAMES, LSP_INSERT_TEXT_FORMAT_SNIPPET,
 } from '../../../shared/lsp.js'
 import { luaKeywordsAt, luaTypesAt, mergeKeywords } from './keywords.js'
+import { warmModelFor } from '../../state/modelWarmer.js'
 
 const LSP_LANGS = ['lua', 'csharp']
 
@@ -79,6 +81,31 @@ export function navTargetOf(selectionOrPosition) {
   return endColumn === undefined ? { line, column, endLine } : { line, column, endLine, endColumn }
 }
 
+/**
+ * 预热定义目标文件的 Monaco model（供 Ctrl+hover 定义链接预览使用）。
+ *
+ * 为什么需要：Monaco 的 GotoDefinitionAtPositionEditorContribution 在渲染定义链接预览时，
+ * 对目标 uri 调 `createModelReference` 后**只挂 then、没有 catch**；本插件的定义目标是
+ * 自造的 `edrv://` uri，目标文件若从未打开过就没有已注册 model，`createModelReference`
+ * 会 reject("Model not found") 变成未捕获的 promise 异常（弹到 Console）。
+ * 本 vendored Monaco 也没有 `registerTextModelContentProvider` 可惰性喂内容，故只能提前建模型。
+ *
+ * 只预热单一定义：多定义分支（`locations.length > 1`）Monaco 走列表、不调
+ * `createModelReference`，没必要读盘。预热纯属增强，任何异常都在此吞掉，
+ * 不得让跳转查询失败（F12 与 Ctrl+点击不依赖模型是否已建）。
+ * @author ddj 2026年10月20号
+ * @param locations findDefinition 的客户端结果（含 edrv uri）
+ */
+async function prewarmDefinitionTarget(locations) {
+  if (!Array.isArray(locations) || locations.length !== 1) return
+  try {
+    const target = lspUriToAbs(locations[0]?.uri)
+    if (target) await warmModelFor(target)
+  } catch (error) {
+    /* 预热失败静默降级：等价于本次 hover 不显示预览 */
+  }
+}
+
 /** 注册全部 Monaco LSP provider 与文档跟踪（幂等）。 */
 export function registerLspProviders(monaco) {
   if (registered) return
@@ -151,10 +178,12 @@ export function registerLspProviders(monaco) {
       },
     }),
     monaco.languages.registerDefinitionProvider(LSP_LANGS, {
-      provideDefinition: (model, position, token) => {
+      provideDefinition: async (model, position, token) => {
         const path = pathOfModel(model)
         if (!path) return []
-        return findDefinition(path, model.getValue(), position)
+        const locations = await findDefinition(path, model.getValue(), position)
+        await prewarmDefinitionTarget(locations)
+        return locations
       },
     }),
     monaco.languages.registerReferenceProvider(LSP_LANGS, {

package/src/client/sidebar/PanelBoundary.ts

@@ -0,0 +1,57 @@
+/** Panel-local callback and React subtree isolation, not a security sandbox. @author ddj 2026年10月22号 */
+import React from 'react'
+import type { SidebarCtx, SidebarPanelDef } from './types.js'
+
+export interface PanelCheck { panel: SidebarPanelDef; badge: number | null; error?: Error }
+interface BoundaryProps { panel: SidebarPanelDef; scope?: string; sessionId?: string; compact?: boolean; children?: React.ReactNode }
+interface BoundaryState { panel: SidebarPanelDef; scope?: string; sessionId?: string; error: Error | null }
+const panelIds = new WeakMap<SidebarPanelDef, number>()
+let nextPanelId = 0
+/** @private @author ddj 2026年10月22号 @param props Subtree ownership. @returns Stable identity that changes on registration, scope or session replacement. */
+function ownerKey(props: BoundaryProps): string {
+  if (!panelIds.has(props.panel)) panelIds.set(props.panel, ++nextPanelId)
+  return JSON.stringify([panelIds.get(props.panel), props.scope, props.sessionId])
+}
+
+/** @public @author ddj 2026年10月22号 @param panel Registered definition. @param ctx Current scope. @returns Hidden marker or isolated visible/badge result; failed guards stay reachable for retry. */
+export function inspectPanel(panel: SidebarPanelDef, ctx: SidebarCtx): PanelCheck | null {
+  try {
+    if (panel.visible && panel.visible(ctx) !== true) return null
+    return { panel, badge: panel.badge?.(ctx) ?? null }
+  } catch (error) {
+    return { panel, badge: null, error: error instanceof Error ? error : new Error(String(error)) }
+  }
+}
+
+/** @public @author ddj 2026年10月22号 @description Reset a failed subtree when registration or scope ownership changes. */
+export class PanelBoundary extends React.Component<BoundaryProps, BoundaryState> {
+  state: BoundaryState = { panel: this.props.panel, scope: this.props.scope, sessionId: this.props.sessionId, error: null }
+
+  /** @public @author ddj 2026年10月22号 @param props Current ownership. @param state Previous ownership/error. @returns Reset only when the owner changes. */
+  static getDerivedStateFromProps(props: BoundaryProps, state: BoundaryState): Partial<BoundaryState> | null {
+    if (state.panel === props.panel && state.scope === props.scope && state.sessionId === props.sessionId) return null
+    return { panel: props.panel, scope: props.scope, sessionId: props.sessionId, error: null }
+  }
+
+  /** @public @author ddj 2026年10月22号 @param error React render/lifecycle error. @returns Local fallback state. */
+  static getDerivedStateFromError(error: Error): Partial<BoundaryState> { return { error } }
+
+  /** @private @author ddj 2026年10月22号 @description Remount only this failed subtree and reevaluate its callbacks. */
+  private retry = (): void => { this.setState({ error: null }) }
+
+  /** @public @author ddj 2026年10月22号 @returns Original subtree or panel-local retry UI. */
+  render(): React.ReactNode {
+    if (!this.state.error) return React.createElement(React.Fragment, { key: ownerKey(this.props) }, this.props.children)
+    if (this.props.compact) return React.createElement('span', { role: 'img', title: '图标加载失败', 'aria-label': '图标加载失败' }, '!')
+    return React.createElement('div', { className: 'edrv-empty', role: 'alert' },
+      this.props.panel.title + '：' + String(this.state.error.message),
+      React.createElement('button', { onClick: this.retry }, '重试'))
+  }
+}
+
+/** @public @author ddj 2026年10月22号 @param props Isolated panel invocation below the boundary. @returns Panel subtree. @throws Extension callback error for the nearest boundary. */
+export function PanelContent(props: { panel: SidebarPanelDef; ctx: SidebarCtx }): React.ReactNode {
+  const checked = inspectPanel(props.panel, props.ctx)
+  if (checked?.error) throw checked.error
+  return checked ? props.panel.render(props.ctx) as React.ReactNode : null
+}

package/src/client/sidebar/SidebarView.ts

@@ -10,6 +10,7 @@
  */
 import React from 'react'
 import type { SidebarCtx } from './types.js'
+import { inspectPanel, PanelBoundary, PanelContent } from './PanelBoundary.js'
 
 const W_MAX = 560
 /** 面板区隐藏时容器的宽度（= 图标列宽，与 editor.css .edrv-rail 对齐）。 */
@@ -50,9 +51,8 @@ function railIconEl(icon) {
 export function SidebarView(props) {
   const ctx = props.ctx
   // 按 visible(ctx) 过滤活动栏图标与面板（能力相关面板：SVN 变更仅在受 SVN 管理时出现）
-  const panels = (props.registry?.list?.() ?? []).filter((panel) => (
-    typeof panel.visible !== 'function' || panel.visible(ctx) === true
-  ))
+  const checked = (props.registry?.list?.() ?? []).map((panel) => inspectPanel(panel, ctx)).filter(Boolean)
+  const panels = checked.map((entry) => entry.panel)
   const activePanel = props.activePanel
   const onActive = props.onActive
   const visible = props.visible !== false
@@ -64,27 +64,66 @@ export function SidebarView(props) {
 
   const active = panels.find((p) => p.id === activePanel) || panels[0]
 
+  const dragCleanup = React.useRef(null)
+  /** @private @author ddj 2026年10月22号 @description End the active drag; safe on repeated teardown. */
+  function stopDrag() { dragCleanup.current?.() }
+  const seamOpening = React.useRef(false)
+  const lastVisible = React.useRef(visible)
+  /** @private @author ddj 2026年10月22号 @description Always release listeners on unmount, including a pending seam expansion. */
+  function dragEffect() { return stopDrag }
+  React.useEffect(dragEffect, [])
+  /** @private @author ddj 2026年10月22号 @description Preserve only the seam's own expansion; external visibility changes cancel ownership. */
+  function visibilityEffect() {
+    if (lastVisible.current !== visible) {
+      if (!(visible && seamOpening.current)) stopDrag()
+      seamOpening.current = false
+      lastVisible.current = visible
+    }
+  }
+  React.useEffect(visibilityEffect, [visible])
+
+  /** @private @author ddj 2026年10月22号 @param pointerId Owning pointer. @param move Pointer movement callback. @description Replace the previous drag and own every exit path. */
+  function bindDrag(pointerId, move) {
+    stopDrag()
+    /** @author ddj 2026年10月22号 @param event Pointer event. @description Ignore another pointer's movement. */
+    function onMove(event) { if (event.pointerId === pointerId) move(event) }
+    /** @author ddj 2026年10月22号 @param event Pointer completion. @description Only the owning pointer ends the drag. */
+    function onEnd(event) { if (event.pointerId === pointerId) cleanup() }
+    /** @author ddj 2026年10月22号 @description Remove all drag listeners and release ownership. */
+    function cleanup() {
+      window.removeEventListener('pointermove', onMove)
+      window.removeEventListener('pointerup', onEnd)
+      window.removeEventListener('pointercancel', onEnd)
+      window.removeEventListener('blur', cleanup)
+      if (dragCleanup.current === cleanup) {
+        dragCleanup.current = null
+        seamOpening.current = false
+      }
+    }
+    dragCleanup.current = cleanup
+    window.addEventListener('pointermove', onMove)
+    window.addEventListener('pointerup', onEnd)
+    window.addEventListener('pointercancel', onEnd)
+    window.addEventListener('blur', cleanup)
+  }
+
+  /** @private @author ddj 2026年10月22号 @param e Starting pointer. @description Resize the visible panel until completion or collapse. */
   const onPointerDown = (e) => {
     e.preventDefault()
     const startX = e.clientX
     const startW = width
-    const cleanup = () => {
-      window.removeEventListener('pointermove', onMove)
-      window.removeEventListener('pointerup', onUp)
-    }
-    const onUp = () => cleanup()
+    /** @author ddj 2026年10月22号 @param ev Owning pointer movement. @description Apply this drag's width calculation. */
     const onMove = (ev) => {
       const raw = startW + (ev.clientX - startX)
       // 低于最小宽度：清理监听并直接收起面板区（不夹住）
       if (raw < wMin) {
-        cleanup()
+        stopDrag()
         onHide()
         return
       }
       onWidth(Math.min(W_MAX, raw))
     }
-    window.addEventListener('pointermove', onMove)
-    window.addEventListener('pointerup', onUp)
+    bindDrag(e.pointerId, onMove)
 
   }
 
@@ -98,29 +137,25 @@ export function SidebarView(props) {
     const baseW = Math.max(wMin, Math.min(W_MAX, Math.round(Number(width) || wMin)))
     let expanded = false
     let expandStartX = 0
-    const cleanup = () => {
-      window.removeEventListener('pointermove', onMove)
-      window.removeEventListener('pointerup', onUp)
-    }
-    const onUp = () => cleanup()
+    /** @author ddj 2026年10月22号 @param ev Owning pointer movement. @description Apply this drag's width calculation. */
     const onMove = (ev) => {
       if (!expanded) {
         if (ev.clientX - startX < PULL_OUT_THRESHOLD) return
         expanded = true
         expandStartX = ev.clientX
+        seamOpening.current = true
         onShow()
         return
       }
       onWidth(Math.max(wMin, Math.min(W_MAX, baseW + (ev.clientX - expandStartX))))
     }
-    window.addEventListener('pointermove', onMove)
-    window.addEventListener('pointerup', onUp)
+    bindDrag(e.pointerId, onMove)
   }
 
   const rail = React.createElement('div', { className: 'edrv-rail' },
     React.createElement('div', { style: { flex: 1, display: 'flex', flexDirection: 'column', gap: 2 } },
       panels.map((p) => {
-        const count = typeof p.badge === 'function' ? p.badge(ctx) : null
+        const count = checked.find((entry) => entry.panel === p)?.badge
         return React.createElement('button', {
           key: p.id,
           className: 'edrv-rail-btn' + (visible && active && p.id === active.id ? ' edrv-rail-on' : ''),
@@ -131,7 +166,8 @@ export function SidebarView(props) {
             if (!visible && typeof onShow === 'function') onShow()
           },
         },
-          React.createElement('span', { className: 'edrv-rail-icon' }, railIconEl(p.icon)),
+          React.createElement('span', { className: 'edrv-rail-icon' },
+            React.createElement(PanelBoundary, { panel: p, scope: ctx?.scope, sessionId: ctx?.sessionId, compact: true }, railIconEl(p.icon))),
           count > 0
             ? React.createElement('span', { className: 'edrv-rail-badge' }, String(count))
             : null)
@@ -150,7 +186,8 @@ export function SidebarView(props) {
     rail,
     visible
       ? React.createElement('div', { className: 'edrv-side-body' },
-          active ? active.render(ctx) : null)
+          active ? React.createElement(PanelBoundary, { panel: active, scope: ctx?.scope, sessionId: ctx?.sessionId },
+            React.createElement(PanelContent, { panel: active, ctx })) : null)
       : null,
     visible
       ? React.createElement('div', { className: 'edrv-side-resize', onPointerDown: onPointerDown })