dsh-vscode-mode 0.18.0 → 0.19.0

package/src/rpc.ts

@@ -56,6 +56,10 @@ import { markActiveSessions, markOfficialFlags, moveOutSessions, planMoveOut, pu
 import { patchHasPerfConfig, patchInsertPerfConfig, patchRemovePerfConfig, perfConfigBlock } from './perfPatch.js'
 import type { FileVersions } from './fileVersions.js'
 import { settingsDocPath } from './settingsDocPath.js'
+import { createTextPages } from './textPages.js'
+
+/** Process-local cursor signer; reads must stay on the Host filesystem capability. */
+const readTextPage = createTextPages()
 
 /** cwd → 上次 stale 自动清理时间：全量轮询（EditorView/DiffBadge/Dock 各自 5s）节流，避免每轮都读文件算指纹。 */
 const staleCheckedAt = new Map<string, number>()
@@ -162,7 +166,7 @@ async function readTargetOf(
   ctx: Ctx,
   sc: { session: Session; cwd: string },
   path: string,
-): Promise<ReadTargetOk | { err: string; resolvedPath?: string }> {
+): Promise<ReadTargetOk | { err: string; resolvedPath?: string; code?: 'file-too-large' }> {
   const fs = ctx.get('fs')
   if (!fs) return { err: '缺少 fs' }
   try {
@@ -173,7 +177,7 @@ async function readTargetOf(
       // 带上解析后的真实路径：跳转失败时可直接看出是路径解析错还是目标本身不存在
       return { err: '文件不存在', resolvedPath: fs.processPath(target) }
     }
-    if ((info.size ?? 0) > BINARY_READ_CAP) return { err: '文件过大（>32MB），不支持整文件预览' }
+    if ((info.size ?? 0) > BINARY_READ_CAP) return { err: '文件过大（>32MB），不支持整文件预览', code: 'file-too-large' }
     return { target, fs, info }
   } catch (error) {
     return { err: '读取失败：' + String(error) }
@@ -186,10 +190,10 @@ async function readTargetOf(
  * @param prep readTargetOf 的失败分支
  * @returns { ok:false } 形态载荷
  */
-function targetErrOf(prep: { err: string; resolvedPath?: string }): { ok: false; error: string; resolvedPath?: string } {
-  return prep.resolvedPath !== undefined
-    ? { ok: false, error: prep.err, resolvedPath: prep.resolvedPath }
-    : { ok: false, error: prep.err }
+function targetErrOf(prep: { err: string; resolvedPath?: string; code?: 'file-too-large' }): { ok: false; error: string; resolvedPath?: string; code?: 'file-too-large' } {
+  return { ok: false, error: prep.err,
+    ...(prep.resolvedPath !== undefined ? { resolvedPath: prep.resolvedPath } : {}),
+    ...(prep.code ? { code: prep.code } : {}) }
 }
 
 /**
@@ -699,6 +703,24 @@ export function buildHandlers(
       const results = await applyDecisions(ctx, sc.session, sc.cwd, bucket, Array.isArray(args.items) ? args.items : [])
       return { ok: true, results }
     },
+    /** @author ddj 2026年10月22号 @param args Read-only request. @returns Bounded official range read, or unsupported on older providers; never bypasses Host IO. */
+    'edrv.textPage': async (args) => {
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err, reason: 'read-failed' }
+      try {
+        const target = await resolveTarget(ctx, sc.session, args.path)
+        const fs = ctx.get('fs')
+        if (typeof fs?.readByteRange !== 'function' || typeof fs.stat !== 'function') return readTextPage(undefined, args)
+        // Keys are opaque identities, never decoded into physical paths. Both legacy string and official FsTarget are supported.
+        const targetKey = typeof target === 'string' ? target : (target as { targetKey?: unknown }).targetKey
+        if (typeof targetKey !== 'string') return readTextPage(undefined, args)
+        /** @author ddj 2026年10月22号 @returns Provider metadata used for before/after freshness checks. */
+        function statPage() { return fs.stat(target) }
+        /** @author ddj 2026年10月22号 @param offset Verified cursor position. @param length Bounded byte count. @returns Bytes through the official provider only. */
+        function readRange(offset: number, length: number) { return fs.readByteRange(target, { offset, length }) }
+        return readTextPage({ identity: JSON.stringify([sc.cwd, targetKey]), stat: statPage, readRange }, args)
+      } catch (error) { return { ok: false, error: '读取失败：' + String(error), reason: 'read-failed' } }
+    },
     'edrv.read': async (args) => {
       const settingsTarget = settingsTargetOf(ctx, args.path)
       if (settingsTarget && args.encoding !== 'base64') {
@@ -735,7 +757,7 @@ export function buildHandlers(
           const content = Buffer.from(bytes).toString('base64')
           return { ok: true, content, size: bytes.byteLength, encoding: 'base64', mime: binaryMimeOf(args.path), version: String(prep.info.version ?? '') }
         }
-        if ((prep.info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持整文件预览' }
+        if ((prep.info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持整文件预览', code: 'file-too-large' }
         const content = await prep.fs.readText(prep.target)
         return { ok: true, content, size: content.length, version: String(prep.info.version ?? '') }
       } catch (error) {

package/src/shared/rpc.ts

@@ -372,6 +372,7 @@ export interface RpcRequestMap {
   'edrv.accept': { sessionId?: string; callId: string; scope?: RpcScope; hunkIndex?: number }
   'edrv.reject': { sessionId?: string; callId: string; scope?: RpcScope; hunkIndex?: number }
   'edrv.decideBatch': { sessionId?: string; items: DecideItem[] }
+  'edrv.textPage': import('./textPages.js').TextPageArgs
   'edrv.read': { sessionId?: string; path: string; encoding?: 'base64' }
   'edrv.readBinary': { sessionId?: string; path: string }
   'edrv.versions': { sessionId?: string; paths: string[] }
@@ -540,6 +541,7 @@ export interface RpcOkMap {
   'edrv.accept': { record: RecordView }
   'edrv.reject': { record: RecordView }
   'edrv.decideBatch': { results: DecideResult[] }
+  'edrv.textPage': Extract<import('./textPages.js').TextPageResult, { ok: true }>
   'edrv.read': { content: string; size: number; encoding?: 'base64'; mime?: string; version?: string }
   'edrv.readBinary': { binary: BinaryReadPayload }
   'edrv.versions': { items: FileVersionItem[] }
@@ -698,7 +700,7 @@ export interface RpcOkMap {
 /** 统一响应：{ok:true, ...payload} 或 {ok:false, error}。 */
 export type RpcResult<M extends RpcMethod> =
   | ({ ok: true } & RpcOkMap[M])
-  | { ok: false; error: string }
+  | { ok: false; error: string; code?: 'file-too-large'; reason?: Extract<import('./textPages.js').TextPageResult, { ok: false }>['reason'] }
 
 /** 每个方法的 handler 签名（host 分发表与 client 类型检查共用）。 */
 export type RpcHandler<M extends RpcMethod> = (

package/src/shared/textPages.ts

@@ -0,0 +1,28 @@
+/** Bounded, read-only text paging protocol. @author ddj 2026年10月22号 */
+export const TEXT_PAGE_BYTES = 256 * 1024
+export const TEXT_VIEW_BYTES = 8 * 1024 * 1024
+export const TEXT_VIEW_LINES = 50_000
+
+export interface TextPageArgs {
+  sessionId?: string
+  path: string
+  cursor?: string
+}
+
+export type TextPageResult = {
+  ok: true
+  text: string
+  version: string
+  /** Absolute byte offset following this page, including the initial BOM. */
+  offset: number
+  size: number
+  eof: boolean
+  nextCursor: string | null
+  encoding: 'utf-8'
+  /** True when this non-final page ends in the middle of a logical line. */
+  partialLine: boolean
+} | {
+  ok: false
+  reason: 'unsupported' | 'invalid-cursor' | 'stale' | 'not-text' | 'read-failed'
+  error: string
+}

package/src/textPages.ts

@@ -0,0 +1,149 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { TEXT_PAGE_BYTES } from './shared/textPages.js'
+import type { TextPageArgs, TextPageResult } from './shared/textPages.js'
+
+/** Only an authorized Host adapter may supply this capability; never use raw fs as fallback. */
+export interface TextPageSource {
+  /** Authorized workspace + canonical target identity; re-authorize every request before supplying this source. */
+  identity: string
+  stat(): Promise<{ version: string; size: number; type: string } | undefined>
+  readRange(offset: number, length: number): Promise<Uint8Array>
+}
+
+interface PageCursor {
+  identity: string
+  sessionId: string
+  path: string
+  version: string
+  offset: number
+  pendingCR: boolean
+}
+
+/**
+ * Create a Host-owned pager with process-local authenticated cursors.
+ * @public @author ddj 2026年10月22号
+ * @returns A bounded reader requiring an independently authorized range capability.
+ */
+export function createTextPages() {
+  const secret = randomBytes(32)
+
+  /** @private @author ddj 2026年10月22号 @param payload Authenticated state. @returns Signed cursor. */
+  function signCursor(payload: PageCursor): string {
+    const body = Buffer.from(JSON.stringify(payload)).toString('base64url')
+    return body + '.' + createHmac('sha256', secret).update(body).digest('base64url')
+  }
+
+  /** @private @author ddj 2026年10月22号 @param token Untrusted cursor. @returns Verified state or null. */
+  function parseCursor(token: string): PageCursor | null {
+    if (typeof token !== 'string' || token.length > 8192) return null
+    const parts = token.split('.')
+    if (parts.length !== 2 || !/^[A-Za-z0-9_-]+$/.test(parts[0]!)) return null
+    const signature = Buffer.from(parts[1]!, 'base64url')
+    const expected = createHmac('sha256', secret).update(parts[0]!).digest()
+    if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) return null
+
+    try {
+      const payload = JSON.parse(Buffer.from(parts[0]!, 'base64url').toString('utf8')) as PageCursor
+      if (typeof payload.identity !== 'string' || typeof payload.version !== 'string'
+        || typeof payload.sessionId !== 'string' || typeof payload.path !== 'string'
+        || typeof payload.pendingCR !== 'boolean' || !Number.isSafeInteger(payload.offset)
+        || payload.offset <= 0) return null
+      return payload
+    } catch { return null }
+  }
+
+  /**
+   * Read at most 256 KiB, validating freshness before and after IO.
+   * @public @author ddj 2026年10月22号
+   * @param source Authorized range capability; absent means unsupported.
+   * @param args Request identity and optional signed cursor.
+   * @returns Strict UTF-8 text or an explicit fail-closed result; never partial success on mutation.
+   */
+  async function readTextPage(source: TextPageSource | undefined, args: TextPageArgs): Promise<TextPageResult> {
+    if (!source) return failure('unsupported', 'Host does not expose authorized range reads')
+    const cursor = args.cursor === undefined ? undefined : parseCursor(args.cursor)
+    if (cursor === null || (cursor && (cursor.identity !== source.identity
+      || cursor.sessionId !== (args.sessionId ?? '') || cursor.path !== args.path))) {
+      return failure('invalid-cursor', 'Cursor does not belong to this file and session')
+    }
+
+    try {
+      const before = await source.stat()
+      if (!before || before.type !== 'file' || typeof before.version !== 'string'
+        || !Number.isSafeInteger(before.size) || before.size < 0) {
+        return failure('unsupported', 'Regular file size and opaque version are required')
+      }
+      if (cursor && (cursor.version !== before.version || cursor.offset >= before.size)) {
+        return failure('stale', 'File changed; restart text preview')
+      }
+      const offset = cursor?.offset ?? 0
+      const length = Math.min(TEXT_PAGE_BYTES, before.size - offset)
+      const bytes = await source.readRange(offset, length)
+      const after = await source.stat()
+      if (!after || after.version !== before.version || after.size !== before.size || after.type !== 'file') {
+        return failure('stale', 'File changed during text read')
+      }
+      if (!(bytes instanceof Uint8Array) || bytes.byteLength !== length) {
+        return failure('read-failed', 'Range reader returned an incomplete or oversized page')
+      }
+      return decodePage(bytes, before, offset, cursor?.pendingCR ?? false, args, source.identity, signCursor)
+    } catch (error) {
+      return failure('read-failed', String(error))
+    }
+  }
+
+  return readTextPage
+}
+
+/** @private @author ddj 2026年10月22号 @param reason Failure discriminator. @param error User-visible error. @returns Failure result. */
+function failure(reason: Extract<TextPageResult, { ok: false }>['reason'], error: string): TextPageResult {
+  return { ok: false, reason, error }
+}
+
+/**
+ * Keep an incomplete final UTF-8 sequence for a bounded re-read on the next page.
+ * @private @author ddj 2026年10月22号
+ * @param bytes Raw page. @returns Complete prefix length; invalid sequences remain for fatal decoding.
+ */
+function utf8Prefix(bytes: Uint8Array): number {
+  let start = bytes.length - 1
+  while (start >= 0 && (bytes[start]! & 0xc0) === 0x80) start--
+  if (start < 0) return bytes.length
+  const lead = bytes[start]!
+  let width = 1
+  if (lead >= 0xc2 && lead <= 0xdf) width = 2
+  else if (lead >= 0xe0 && lead <= 0xef) width = 3
+  else if (lead >= 0xf0 && lead <= 0xf4) width = 4
+  return bytes.length - start < width ? start : bytes.length
+}
+
+/**
+ * Decode one page preserving original line endings without buffering a long line.
+ * @private @author ddj 2026年10月22号
+ * @param bytes Raw page. @param info File snapshot. @param offset Current offset.
+ * @param pendingCR Previous trailing CR. @param args Request identity. @param identity Authorized target identity.
+ * @param signCursor Host cursor signer. @returns Page or strict decoding failure.
+ */
+function decodePage(
+  bytes: Uint8Array, info: { size: number; version: string }, offset: number, pendingCR: boolean,
+  args: TextPageArgs, identity: string, signCursor: (cursor: PageCursor) => string,
+): TextPageResult {
+  const finalRange = offset + bytes.length === info.size
+  const consumed = finalRange ? bytes.length : utf8Prefix(bytes)
+  let text: string
+  try {
+    text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, consumed))
+  } catch { return failure('not-text', 'File is not valid UTF-8') }
+  if (text.includes('\0')) return failure('not-text', 'Binary text preview is unsupported')
+  if (offset === 0 && text.startsWith('\uFEFF')) text = text.slice(1)
+  if (pendingCR) text = '\r' + text
+
+  const nextOffset = offset + consumed
+  const eof = nextOffset === info.size
+  const trailingCR = !eof && text.endsWith('\r')
+  if (trailingCR) text = text.slice(0, -1)
+  const nextCursor = eof ? null : signCursor({ identity, sessionId: args.sessionId ?? '', path: args.path,
+    version: info.version, offset: nextOffset, pendingCR: trailingCR })
+  return { ok: true, text, version: info.version, offset: nextOffset, size: info.size, eof, nextCursor,
+    encoding: 'utf-8', partialLine: !eof && !/[\r\n]$/.test(text) }
+}

package/src/treeIndex.ts

@@ -21,9 +21,9 @@ import { DirListError, listDirCheap } from './treeRead.js'
 import { LEGACY_TREE_SIDECARS, treeCacheFile } from './paths.js'
 
 // --region 常量
-/** 命中新鲜度：超过则视为过期，按需重列。 */
+/** 硬 TTL：距最近实列确认达到此时间即过期，命中不续期。 */
 export const TREE_TTL_MS = 60_000
-/** 内存目录上限：超出按 ts 逐出最旧（常驻目录命中保活，不会误逐）。 */
+/** 内存目录上限：超出按独立运行时 LRU 逐出，不改变确认时间。 */
 export const MEM_MAX_DIRS = 2000
 /** 落盘目录上限（按 ts 裁旧）。 */
 export const PERSIST_MAX_DIRS = 400
@@ -65,6 +65,8 @@ interface IndexState {
   cwd: string
   data: TreeIndexData
   stale: Set<string>
+  /** 插入顺序即访问顺序，仅运行时使用，不写入 v1 快照。 */
+  lru: Map<string, true>
   dirty: boolean
   persistTimer: ReturnType<typeof setTimeout> | null
   healTimer: ReturnType<typeof setTimeout> | null
@@ -75,14 +77,6 @@ interface IndexState {
 
 /** cwd → 索引状态（随会话销毁清理）。 */
 const states = new Map<string, IndexState>()
-/** 单调时钟：连续 put 的 ts 严格递增（同毫秒不并列，逐出/裁剪顺序可预期）。 */
-let clock = 0
-
-/** 取下一时间戳（不小于真实时间且严格递增）。 */
-function nextTs(): number {
-  clock = Math.max(Date.now(), clock + 1)
-  return clock
-}
 
 // --region 纯函数（可单测）
 /** 条目原始值 → 合法条目（非法返回 null）。 */
@@ -147,8 +141,9 @@ export function indexParse(text: string | null): TreeIndexData | null {
         if (!e) continue
         entries.push({ name: e.name, path: rel ? rel + '/' + e.name : e.name, type: e.type })
       }
-      if (!entries.length) continue
-      dirs[rel] = { ts: typeof dir.ts === 'number' ? dir.ts : 0, full: dir.full === true, entries }
+      // 丢弃非法条目后不能再声称快照完整；空目录本身仍是有效快照。
+      const full = dir.full === true && entries.length === dir.entries.length
+      dirs[rel] = { ts: typeof dir.ts === 'number' ? dir.ts : 0, full, entries }
     }
     return { v: 1, root: typeof raw.root === 'string' ? raw.root : null, dirs }
   } catch (error) {
@@ -162,15 +157,16 @@ export function trimPersist(data: TreeIndexData, maxDirs = PERSIST_MAX_DIRS, max
   const sorted = Object.entries(data.dirs).sort((a, b) => b[1].ts - a[1].ts)
   for (const [rel, dir] of sorted) {
     if (Object.keys(dirs).length >= maxDirs) break
-    const full = dir.entries.length <= maxEntries
-    dirs[rel] = { ts: dir.ts, full, entries: full ? dir.entries : dir.entries.slice(0, maxEntries) }
+    const truncated = dir.entries.length > maxEntries
+    const full = dir.full && !truncated
+    dirs[rel] = { ts: dir.ts, full, entries: truncated ? dir.entries.slice(0, maxEntries) : dir.entries }
   }
   return { v: 1, root: data.root, dirs }
 }
 // --endregion
 
 // --region 状态机
-/** 取（或建）某 cwd 的索引状态，并惰性加载落盘快照（合并：文件 ts 更新才采纳）。 */
+/** 取（或建）某 cwd 的索引状态并惰性加载快照；加载期间真实列取优先，不被旧快照覆盖。 */
 function ensureState(ctx: Ctx, cwd: string): IndexState {
   const existing = states.get(cwd)
   if (existing) return existing
@@ -179,6 +175,7 @@ function ensureState(ctx: Ctx, cwd: string): IndexState {
     cwd,
     data: { v: 1, root: null, dirs: {} },
     stale: new Set(),
+    lru: new Map(),
     dirty: false,
     persistTimer: null,
     healTimer: null,
@@ -209,9 +206,12 @@ async function loadIndex(state: IndexState): Promise<void> {
   try {
     const parsed = indexParse(await readFile(treeCacheFile(state.cwd), 'utf8'))
     if (!parsed) return
-    for (const [rel, dir] of Object.entries(parsed.dirs)) {
-      const cur = state.data.dirs[rel]
-      if (!cur || dir.ts > cur.ts) state.data.dirs[rel] = dir
+    // 旧快照先进入 LRU；加载期间完成的真实列取优先，不被磁盘覆盖。
+    const snapshots = Object.entries(parsed.dirs).sort((a, b) => a[1].ts - b[1].ts)
+    for (const [rel, dir] of snapshots) {
+      if (state.data.dirs[rel]) continue
+      state.data.dirs[rel] = dir
+      touchDir(state, rel)
     }
     if (parsed.root && !state.data.root) state.data.root = parsed.root
   } catch (error) { /* 缺失/损坏/失败均按空索引 */ }
@@ -220,34 +220,57 @@ async function loadIndex(state: IndexState): Promise<void> {
   }
 }
 
-/** 命中：新鲜且未失效 → 条目（并刷新 ts 保活）；否则 null。 */
+/**
+ * @private
+ * @author ddj 2026年10月22号
+ * @description 更新运行时访问顺序，超限时同步清理目录及失效标记。
+ * @param state 工作区索引状态
+ * @param rel 本次访问的相对目录
+ */
+function touchDir(state: IndexState, rel: string): void {
+  state.lru.delete(rel)
+  state.lru.set(rel, true)
+  if (state.lru.size <= MEM_MAX_DIRS) return
+
+  const oldest = state.lru.keys().next().value
+  if (oldest === undefined) return
+  state.lru.delete(oldest)
+  state.stale.delete(oldest)
+  delete state.data.dirs[oldest]
+}
+
+/**
+ * @public
+ * @author ddj 2026年10月22号
+ * @description 完整、新鲜且未失效才命中；访问仅更新 LRU，不续期硬 TTL。
+ * @param cwd 工作区根
+ * @param rel 相对目录
+ * @returns 完整条目，或未命中时的 null
+ */
 export function hitIndex(cwd: string, rel: string): TreeEntry[] | null {
   const state = states.get(cwd)
   if (!state) return null
   const dir = state.data.dirs[rel]
-  if (!dir || state.stale.has(rel)) return null
-  const now = Date.now()
-  if (now - dir.ts > TREE_TTL_MS) return null
-  dir.ts = now
+  if (!dir || !dir.full || state.stale.has(rel)) return null
+  if (Date.now() - dir.ts >= TREE_TTL_MS) return null
+  touchDir(state, rel)
   return dir.entries
 }
 
-/** 更新某目录条目：写内存 + 打脏 + 防抖落盘；stale 撤销。 */
+/**
+ * @public
+ * @author ddj 2026年10月22号
+ * @description 保存完整实列结果与确认时间，更新 LRU、撤销 stale 并防抖落盘。
+ * @param ctx 工作区上下文
+ * @param cwd 工作区根
+ * @param rel 相对目录
+ * @param entries 完整实列条目
+ */
 export function putIndex(ctx: Ctx, cwd: string, rel: string, entries: TreeEntry[]): void {
   const state = ensureState(ctx, cwd)
-  const dirs = state.data.dirs
-  if (!dirs[rel] && Object.keys(dirs).length >= MEM_MAX_DIRS) {
-    let oldest = rel
-    let oldestTs = Infinity
-    for (const [k, v] of Object.entries(dirs)) {
-      if (v.ts < oldestTs) {
-        oldestTs = v.ts
-        oldest = k
-      }
-    }
-    delete dirs[oldest]
-  }
-  dirs[rel] = { ts: nextTs(), full: entries.length <= PERSIST_DIR_ENTRIES, entries }
+  // 实列结果在内存中始终完整；条目上限仅约束持久化副本。
+  state.data.dirs[rel] = { ts: Date.now(), full: true, entries }
+  touchDir(state, rel)
   state.stale.delete(rel)
   state.dirty = true
   schedulePersist(state)
@@ -319,6 +342,7 @@ export function disposeIndex(cwd: string): void {
     state.healTimer = null
   }
   if (state.dirty) void persistNow(state)
+  state.lru.clear()
   states.delete(cwd)
 }
 // --endregion
@@ -379,6 +403,7 @@ export async function listDirCached(
       if (error instanceof DirListError && error.code === 'not-found') {
         if (state.data.dirs[rel]) {
           delete state.data.dirs[rel]
+          state.lru.delete(rel)
           state.dirty = true
           schedulePersist(state)
         }