dsh-vscode-mode 0.3.1 → 0.3.3

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; }
@@ -26,6 +29,8 @@
 [data-edrv-view] .edrv-search-pop { position: absolute; top: calc(100% + 4px); right: 8px; width: min(460px, calc(100vw - 24px)); max-height: 300px; overflow: auto; background: var(--dsw-alias-bg-overlay, #1c1c1c); border: 1px solid var(--dsw-alias-border-l2, #555); border-radius: 10px; box-shadow: 0 6px 20px rgba(0,0,0,.4); z-index: 60; padding: 4px; }
 [data-edrv-view] .edrv-search-item { display: flex; flex-direction: column; gap: 1px; padding: 5px 8px; border-radius: 6px; cursor: pointer; }
 [data-edrv-view] .edrv-search-item:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,.07)); }
+/* 键盘高亮项（↑↓ 选择）：与 hover 同特异性但声明在后，故选中态稳定可辨 @author ddj 2026年09月11号 */
+[data-edrv-view] .edrv-search-item.edrv-search-sel { background: var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,.14)); }
 [data-edrv-view] .edrv-search-item .n { color: var(--dsw-alias-label-primary, #eee); font-size: 12px; word-break: break-all; }
 [data-edrv-view] .edrv-search-item .d { color: var(--dsw-alias-label-tertiary, #888); font-size: 11px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 [data-edrv-view] .edrv-search-empty { padding: 8px; font-size: 12px; color: var(--dsw-alias-label-tertiary, #888); }
@@ -94,14 +99,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 +259,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); }

package/src/client/tabActions.ts

@@ -0,0 +1,326 @@
+/**
+ * dsh-vscode-mode client — 文件页签操作纯函数（关闭族 / 固定 / 路径推导）。
+ * 页签状态是 EditorView 的 `{ path, pinned }[]`；本模块不触 React/DOM，可 node 单测，
+ * 菜单动作（tabMenu）与编辑器（EditorView）共用同一份语义，避免规则散落两处。
+ *
+ * 核心约定 —— **固定 = 保护**：
+ * 「关闭其他 / 关闭右侧 / 关闭已保存 / 全部关闭」一律不关固定页签；
+ * 只有单项「关闭」可以显式关掉一个固定页签（用户明确点了它）。
+ *
+ * 关闭后的活动页签：原活动页签未被关 → 不变；被关 → 右侧优先、否则左侧末位（VS Code 行为）。
+ * 作者 ddj 2026年09月11号
+ */
+
+/** 页签的最小形状（EditorView 持有超集）。 */
+export interface TabLike {
+  path: string
+  pinned?: boolean
+}
+
+/** 关闭操作结果（tabs 未变化时返回原引用，React 可跳过重渲染）。 */
+export interface CloseResult {
+  tabs: TabLike[]
+  active: string | null
+}
+
+// --region 关闭族
+
+/**
+ * 关闭指定集合：活动页签被关时按「右侧优先、否则左侧末位」补位。
+ * @author ddj 2026年09月11号
+ * @param tabs 当前页签
+ * @param closing 待关闭路径集合
+ * @param active 当前活动页签路径
+ * @returns 剩余页签与新的活动页签
+ */
+export function applyClose(tabs: TabLike[], closing: Set<string>, active: string | null): CloseResult {
+  const remaining = tabs.filter((tab) => !closing.has(tab.path))
+  if (remaining.length === tabs.length) return { tabs, active }
+  if (active && !closing.has(active)) return { tabs: remaining, active }
+  return { tabs: remaining, active: pickNeighbor(tabs, remaining, active) }
+}
+
+/**
+ * 关闭其他：保留目标页签与全部固定页签。
+ * @author ddj 2026年09月11号
+ * @param tabs 当前页签
+ * @param target 保留的目标页签路径
+ * @param active 当前活动页签路径
+ * @returns 关闭结果
+ */
+export function closeOthers(tabs: TabLike[], target: string, active: string | null): CloseResult {
+  return applyClose(tabs, closingExcept(tabs, (tab) => tab.path === target || tab.pinned === true), active)
+}
+
+/**
+ * 关闭右侧：关闭目标之后、未被固定的页签。
+ * @author ddj 2026年09月11号
+ * @param tabs 当前页签
+ * @param target 基准页签路径（其右侧才关）
+ * @param active 当前活动页签路径
+ * @returns 关闭结果
+ */
+export function closeRight(tabs: TabLike[], target: string, active: string | null): CloseResult {
+  const at = tabs.findIndex((tab) => tab.path === target)
+  const closing = new Set<string>()
+  for (let i = at + 1; i > 0 && i < tabs.length; i += 1) {
+    if (tabs[i].pinned !== true) closing.add(tabs[i].path)
+  }
+  return applyClose(tabs, closing, active)
+}
+
+/**
+ * 关闭已保存：关闭未固定且无未保存修改的页签。
+ * @author ddj 2026年09月11号
+ * @param tabs 当前页签
+ * @param dirty 路径 → 是否有未保存修改
+ * @param active 当前活动页签路径
+ * @returns 关闭结果
+ */
+export function closeSaved(tabs: TabLike[], dirty: Record<string, boolean>, active: string | null): CloseResult {
+  return applyClose(tabs, closingExcept(tabs, (tab) => tab.pinned === true || dirty[tab.path] === true), active)
+}
+
+/**
+ * 全部关闭：仅关未固定页签（全部固定时无操作）。
+ * @author ddj 2026年09月11号
+ * @param tabs 当前页签
+ * @param active 当前活动页签路径
+ * @returns 关闭结果
+ */
+export function closeAll(tabs: TabLike[], active: string | null): CloseResult {
+  return applyClose(tabs, closingExcept(tabs, (tab) => tab.pinned === true), active)
+}
+
+/**
+ * 反选可关闭集合（保留 keep 命中的页签，其余进关闭集）。
+ * @author ddj 2026年09月11号
+ * @param tabs 当前页签
+ * @param keep 保留判定
+ * @returns 待关闭路径集合
+ */
+function closingExcept(tabs: TabLike[], keep: (tab: TabLike) => boolean): Set<string> {
+  const closing = new Set<string>()
+  for (const tab of tabs) if (!keep(tab)) closing.add(tab.path)
+  return closing
+}
+
+/**
+ * 选补位页签：先向右找最近的存活页签，再向左找，都没有则取剩余首个。
+ * @author ddj 2026年09月11号
+ * @param tabs 关闭前的页签（用于取原索引）
+ * @param remaining 关闭后剩余的页签
+ * @param active 被关掉的活动页签路径
+ * @returns 补位页签路径；无剩余返回 null
+ */
+function pickNeighbor(tabs: TabLike[], remaining: TabLike[], active: string | null): string | null {
+  const first = remaining[0]
+  if (!first) return null
+  const at = tabs.findIndex((tab) => tab.path === active)
+  if (at < 0) return first.path
+  const alive = new Set(remaining.map((tab) => tab.path))
+  for (let i = at + 1; i < tabs.length; i += 1) if (alive.has(tabs[i].path)) return tabs[i].path
+  for (let i = at - 1; i >= 0; i -= 1) if (alive.has(tabs[i].path)) return tabs[i].path
+  return first.path
+}
+// --endregion
+
+// --region 固定与插入
+
+/**
+ * 切换页签固定态：固定页签整体前移（两侧各自保持相对顺序）。
+ * @author ddj 2026年09月11号
+ * @param tabs 当前页签
+ * @param target 目标页签路径
+ * @returns 重排后的页签（目标不存在时原样返回）
+ */
+export function togglePin(tabs: TabLike[], target: string): TabLike[] {
+  if (!tabs.some((tab) => tab.path === target)) return tabs
+  const next = tabs.map((tab) => (
+    tab.path === target ? { path: tab.path, pinned: tab.pinned !== true } : tab
+  ))
+  return pinnedFirst(next)
+}
+
+/**
+ * 新增页签：已存在则原样返回；否则插到最后一个固定页签之后。
+ * @author ddj 2026年09月11号
+ * @param tabs 当前页签
+ * @param path 新页签路径
+ * @returns 新页签数组
+ */
+export function insertTab(tabs: TabLike[], path: string): TabLike[] {
+  if (tabs.some((tab) => tab.path === path)) return tabs
+  // 缺省追加到末尾；存在固定页签时插到最后一个固定页签之后
+  let at = tabs.length
+  for (let i = tabs.length - 1; i >= 0; i -= 1) {
+    if (tabs[i].pinned !== true) continue
+    at = i + 1
+    break
+  }
+  return tabs.slice(0, at).concat([{ path }], tabs.slice(at))
+}
+
+/**
+ * 固定分区：固定页签在前，两侧各自保持原相对顺序。
+ * @author ddj 2026年09月11号
+ * @param tabs 页签
+ * @returns 重排后的页签
+ */
+function pinnedFirst(tabs: TabLike[]): TabLike[] {
+  return tabs.filter(isPinned).concat(tabs.filter((tab) => !isPinned(tab)))
+}
+
+/**
+ * 是否固定页签。
+ * @author ddj 2026年09月11号
+ * @param tab 页签
+ * @returns 是否固定
+ */
+function isPinned(tab: TabLike): boolean {
+  return tab.pinned === true
+}
+
+/**
+ * 归一化持久化的页签数据：兼容旧版 `string[]`、去重、固定分区。
+ * 损坏项（非字符串/非对象/无 path）直接丢弃。
+ * @author ddj 2026年09月11号
+ * @param raw localStorage 解析结果（任意形状）
+ * @returns 归一化后的页签数组
+ */
+export function normalizeTabs(raw: unknown): TabLike[] {
+  if (!Array.isArray(raw)) return []
+  const seen = new Set<string>()
+  const out: TabLike[] = []
+  for (const item of raw) {
+    const tab = tabOf(item)
+    if (!tab || seen.has(tab.path)) continue
+    seen.add(tab.path)
+    out.push(tab)
+  }
+  return pinnedFirst(out)
+}
+
+/**
+ * 解释单条持久化页签：字符串 = 路径（旧版），对象取 path/pinned。
+ * @author ddj 2026年09月11号
+ * @param item 原始条目
+ * @returns 页签或 null（无法解释）
+ */
+function tabOf(item: unknown): TabLike | null {
+  if (typeof item === 'string') return item ? { path: item } : null
+  if (!item || typeof item !== 'object') return null
+  const raw = item as { path?: unknown; pinned?: unknown }
+  if (typeof raw.path !== 'string' || !raw.path) return null
+  return raw.pinned === true ? { path: raw.path, pinned: true } : { path: raw.path }
+}
+
+/**
+ * 选活动页签：恢复值仍存在则用它，否则取首个（无页签返回 null）。
+ * @author ddj 2026年09月11号
+ * @param tabs 页签
+ * @param wanted 持久化的活动路径
+ * @returns 活动页签路径
+ */
+export function pickActive(tabs: TabLike[], wanted: unknown): string | null {
+  const first = tabs[0]
+  if (!first) return null
+  if (typeof wanted === 'string' && tabs.some((tab) => tab.path === wanted)) return wanted
+  return first.path
+}
+// --endregion
+
+// --region 路径推导
+
+/** Windows 盘符 / UNC / POSIX 根：视为工作区外的绝对路径。 */
+const ABSOLUTE_RE = /^(?:[a-z]:[\\/]|\\\\|\/)/i
+
+/**
+ * 是否绝对路径（工作区外）。
+ * @author ddj 2026年09月11号
+ * @param path 路径
+ * @returns 是否绝对路径
+ */
+export function isAbsolutePath(path: string): boolean {
+  return ABSOLUTE_RE.test(String(path ?? ''))
+}
+
+/**
+ * 是否可在资源管理器视图中定位（工作区相对且不含 `..` 上跳段）。
+ * @author ddj 2026年09月11号
+ * @param path 路径
+ * @returns 是否可定位
+ */
+export function isTreeRevealable(path: string): boolean {
+  const text = String(path ?? '').trim()
+  if (!text || isAbsolutePath(text)) return false
+  return !text.replace(/\\/g, '/').split('/').includes('..')
+}
+
+/**
+ * 相对路径：cwd 内路径去掉工作区前缀；工作区外/无 cwd 回退规范化原路径。
+ * @author ddj 2026年09月11号
+ * @param path 路径
+ * @param cwd 会话工作区目录（可空）
+ * @returns 展示/复制用的相对路径
+ */
+export function relativeOf(path: string, cwd?: string | null): string {
+  const target = normalizeSlashes(path)
+  const base = normalizeSlashes(cwd).replace(/\/+$/, '')
+  if (base && target.toLowerCase().startsWith((base + '/').toLowerCase())) return target.slice(base.length + 1)
+  return target
+}
+
+/**
+ * 绝对路径：相对路径按 cwd 拼接；已是绝对路径或没有 cwd 时回退规范化原路径。
+ * @author ddj 2026年09月11号
+ * @param path 路径
+ * @param cwd 会话工作区目录（可空）
+ * @returns 展示/复制用的绝对路径
+ */
+export function absoluteOf(path: string, cwd?: string | null): string {
+  const target = normalizeSlashes(path)
+  if (isAbsolutePath(target)) return target
+  const base = normalizeSlashes(cwd).replace(/\/+$/, '')
+  return base ? base + '/' + target : target
+}
+
+/**
+ * 反斜杠归一为斜杠（页签/引用/剪贴板统一用正斜杠，与既有 mentionOf 口径一致）。
+ * @author ddj 2026年09月11号
+ * @param path 路径
+ * @returns 正斜杠路径
+ */
+function normalizeSlashes(path: string | null | undefined): string {
+  return String(path ?? '').replace(/\\/g, '/')
+}
+
+/**
+ * 文件路径的祖先目录（由浅到深）：`a/b/c.ts` → `['a', 'a/b']`。
+ * 根级文件、绝对路径与含 `..` 的路径返回空数组。
+ * @author ddj 2026年09月11号
+ * @param path 工作区相对路径
+ * @returns 祖先目录相对路径数组
+ */
+export function ancestorDirsOf(path: string): string[] {
+  if (!isTreeRevealable(path)) return []
+  const segs = normalizeSlashes(path).split('/').filter(Boolean)
+  const out: string[] = []
+  for (let i = 1; i < segs.length; i += 1) {
+    const prev = segs[i - 1]
+    out.push(out.length ? out[out.length - 1] + '/' + prev : prev)
+  }
+  return out
+}
+
+/**
+ * 文件名（页签/状态栏展示与 tooltip 用）。
+ * @author ddj 2026年09月11号
+ * @param path 路径
+ * @returns 末段文件名；空路径返回空串
+ */
+export function baseNameOf(path: string): string {
+  const text = normalizeSlashes(path)
+  return text.split('/').filter(Boolean).pop() ?? ''
+}
+// --endregion

package/src/client/tabMenu.ts

@@ -0,0 +1,107 @@
+/**
+ * dsh-vscode-mode client — 文件页签右键菜单模型（纯函数，可单测）。
+ * 菜单是「数据」而非 JSX：条目顺序、分组分隔线、禁用规则与键位提示全部在此收敛，
+ * EditorView 只把结果映射成 ContextMenu 的 entries 并派发动作。
+ *
+ * 与参考图（VS Code / CodeBuddy 页签右键菜单）的对齐口径：
+ * 保留其分组顺序（对话 / 关闭族 / 路径 / 定位 / 固定），**省略**本架构无法实现的
+ * 「向右拆分 / Split & Move / 移动到新窗口 / 复制到新窗口」（浏览器内单编辑器实例）。
+ * 只显示**真实已绑定**的键位；参考图里的两步弦（Ctrl+K W 等）引擎不支持，故不伪造。
+ *
+ * 「固定 = 保护」：关闭其他 / 关闭右侧 / 关闭已保存 / 全部关闭 一律不关固定页签，
+ * 故这些条目在「固定页签是唯一可关对象」时判定为禁用（与 tabActions 语义同源）。
+ * 作者 ddj 2026年09月11号
+ */
+import { closeAll, closeOthers, closeRight, closeSaved, isTreeRevealable, type TabLike } from './tabActions.js'
+
+/** 菜单构建输入（EditorView 每次打开菜单时按最新状态快照传入）。 */
+export interface TabMenuState {
+  /** 右键目标页签路径。 */
+  path: string
+  /** 当前全部页签。 */
+  tabs: TabLike[]
+  /** 当前活动页签路径。 */
+  active: string | null
+  /** 路径 → 是否有未保存修改。 */
+  dirty: Record<string, boolean>
+  /** 会话工作区目录（相对路径复制与「资源管理器视图中显示」用）。 */
+  cwd?: string | null
+  /** 是否有活动会话（复制/定位类动作依赖）。 */
+  hasSession: boolean
+  /** 「添加到对话」动作集是否可用。 */
+  canAddToConversation: boolean
+  /** 「关闭」项的键位提示（缺省无提示；由调用方读 chordOf 注入）。 */
+  closeChord?: string | null
+}
+
+/** 一条页签菜单项（ContextMenu 的展示形状 + 动作 id）。 */
+export interface TabMenuEntry {
+  id: string
+  label: string
+  /** 右侧键位提示（仅在真实绑定键位时出现）。 */
+  hint?: string
+  disabled?: boolean
+  danger?: boolean
+  /** 前置分隔线（分组的首条）。 */
+  separator?: boolean
+}
+
+/** 关闭族 id（EditorView 的动作表按 id 分派；导出便于测试与静态校验）。 */
+export const CLOSE_MENU_IDS = ['close', 'close-others', 'close-right', 'close-saved', 'close-all'] as const
+
+/** 本架构不支持的条目 id（参考图有、浏览器单编辑器实例无法实现）——显式登记以防误加。 */
+export const UNSUPPORTED_MENU_IDS = ['split-right', 'split-move', 'move-new-window', 'copy-new-window'] as const
+
+/**
+ * 构建页签右键菜单条目。
+ * @author ddj 2026年09月11号
+ * @param state 菜单状态快照
+ * @returns 菜单条目（已按参考图分组排序）
+ */
+export function buildTabMenu(state: TabMenuState): TabMenuEntry[] {
+  const { path, tabs, active, dirty, cwd, hasSession, canAddToConversation, closeChord } = state
+  const current = tabs.find((tab) => tab.path === path)
+  const pinned = current?.pinned === true
+  return [
+    {
+      id: 'add-to-conversation',
+      label: '添加到对话',
+      disabled: !(hasSession && canAddToConversation),
+    },
+    { id: 'close', label: '关闭', separator: true, ...(closeChord ? { hint: closeChord } : {}) },
+    { id: 'close-others', label: '关闭其他', disabled: nothingToClose(closeOthers(tabs, path, active), tabs) },
+    { id: 'close-right', label: '关闭右侧标签页', disabled: nothingToClose(closeRight(tabs, path, active), tabs) },
+    { id: 'close-saved', label: '关闭已保存', disabled: nothingToClose(closeSaved(tabs, dirty, active), tabs) },
+    { id: 'close-all', label: '全部关闭', disabled: nothingToClose(closeAll(tabs, active), tabs) },
+    { id: 'copy-path', label: '复制路径', separator: true },
+    { id: 'copy-relative-path', label: '复制相对路径', disabled: !hasCwd(cwd) },
+    { id: 'reveal-in-os', label: '在文件资源管理器中显示', separator: true, disabled: !hasSession },
+    { id: 'reveal-in-view', label: '在资源管理器视图中显示', disabled: !isTreeRevealable(path) },
+    {
+      id: 'toggle-pinned',
+      label: pinned ? '取消固定' : '固定',
+      separator: true,
+    },
+  ]
+}
+
+/**
+ * 关闭族是否无可关对象（结果页签数与关闭前一致 = 一个也没关掉）。
+ * @author ddj 2026年09月11号
+ * @param result 关闭结果
+ * @param tabs 关闭前的页签
+ * @returns 是否无可关对象
+ */
+function nothingToClose(result: { tabs: TabLike[] }, tabs: TabLike[]): boolean {
+  return result.tabs.length >= tabs.length
+}
+
+/**
+ * 是否有可用工作区目录（复制相对路径需要）。
+ * @author ddj 2026年09月11号
+ * @param cwd 会话工作区目录
+ * @returns 是否可用
+ */
+function hasCwd(cwd: string | null | undefined): boolean {
+  return typeof cwd === 'string' && cwd.trim() !== ''
+}