dsh-vscode-mode 0.4.3 → 0.4.4

package/src/fileVersions.ts

@@ -0,0 +1,167 @@
+/**
+ * dsh-vscode-mode host — 文件磁盘新鲜度观察（外部改动检测的 host 半）。
+ *
+ * 用途：客户端（编辑区）在无法感知外部写盘的前提下会把陈旧缓冲当权威内容，
+ * 甚至在防抖自动保存时覆盖外部改动。本模块为客户端提供轻量批查：给一批路径
+ * 返回当前磁盘版本令牌（ctx.fs.stat 的 version）+ 类型，客户端与本地基线比对后
+ * 决定是否重载/提示/拒绝保存。
+ *
+ * 附带职责（文件树同步）：对每次都变化的路径调用 treeIndex.invalidateIndex，
+ * 使「外部新增/删除文件」不再只依赖 60s TTL——已展开目录在下次展开时即为最新。
+ *
+ * 设计取舍：
+ * - 不注册 fs.watch：句柄占用、网络盘/长路径兼容性差且难单测；批 stat 由系统
+ *   缓存兜底，1–20 条/轮的代价可忽略，因此观察逻辑全部落在本模块且可确定性测试。
+ * - 基准版本表（path → version）只用于「是否变化」判定，不参与客户端语义；
+ *   每条记忆带 TTL（MEM_TTL_MS），超过即视为陈旧重新记基准；总量有上限兜底。
+ * - 单条失败不影响整批：解析失败/不存在以 type='missing' 返回，响应始终 ok。
+ *
+ * 作者 ddj 2026-09-15
+ */
+import type { FileVersionItem } from './shared/rpc.js'
+import type { Ctx } from './store.js'
+import { cwdOf, sessionOf } from './registry.js'
+import { invalidateIndex } from './treeIndex.js'
+import { log } from './log.js'
+
+// --region 常量
+
+/** 基准版本记忆上限：超出按写入序逐出最旧（防长时间运行无界增长）。 */
+export const MEM_MAX = 500
+/** 基准版本记忆新鲜期：超过即视为陈旧（重记基准，不报一次假变化）。 */
+export const MEM_TTL_MS = 5 * 60_000
+/** 批量路径上限：超出只处理前 N 条（客户端只发已打开页签，正常远小于此值）。 */
+export const MAX_PATHS = 200
+
+// --endregion
+
+// --region 类型
+
+/** 版本观察器实例。 */
+export interface FileVersions {
+  /**
+   * 批查路径的磁盘版本。
+   * @param args 会话 id 与路径列表
+   */
+  versions(args: { sessionId?: string; paths: string[] }): Promise<{ ok: true; items: FileVersionItem[] }>
+  /** 卸载收尾：清空基准表（会话销毁/插件卸载调用）。 */
+  dispose(): void
+}
+
+/** 一条基准记忆（版本 + 记录时间）。 */
+interface Memo {
+  version: string
+  at: number
+}
+
+// --endregion
+
+// --region 基准表
+
+/** 基准表键：工作区根 + 归一化路径。 */
+function memoKey(cwd: string, path: string): string {
+  return String(cwd).replace(/\\/g, '/') + '\u0000' + String(path).replace(/\\/g, '/')
+}
+
+/** 清理超期/超量记忆（每次写入前调用，摊还 O(1)）。 */
+function sweep(memos: Map<string, Memo>, now: number): void {
+  if (memos.size === 0) return
+  for (const [key, memo] of memos) {
+    if (now - memo.at > MEM_TTL_MS) memos.delete(key)
+  }
+  while (memos.size > MEM_MAX) {
+    const oldest = memos.keys().next().value
+    if (oldest === undefined) break
+    memos.delete(oldest)
+  }
+}
+
+// --endregion
+
+// --region 观察器
+
+/**
+ * 创建文件版本观察器（host 单例，随插件装配创建、卸载 dispose）。
+ * @author ddj 2026年09月15号
+ * @param ctx DSH host 上下文
+ * @returns 观察器实例
+ */
+export function createFileVersions(ctx: Ctx): FileVersions {
+  /** 基准表：memoKey → 上次观察到的版本（仅用于变化判定与树失效）。 */
+  const memos = new Map<string, Memo>()
+
+  /**
+   * 记录一次观察并按需失效目录树；返回本次是否为「变化」。
+   * @author ddj 2026年09月15号
+   * @param cwd 工作区根
+   * @param path 请求路径
+   * @param version 当前版本令牌（空串 = 后端不提供）
+   * @param present 磁盘上是否存在
+   * @returns 是否检测到变化
+   */
+  const syncTree = (cwd: string, path: string, version: string, present: boolean): boolean => {
+    const now = Date.now()
+    const key = memoKey(cwd, path)
+    const prev = memos.get(key)
+    sweep(memos, now)
+    const changed = prev !== undefined && (prev.version !== version || !present)
+    memos.set(key, { version, at: now })
+    // 每个路径只在「检测到变化」时落一行（正常编辑频率，不会刷屏）：外部改动没跟上时先看这条日志
+    if (changed) log.debug('检测到磁盘变化（已失效目录树）：' + path)
+    if (changed) invalidateIndex(ctx, cwd, path)
+    return changed
+  }
+
+  /**
+   * 单条路径观察：解析 → stat → 组装条目（异常一律降级为 missing，不整批失败）。
+   * @author ddj 2026年09月15号
+   * @param fs host fs 服务
+   * @param cwd 工作区根（为空表示会话无工作区，跳过变化判定）
+   * @param path 请求路径
+   * @returns 版本条目
+   */
+  const observe = async (fs: Ctx, cwd: string | null, path: string): Promise<FileVersionItem> => {
+    try {
+      const target = await fs.resolve(path, cwd ? { cwd } : {})
+      const info = await fs.stat(target)
+      if (!info || info.type === 'other') {
+        if (cwd) syncTree(cwd, path, '', false)
+        return { path, version: '', type: 'missing' }
+      }
+      const version = info.version ? String(info.version) : ''
+      if (cwd) syncTree(cwd, path, version, true)
+      return { path, version, size: typeof info.size === 'number' ? info.size : undefined, type: info.type }
+    } catch (error) {
+      if (cwd) syncTree(cwd, path, '', false)
+      return { path, version: '', type: 'missing', error: String(error) }
+    }
+  }
+
+  /**
+   * 批查入口（RPC handler 直接委托）：同一会话的路径共享一次会话解析。
+   * @author ddj 2026年09月15号
+   * @param args 会话 id 与路径列表
+   * @returns 始终 ok 的逐条结果
+   */
+  const versions = async (args: { sessionId?: string; paths: string[] }): Promise<{ ok: true; items: FileVersionItem[] }> => {
+    const fs = ctx.get('fs')
+    const paths = (Array.isArray(args.paths) ? args.paths : [])
+      .filter((p): p is string => typeof p === 'string' && p.length > 0)
+      .slice(0, MAX_PATHS)
+    if (!fs || !paths.length) return { ok: true, items: [] }
+    const session = sessionOf(ctx, args.sessionId)
+    const cwd = cwdOf(session)
+    const items: FileVersionItem[] = []
+    for (const path of paths) items.push(await observe(fs, cwd, path))
+    return { ok: true, items }
+  }
+
+  return {
+    versions,
+    dispose() {
+      memos.clear()
+    },
+  }
+}
+
+// --endregion

package/src/index.ts

@@ -25,6 +25,7 @@ import { createLspManager } from './lsp/manager.js'
 import { createLspRpc } from './lsp/rpc.js'
 import { disposeAllServers, hookExitReclaim } from './lsp/transport.js'
 import { createAiRpc } from './ai/rpc.js'
+import { createFileVersions } from './fileVersions.js'
 import { installRulesSection } from './rules.js'
 import { installSkillGroup } from './skills.js'
 import type { RpcHandlerMap } from './shared/rpc.js'
@@ -65,6 +66,8 @@ export function apply(ctx: Ctx, config?: unknown): void {
   /** AI 内联补全 RPC（settings 状态桥接 + llm 惰性获取）。 */
   const aiRpc = createAiRpc({ ctx, settings: openSettings })
   const aiHandlers: Partial<RpcHandlerMap> = aiRpc.handlers
+  /** 文件磁盘新鲜度观察器（客户端轮询 edrv.versions；变化时顺带失效目录树缓存）。 */
+  const fileVersions = createFileVersions(ctx)
 
   ctx.on('tools/result', (exec: unknown, result: unknown) => {
     void captureToolResult(ctx, registry, exec, result)
@@ -83,7 +86,7 @@ export function apply(ctx: Ctx, config?: unknown): void {
     if (typeof sid === 'string') lspRpc.disposeSession(sid)
   })
 
-  registerRoutes(ctx, config, (method, args) => handleRpc(ctx, registry, method, args, searcher, contentSearcher, lspHandlers, aiHandlers), (warning) => warnings.push(warning))
+  registerRoutes(ctx, config, (method, args) => handleRpc(ctx, registry, method, args, searcher, contentSearcher, lspHandlers, aiHandlers, fileVersions), (warning) => warnings.push(warning))
   installIsolation(ctx)
   // 系统集成生命周期：启动自动恢复右键菜单注册（marker 存在时）；插件卸载/reload 清理注册痕迹
   ctx.effect(() => shellMenuLifecycle(ctx))
@@ -95,6 +98,8 @@ export function apply(ctx: Ctx, config?: unknown): void {
     void lspManager.disposeAll().catch(() => {})
     disposeAllServers()
   })
+  // 卸载时清空文件版本基准表（观察器为模块内单例，不清会跨装配残留陈旧版本）
+  ctx.effect(() => () => fileVersions.dispose())
   // 宿主进程退出回收：ctx.effect 清理不覆盖进程退出，缺此注册会留下跨重启的孤儿服务器
   hookExitReclaim()
 

package/src/rpc.ts

@@ -20,7 +20,7 @@ import {
   resolveTarget,
   saveBucket,
 } from './store.js'
-import { mkdir, readFile, rm, writeFile, readdir } from 'node:fs/promises'
+import { mkdir, readFile, rm, stat, writeFile, readdir } from 'node:fs/promises'
 import { basename, join } from 'node:path'
 import { archiveEntryFor, markDecision, recordResolved, reconstructOriginal } from './model.js'
 import type { Registry } from './registry.js'
@@ -48,6 +48,7 @@ import { dshHome } from './paths.js'
 import { debugRecord } from './debugLog.js'
 import { markActiveSessions, moveOutSessions, planMoveOut, purgeArchive, restoreSession, scanSessionInventory, sessionsArchiveRoot, sessionSizeOf, sidecarSummaryOf } from './perf.js'
 import { patchHasPerfConfig, patchInsertPerfConfig, patchRemovePerfConfig, perfConfigBlock } from './perfPatch.js'
+import type { FileVersions } from './fileVersions.js'
 
 /** cwd → 上次 stale 自动清理时间：全量轮询（EditorView/DiffBadge/Dock 各自 5s）节流，避免每轮都读文件算指纹。 */
 const staleCheckedAt = new Map<string, number>()
@@ -105,6 +106,32 @@ function snippetTargetOf(path: string): string | null {
   return isSnippetFilePath(path) ? path.replace(/\\/g, '/') : null
 }
 
+/**
+ * 本地文件系统版本令牌（mtime+size）：与 ctx.fs 的不透明版本串用途相同，
+ * 仅供全局片段文件（走 node:fs 直读、不经 ctx.fs）在 edrv.read 时回带。
+ * @author ddj 2026年09月15号
+ * @param info node fs.Stats（stat 失败传 null）
+ * @returns 版本令牌；取不到 → 空串（不启用护栏）
+ */
+function fileVersionOf(info: { mtimeMs?: number; size?: number } | null): string {
+  if (!info || typeof info.mtimeMs !== 'number' || typeof info.size !== 'number') return ''
+  return info.mtimeMs + ':' + info.size
+}
+
+/**
+ * 判定错误是否为「读取后文件已被外部修改」（版本守卫拒绝写入）。
+ * 不依赖 host fs 的 FsError 类（外置模块，instanceof 不可靠），按错误码与文案双重判定。
+ * @author ddj 2026年09月15号
+ * @param error 捕获到的异常
+ * @returns 是否为版本冲突
+ */
+function isStaleVersion(error: unknown): boolean {
+  const err = error as { code?: unknown; message?: unknown } | null
+  if (err && err.code === 'FS_STALE_VERSION') return true
+  const message = err && typeof err.message === 'string' ? err.message : String(error)
+  return message.includes('changed since it was read')
+}
+
 /**
  * 手动保存收尾（edrv.save / edrv.saveBinary 共用）：目录树失效 + 该路径 pending
  * 文本差异记录标记 superseded 并归档（旧文本 diff 不得再应用到新内容上）。
@@ -227,6 +254,7 @@ export function buildHandlers(
   contentSearcher = newContentSearcher(ctx),
   lspHandlers?: Partial<RpcHandlerMap>,
   aiHandlers?: Partial<RpcHandlerMap>,
+  fileVersions?: FileVersions,
 ): RpcHandlerMap {
   return {
     // edrv.lsp.* 由 createLspRpc 一次性提供（tracker 跨请求保留），这里并入。
@@ -289,7 +317,9 @@ export function buildHandlers(
       if (snippetTarget && args.encoding !== 'base64') {
         try {
           const content = await readFile(snippetTarget, 'utf8')
-          return { ok: true, content, size: content.length }
+          // 版本令牌随读带回：客户端据此判断「读后是否被外部改过」（片段文件同理）
+          const info = await stat(snippetTarget).catch(() => null)
+          return { ok: true, content, size: content.length, version: fileVersionOf(info) }
         } catch (error) {
           return { ok: false, error: '读取片段文件失败：' + String(error), resolvedPath: snippetTarget }
         }
@@ -310,15 +340,20 @@ export function buildHandlers(
           // 图片/PDF 等二进制预览：readBytes 无解码、无二进制拒绝；超上限已由上方 stat 拦截
           const bytes = await fs.readBytes(target, undefined, BINARY_READ_CAP)
           const content = Buffer.from(bytes).toString('base64')
-          return { ok: true, content, size: bytes.byteLength, encoding: 'base64', mime: binaryMimeOf(args.path) }
+          return { ok: true, content, size: bytes.byteLength, encoding: 'base64', mime: binaryMimeOf(args.path), version: String(info.version ?? '') }
         }
         if ((info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持整文件预览' }
         const content = await fs.readText(target)
-        return { ok: true, content, size: content.length }
+        return { ok: true, content, size: content.length, version: String(info.version ?? '') }
       } catch (error) {
         return { ok: false, error: '读取失败：' + String(error) }
       }
     },
+    'edrv.versions': async (args) => {
+      // 外部改动检测：批量返回已打开文件的磁盘版本（观察器同时失效变化的目录树）
+      if (!fileVersions) return { ok: false, error: '文件版本观察器未装配' }
+      return fileVersions.versions(args)
+    },
     'edrv.original': async (args) => {
       // 重建"本批次修改前"内容：DiffEditor 原始侧。仅反解 pending 块；
       // 全部反解失败时回退到最早记录的整体 before（若存在）。
@@ -361,10 +396,17 @@ export function buildHandlers(
       if (!fs) return { ok: false, error: '缺少 fs' }
       try {
         const target = await resolveTarget(ctx, sc.session, args.path)
-        await fs.writeText(target, args.content, void 0, void 0, policyOf(ctx, sc.session))
+        // 版本守卫（客户端带回上次读取的版本）：文件在读取后被外部改过则拒绝写入，
+        // 避免用陈旧缓冲静默覆盖外部改动；客户端未带 rev（旧版/无版本后端）时行为不变。
+        const rev = typeof args.rev === 'string' && args.rev ? args.rev : null
+        const intent = rev ? { kind: 'replaceIfVersion', version: rev } : undefined
+        const outcome = await fs.writeText(target, args.content, intent, void 0, policyOf(ctx, sc.session))
         await afterManualSave(ctx, registry, sc, args.path)
-        return { ok: true }
+        return { ok: true, rev: outcome?.version ? String(outcome.version) : rev ?? undefined }
       } catch (error) {
+        if (isStaleVersion(error)) {
+          return { ok: false, conflict: true, error: '文件已被外部修改，请先重新加载（或用编辑器内容覆盖）' }
+        }
         return { ok: false, error: '保存失败：' + String(error) }
       }
     },
@@ -871,8 +913,9 @@ export async function handleRpc<M extends RpcMethod>(
   contentSearcher = newContentSearcher(ctx),
   lspHandlers?: Partial<RpcHandlerMap>,
   aiHandlers?: Partial<RpcHandlerMap>,
+  fileVersions?: FileVersions,
 ): Promise<RpcResult<M>> {
-  const handlers = buildHandlers(ctx, registry, searcher, contentSearcher, lspHandlers, aiHandlers)
+  const handlers = buildHandlers(ctx, registry, searcher, contentSearcher, lspHandlers, aiHandlers, fileVersions)
   const handler = handlers[method]
   if (!handler) return { ok: false, error: '未知方法: ' + String(method) } as RpcResult<M>
   return handler(args)

package/src/shared/rpc.ts

@@ -137,6 +137,24 @@ export interface SidecarPerfSummary {
 }
 // --endregion
 
+/**
+ * 单个路径的磁盘新鲜度（edrv.versions 逐条结果）。
+ * version 为 host fs 的不透明新鲜度令牌（本地后端 = dev:ino:size:mtimeNs:ctimeNs）：
+ * 客户端只做字符串相等比较判「是否变化」，不解析其内部结构。
+ */
+export interface FileVersionItem {
+  /** 请求时的原始路径（原样回带，客户端按此对齐基线）。 */
+  path: string
+  /** 当前磁盘版本令牌；空串 = 该后端不提供版本，调用方应停用护栏。 */
+  version: string
+  /** 文件字节数（后端可报时）。 */
+  size?: number
+  /** 目标类型；'missing' = 已不存在（外部删除或路径解析失败）。 */
+  type?: 'file' | 'directory' | 'other' | 'missing'
+  /** 单条失败原因（仅诊断用；解析失败/缺失也可能只体现在 type='missing'）。 */
+  error?: string
+}
+
 /** 一条批量决策项（decideBatch 的 items 元素，与 accept/reject 单条参数同构）。 */
 export interface DecideItem {
   callId: string
@@ -162,8 +180,9 @@ export interface RpcRequestMap {
   'edrv.reject': { sessionId?: string; callId: string; scope?: RpcScope; hunkIndex?: number }
   'edrv.decideBatch': { sessionId?: string; items: DecideItem[] }
   'edrv.read': { sessionId?: string; path: string; encoding?: 'base64' }
+  'edrv.versions': { sessionId?: string; paths: string[] }
   'edrv.original': { sessionId?: string; path: string }
-  'edrv.save': { sessionId?: string; path: string; content: string }
+  'edrv.save': { sessionId?: string; path: string; content: string; rev?: string }
   'edrv.saveBinary': { sessionId?: string; path: string; content: string; encoding: 'base64' }
   'edrv.archiveList': { sessionId?: string }
   'edrv.archiveRead': { sessionId?: string; path?: string }
@@ -254,9 +273,10 @@ export interface RpcOkMap {
   'edrv.accept': { record: RecordView }
   'edrv.reject': { record: RecordView }
   'edrv.decideBatch': { results: DecideResult[] }
-  'edrv.read': { content: string; size: number; encoding?: 'base64'; mime?: string }
+  'edrv.read': { content: string; size: number; encoding?: 'base64'; mime?: string; version?: string }
+  'edrv.versions': { items: FileVersionItem[] }
   'edrv.original': { content: string; size: number; stale: StaleHunk[]; fallback: boolean }
-  'edrv.save': object
+  'edrv.save': { rev?: string; conflict?: boolean }
   'edrv.saveBinary': object
   'edrv.archiveList': { entries: ArchiveEntry[] }
   'edrv.archiveRead': { batches: ArchiveBatch[] }