dsh-vscode-mode 0.10.0 → 0.11.0

package/package.json

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

package/src/client/dap/hover.ts

@@ -7,6 +7,7 @@
  */
 import { dapStore } from './store.js'
 import { pathOfModel } from '../monaco/lsp/lspClient.js'
+import { LUA_RESERVED_WORD_SET } from '../luaReservedWords.js'
 import { BLOCK_ATTR, EQ_ATTR, EXPR_ATTR, HEAD_ATTR, TYPE_ATTR, VAL_ATTR, createTreeState, escapeHtml, initialHtml } from './hoverTree.js'
 
 const GLOBAL_KEY = '__edrvDapHoverProvider__'
@@ -35,12 +36,6 @@ function treeKeyOf(target: { expression: string; lineNumber: number; startColumn
   return target.expression + '@' + path + ':' + target.lineNumber + ':' + target.startColumn + '-' + target.endColumn
 }
 
-/** Lua 保留字集合（保留字不是可求值表达式，避免 adapter 返回 syntax err 噪声）。 */
-const LUA_KEYWORDS = new Set([
-  'and', 'break', 'do', 'else', 'elseif', 'end', 'false', 'for', 'function', 'goto',
-  'if', 'in', 'local', 'nil', 'not', 'or', 'repeat', 'return', 'then', 'true', 'until', 'while',
-])
-
 /** 可求值路径表达式：标识符链，成员用 . 或 : 连接（注释里的中文文本等一律不匹配）。 */
 const EVAL_EXPR = /^[A-Za-z_][A-Za-z0-9_]*(?:[.:][A-Za-z_][A-Za-z0-9_]*)*$/
 
@@ -51,7 +46,7 @@ const EVAL_EXPR = /^[A-Za-z_][A-Za-z0-9_]*(?:[.:][A-Za-z_][A-Za-z0-9_]*)*$/
  * @returns 是否可求值
  */
 function isEvalExpr(text: string): boolean {
-  return EVAL_EXPR.test(text) && !LUA_KEYWORDS.has(text)
+  return EVAL_EXPR.test(text) && !LUA_RESERVED_WORD_SET.has(text)
 }
 
 /**

package/src/client/index.ts

@@ -27,6 +27,8 @@ import { createFileOpenerRegistry, scanSidebar, officialSidebarOpener, shouldCla
 import type { FileOpenerRegistry } from './fileOpeners.js'
 import { installOpenPathRouter, vscodeOpener, autoValue } from './openPathRouter.js'
 import { patchRemoteOpen, probeRemoteOpen } from './remoteOpenRouter.js'
+import { patchSettingsDoc, probeSettingsDoc } from './settingsDocRouter.js'
+import { openEditorView } from './events.js'
 import { setupExtOpen } from './externalOpen.js'
 import { SettingsContext } from './settingsContext.js'
 import { SIDEBAR_PLUGIN, registerSlotSafely, settingsBridge } from './compat.js'
@@ -104,6 +106,29 @@ function setupCommands(ctx: any): void {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function apply(ctx: any): void {
   const schedule = (fn: () => void, ms: number) => ctx.timeout(fn, ms)
+  ctx.effect(() => {
+    let disposed = false
+    let attempts = 0
+    let restore: (() => void) | null = null
+    const install = (): void => {
+      if (disposed || restore || attempts >= 15) return
+      attempts += 1
+      const service = probeSettingsDoc(ctx)
+      if (service) {
+        restore = patchSettingsDoc(service, async () => {
+          const result = await rpc('vscode.settingsDocumentPath', {})
+          return result.ok ? { ok: true, path: result.path } : { ok: false, error: result.error }
+        }, openEditorView, (message) => log.warn(message))
+        if (restore) return
+      }
+      if (attempts < 15) schedule(install, 2000)
+    }
+    install()
+    return () => {
+      disposed = true
+      restore?.()
+    }
+  }, 'vscode-mode: settings document editor route')
 
   // 指令系统（命令栏 + 指令注册表）先装配：命令栏在被任何 React slot 渲染前即可唤起
   setupCommands(ctx)

package/src/client/luaReservedWords.ts

@@ -0,0 +1,10 @@
+/**
+ * Lua 5.3 保留字，供编辑器补全与调试悬停共同使用。
+ * 作者 ddj 2026年09月24号
+ */
+export const LUA_RESERVED_WORDS = [
+  'and', 'break', 'do', 'else', 'elseif', 'end', 'false', 'for', 'function', 'goto',
+  'if', 'in', 'local', 'nil', 'not', 'or', 'repeat', 'return', 'then', 'true', 'until', 'while',
+] as const
+
+export const LUA_RESERVED_WORD_SET: ReadonlySet<string> = new Set(LUA_RESERVED_WORDS)

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

@@ -0,0 +1,121 @@
+/**
+ * 为 Lua 的 LSP 补全补充服务器缺失的保留字与注解基础类型候选。
+ * 作者 ddj 2026年09月24号
+ */
+import { LUA_RESERVED_WORDS } from '../../luaReservedWords.js'
+
+const LUA_BASE_TYPES = [
+  'any', 'boolean', 'integer', 'nil', 'number', 'string', 'table', 'thread', 'userdata',
+] as const
+const TYPE_START = /^\s*---@(?:(?:type|return)\s+|param\s+\S+\s+|field\s+(?:(?:public|private|protected|package)\s+)?\S+\s+)(.*)$/
+
+interface KeywordRange {
+  startLineNumber: number
+  endLineNumber: number
+  startColumn: number
+  endColumn: number
+}
+
+interface KeywordItem {
+  label: string
+  kind: number
+  insertText: string
+  range: KeywordRange
+  detail: string
+}
+
+/**
+ * 构造轻量本地候选，保留服务器同名项的优先权交给 mergeKeywords。
+ * @author ddj 2026年09月24号
+ * @param words 候选文本
+ * @param kind Monaco 候选类型
+ * @param range 当前单词范围
+ * @param detail 候选说明
+ * @returns 可直接交给 Monaco 的候选
+ */
+function keywordItems(words: readonly string[], kind: number, range: KeywordRange, detail: string): KeywordItem[] {
+  return words.map((label) => ({ label, kind, insertText: label, range, detail }))
+}
+
+/**
+ * 判断光标是否在 EmmyLua 注解的类型槽；普通注释和描述文字均不匹配。
+ * @author ddj 2026年09月24号
+ * @param model 当前文档
+ * @param position 光标所在行
+ * @param range 当前词范围
+ * @returns 是否应提示基础类型
+ */
+export function isLuaTypeSlot(
+  model: { getLineContent(lineNumber: number): string },
+  position: { lineNumber: number },
+  range: Pick<KeywordRange, 'startColumn'>,
+): boolean {
+  const beforeWord = model.getLineContent(position.lineNumber).slice(0, range.startColumn - 1)
+  const match = TYPE_START.exec(beforeWord)
+  if (!match) return false
+  const context = match[1] ?? ''
+  const typePrefix = context.trimEnd()
+  if (/[.:]$/.test(typePrefix)) return false
+  return !(/\s$/.test(context) && typePrefix && !/[|&,<]$/.test(typePrefix))
+}
+
+/**
+ * 在普通代码位置生成关键字；成员名和类型注解位置只交给对应候选。
+ * @author ddj 2026年09月24号
+ * @param monaco Monaco 语言枚举
+ * @param model 当前文档
+ * @param position 光标所在行
+ * @param range 当前单词的替换范围
+ * @returns 当前上下文可用的 Lua 关键字候选
+ */
+export function luaKeywordsAt(
+  monaco: { languages: { CompletionItemKind: { Keyword: number } } },
+  model: { getLineContent(lineNumber: number): string },
+  position: { lineNumber: number },
+  range: KeywordRange,
+): KeywordItem[] {
+  const line = model.getLineContent(position.lineNumber)
+  const beforeWord = line.charAt(range.startColumn - 2)
+  if (beforeWord === '.' || beforeWord === ':' || /^\s*---@/.test(line)) return []
+  return keywordItems(LUA_RESERVED_WORDS, monaco.languages.CompletionItemKind.Keyword, range, 'Lua 关键字')
+}
+
+/**
+ * 仅在注解类型槽补最基本类型，项目类型和服务器自带类型仍由 LSP 提供。
+ * @author ddj 2026年09月24号
+ * @param monaco Monaco 语言枚举
+ * @param model 当前文档
+ * @param position 光标所在行
+ * @param range 当前单词的替换范围
+ * @returns 类型候选；非注解返回空数组
+ */
+export function luaTypesAt(
+  monaco: { languages: { CompletionItemKind: { Keyword: number } } },
+  model: { getLineContent(lineNumber: number): string },
+  position: { lineNumber: number },
+  range: KeywordRange,
+): KeywordItem[] {
+  if (!isLuaTypeSlot(model, position, range)) return []
+  return keywordItems(LUA_BASE_TYPES, monaco.languages.CompletionItemKind.Keyword, range, 'Lua 基础类型')
+}
+
+/**
+ * 合并 LSP 与本地关键字，服务器同名项优先并保持原顺序。
+ * @author ddj 2026年09月24号
+ * @param server 服务器候选
+ * @param keywords 本地关键字候选
+ * @returns 去重后的补全列表
+ */
+export function mergeKeywords<T extends { label: string }, U extends { label: string }>(
+  server: T[],
+  keywords: U[],
+): Array<T | U> {
+  if (keywords.length === 0) return server
+  const labels = new Set(server.map((item) => item.label))
+  const merged: Array<T | U> = [...server]
+  for (const keyword of keywords) {
+    if (labels.has(keyword.label)) continue
+    merged.push(keyword)
+  }
+  return merged
+}

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

@@ -5,8 +5,9 @@
  * 并提供 definition/references/documentSymbol/hover/status 的 RPC 薄封装。
  * 作者 ddj 2026-08-27
  */
-import { rpc } from '../../rpc.js'
+import { rpc, dbg } from '../../rpc.js'
 import { monoToLsp } from '../../../shared/lsp.js'
+import { classifyMemberSet } from './memberScope.js'
 
 /** edrv:// 模型 URI → 工作区相对/绝对路径（与 host 侧 path 对齐）。 */
 export function pathOfModel(model) {
@@ -23,9 +24,11 @@ export function pathOfModel(model) {
 }
 
 const SYNC_DEBOUNCE_MS = 250
+const MAX_DOC_VERSION = 2147483647
 
 let sessionId
 const syncTimers = new Map()
+const docVersions = new Map()
 let statusCache = { servers: [], at: 0 }
 let progressListeners = new Set()
 let ready = false
@@ -47,6 +50,9 @@ function reportStatus(text) {
  */
 export function setLspSession(id) {
   if (sessionId === id) return
+  for (const timer of syncTimers.values()) clearTimeout(timer)
+  syncTimers.clear()
+  docVersions.clear()
   sessionId = id
   void refreshStatus()
 }
@@ -87,6 +93,18 @@ function publishProgress() {
   }
 }
 
+/**
+ * LSP 版本须可被 Roslyn 的 Int32 反序列化；时间戳会直接使其退出。
+ * @author ddj 2026年09月24号
+ * @param path 文档路径
+ * @returns 当前文档下一个协议版本
+ */
+function nextDocVer(path) {
+  const version = Math.min(MAX_DOC_VERSION, (docVersions.get(path) ?? 0) + 1)
+  docVersions.set(path, version)
+  return version
+}
+
 /**
  * 立即同步某文档到 host（首次打开/查询前保证服务器已认识该文档）。
  * sessionId 缺失时仍发起请求：host 对唯一活跃会话有兜底解析，弃发会白白丢失文档归属。
@@ -99,13 +117,13 @@ export async function syncDoc(path, text, immediate = false) {
   if (!path || typeof text !== 'string') return
   if (immediate) {
     clearPending(path)
-    await rpc('edrv.lsp.sync', { sessionId, path, text, version: Date.now() }).catch(() => {})
+    await rpc('edrv.lsp.sync', { sessionId, path, text, version: nextDocVer(path) }).catch(() => {})
     return
   }
   clearPending(path)
   syncTimers.set(path, setTimeout(() => {
     syncTimers.delete(path)
-    rpc('edrv.lsp.sync', { sessionId, path, text, version: Date.now() }).catch(() => {})
+    rpc('edrv.lsp.sync', { sessionId, path, text, version: nextDocVer(path) }).catch(() => {})
   }, SYNC_DEBOUNCE_MS))
 }
 
@@ -117,6 +135,7 @@ function clearPending(path) {
 /** 文档关闭：停止去抖并通知 host。 */
 export function closeDoc(path) {
   clearPending(path)
+  docVersions.delete(path)
   void rpc('edrv.lsp.close', { sessionId, path }).catch(() => {})
 }
 
@@ -171,22 +190,65 @@ export async function fetchHover(path, text, position) {
   return res.hover || null
 }
 
+/**
+ * 成员触发字符：这类位置的补全最易被服务器的旧解析树错答（外层作用域 / 全局集）。
+ * @author ddj 2026年09月24号
+ */
+const MEMBER_TRIGGERS = new Set(['.', ':'])
+
+/**
+ * 记录成员补全诊断（仅日志，不改结果）。
+ *
+ * 现场：`ECommon.` 这类成员位置偶尔返回 `this` 的外层作用域成员或全局集
+ * （含 `this`/`...` 与大量 `CS_*`），根因指向服务器对刚输入文本的解析新鲜度，
+ * 且非确定性。此处只把每次成员补全的形态打标，供真实使用中取证后再定修复。
+ * @author ddj 2026年09月24号
+ * @param path 工作区相对路径
+ * @param position Monaco 位置（1-based）
+ * @param context LSP CompletionContext（取触发字符）
+ * @param prefix 当前输入前缀
+ * @param list 服务器归一化后的补全结果
+ */
+function logMemberDiag(path, position, context, prefix, list) {
+  const ch = context?.triggerCharacter
+  if (!MEMBER_TRIGGERS.has(ch)) return
+  const info = classifyMemberSet(list.items)
+  dbg(sessionId, '成员补全诊断 ch=' + ch
+    + ' path=' + path
+    + ' pos=' + position.lineNumber + ':' + position.column
+    + ' prefix=' + JSON.stringify(prefix ?? '')
+    + ' 条数=' + info.total
+    + ' CS_*=' + info.csCount
+    + ' 分类=' + info.kind
+    + ' 首' + info.head.length + '=' + info.head.join(','))
+}
+
 /**
  * 查询补全列表（列表阶段不带 documentation，由 resolve 补全）。
- * @author ddj 2026年09月22号
+ *
+ * `prefix` 必须随请求上报：host 在 500 条上限处做前缀感知截断，不带前缀时
+ * 只能按服务器原始顺序切，项目全局（ECommon 等）会被上万个 CS_* 桩挤出上限。
+ * @author ddj 2026年09月22号 / 2026年09月24号
  * @param path 工作区相对路径
  * @param text 文档全文（未保存内容必须进服务器，否则按旧文本解析）
  * @param position Monaco 位置（1-based）
  * @param context LSP CompletionContext（触发类型/触发字符）
+ * @param prefix 当前输入前缀（Monaco getWordUntilPosition 的词；可缺省）
  * @returns { items, incomplete }；失败或空时 null
  */
-export async function fetchCompletions(path, text, position, context) {
+export async function fetchCompletions(path, text, position, context, prefix) {
   await syncDoc(path, text, true)
   const args = { path, position: monoToLsp(position.lineNumber, position.column) }
   if (context) args.context = context
+  if (prefix) args.prefix = prefix
   const res = await queryLsp('查询补全', 'edrv.lsp.completion', args)
   if (!res || !res.completions) return null
-  return res.completions
+  const list = res.completions
+  if (list.truncated === true) {
+    dbg(sessionId, '补全结果被截断（候选超上限）：' + path + ' prefix=' + String(prefix ?? ''))
+  }
+  logMemberDiag(path, position, context, prefix, list)
+  return list
 }
 
 /**

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

@@ -0,0 +1,90 @@
+/**
+ * dsh-vscode-mode client — 成员补全结果集的形态分类（纯函数，node 可测）。
+ *
+ * 背景：`ECommon.` 这类成员位置偶尔被错答为**外层作用域集**（`this` 的成员）
+ * 或**全局集**（含 `this`/`...` 与大量 `CS_*` xLua 绑定桩），而正确答案应是
+ * `ECommon` 自身的字段。根因指向服务器对「刚输入文本」的解析新鲜度，且非确定性。
+ * 本模块只做「形态打标」供诊断日志使用，**不改变任何补全结果**。
+ *
+ * 作者 ddj 2026-09-24
+ */
+import type { LspCompletionItem } from '../../../shared/lsp.js'
+
+/** 结果集形态：empty 空；globals 全局集；outerScope 外层作用域集；member 成员集；other 其他。 */
+export type CompletionSetKind = 'empty' | 'globals' | 'outerScope' | 'member' | 'other'
+
+/** 分类结果：形态 + 计数 + 前几项（供日志与人工判读）。 */
+export interface CompletionSetInfo {
+  /** 形态标签 */
+  kind: CompletionSetKind
+  /** 条目总数 */
+  total: number
+  /** `CS_*` 绑定桩条数 */
+  csCount: number
+  /** 绑定桩占比（0–1；空集为 0） */
+  csRatio: number
+  /** 前若干条 label（便于人工判读，不参与判定） */
+  head: string[]
+}
+
+/**
+ * 外层作用域（`this` 成员）特征名。
+ *
+ * ⚠️ 这是**捕获派生的启发式标记**，不是通用的作用域判定：名单来自 2026-09-24
+ * 在 `RechargeHeartView.lua` 真实键盘复现到的 87 条错答样本（`this` 成员列表）。
+ * 用途仅是把「疑似外层作用域」的观测标出来供取证；未命中足够标记时归入 `member`，
+ * 因此**不会**把正常的成员集误报成外层集。
+ */
+const INSTANCE_MARKERS = new Set([
+  'addframe', 'addtimer', 'clearalltimers', 'buyheart', 'canvas', 'canvasgroup',
+])
+
+/**
+ * 取条目匹配文本（Monaco 口径：filterText 优先，回落 label）。
+ *
+ * 与 host 侧 `lsp/completionCap.ts` 的同名私有函数刻意各留一份：两者分属
+ * host / client 两个打包平面，不为 3 行逻辑建立跨平面依赖。
+ * @author ddj 2026年09月24号
+ * @param item 补全项
+ * @returns 匹配文本；无可用文本时为空串
+ */
+function textOfItem(item: LspCompletionItem): string {
+  const raw = typeof item?.filterText === 'string' && item.filterText ? item.filterText : item?.label
+  return typeof raw === 'string' ? raw : ''
+}
+
+/**
+ * 依据条目形态判定结果集属于哪一类。
+ * @author ddj 2026年09月24号
+ * @param lower 全部条目文本（已小写）
+ * @param total 条目总数
+ * @param csCount `CS_*` 条数
+ * @param csRatio `CS_*` 占比
+ * @returns 形态标签
+ */
+function kindOf(lower: string[], total: number, csCount: number, csRatio: number): CompletionSetKind {
+  if (total === 0) return 'empty'
+  if (lower.includes('this') || lower.includes('...') || csRatio > 0.5) return 'globals'
+  if (csCount === 0 && lower.filter((t) => INSTANCE_MARKERS.has(t)).length >= 2) return 'outerScope'
+  if (csCount === 0) return 'member'
+  return 'other'
+}
+
+/**
+ * 分类成员补全结果集（纯函数，无副作用）。
+ * @author ddj 2026年09月24号
+ * @param items 服务器归一化后的补全条目（非数组按空处理）
+ * @param headSize 日志携带的前缀条数（缺省 3）
+ * @returns 形态、计数与前几项
+ */
+export function classifyMemberSet(items: LspCompletionItem[], headSize: number = 3): CompletionSetInfo {
+  const list = Array.isArray(items) ? items : []
+  // 判定用 filterText 优先（与过滤器同口径）；日志展示用 label（人工判读友好）。
+  const texts = list.map(textOfItem)
+  const lower = texts.map((t) => t.toLowerCase())
+  const total = list.length
+  const csCount = texts.filter((t) => t.startsWith('CS_')).length
+  const csRatio = total ? csCount / total : 0
+  const head = list.slice(0, Math.max(0, headSize)).map((item) => String(item?.label ?? ''))
+  return { kind: kindOf(lower, total, csCount, csRatio), total, csCount, csRatio, head }
+}

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

@@ -18,6 +18,7 @@ import {
   LSP_SEMANTIC_TOKEN_MODIFIERS, LSP_SEMANTIC_TOKEN_TYPES,
   LSP_COMPLETION_KIND_NAMES, LSP_INSERT_TEXT_FORMAT_SNIPPET,
 } from '../../../shared/lsp.js'
+import { luaKeywordsAt, luaTypesAt, mergeKeywords } from './keywords.js'
 
 const LSP_LANGS = ['lua', 'csharp']
 
@@ -352,18 +353,27 @@ function completionsFor(monaco, lang) {
     provideCompletionItems: async (model, position, context, token) => {
       const path = pathOfModel(model)
       if (!path) return { suggestions: [] }
-      const list = await fetchCompletions(path, model.getValue(), position, toLspContext(context))
-      if (!list || !list.items.length || token?.isCancellationRequested) return { suggestions: [] }
       const word = model.getWordUntilPosition(position)
+      // 前缀必须上报：host 在条目上限处按前缀分桶截断，否则项目全局
+      // （ECommon 等）会被 xLua 绑定桩（上万个 CS_*）挤出上限且无法恢复。
+      const list = await fetchCompletions(path, model.getValue(), position, toLspContext(context), word.word)
+      if (token?.isCancellationRequested) return { suggestions: [] }
+      if (lang !== 'lua' && (!list || !list.items.length)) return { suggestions: [] }
       const fallback = {
         startLineNumber: position.lineNumber,
         endLineNumber: position.lineNumber,
         startColumn: word.startColumn,
         endColumn: word.endColumn,
       }
+      const serverItems = (list?.items ?? []).map((item) => toMonoSuggestion(monaco, item, fallback, path))
       return {
-        suggestions: list.items.map((item) => toMonoSuggestion(monaco, item, fallback, path)),
-        incomplete: list.incomplete === true,
+        suggestions: lang === 'lua'
+          ? mergeKeywords(serverItems, [
+            ...luaKeywordsAt(monaco, model, position, fallback),
+            ...luaTypesAt(monaco, model, position, fallback),
+          ])
+          : serverItems,
+        incomplete: list?.incomplete === true,
       }
     },
     resolveCompletionItem: async (item, token) => {

package/src/client/settingsDocRouter.ts

@@ -0,0 +1,52 @@
+/** Redirect the DSH settings document action into the plugin editor. */
+import { patchAccessor } from './compat.js'
+
+export interface SettingsDocResult {
+  ok: boolean
+  value?: { opened: boolean }
+}
+
+type SettingsDocOpen = (...args: unknown[]) => Promise<SettingsDocResult>
+
+/**
+ * Patch the optional DSH settings document opener; failed handoff keeps native behavior.
+ * @author ddj 2026年10月02号
+ * @param service DSH remote settings namespace
+ * @param getPath plugin RPC that prepares the profile document
+ * @param openEditor current plugin editor action
+ * @param logger optional diagnostic sink
+ * @returns disposer, or null if the DSH API is unavailable
+ */
+export function patchSettingsDoc(
+  service: object,
+  getPath: () => Promise<{ ok: boolean; path?: string; error?: string }>,
+  openEditor: (path: string) => void,
+  logger?: (message: string) => void,
+): (() => void) | null {
+  return patchAccessor(service, 'openSettingsDocument', async (original, ...args) => {
+    try {
+      const result = await getPath()
+      if (!result.ok || !result.path) throw new Error(result.error || '设置配置文件路径不可用')
+      openEditor(result.path)
+      return { ok: true, value: { opened: true } }
+    } catch (error) {
+      logger?.('插件编辑器打开设置配置文件失败，回退 DSH 原生打开: ' + String(error))
+      return (original as SettingsDocOpen)(...args)
+    }
+  })
+}
+
+/**
+ * Safely locate the optional DSH settings remote service.
+ * @author ddj 2026年10月02号
+ * @param ctx Client service context
+ * @returns The settings service when its document opener exists
+ */
+export function probeSettingsDoc(ctx: { get: (name: string) => unknown }): object | undefined {
+  try {
+    const service = ctx.get('remote.settings') as { openSettingsDocument?: unknown } | undefined
+    return typeof service?.openSettingsDocument === 'function' ? service : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/client/sidebar/menuItems.ts

@@ -504,6 +504,7 @@ function treeRunCtx(target: TreeMenuTarget, ctx: SidebarCtx): SvnActionRunCtx {
     path: target.path,
     notify: (message) => ctx.notify?.(message),
     openSvnDiff: (p) => ctx.openSvnDiff?.(p),
+    openSvnUpdate: (p) => ctx.openSvnUpdate?.(p),
     openSvnLog: ctx.openSvnLog,
     refreshChanges: ctx.refreshSvnChanges,
     // 确认对话框可注入（测试/宿主可替换；缺省走 window.confirm）

package/src/client/sidebar/types.ts

@@ -45,6 +45,8 @@ export interface SidebarCtx {
   openSvnLocalPair?: (left: string, right: string, leftLabel: string, rightLabel: string, title: string) => void
   /** 重查 SVN 变更清单（CLI 更新/还原/加入版本控制后由菜单动作调用）。 */
   refreshSvnChanges?: () => void
+  /** 打开 SVN 更新窗口（树菜单与其它入口共用）。 */
+  openSvnUpdate?: (path: string) => void
   /** 打开 SVN 日志弹窗（P3；菜单/命令栏「查看日志」）。 */
   openSvnLog?: (path?: string) => void
   /** 确认对话框（破坏性动作守卫；缺省走 window.confirm，测试可注入）。 */