dsh-vscode-mode 0.3.1 → 0.3.2

package/package.json

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

package/src/client/addToConversation.ts

@@ -12,27 +12,155 @@ export interface RefRange {
   endLine: number
 }
 
-/** 引用动作的返回状态。 */
-export type AddOutcome = 'ok' | 'busy' | 'unavailable'
+/** 引用动作的返回状态（failed = 两条通道都没写成，内容未被改动）。 */
+export type AddOutcome = 'ok' | 'busy' | 'unavailable' | 'failed'
 
 /** 引用外观类型：文件/文件夹（DSH reference source 均支持）。 */
 export type RefAppearance = 'file' | 'folder'
 
 /** 把追加引用结果映射为可读文案（ok 用 okText；busy 提示已降级纯文本；unavailable 提示不可用）。
- * @author ddj 2026年09月03号
+ * @author ddj 2026年09月03号 / 2026年09月11号
  * @param outcome 追加结果状态
  * @param okText 成功文案（如「已添加文件引用」/「已添加文件夹引用」）
  * @returns 状态栏/通知用文案
  */
 export function statusOfAdd(outcome: AddOutcome, okText: string): string {
   if (outcome === 'ok') return okText
-  if (outcome === 'busy') return okText + '（输入框忙，已降级纯文本）'
+  if (outcome === 'busy') return okText + '（已降级纯文本）'
+  if (outcome === 'failed') return '添加引用失败（输入框忙或未就绪，请重试）'
   return '无法添加到对话（无会话或输入框不可用）'
 }
 
 /** DSH reference source 名（dsh-client-ui-reference 注册的 @file/@session 统一源）。 */
 const REF_SOURCE = 'reference'
 
+/** 输入快照的引用出现项（clipboard 投影中的位置与长度，用于坐标换算）。 */
+export interface OccurrenceLike {
+  /** clipboard 投影中的起始偏移（chip 左边界）。 */
+  offset?: number
+  /** clipboard 投影中的长度（chip 展开成 `@path` 全文的长度）。 */
+  length?: number
+}
+
+/** 输入快照（draft 为 clipboard 投影；occurrences 为 chip 列表）。 */
+export interface CursorSnapshot {
+  draft: string
+  draftRev: number
+  occurrences?: readonly OccurrenceLike[]
+}
+
+/**
+ * 把 clipboard 投影的末尾折算成 **detect 投影**的末尾。
+ *
+ * ⚠️ 两个投影对 chip 的计长不同，混用会直接毁掉已插入的引用（真实缺陷，勿改回 `draft.length`）：
+ * DSH 的 `$composerLayout()` 中 chip 在 detect 投影里只贡献 **1 个 U+FFFC**，
+ * 在 clipboard 投影里贡献 `clipboardText` 全文
+ * （`pushLeaf('chip', kid, '', kid.getTextContent())`）。
+ * 而 `insertReference(ref, span)` 的 span 走 detect 坐标并经 `selectSpan` 校验：
+ * `span.end > layout.detectLength` 时返回 null → 插入失败。
+ *
+ * 旧实现直接用 `draft.length`（clipboard 长度）当 detect 起点：草稿里一旦有 chip，
+ * 该值就超出 detect 长度 → 插入被拒 → 落入 `setDraft` 兜底，
+ * 而 `setDraft` 会整篇重建并剔除 U+FFFC（`text.replace(REFERENCE_PLACEHOLDER_RE, '')`），
+ * 于是**既有 chip 被销毁、引用退化为重复的纯文本**（即「连续添加多个引用显示异常」）。
+ *
+ * 换算：每个 chip 在 clipboard 中多算了 `length - 1`，逐个扣回即得 detect 末尾。
+ * 无 occurrences（旧版 DSH）时退化为 `draft.length`，与旧行为一致。
+ * @author ddj 2026年09月11号
+ * @param snapshot 输入快照
+ * @returns detect 投影中的文档末尾偏移
+ */
+export function detectEndOf(snapshot: CursorSnapshot): number {
+  const total = String(snapshot?.draft ?? '').length
+  const occurrences = snapshot?.occurrences
+  if (!Array.isArray(occurrences) || !occurrences.length) return total
+  let clipped = 0
+  for (const occurrence of occurrences) {
+    const length = Number(occurrence?.length ?? 0)
+    if (!Number.isFinite(length) || length <= 1) continue
+    clipped += length - 1
+  }
+  return Math.max(0, total - clipped)
+}
+
+/** chip 列表按 clipboard 偏移升序（官方已排序，此处防御性归一，丢弃非法项）。 */
+function chipsOf(snapshot: CursorSnapshot): Array<{ offset: number; length: number }> {
+  const occurrences = snapshot?.occurrences
+  if (!Array.isArray(occurrences) || !occurrences.length) return []
+  const out: Array<{ offset: number; length: number }> = []
+  for (const occurrence of occurrences) {
+    const offset = Number(occurrence?.offset ?? Number.NaN)
+    const length = Number(occurrence?.length ?? Number.NaN)
+    if (!Number.isFinite(offset) || !Number.isFinite(length) || length <= 1) continue
+    out.push({ offset: Math.max(0, offset), length })
+  }
+  return out.sort((a, b) => a.offset - b.offset)
+}
+
+/**
+ * detect 偏移 → clipboard 偏移（paddingAt 用：draft 是 clipboard 投影，不能直接按下标取字符）。
+ * 每个位于该偏移之前的 chip 在 clipboard 中多占 `length − 1`，累计补上即可。
+ * @author ddj 2026年09月11号
+ * @param snapshot 输入快照
+ * @param detectOffset detect 投影偏移
+ * @returns clipboard 投影偏移（已夹到 draft 范围内）
+ */
+export function detectToClipboardOf(snapshot: CursorSnapshot, detectOffset: number): number {
+  const total = String(snapshot?.draft ?? '').length
+  const target = Math.max(0, Math.min(Number(detectOffset) || 0, detectEndOf(snapshot)))
+  let shift = 0
+  for (const chip of chipsOf(snapshot)) {
+    const chipDetect = chip.offset - shift
+    if (chipDetect >= target) break
+    shift += chip.length - 1
+  }
+  return Math.max(0, Math.min(target + shift, total))
+}
+
+/**
+ * 插入点两侧是否需要补空格（仅纯文本通道需要；chip 由 facade 自行补尾随空格）。
+ *
+ * 在 detect 坐标的任意位置求值，故**末尾追加的行为与旧实现逐字符一致**
+ * （末尾前为非空白 → 前后各补一个空格；末尾前已是空白 → 只补尾随空格），
+ * 同时正确支持「插在文本中间」不再贴字。
+ * @author ddj 2026年09月11号
+ * @param snapshot 输入快照
+ * @param detectOffset detect 投影插入点
+ * @returns 是否需要前导/尾随空格
+ */
+export function paddingAt(snapshot: CursorSnapshot, detectOffset: number): { lead: boolean; tail: boolean } {
+  const draft = String(snapshot?.draft ?? '')
+  const at = detectToClipboardOf(snapshot, detectOffset)
+  const before = at > 0 ? draft.slice(at - 1, at) : ''
+  const after = at < draft.length ? draft.slice(at, at + 1) : ''
+  return {
+    lead: before !== '' && !/\s/.test(before),
+    // 末尾（after 为空）也补尾随空格：与旧「追加到末尾」行为一致
+    tail: after === '' || !/\s/.test(after),
+  }
+}
+
+/**
+ * 解析插入点（detect 坐标）：优先用输入框**当前光标/选区**（`caretSpan()`，
+ * 官方契约即 detect 坐标，无选区时回落文档末尾），并夹到 `[0, detectLength]`。
+ *
+ * 选区非塌缩时取 `end`（右边界）—— 插入而非替换，绝不删除用户已选中的内容。
+ * caret 缺失/非法（旧版 facade 无该方法、抛异常、NaN 等）一律回落到文档末尾。
+ * @author ddj 2026年09月11号
+ * @param caret caretSpan() 的返回值（可为 null/非法）
+ * @param detectLength detect 投影文档长度
+ * @returns detect 投影插入偏移
+ */
+export function insertOffsetOf(caret: unknown, detectLength: number): number {
+  const max = Math.max(0, Number(detectLength) || 0)
+  if (!caret || typeof caret !== 'object') return max
+  const span = caret as { start?: unknown; end?: unknown }
+  const raw = Number(span.end)
+  const value = Number.isFinite(raw) ? raw : Number(span.start)
+  if (!Number.isFinite(value)) return max
+  return Math.max(0, Math.min(value, max))
+}
+
 /**
  * 生成 DSH @file 语法引用串：cwd 相对化、\ → /、含空白时按 @"path" 语法加引号。
  * cwd 外/无法相对化的路径回退原路径。
@@ -103,8 +231,15 @@ export function buildFileRef(
 
 /** 输入门面最小形状（运行时来自 ctx.conversation.input，避免引入新类型依赖）。 */
 export interface InputLike {
-  state: { getSnapshot: () => { draft: string; draftRev: number } }
+  state: { getSnapshot: () => CursorSnapshot }
+  /**
+   * 当前光标/选区（**detect 坐标**；无选区时回落为文档末尾的塌缩 span）。
+   * 官方 facade 契约：`caretSpan(): { start, end }`，与 insertReference 同一坐标系。
+   */
+  caretSpan?: () => { start?: number; end?: number } | null
   insertReference: (ref: ReferenceInsertLike, span: TokenSpanLike) => boolean
+  /** 纯文本插入（官方 plain-text reference path；按 detect 坐标替换，不重建文档）。 */
+  insertText?: (text: string, span: TokenSpanLike, keepCompleting?: boolean) => boolean
   setDraft: (text: string) => void
 }
 
@@ -154,19 +289,24 @@ export function inputFor(ctx: CtxLike, sessionId: string | undefined): InputLike
     const conversation = ctx.get('conversation') as { input?: { for: (actx: unknown) => unknown } } | undefined
     const actx = sessions?.scope?.(sessionId)
     const shell = actx && conversation?.input?.for?.(actx)
-    return (shell && typeof (shell as InputLike).setDraft === 'function') ? shell as InputLike : undefined
+    // 探针须是我们的**实际依赖**（insertReference），而不是会被整篇重建的 setDraft
+    return (shell && typeof (shell as InputLike).insertReference === 'function') ? shell as InputLike : undefined
   } catch {
     return undefined
   }
 }
 
-/** 取当前草稿长度与版本；无输入门面时返回 null。
- * @author ddj 2026年08月25号 */
-function draftCursor(input: InputLike | undefined): { draft: string; draftRev: number } | null {
+/** 取当前草稿快照（长度/版本/chip 列表）；无输入门面时返回 null。
+ * @author ddj 2026年08月25号 / 2026年09月11号 */
+function draftCursor(input: InputLike | undefined): CursorSnapshot | null {
   try {
     const s = input?.state?.getSnapshot?.()
     if (!s) return null
-    return { draft: String(s.draft ?? ''), draftRev: Number(s.draftRev ?? 0) }
+    return {
+      draft: String(s.draft ?? ''),
+      draftRev: Number(s.draftRev ?? 0),
+      occurrences: Array.isArray(s.occurrences) ? s.occurrences : undefined,
+    }
   } catch {
     return null
   }
@@ -196,9 +336,40 @@ function safeInsert(input: InputLike, reference: ReferenceInsertLike, span: Toke
   }
 }
 
+/** 输入门面插入纯文本（官方 plain-text 通道；不存在或异常视作未应用）。
+ * @author ddj 2026年09月11号 */
+function safeInsertText(input: InputLike, text: string, span: TokenSpanLike): boolean {
+  if (typeof input.insertText !== 'function') return false
+  try {
+    return input.insertText(text, span) === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 读输入框当前光标（detect 坐标）；门面缺失/异常返回 null（由调用方回落到文档末尾）。
+ * @author ddj 2026年09月11号
+ * @param input 输入门面
+ * @returns caretSpan 结果或 null
+ */
+function caretOf(input: InputLike): { start?: number; end?: number } | null {
+  if (typeof input.caretSpan !== 'function') return null
+  try {
+    return input.caretSpan() ?? null
+  } catch {
+    return null
+  }
+}
+
 /**
  * 创建「添加到对话」动作集（apply 阶段构建一次，随 props 传给 EditorView）。
- * @author ddj 2026年08月25号
+ *
+ * 插入位置 = 输入框**当前光标**（`caretSpan()`，detect 坐标；无光标提示时回落文档末尾），
+ * 不再固定追加到最末尾。坐标一律用 **detect 投影**（见 detectEndOf 的缺陷说明）；
+ * 两条写入通道都失败时**不写任何内容**并返回 'failed' —— 旧实现在此处退回 `setDraft`
+ * 整篇重建，会把既有 chip 全部销毁（连续添加多个引用即触发）。
+ * @author ddj 2026年08月25号 / 2026年09月11号
  * @param ctx 客户端服务上下文（sessions + conversation）
  * @returns 动作集
  */
@@ -209,15 +380,16 @@ export function createAddToConversation(ctx: CtxLike): AddToConversation {
     const cur = draftCursor(input)
     if (!cur) return 'unavailable'
     const { reference, mention } = buildFileRef(path, cwdOf(ctx, sessionId), range, appearance)
-    const span: TokenSpanLike = { start: cur.draft.length, end: cur.draft.length, draftRev: cur.draftRev }
-    const ok = safeInsert(input, reference, span)
-    if (!ok) {
-      // 忙态（adjudicating/submitting）或 CAS 失败：降级纯文本追加，保证动作有落点。
-      const gap = cur.draft.length > 0 && !/\s$/.test(cur.draft) ? ' ' : ''
-      input.setDraft(cur.draft + gap + mention + ' ')
-      return 'busy'
-    }
-    return 'ok'
+    // 光标位置（detect 坐标）；caretSpan 不可用时 = 文档末尾（旧行为）
+    const at = insertOffsetOf(caretOf(input), detectEndOf(cur))
+    const span: TokenSpanLike = { start: at, end: at, draftRev: cur.draftRev }
+    if (safeInsert(input, reference, span)) return 'ok'
+    // chip 通道被拒（忙态/坐标 CAS 过期）：改用纯文本通道就地替换，**保留既有 chip**。
+    const pad = paddingAt(cur, at)
+    const text = (pad.lead ? ' ' : '') + mention + (pad.tail ? ' ' : '')
+    if (safeInsertText(input, text, span)) return 'busy'
+    // 两条通道都不可用：宁可不写，也不整篇重建（那会销毁用户已插入的引用）
+    return 'failed'
   }
 
   return { appendReference }

package/src/client/editorModelState.ts

@@ -19,6 +19,12 @@ export const EDITOR_ROOT_SELECTOR = '.edrv-editor-row'
 /** Monaco 编辑器实例选择器（限定在插件编辑器行内，排除官方预览等其它 Monaco）。 */
 export const EDITOR_MODEL_SELECTOR = EDITOR_ROOT_SELECTOR + ' .monaco-editor'
 
+/**
+ * 已打开文件页签选择器（页签栏在编辑器行内；空态时无此节点）。
+ * 判据同样不依赖 Monaco：图片/PDF 页签没有 Monaco 实例，但仍是「有页签可关」。
+ */
+export const TAB_SELECTOR = EDITOR_ROOT_SELECTOR + ' .edrv-tabs .edrv-tab'
+
 /**
  * 当前文档是否挂载了编辑器视图（无 document 的运行环境返回 false）。
  * @author ddj 2026年09月10号
@@ -40,3 +46,15 @@ export function hasEditorModel(): boolean {
   if (typeof document === 'undefined') return false
   return document.querySelector(EDITOR_MODEL_SELECTOR) !== null
 }
+
+/**
+ * 当前是否已打开文件页签（「关闭当前页签」等页签级命令的可用性判据）。
+ * 用页签 DOM 而非 Monaco model 判定：图片/PDF 页签没有 Monaco 实例但可以关闭；
+ * 无页签时返回 false，让 Ctrl+F4 之类按键放行给浏览器（与 addSelectionRef「不吞键」同款约定）。
+ * @author ddj 2026年09月11号
+ * @returns 是否存在已打开的文件页签
+ */
+export function hasOpenTabs(): boolean {
+  if (typeof document === 'undefined') return false
+  return document.querySelector(TAB_SELECTOR) !== null
+}

package/src/client/openFlow.ts

@@ -312,7 +312,8 @@ function realDeps(ctx: unknown, overrides: Partial<OpenDeps> = {}): OpenDeps {
     openSession: (id) => service('sessions').open(id),
     reference: async (sessionId, path, appearance) => {
       const outcome: AddOutcome = await add.appendReference(sessionId, path, undefined, appearance)
-      return outcome !== 'unavailable'
+      // ok/busy（纯文本降级）都算已落点；unavailable/failed 交给 settleRef 继续重试
+      return outcome === 'ok' || outcome === 'busy'
     },
     choose: (title, folder) => chooseWorkspace(title, folder),
     openEditor: (path, line, column) => {

package/src/client/paths.ts

@@ -14,8 +14,10 @@ export const CACHE_KEY = {
   entries: 'edrv.cache.entries.v2.',
   /** 编辑区视图状态（viewStateCache v1）。 */
   viewstate: 'edrv.cache.viewstate.v1.',
-  /** 编辑器页签/活动文件（EditorView v2）。 */
-  editor: 'edrv.editor.v2.',
+  /** 编辑器页签/活动文件（EditorView v3：页签带 pinned 固定标记）。 */
+  editor: 'edrv.editor.v3.',
+  /** 旧编辑器页签键（v2：页签为纯路径数组）——仅用于一次性回读迁移，不再写入。 */
+  editorLegacy: 'edrv.editor.v2.',
   /** 侧边栏状态（EditorView；按布局 side/central 追加段）。 */
   sidebar: 'edrv.sidebar.',
   /** 搜索面板条件（SearchPanel v1）。 */

package/src/client/saveDebounce.ts

@@ -0,0 +1,69 @@
+/**
+ * dsh-vscode-mode client — 防抖保存槽（纯逻辑，可单测）。
+ *
+ * 存在意义（真实缺陷，勿把「取消」与「保存」再合并回一个句柄）：
+ * 自动保存由 `schedule(fn, 700)` 承载，而 `schedule` = `ctx.timeout(fn, ms)` 的返回值是
+ * **cordis disposer**（只 `clearTimeout`，不执行 fn）。旧实现把定时器句柄直接存下，并在
+ * 「切页签 / 关闭文件 / 卸载」时调用它来「立即保存」—— 实际只取消了这一轮保存，
+ * 于是 700ms 防抖窗口内的编辑**既不落盘也不再重试**，静默丢改动
+ * （实测：改文件后 150ms 内关闭页签，磁盘仍是旧内容）。
+ *
+ * 故把「取消」与「立即提交」拆成两个明确入口：
+ * - `arm()`   重新计时（先取消上一轮，到点自动执行）
+ * - `flush()` 立即执行待提交的保存（先取消定时器防重复，再执行回调体）
+ * - `cancel()` 纯取消（确实要放弃时才用）
+ *
+ * 作者 ddj 2026年09月11号
+ */
+
+/** 定时器调度器（EditorView 传入 ctx.timeout 包装；返回值为 canceller）。 */
+export type Scheduler = (fn: () => void, ms: number) => (() => void) | undefined
+
+/** 防抖保存槽句柄。 */
+export interface SaveTimer {
+  /** 重新计时：取消上一轮并挂新定时器（到点自动执行并清槽）。 */
+  arm(schedule: Scheduler, delay: number, run: () => void): void
+  /** 立即提交待执行的保存（无待提交时为空操作）；幂等。 */
+  flush(): void
+  /** 纯取消（不保存）。 */
+  cancel(): void
+  /** 当前是否有待提交的保存。 */
+  isPending(): boolean
+}
+
+/**
+ * 创建防抖保存槽。
+ * @author ddj 2026年09月11号
+ * @returns 保存槽句柄
+ */
+export function createSaveTimer(): SaveTimer {
+  let pending: { cancel?: () => void; run: () => void } | null = null
+  return {
+    arm(schedule, delay, run) {
+      if (pending) { pending.cancel?.(); pending = null }
+      const cancel = schedule(() => {
+        // 到点：先清槽再执行，避免回调内 flush 重入同一份保存
+        pending = null
+        run()
+      }, delay)
+      pending = { cancel: typeof cancel === 'function' ? cancel : undefined, run }
+    },
+    flush() {
+      const slot = pending
+      if (!slot) return
+      pending = null
+      // 先取消定时器再执行：否则到点后会重复保存一次
+      slot.cancel?.()
+      slot.run()
+    },
+    cancel() {
+      const slot = pending
+      if (!slot) return
+      pending = null
+      slot.cancel?.()
+    },
+    isPending() {
+      return pending !== null
+    },
+  }
+}

package/src/client/sidebar/panels/FileExplorer.ts

@@ -16,6 +16,7 @@ import { buildTreeMenu } from '../contextMenu.js'
 import { explorerLoad, explorerSave } from '../../state/explorerCache.js'
 import { entriesCacheGet, entriesCacheIsFresh, entriesCachePut } from '../../state/explorerEntriesCache.js'
 import { workspaceScopeOf } from '../../state/scopeStore.js'
+import { ancestorDirsOf } from '../../tabActions.js'
 import type { SidebarCtx } from '../types.js'
 
 const DIR_CAP = 4000
@@ -23,6 +24,10 @@ const SAVE_DEBOUNCE_MS = 300
 const FOLLOW_INTERVAL_MS = 10_000
 const PREFETCH_MAX = 4
 const PREFETCH_EXCLUDED = new Set(['node_modules', '.git', '.hg', '.svn', '.pnpm', '.pnpm-store'])
+/** 「在资源管理器视图中显示」高亮时长与定位重试上限（目录懒加载需等待行渲染）。 */
+const REVEAL_HIGHLIGHT_MS = 2000
+const REVEAL_RETRY_MAX = 6
+const REVEAL_RETRY_MS = 120
 
 // --region 行图标（官方原语：目录文件夹图标 + 文件类型图标；缺失时回落纯文本）
 
@@ -76,6 +81,16 @@ function refreshIconEl() {
 }
 // --endregion
 
+/**
+ * 转义 CSS 属性选择器的值（路径含引号/反斜杠时避免选择器语法错误）。
+ * @author ddj 2026年09月11号
+ * @param value 原始值
+ * @returns 可安全嵌入 `[attr="…"]` 的字符串
+ */
+function cssEscape(value) {
+  return String(value ?? '').replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
 /**
  * 目录树面板主体（SWR：有缓存先渲染，无缓存才显示加载态；加载总在后台）。
  * @param props.ctx 面板共享上下文（sessionId/openFile/activePath/pendingByPath/fileMenuItems/notify）
@@ -94,6 +109,7 @@ export function FileExplorer(props) {
   const [loading, setLoading] = React.useState({})
   const [errors, setErrors] = React.useState({}) // rel → 错误文案（仅无任何数据时展示）
   const [menu, setMenu] = React.useState(null) // 右键菜单 { x, y, target }
+  const [revealPath, setRevealPath] = React.useState(null) // 高亮的相对路径（「在资源管理器视图中显示」）
   // 各状态 ref 镜像：定时器/监听用最新闭包
   const tokensRef = React.useRef({})
   const expandedRef = React.useRef({})
@@ -105,6 +121,10 @@ export function FileExplorer(props) {
   const saveTimerRef = React.useRef(null)
   const loadDirRef = React.useRef(null)
   const refreshRef = React.useRef(null)
+  const revealTimerRef = React.useRef(null) // 高亮清除计时器
+  const revealTryRef = React.useRef(0) // 当前定位的重试计数（行渲染需等目录加载）
+  const revealInTreeRef = React.useRef(null) // 定位动作最新闭包（窗口监听读取）
+  const treeRef = React.useRef(null) // 目录树容器（定位时按 data-edrv-path 查行）
 
   /** 渲染取数：内存态 → 本地条目缓存 → null（显示加载态）。 */
   const entriesOf = (rel) => dirsRef.current[rel] ?? entriesCacheGet(scope, rel) ?? null
@@ -179,6 +199,50 @@ export function FileExplorer(props) {
     void loadDir(rel, { prefetch: true })
   }
 
+  /**
+   * 尝试把目标行滚入可见并高亮；行尚未渲染（祖先目录仍在加载）时按上限重试。
+   * @author ddj 2026年09月11号
+   * @param path 目标相对路径
+   */
+  const tryReveal = (path) => {
+    const host = treeRef.current
+    const row = host?.querySelector?.('[data-edrv-path="' + cssEscape(path) + '"]')
+    if (!row) {
+      revealTryRef.current += 1
+      if (revealTryRef.current < REVEAL_RETRY_MAX) {
+        window.setTimeout(() => tryReveal(path), REVEAL_RETRY_MS)
+      }
+      return
+    }
+    row.scrollIntoView?.({ block: 'center' })
+    setRevealPath(path)
+    if (revealTimerRef.current) clearTimeout(revealTimerRef.current)
+    revealTimerRef.current = window.setTimeout(() => {
+      revealTimerRef.current = null
+      setRevealPath(null)
+    }, REVEAL_HIGHLIGHT_MS)
+  }
+
+  /**
+   * 在资源管理器视图中显示：展开全部祖先目录并定位高亮目标文件。
+   * 目录条目懒加载，故先展开祖先并触发加载，再由 tryReveal 轮询等行渲染。
+   * @author ddj 2026年09月11号
+   * @param path 目标相对路径
+   */
+  const revealInTree = (path) => {
+    if (!path) return
+    const ancestors = ancestorDirsOf(path)
+    revealTryRef.current = 0
+    setExpanded((prev) => {
+      const next = Object.assign({}, prev)
+      for (const dir of ancestors) next[dir] = true
+      return next
+    })
+    for (const dir of ancestors) void loadDir(dir, { prefetch: false })
+    tryReveal(path)
+  }
+  revealInTreeRef.current = revealInTree
+
   const refresh = () => {
     const keep = Object.keys(expandedRef.current).filter((k) => expandedRef.current[k] === true)
     tokensRef.current = {}
@@ -206,6 +270,7 @@ export function FileExplorer(props) {
     setErrors({})
     setMenu(null)
     setRoot(null)
+    setRevealPath(null)
     // 恢复上次展开状态（对齐 VSCode：持久化展开路径，条目缓存即时渲染、后台刷新）
     const cached = scope ? explorerLoad(scope) : null
     const restored = cached?.expanded ?? []
@@ -244,6 +309,20 @@ export function FileExplorer(props) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
+  // 在资源管理器视图中显示（页签右键菜单）：展开祖先目录并定位高亮
+  React.useEffect(() => {
+    const onReveal = (event) => {
+      const path = event?.detail?.path
+      if (typeof path === 'string' && path) revealInTreeRef.current?.(path)
+    }
+    window.addEventListener('edrv:reveal-path', onReveal)
+    return () => {
+      window.removeEventListener('edrv:reveal-path', onReveal)
+      if (revealTimerRef.current) { clearTimeout(revealTimerRef.current); revealTimerRef.current = null }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
   // 10s 轻量跟随：已展开目录后台刷新（命中 host 索引，近零成本），树跟随 agent 写入
   React.useEffect(() => {
     if (!scope) return
@@ -267,8 +346,10 @@ export function FileExplorer(props) {
       key: e.path,
       className: 'edrv-tree-row'
         + (active ? ' edrv-tree-active' : '')
-        + (contextTarget ? ' edrv-tree-context' : ''),
+        + (contextTarget ? ' edrv-tree-context' : '')
+        + (revealPath === e.path ? ' edrv-tree-reveal' : ''),
       title: e.path,
+      'data-edrv-path': e.path,
       style: { paddingLeft: 6 + depth * 14 },
       onClick: () => { if (isDir) toggle(e.path); else openFile(e.path) },
       onContextMenu: (ev) => {
@@ -338,7 +419,7 @@ export function FileExplorer(props) {
       React.createElement('span', { className: 'edrv-side-root', title: root || '' }, rootName),
       React.createElement('span', { style: { flex: 1 } }),
       React.createElement('button', { className: 'edrv-side-btn', title: '刷新目录树', onClick: refresh }, refreshIconEl())),
-    React.createElement('div', { className: 'edrv-tree' },
+    React.createElement('div', { className: 'edrv-tree', ref: treeRef },
       (errorText
         ? React.createElement('div', { className: 'edrv-tree-error' },
             React.createElement('span', null, String(errorText)),

package/src/client/state/scopeStore.ts

@@ -45,7 +45,8 @@ export function workspaceScopeOf(cwd: string | undefined | null, sessionId: stri
 
 /** 参与迁移的 localStorage 键前缀（编辑区全部按会话持久化的旧键）。 */
 const MIGRATE_PREFIXES: readonly string[] = [
-  CACHE_KEY.editor,
+  // 页签键已升 v3；v2 键仍按会话持久化过，故迁移对象用 legacy 前缀（v3 无旧会话数据）
+  CACHE_KEY.editorLegacy,
   CACHE_KEY.viewstate,
   CACHE_KEY.sidebar + 'side.',
   CACHE_KEY.sidebar,

package/src/client/styles/editor.css

@@ -12,6 +12,9 @@
 [data-edrv-view] .edrv-tab .edrv-tab-star { color: var(--dsw-alias-brand-primary, #4f8cff); font-size: 13px; font-weight: 700; line-height: 1; flex-shrink: 0; } /* 未保存修改星号 @author ddj 2026年09月09号 */
 [data-edrv-view] .edrv-tab .edrv-tab-x { display: inline-flex; align-items: center; justify-content: center; width: 16px; height: 16px; border-radius: 4px; color: var(--dsw-alias-label-tertiary, #888); font-size: 11px; }
 [data-edrv-view] .edrv-tab .edrv-tab-x:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,.12)); color: var(--dsw-alias-label-primary, #eee); }
+/* 固定页签：📌 标记 + 免关闭按钮（固定页签不渲染 ×，仅可经右键菜单取消固定） */
+[data-edrv-view] .edrv-tab .edrv-tab-pin { flex-shrink: 0; font-size: 10px; line-height: 1; opacity: .85; }
+[data-edrv-view] .edrv-tab.edrv-tab-pinned { background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,.04)); }
 [data-edrv-view] .edrv-tab-add { display: inline-flex; align-items: center; justify-content: center; width: 24px; height: 24px; margin-left: 2px; border: none; border-radius: 6px; background: transparent; color: var(--dsw-alias-label-secondary, #aaa); font-size: 14px; cursor: pointer; flex-shrink: 0; }
 [data-edrv-view] .edrv-tab-add:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,.06)); }
 [data-edrv-view] .edrv-pathbar { display: flex; align-items: center; gap: 8px; height: 26px; padding: 0 10px; background: var(--dsw-alias-bg-layer-1, #ffffff); border-bottom: 1px solid var(--dsw-alias-border-l1, #e0e6e8); font-size: 12px; flex-shrink: 0; overflow: hidden; }
@@ -94,14 +97,21 @@
 [data-edrv-view] .edrv-diffmenu-item:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.08)); }
 [data-edrv-view] .edrv-diffmenu-item.danger { color: var(--dsw-alias-state-error-primary, #d9534f); }
 [data-edrv-view] .edrv-diffmenu-sep { height: 1px; margin: 2px 4px; background: var(--dsw-alias-border-l1, #e0e6e8); }
-/* 编辑区 / Tab 右键菜单（添加文件/选中内容到对话） */
-[data-edrv-view] .edrv-ctxmenu { position: fixed; z-index: 71; min-width: 200px; max-width: 320px; border-radius: 10px; background: var(--dsw-alias-bg-overlay, #ffffff); border: 1px solid var(--dsw-alias-border-l2, #cbd2d9); box-shadow: 0 8px 26px rgba(31,41,51,.2); padding: 4px; display: flex; flex-direction: column; gap: 1px; }
+/* 编辑区 / Tab 右键菜单（页签右键菜单 + 文件树右键菜单共用）。
+   页签菜单 11 条 + 键位提示，故限高可滚（ContextMenu 以实测尺寸做 viewport clamp）。
+   ⚠️ z-index 71 在既有浮层阶梯内（见文件末尾命令栏注释），不得上调越过命令栏/片段浮窗。 */
+[data-edrv-view] .edrv-ctxmenu { position: fixed; z-index: 71; min-width: 220px; max-width: 360px; max-height: min(70vh, 520px); overflow-y: auto; border-radius: 10px; background: var(--dsw-alias-bg-overlay, #ffffff); border: 1px solid var(--dsw-alias-border-l2, #cbd2d9); box-shadow: 0 8px 26px rgba(31,41,51,.2); padding: 4px; display: flex; flex-direction: column; gap: 1px; }
 [data-edrv-view] .edrv-ctxmenu-item { display: flex; align-items: center; gap: 8px; font-size: 12px; line-height: 18px; padding: 7px 10px; border: none; border-radius: 6px; background: transparent; color: var(--dsw-alias-label-primary, #1f2933); cursor: pointer; text-align: left; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 [data-edrv-view] .edrv-ctxmenu-item:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.08)); }
 [data-edrv-view] .edrv-ctxmenu-item.edrv-ctxmenu-danger { color: var(--dsw-alias-state-error-primary, #d9534f); }
 [data-edrv-view] .edrv-ctxmenu-item:disabled,
 [data-edrv-view] .edrv-ctxmenu-item.edrv-ctxmenu-disabled { color: var(--dsw-alias-label-disabled, #b0b7c0); cursor: default; background: transparent; }
 [data-edrv-view] .edrv-ctxmenu-sep { height: 1px; margin: 3px 4px; background: var(--dsw-alias-border-l1, #e0e6e8); }
+/* 菜单项文案（弹性占宽，超出省略）与右侧键位提示（不缩放，等宽字体） */
+[data-edrv-view] .edrv-ctxmenu-label { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
+[data-edrv-view] .edrv-ctxmenu-hint { flex: 0 0 auto; padding-left: 18px; color: var(--dsw-alias-label-tertiary, #9aa5b1); font-family: var(--ds-font-family-code, ui-monospace, monospace); font-size: 11px; }
+[data-edrv-view] .edrv-ctxmenu-item:disabled .edrv-ctxmenu-hint,
+[data-edrv-view] .edrv-ctxmenu-item.edrv-ctxmenu-disabled .edrv-ctxmenu-hint { color: var(--dsw-alias-label-disabled, #b0b7c0); }
 [data-edrv-view] .edrv-diffbar-body { max-height: 130px; max-width: min(560px, calc(100vw - 40px)); overflow: auto; padding: 4px 8px 8px; display: flex; flex-direction: column; gap: 4px; border-top: 1px solid var(--dsw-alias-border-l1, #e0e6e8); }
 [data-edrv-view] .edrv-diffrow { display: flex; align-items: center; gap: 8px; padding: 3px 6px; border: 1px solid var(--dsw-alias-border-l1, #e0e6e8); border-radius: 6px; background: var(--dsw-alias-bg-layer-2, #f0f4f4); cursor: pointer; flex-wrap: wrap; }
 [data-edrv-view] .edrv-diffrow:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.08)); }
@@ -247,6 +257,9 @@
 [data-edrv-view] .edrv-tree-row:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.08)); }
 [data-edrv-view] .edrv-tree-row.edrv-tree-active { background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.14)); }
 [data-edrv-view] .edrv-tree-row.edrv-tree-context { box-shadow: inset 0 0 0 1px var(--dsw-alias-brand-primary, #0f9d58); background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.12)); }
+/* 「在资源管理器视图中显示」的定位高亮（短时淡出，区别于常驻的 active 态） */
+[data-edrv-view] .edrv-tree-row.edrv-tree-reveal { box-shadow: inset 0 0 0 1px var(--dsw-alias-brand-primary, #0f9d58); background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.18)); animation: edrv-tree-reveal-fade 2s ease-out; }
+@keyframes edrv-tree-reveal-fade { from { background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.32)); } to { background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.18)); } }
 [data-edrv-view] .edrv-tree-chev { width: 12px; flex-shrink: 0; color: var(--dsw-alias-label-tertiary, #9aa5b1); font-size: 10px; text-align: center; }
 [data-edrv-view] .edrv-tree-name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
 [data-edrv-view] .edrv-tree-name.edrv-tree-dim { color: var(--dsw-alias-label-tertiary, #9aa5b1); }