dsh-vscode-mode 0.10.0 → 0.12.0

package/src/shared/keybindings.ts

@@ -5,6 +5,8 @@
  * `|` 连接多个候选（任一命中即触发），如 `Alt+ArrowLeft|Ctrl+Alt+-`。
  * 约束：本模块被 host 与 client 两半共用，**禁止 import client 侧模块**（React/浏览器 API）。
  * 与 client/ui/commandCatalog 的一致性由 tests/commands.test.ts 断言兜底。
+ * 官方机制（2026-10）：SHORTCUT_PROFILES 描述各命令在官方 ctx.shortcuts 的 profile 默认键位
+ * （由 client 注册官方服务时使用）；chordToBinding/bindingToChord 负责插件弦与官方绑定互转。
  * 作者 ddj 2026年08月26号 / 2026年09月10号
  */
 
@@ -66,3 +68,254 @@ export function normalizeKeybindings(raw: unknown): Record<string, string> {
   }
   return out
 }
+
+//#region 官方 shortcuts 机制映射层（纯数据/纯函数，禁 import client 侧与官方包）
+
+/** 官方 shortcuts 服务的修饰符标记（'primary' = 桌面端按平台展开为 Ctrl/Cmd，web 同语义）。 */
+export type OfficialModifier = 'primary' | 'control' | 'alt' | 'shift' | 'meta'
+
+/** 官方绑定形状（物理 code + 修饰符；与 @deepseek-ai/dsh-client-shortcuts 绑定契约同构，鸭子类型）。 */
+export interface OfficialBinding {
+  code: string
+  modifiers: OfficialModifier[]
+  secondCode?: string
+}
+
+/** 官方 profile 键（desktop|web × macos|windows|linux）。 */
+export type ShortcutProfileKey =
+  | 'desktop:macos' | 'desktop:windows' | 'desktop:linux'
+  | 'web:macos' | 'web:windows' | 'web:linux'
+
+/** 命令 id → 各 profile 官方默认键位（缺 profile = 该端不绑定）。 */
+export type ShortcutProfiles = Partial<Record<ShortcutProfileKey, OfficialBinding>>
+
+/** 显示主键 → 官方物理 code 对照（官方 code 白名单：Key[A-Z]|Digit[0-9]|F1-24|具名键）。 */
+const DISPLAY_KEY_TO_CODE: Record<string, string> = {
+  '-': 'Minus', '=': 'Equal', '[': 'BracketLeft', ']': 'BracketRight',
+  ';': 'Semicolon', "'": 'Quote', ',': 'Comma', '.': 'Period',
+  '/': 'Slash', '\\': 'Backslash', '`': 'Backquote',
+  Enter: 'Enter', Tab: 'Tab', Backspace: 'Backspace', Delete: 'Delete',
+  Escape: 'Escape', Space: 'Space',
+  ArrowUp: 'ArrowUp', ArrowDown: 'ArrowDown', ArrowLeft: 'ArrowLeft', ArrowRight: 'ArrowRight',
+}
+
+/** 官方具名 code（非 Key/Digit/F 前缀且可回显的部分）。 */
+const NAMED_CODES = ['Enter', 'Tab', 'Backspace', 'Delete', 'Escape', 'Space',
+  'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'] as const
+
+/** 官方 code → 显示主键（符号键反向对照）。 */
+const CODE_TO_DISPLAY_KEY: Record<string, string> = {
+  Minus: '-', Equal: '=', BracketLeft: '[', BracketRight: ']',
+  Semicolon: ';', Quote: "'", Comma: ',', Period: '.',
+  Slash: '/', Backslash: '\\', Backquote: '`',
+}
+
+/** 显示主键 → 官方 code（PageUp/PageDown/Home/End/Insert 等官方不支持 → null）。 */
+function keyToCode(key: string): string | null {
+  if (Object.hasOwn(DISPLAY_KEY_TO_CODE, key)) return DISPLAY_KEY_TO_CODE[key]
+  if (key.length === 1 && key >= 'a' && key <= 'z') return 'Key' + key.toUpperCase()
+  if (key.length === 1 && key >= 'A' && key <= 'Z') return 'Key' + key
+  if (key.length === 1 && key >= '0' && key <= '9') return 'Digit' + key
+  if (/^F([1-9]|1[0-9]|2[0-4])$/u.test(key)) return key
+  return null
+}
+
+/** 官方 code → 显示主键（不可回显 → null）。 */
+function codeToKey(code: string): string | null {
+  if (Object.hasOwn(CODE_TO_DISPLAY_KEY, code)) return CODE_TO_DISPLAY_KEY[code]
+  if (/^Key[A-Z]$/u.test(code)) return code.slice(3)
+  if (/^Digit[0-9]$/u.test(code)) return code.slice(5)
+  if (/^F([1-9]|1[0-9]|2[0-4])$/u.test(code)) return code
+  if ((NAMED_CODES as readonly string[]).includes(code)) return code
+  return null
+}
+
+/** 插件弦的修饰符 token → 官方修饰符（Ctrl 与 Cmd 同为 primary，与 matchEvent 的互认语义一致）。 */
+const CHORD_MODIFIER_TOKENS: Record<string, OfficialModifier> = {
+  ctrl: 'primary', control: 'primary', cmd: 'primary', meta: 'primary',
+  shift: 'shift', alt: 'alt',
+}
+
+/**
+ * 插件键位弦（单候选）→ 官方绑定。
+ * 不可表示的主键（PageUp/PageDown/Home/End/Insert 等）返回 null，调用方跳过。
+ * @author ddj 2026年10月
+ * @param chord 键位弦（如 `Ctrl+Alt+-` / `F9` / `Alt+ArrowLeft`）
+ * @returns 官方绑定或 null
+ */
+export function chordToBinding(chord: string): OfficialBinding | null {
+  const parts = String(chord ?? '').split('+').map((part) => part.trim()).filter(Boolean)
+  if (!parts.length) return null
+  const modifiers = new Set<OfficialModifier>()
+  let key = ''
+  for (const part of parts) {
+    const modifier = CHORD_MODIFIER_TOKENS[part.toLowerCase()]
+    if (modifier) {
+      modifiers.add(modifier)
+      continue
+    }
+    if (key) return null
+    key = part
+  }
+  if (!key) return null
+  if (key === ' ') key = 'Space'
+  else if (key.length === 1 && key >= 'a' && key <= 'z') key = key.toUpperCase()
+  const code = keyToCode(key)
+  return code === null ? null : { code, modifiers: [...modifiers] }
+}
+
+/**
+ * 官方绑定 → 插件显示键位弦（primary 显示为 Ctrl，与历史 tooltip 文案保持一致）。
+ * @author ddj 2026年10月
+ * @param binding 官方绑定
+ * @returns 插件弦（不可表示 → null）
+ */
+export function bindingToChord(binding: OfficialBinding): string | null {
+  if (!binding || typeof binding !== 'object') return null
+  const key = codeToKey(binding.code)
+  if (key === null) return null
+  let suffix = ''
+  if (binding.secondCode !== undefined) {
+    const secondKey = codeToKey(binding.secondCode)
+    if (secondKey === null) return null
+    suffix = '+' + secondKey
+  }
+  const parts: string[] = []
+  if (binding.modifiers.includes('primary')) parts.push('Ctrl')
+  if (binding.modifiers.includes('shift')) parts.push('Shift')
+  if (binding.modifiers.includes('alt')) parts.push('Alt')
+  return [...parts, key + suffix].join('+')
+}
+
+/** 官方绑定字面量构造（表格可读性辅助）。 */
+function bind(code: string, modifiers: OfficialModifier[]): OfficialBinding {
+  return { code, modifiers }
+}
+
+/**
+ * 命令 id → 官方 profile 默认键位（与 KEYBINDING_DEFAULTS 一一对应；client 注册官方服务的数据源）。
+ * 取值约束（对齐官方 bindingIssue/isWebBindingAllowed 校验，错报会在注册时抛错）：
+ * - desktop:macos/windows：官方不做保留校验，用 VS Code 同款 chord；
+ * - desktop:linux / web:linux：Arrow*、裸 F 键、全 Shift、Ctrl+V/C/X/Z/Y/Q/H/A、Meta 均为保留键 → 不声明；
+ * - web:macos/windows：单修饰符组合不在白名单 → 用 primary+alt / primary+shift 变体（官方 ui-layout 同款）；
+ * - Ctrl+PageDown/PageUp 候选废弃（官方 code 白名单无 PageUp/PageDown）；
+ * - edrv.toggleSidebar 留空：Ctrl+B 与官方 sidebar.left.toggle（Mod+B）冲突，注册会抛错且冲突键互相阻断。
+ * @author ddj 2026年10月
+ */
+export const SHORTCUT_PROFILES: Record<string, ShortcutProfiles> = {
+  'edrv.toggleSidebar': {},
+  'edrv.save': {
+    'desktop:macos': bind('KeyS', ['primary']),
+    'desktop:windows': bind('KeyS', ['primary']),
+    'desktop:linux': bind('KeyS', ['primary']),
+  },
+  // 官方 workspace.files 已占用桌面 primary+P 和 Web primary+alt+P；插件 QuickOpen 使用非冲突组合。
+  'edrv.quickOpen': {
+    'desktop:macos': bind('KeyP', ['primary', 'alt']),
+    'desktop:windows': bind('KeyP', ['primary', 'alt']),
+    'desktop:linux': bind('KeyP', ['primary', 'alt']),
+    'web:macos': bind('KeyP', ['primary', 'alt', 'shift']),
+    'web:windows': bind('KeyP', ['primary', 'alt', 'shift']),
+  },
+  'edrv.searchInFiles': {
+    'desktop:macos': bind('KeyF', ['primary', 'shift']),
+    'desktop:windows': bind('KeyF', ['primary', 'shift']),
+    'desktop:linux': bind('KeyF', ['primary', 'shift']),
+    'web:macos': bind('KeyF', ['primary', 'shift']),
+    'web:windows': bind('KeyF', ['primary', 'shift']),
+  },
+  // Ctrl+Shift+V（primary+KeyV）在 linux 为保留键（官方 bindingIssue 不豁免 shift），desktop:linux 不声明
+  'edrv.toggleMarkdownPreview': {
+    'desktop:macos': bind('KeyV', ['primary', 'shift']),
+    'desktop:windows': bind('KeyV', ['primary', 'shift']),
+    'web:macos': bind('KeyV', ['primary', 'shift']),
+    'web:windows': bind('KeyV', ['primary', 'shift']),
+  },
+  // 导航历史：主候选 Alt+Arrow 在 linux/web 为保留或白名单外；web 取第二候选（Ctrl+Alt+- / Ctrl+Shift+-）
+  'edrv.navigateBack': {
+    'desktop:macos': bind('ArrowLeft', ['alt']),
+    'desktop:windows': bind('ArrowLeft', ['alt']),
+    'web:macos': bind('Minus', ['primary', 'alt']),
+    'web:windows': bind('Minus', ['primary', 'alt']),
+  },
+  'edrv.navigateForward': {
+    'desktop:macos': bind('ArrowRight', ['alt']),
+    'desktop:windows': bind('ArrowRight', ['alt']),
+    'web:macos': bind('Minus', ['primary', 'shift']),
+    'web:windows': bind('Minus', ['primary', 'shift']),
+  },
+  // 页签循环：Ctrl+PageDown/PageUp 候选官方不可表示，仅保留 Ctrl+Alt+Arrow 主候选
+  'edrv.nextTab': {
+    'desktop:macos': bind('ArrowRight', ['primary', 'alt']),
+    'desktop:windows': bind('ArrowRight', ['primary', 'alt']),
+    'web:macos': bind('ArrowRight', ['primary', 'alt']),
+    'web:windows': bind('ArrowRight', ['primary', 'alt']),
+  },
+  'edrv.prevTab': {
+    'desktop:macos': bind('ArrowLeft', ['primary', 'alt']),
+    'desktop:windows': bind('ArrowLeft', ['primary', 'alt']),
+    'web:macos': bind('ArrowLeft', ['primary', 'alt']),
+    'web:windows': bind('ArrowLeft', ['primary', 'alt']),
+  },
+  'edrv.goToLine': {
+    'desktop:macos': bind('KeyG', ['primary']),
+    'desktop:windows': bind('KeyG', ['primary']),
+    'desktop:linux': bind('KeyG', ['primary']),
+  },
+  'edrv.showCommands': {
+    'desktop:macos': bind('KeyP', ['primary', 'shift']),
+    'desktop:windows': bind('KeyP', ['primary', 'shift']),
+    'desktop:linux': bind('KeyP', ['primary', 'shift']),
+    'web:macos': bind('KeyP', ['primary', 'shift']),
+    'web:windows': bind('KeyP', ['primary', 'shift']),
+  },
+  'edrv.nextEditorRow': {
+    'desktop:macos': bind('ArrowDown', ['primary', 'alt']),
+    'desktop:windows': bind('ArrowDown', ['primary', 'alt']),
+    'web:macos': bind('ArrowDown', ['primary', 'alt']),
+    'web:windows': bind('ArrowDown', ['primary', 'alt']),
+  },
+  'edrv.prevEditorRow': {
+    'desktop:macos': bind('ArrowUp', ['primary', 'alt']),
+    'desktop:windows': bind('ArrowUp', ['primary', 'alt']),
+    'web:macos': bind('ArrowUp', ['primary', 'alt']),
+    'web:windows': bind('ArrowUp', ['primary', 'alt']),
+  },
+  'edrv.addSelectionRef': {
+    'desktop:macos': bind('KeyU', ['primary']),
+    'desktop:windows': bind('KeyU', ['primary']),
+    'desktop:linux': bind('KeyU', ['primary']),
+  },
+  'edrv.closeTab': {
+    'desktop:macos': bind('F4', ['primary']),
+    'desktop:windows': bind('F4', ['primary']),
+    'desktop:linux': bind('F4', ['primary']),
+  },
+  // 调试 F 键：linux 判 modifier-required（裸 F/全 Shift），仅 desktop:macos/windows
+  'edrv.debugToggleBreakpoint': {
+    'desktop:macos': bind('F9', []),
+    'desktop:windows': bind('F9', []),
+  },
+  'edrv.debugStartContinue': {
+    'desktop:macos': bind('F5', []),
+    'desktop:windows': bind('F5', []),
+  },
+  'edrv.debugStepOver': {
+    'desktop:macos': bind('F10', []),
+    'desktop:windows': bind('F10', []),
+  },
+  'edrv.debugStepInto': {
+    'desktop:macos': bind('F11', []),
+    'desktop:windows': bind('F11', []),
+  },
+  'edrv.debugStepOut': {
+    'desktop:macos': bind('F11', ['shift']),
+    'desktop:windows': bind('F11', ['shift']),
+  },
+  'edrv.debugStop': {
+    'desktop:macos': bind('F5', ['shift']),
+    'desktop:windows': bind('F5', ['shift']),
+  },
+}
+
+//#endregion

package/src/shared/rpc.ts

@@ -19,7 +19,7 @@ import type { RuleInfo, RuleProject, RuleRefInput, RuleSaveInput } from './rules
 import type { SnippetEntry, SnippetInfo, SnippetProject, SnippetRefInput, SnippetSaveInput } from './snippets.js'
 import type { LspCompletionItem, LspCompletionList, LspEnvInstallState, LspExtInfo, LspExtUpdate, LspHover, LspLocation, LspMarketItem, LspPosition, LspSemanticTokens, LspServerStatus, LspSignatureHelp, LspSymbol } from './lsp.js'
 import type { AiConfigPatch, AiConfigView, AiDirectoryView, AiInlineRequest, AiInlineResult } from './ai.js'
-import type { SvnAction, SvnAiPlan, SvnChangeEntry, SvnConflictArtifact, SvnDiffRevResult, SvnIgnoreItem, SvnLogEntry, SvnRemoteOutdatedEntry, SvnStatusPayload, SvnSumEntry, SvnUpdateResult } from './svn.js'
+import type { SvnAction, SvnAiPlan, SvnChangeEntry, SvnConflictArtifact, SvnDiffRevResult, SvnIgnoreItem, SvnLogEntry, SvnRemoteOutdatedEntry, SvnStatusPayload, SvnSumEntry, SvnUpdatePoll, SvnUpdateResult, SvnUpdateState } from './svn.js'
 import type { DapAction, DapAdapterInfo, DapBreakpointAck, DapBreakpointInput, DapConfigSnippet, DapConfigSource, DapDebugConfig, DapFrameView, DapPhase, DapPollResult, DapProcessInfo, DapScopeView, DapVariableView } from './dap.js'
 import { DAP_ACTIONS } from './dap.js'
 import type { LoggerLevel } from './logger.js'
@@ -371,6 +371,7 @@ export interface RpcRequestMap {
   'mcp.projectToggle': { workspacePath: string; serverName: string; enabled: boolean }
   'mcp.projectRefresh': { workspacePath: string; serverName: string }
   'vscode.fileOpenSettingsGet': {}
+  'vscode.settingsDocumentPath': {}
   'vscode.fileOpenSettingsUpdate': { fileOpenTool: string; integrationBaseUrl?: string; expectedRevision?: number }
   'edrv.integration.status': {}
   'edrv.integration.register': {}
@@ -396,7 +397,7 @@ export interface RpcRequestMap {
   'edrv.lsp.workspaceSymbol': { sessionId?: string; query: string }
   'edrv.lsp.hover': { sessionId?: string; path: string; position: LspPosition }
   'edrv.lsp.semanticTokens': { sessionId?: string; path: string }
-  'edrv.lsp.completion': { sessionId?: string; path: string; position: LspPosition; context?: { triggerKind?: number; triggerCharacter?: string } }
+  'edrv.lsp.completion': { sessionId?: string; path: string; position: LspPosition; context?: { triggerKind?: number; triggerCharacter?: string }; prefix?: string }
   'edrv.lsp.resolveCompletion': { sessionId?: string; path: string; item: LspCompletionItem }
   'edrv.lsp.signatureHelp': { sessionId?: string; path: string; position: LspPosition }
   'edrv.lsp.redetect': { languageId: string }
@@ -447,6 +448,10 @@ export interface RpcRequestMap {
   'svn.wcRev': { sessionId?: string; path?: string }
   'svn.cleanup': { sessionId?: string; removeUnversioned?: boolean; removeIgnored?: boolean }
   'svn.update': { sessionId?: string; path?: string }
+  'svn.updateStart': { sessionId?: string; path?: string }
+  'svn.updatePoll': { sessionId?: string; jobId: string; since: number }
+  'svn.updateCancel': { sessionId?: string; jobId: string }
+  'svn.updateActive': { sessionId?: string }
   'svn.tortoise': { sessionId?: string; action: SvnAction; path?: string }
   'svn.patchText': { sessionId?: string; path: string; whitespace?: 'none' | 'b' | 'w'; ignoreEol?: boolean; unified?: number }
   'svn.diffSum': { sessionId?: string; path?: string; revA: number; revB: number }
@@ -519,6 +524,7 @@ export interface RpcOkMap {
   'mcp.projectToggle': { project: MpcProject }
   'mcp.projectRefresh': { project: MpcProject }
   'vscode.fileOpenSettingsGet': { fileOpenTool: string; integrationBaseUrl: string; revision?: number }
+  'vscode.settingsDocumentPath': { path: string }
   'vscode.fileOpenSettingsUpdate': { fileOpenTool: string; integrationBaseUrl: string; revision?: number }
   'edrv.integration.status': ShellIntegrationStatus
   'edrv.integration.register': ShellIntegrationStatus
@@ -595,6 +601,10 @@ export interface RpcOkMap {
   'svn.wcRev': { revision: number | null }
   'svn.cleanup': { summary: string; output: string }
   'svn.update': SvnUpdateResult
+  'svn.updateStart': SvnUpdateState
+  'svn.updatePoll': SvnUpdatePoll
+  'svn.updateCancel': SvnUpdateState
+  'svn.updateActive': { job: SvnUpdateState | null }
   'svn.tortoise': { launched: string }
   'svn.patchText': { text: string; truncated: boolean; binary: boolean }
   'svn.diffSum': { entries: SvnSumEntry[]; truncated: boolean }

package/src/shared/rules.ts

@@ -4,7 +4,10 @@
  * 作者 ddj 2026年09月03号
  */
 
-/** 规则作用域：用户规则（~/.dsh/rules）或项目规则（<工作区>/.dsh/rules）。 */
+/** 用户规则来源：当前 DSH_HOME 或系统用户目录的旧版 .dsh。 */
+export type UserRuleOrigin = 'current' | 'legacy'
+
+/** 规则作用域：用户规则（DSH_HOME/rules + ~/.dsh/rules）或项目规则（<工作区>/.dsh/rules）。 */
 export type RuleScope = 'user' | 'project'
 
 /** 规则生效类型（由 frontmatter 推导）：总是 / 自动（globs 命中时）/ 手动（仅索引）。 */
@@ -13,6 +16,8 @@ export type RuleType = 'always' | 'auto' | 'manual'
 /** 一条 .mdc 规则的元信息（列表行展示 + 注入语义所需的最小集）。 */
 export interface RuleInfo {
   scope: RuleScope
+  /** 用户规则的实际来源；项目规则不设置。 */
+  origin?: UserRuleOrigin
   /** 文件名（含 .mdc 后缀，不含路径）。 */
   file: string
   /** 绝对路径（host 解析，供展示与按需读取）。 */
@@ -48,6 +53,8 @@ export interface RuleSaveInput {
   scope: RuleScope
   /** project 必填：目标工作区绝对路径（须为 DSH 已注册 workspace）。 */
   workspacePath?: string
+  /** 缺省 current；仅用户规则可指定 legacy。 */
+  origin?: UserRuleOrigin
   file: string
   content: string
 }
@@ -56,5 +63,6 @@ export interface RuleSaveInput {
 export interface RuleRefInput {
   scope: RuleScope
   workspacePath?: string
+  origin?: UserRuleOrigin
   file: string
 }

package/src/shared/svn.ts

@@ -99,6 +99,44 @@ export interface SvnUpdateResult {
   output: string
 }
 
+/** 原生更新窗口的真实执行阶段。 */
+export type SvnUpdatePhase = 'starting' | 'running' | 'cancelling' | 'completed' | 'failed' | 'cancelled'
+
+/** 流式更新行；relPath 仅在目标位于当前工作区内时可操作。 */
+export interface SvnUpdateRow {
+  seq: number
+  action: SvnUpdateAction | null
+  path: string
+  relPath: string | null
+  label: string
+  raw: string
+}
+
+/** 分类数量按 svn 输出中的条目行计，不猜文件总数或网络字节。 */
+export type SvnUpdateCounts = Record<SvnUpdateAction, number>
+
+/** 更新任务快照（窗口第一次连接和每次增量 poll 共用）。 */
+export interface SvnUpdateState {
+  jobId: string
+  target: string
+  phase: SvnUpdatePhase
+  counts: SvnUpdateCounts
+  revision: number | null
+  elapsedMs: number
+  error: string
+  rawTail: string
+  truncated: boolean
+  nextSeq: number
+}
+
+/** 增量读取结果：rows 只含 since 之后的一页，offset 表示目前可重放的首条序号。 */
+export interface SvnUpdatePoll extends SvnUpdateState {
+  rows: SvnUpdateRow[]
+  offset: number
+  /** 当前后台总序号；nextSeq 仅是本次前端已经拿到的最后一条。 */
+  totalSeq: number
+}
+
 /** revert/add 等批量动作结果（计数 + 摘要 + 原文）。 */
 export interface SvnActionResult {
   /** 处理条目数（宽松计数）。 */

package/src/svn.ts

@@ -7,7 +7,7 @@
  * 作者 ddj 2026年09月16号
  */
 import { readdir, stat } from 'node:fs/promises'
-import { basename, dirname, join } from 'node:path'
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import type { Ctx, Session } from './store.js'
 import { cwdOf, sessionOf } from './registry.js'
@@ -18,6 +18,8 @@ import { buildAiPrompt, svnAiPlanOf } from './ai/svnTriage.js'
 import { attrOf, numAttrOf, scanXmlTags, textOf, unescapeXml } from './svnXml.js'
 import { TEXT_OUTPUT_CAP, batchResultOf, tailOfText, updateResultOf } from './svnText.js'
 import { LOG_CAP, LOG_DEFAULT_LIMIT, SVN_LOG_SHOW_ALL_CAP, parseLogXml, parseSvnInfoRevision } from './svnLog.js'
+import { SvnUpdateJobs } from './svnUpdateJob.js'
+import type { UpdateProcess } from './svnUpdateJob.js'
 export { batchResultOf, commitResultOf, updateResultOf } from './svnText.js'
 export { mapRepoPath, parseLogXml } from './svnLog.js'
 
@@ -387,6 +389,7 @@ interface SvnRunOutcome { code: number | null; stdout: string; stderr: string }
 /** subprocess 产句柄最小结构面（done 载荷对齐 revert.ts 的 exitCode/code 双读）。 */
 interface SpawnedHandle {
   done: Promise<{ exitCode?: number; code?: number } | undefined>
+  terminate?: () => void
   collected?: {
     stdout?: { readFrom: (n: number) => { text: string } }
     stderr?: { readFrom: (n: number) => { text: string } }
@@ -466,18 +469,35 @@ function safeRel(raw: unknown): string | null {
   return rel
 }
 
+/**
+ * 会话根可在 SVN 工作副本的子目录；CLI 在 wcRoot 执行时必须换算目标坐标。
+ * @author ddj 2026年09月24号
+ * @param cwd 当前会话目录
+ * @param wcRoot SVN 工作副本根
+ * @param rel 会话相对目标
+ * @returns SVN 根相对目标；越界返回 null
+ */
+export function svnPathOf(cwd: string, wcRoot: string, rel: string): string | null {
+  if (safeRel(rel) === null) return null
+  const wcRel = relative(wcRoot, resolve(cwd, rel || '.'))
+  if (isAbsolute(wcRel) || wcRel === '..' || wcRel.startsWith('../') || wcRel.startsWith('..\\')) return null
+  return wcRel.replace(/\\/g, '/') || '.'
+}
+
 /**
  * 创建 svn.* RPC handlers（缓存随装配生命周期；lsp/ai 同模式并入 buildHandlers）。
  * @author ddj 2026年09月16号
  * @param deps ctx + 设置读取面 + 可注入时钟
  * @returns handlers（Partial<RpcHandlerMap> 形状）
  */
-export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unknown> } {
+export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unknown>; dispose: () => void } {
   const { ctx, settings } = deps
   const now = deps.now ?? (() => Date.now())
   const findRoot = deps.findRoot ?? ((cwd: string) => findSvnRoot(cwd))
   const findTortoise = deps.findTortoise ?? ((dir: string) => findTortoiseProc(dir))
   const statusCache = new Map<string, { at: number; payload: SvnStatusPayload }>()
+  /** 运行中更新按会话目录复用工作副本根；TTL 到期才重新扫描 .svn。 */
+  const updateRootCache = new Map<string, { at: number; root: string }>()
   /** 变更清单缓存（键 = 工作副本根；TTL 短，仅合并同一轮 UI 的多处拉取）。 */
   const changesCache = new Map<string, { at: number; value: { entries: SvnChangeEntry[]; truncated: boolean } }>()
   /** 混合通道方案收件箱（key = 工作副本根；覆盖式入箱 + TTL，见 svn.aiPlanSubmit/Pending）。 */
@@ -485,6 +505,11 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
   /** 工作副本根 relative-url 缓存（日志路径映射用；探测失败也缓存空串避免反复 spawn）。 */
   const urlCache = new Map<string, { at: number; value: string }>()
   let cliProbe: { at: number; exe: string; ok: boolean } | null = null
+  const updateJobs = new SvnUpdateJobs(
+    () => ctx.get('subprocess') as UpdateProcess | null,
+    deps.platform ?? process.platform,
+    now,
+  )
 
   const subprocess = (): SpawnFn | null => {
     const sub = ctx.get('subprocess') as { spawn?: unknown } | null | undefined
@@ -499,6 +524,9 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
     let ok = false
     const spawn = subprocess()
     if (spawn) {
+      const controller = new AbortController()
+      const deadline = setTimeout(() => controller.abort(new Error('SVN CLI 探测超时')), CLI_GRACE_MS)
+      deadline.unref?.()
       try {
         const handle = spawn({
           argv: [exe, '--version', '--quiet'],
@@ -507,11 +535,20 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
           cwd: tmpdir(),
           stdio: { stdout: 'inherit', stderr: 'inherit', stdin: 'ignore' },
           graceMs: CLI_GRACE_MS,
+          signal: controller.signal,
+        })
+        const expired = new Promise<never>((_, reject) => {
+          controller.signal.addEventListener('abort', () => {
+            try { handle.terminate?.() } catch { /* 返回探测超时即可 */ }
+            reject(controller.signal.reason)
+          }, { once: true })
         })
-        const outcome = await handle.done
+        const outcome = await Promise.race([handle.done, expired])
         ok = (outcome?.exitCode ?? outcome?.code) === 0
       } catch {
         ok = false
+      } finally {
+        clearTimeout(deadline)
       }
     }
     cliProbe = { at, exe, ok }
@@ -543,6 +580,28 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
     return payload
   }
 
+  /**
+   * 验证更新请求属于当前会话的工作副本；取消/轮询不依赖 CLI 仍可用。
+   * @author ddj 2026年09月24号
+   * @param sessionId 当前会话 id
+   * @param needCli 仅真正启动更新时才探测 SVN 客户端
+   * @returns 已校验的目录和状态，或错误
+   */
+  const updateScope = async (sessionId?: string, needCli = false) => {
+    const sc = await requireSvnSession(ctx, sessionId)
+    if ('err' in sc) return { err: sc.err }
+    if (!needCli) {
+      const cached = updateRootCache.get(sc.cwd)
+      const root = cached && now() - cached.at < STATUS_TTL_MS ? cached.root : await findRoot(sc.cwd)
+      if (root && (!cached || now() - cached.at >= STATUS_TTL_MS)) updateRootCache.set(sc.cwd, { at: now(), root })
+      return root ? { cwd: sc.cwd, root, exe: '', cli: false } : { err: '当前工作区不受 SVN 管理' }
+    }
+    const status = await statusOf(sc.cwd)
+    if (!status.managed || !status.wcRoot) return { err: '当前工作区不受 SVN 管理' }
+    updateRootCache.set(sc.cwd, { at: now(), root: status.wcRoot })
+    return { cwd: sc.cwd, root: status.wcRoot, exe: status.svnPath, cli: status.svnCli }
+  }
+
   /**
    * 运行 svn CLI（管道收集；spawn 级失败回退 inherit，输出降级为空）。
    * @author ddj 2026年08月26号 / 2026年09月17号
@@ -966,8 +1025,10 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
       const status = await statusOf(sc.cwd)
       if (!status.managed || !status.wcRoot) return { ok: false as const, error: '当前工作区不受 SVN 管理' }
       if (!status.svnCli) return { ok: false as const, error: 'svn 命令不可用（可在设置页配置 svn 路径）' }
+      const svnTarget = svnPathOf(sc.cwd, status.wcRoot, rel)
+      if (svnTarget === null) return { ok: false as const, error: '日志路径不在 SVN 工作副本内' }
       try {
-        const result = await logOf(status.wcRoot, rel, args.limit ?? LOG_DEFAULT_LIMIT, {
+        const result = await logOf(status.wcRoot, svnTarget === '.' ? '' : svnTarget, args.limit ?? LOG_DEFAULT_LIMIT, {
           stopOnCopy: args.stopOnCopy === true,
           showMerged: args.showMerged === true,
           range: args.startRev && args.endRev
@@ -1026,6 +1087,8 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
       const status = await statusOf(sc.cwd)
       if (!status.managed || !status.wcRoot) return { ok: false as const, error: '当前工作区不受 SVN 管理' }
       if (!status.svnCli) return { ok: false as const, error: 'svn 命令不可用（可在设置页配置 svn 路径）' }
+      const svnRel = svnPathOf(sc.cwd, status.wcRoot, rel)
+      if (!svnRel) return { ok: false as const, error: '比较路径不在 SVN 工作副本内' }
       const fs = ctx.get('fs') as {
         resolve?: (p: string, o: object) => Promise<unknown>
         stat?: (t: unknown) => Promise<{ type?: string; size?: number } | null>
@@ -1039,7 +1102,7 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
         if ((info.size ?? 0) > READ_CAP) return { ok: false as const, error: '文件过大（>8MB），不支持与工作副本比较' }
         const working = await fs.readText(resolved)
         // 左侧 = 该版本内容；cat 失败按「该版本尚无此文件」处理（新增语义，非错误）
-        const leftOutcome = await runSvn(status.wcRoot, ['cat', '-r', String(Math.floor(revision)), '--', rel], READ_GRACE_MS)
+        const leftOutcome = await runSvn(status.wcRoot, ['cat', '-r', String(Math.floor(revision)), '--', svnRel], READ_GRACE_MS)
         if (leftOutcome.code !== 0) {
           const text = (leftOutcome.stderr || leftOutcome.stdout).trim()
           return { ok: true as const, left: null, right: working, reason: 'not-exist', error: tailOfText(text), ...guardSides(null, working) }
@@ -1363,7 +1426,7 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
       if (!status.managed) return { ok: false as const, error: '当前工作区不受 SVN 管理' }
       if (!status.svnCli) return { ok: false as const, error: 'svn 命令不可用（可在设置页配置 svn 路径）' }
       try {
-        const outcome = await runSvn(sc.cwd, ['update', rel || '.'], UPDATE_GRACE_MS)
+        const outcome = await runSvn(sc.cwd, ['update', '--', rel || '.'], UPDATE_GRACE_MS)
         const result = updateResultOf(outcome.stdout, outcome.stderr, outcome.code)
         if (outcome.code !== 0) return { ok: false as const, error: '更新失败：' + tailOfText(result.output) }
         return { ok: true as const, ...result }
@@ -1371,6 +1434,38 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
         return { ok: false as const, error: '更新失败：' + String(error) }
       }
     },
+    'svn.updateStart': async (args: { sessionId?: string; path?: string }) => {
+      const scope = await updateScope(args.sessionId, true)
+      if ('err' in scope) return { ok: false as const, error: scope.err }
+      if (!scope.cli) return { ok: false as const, error: 'svn 命令不可用（可在设置页配置 svn 路径）' }
+      const rel = safeRel(args.path)
+      if (rel === null) return { ok: false as const, error: '路径不合法' }
+      try {
+        const fs = ctx.get('fs') as { resolve?: (p: string, o: object) => Promise<unknown>; processPath?: (t: unknown) => string } | undefined
+        const cwd = fs?.resolve && fs?.processPath
+          ? fs.processPath(await fs.resolve(scope.cwd, {})) : scope.cwd
+        return { ok: true as const, ...updateJobs.start({ cwd, root: scope.root, path: rel, exe: scope.exe }) }
+      } catch (error) {
+        return { ok: false as const, error: '启动 SVN 更新失败：' + String(error) }
+      }
+    },
+    'svn.updatePoll': async (args: { sessionId?: string; jobId: string; since: number }) => {
+      const scope = await updateScope(args.sessionId)
+      if ('err' in scope) return { ok: false as const, error: scope.err }
+      try { return { ok: true as const, ...updateJobs.poll(scope.root, args.jobId, args.since) } }
+      catch (error) { return { ok: false as const, error: String(error) } }
+    },
+    'svn.updateCancel': async (args: { sessionId?: string; jobId: string }) => {
+      const scope = await updateScope(args.sessionId)
+      if ('err' in scope) return { ok: false as const, error: scope.err }
+      try { return { ok: true as const, ...updateJobs.cancel(scope.root, args.jobId) } }
+      catch (error) { return { ok: false as const, error: String(error) } }
+    },
+    'svn.updateActive': async (args: { sessionId?: string }) => {
+      const scope = await updateScope(args.sessionId)
+      if ('err' in scope) return { ok: false as const, error: scope.err }
+      return { ok: true as const, job: updateJobs.active(scope.root) }
+    },
     'svn.tortoise': async (args: { sessionId?: string; action?: SvnAction; path?: string }) => {
       const sc = await requireSvnSession(ctx, args.sessionId)
       if ('err' in sc) return { ok: false as const, error: sc.err }
@@ -1397,5 +1492,5 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
       }
     },
   }
-  return { handlers }
+  return { handlers, dispose: () => { updateJobs.dispose(); updateRootCache.clear() } }
 }