@dimina-kit/fs-core 0.2.0-dev.20260710085051

package/src/client.ts

@@ -0,0 +1,284 @@
+/**
+ * ProjectFsClient — 主线程侧 ProjectFS 封装（P0，同 origin）。
+ * 起 fs-core / fs-query 两个 worker，牵好 core→query 的 diff 端口，
+ * 暴露 Promise API；写请求自动带 opId，超时重试幂等（同 opId 重发）。
+ */
+const WRITE_TIMEOUT_MS = 8000
+
+type Mode = 'starting' | 'writer' | 'readonly' | 'draining' | 'dead'
+
+/**
+ * Loosely-shaped dynamic message bag flowing over the fs-core worker's main
+ * port: both the WELCOME/PONG/event messages (`event()`/`welcome()` in
+ * fs-core.worker.ts) and the RPC reply messages (`respond()`/`fail()` there)
+ * land here, distinguished at runtime by which optional fields are present.
+ * One flat interface (rather than a narrowed union) matches how the code
+ * actually reads it — every field is optional and independently checked.
+ */
+export interface CoreMessage {
+  type?: string
+  evt?: string
+  error?: string
+  mode?: Mode
+  readonly?: boolean
+  gen?: number
+  id?: number
+  ok?: boolean
+  result?: unknown
+  code?: string
+  humanPaths?: string[]
+  auditGap?: boolean
+  actor?: string
+  paths?: string[]
+  count?: number
+  restore?: string
+  t?: number
+}
+
+interface PendingEntry {
+  resolve: (v: unknown) => void
+  reject: (e: unknown) => void
+  timer: ReturnType<typeof setTimeout> | null
+}
+
+interface QPendingEntry {
+  resolve: (v: unknown) => void
+  reject: (e: unknown) => void
+}
+
+interface DiffResult {
+  turnId: string
+  changes: Array<{ gen: number; op: string; path?: string; from?: string; to?: string }>
+  cpId: string | undefined
+  auditWindow: { cap: number; sinceGen: number }
+}
+
+interface StatusResult {
+  mode: string
+  appendedGen: number
+  walGen: number
+  memGen: number
+  ackGen: number
+  compactGen: number
+  epoch: number
+  walStartGen: number
+  checkpoints: string[]
+  turn: { turnId: string; cpId: string; expiresAt: number; ops: number } | null
+}
+
+export class ProjectFsClient {
+  projectId!: string
+  clientId!: string
+  core!: Worker
+  query!: Worker
+  pending!: Map<number, PendingEntry>
+  qPending!: Map<number, QPendingEntry>
+  changeCbs!: Set<(evt: CoreMessage) => void>
+  modeCbs!: Set<(mode: Mode) => void>
+  _mode!: Mode
+  seq!: number
+  welcome: CoreMessage | null = null
+  pingTimer!: ReturnType<typeof setInterval>
+  lastPong!: number
+  private _retried?: boolean
+
+  /** 测试用：抹掉一个项目的全部持久层（只能在无 core 运行时调用）。 */
+  static async wipe(projectId: string): Promise<void> {
+    const root = await navigator.storage.getDirectory()
+    try { await root.removeEntry(projectId, { recursive: true }) } catch {}
+  }
+
+  static async connect({
+    projectId,
+    coreUrl = '/ide/fs/fs-core.worker.js',
+    queryUrl = '/ide/fs/fs-query.worker.js',
+    clientId = 'c-' + Math.random().toString(36).slice(2, 10),
+  }: {
+    projectId: string
+    coreUrl?: string
+    queryUrl?: string
+    clientId?: string
+  }): Promise<ProjectFsClient> {
+    const c = new ProjectFsClient()
+    c.projectId = projectId
+    c.clientId = clientId
+    c.core = new Worker(coreUrl, { type: 'module' })
+    c.query = new Worker(queryUrl, { type: 'module' })
+    c.pending = new Map() // id -> {resolve, reject, timer}
+    c.qPending = new Map()
+    c.changeCbs = new Set()
+    c.modeCbs = new Set()
+    c._mode = 'starting'
+    c.seq = 0
+    c.welcome = null
+
+    const chan = new MessageChannel()
+    const welcomed = new Promise<CoreMessage>((resolve, reject) => {
+      c.core.onmessage = (e) => c._onCoreMessage(e.data, resolve, reject)
+      c.core.onerror = (e) => reject(new Error('fs-core worker error: ' + e.message))
+    })
+    c.query.onmessage = (e) => c._onQueryMessage(e.data)
+    c.query.postMessage({ type: 'init', corePort: chan.port2 }, [chan.port2])
+    c.core.postMessage({ type: 'HELLO', projectId, clientId, capabilityRequest: { mode: 'rw' }, queryPort: chan.port1 }, [chan.port1])
+    c.welcome = await welcomed
+    c._setMode(c.welcome.mode || (c.welcome.readonly ? 'readonly' : 'writer'))
+
+    c.pingTimer = setInterval(() => { try { c.core.postMessage({ type: 'PING', t: Date.now() }) } catch {} }, 10000)
+    c.lastPong = Date.now()
+    return c
+  }
+
+  _onCoreMessage(msg: CoreMessage, resolveWelcome: ((v: CoreMessage) => void) | null, rejectWelcome: ((e: Error) => void) | null): void {
+    if (msg.type === 'WELCOME') { this._handleWelcome(msg, resolveWelcome); return }
+    if (msg.type === 'FATAL') { this._handleFatal(msg, rejectWelcome); return }
+    if (msg.type === 'PONG') { this.lastPong = Date.now(); return }
+    if (msg.evt) { this._handleEvt(msg); return }
+    if (msg.id !== undefined) this._handleRpcReply(msg)
+  }
+
+  _handleWelcome(msg: CoreMessage, resolveWelcome: ((v: CoreMessage) => void) | null): void {
+    if (resolveWelcome) resolveWelcome(msg)
+  }
+
+  _handleFatal(msg: CoreMessage, rejectWelcome: ((e: Error) => void) | null): void {
+    this._setMode('dead')
+    const err = new Error('fs-core fatal: ' + msg.error)
+    if (rejectWelcome) rejectWelcome(err)
+    for (const [, p] of this.pending) p.reject(err)
+    this.pending.clear()
+  }
+
+  _handleEvt(msg: CoreMessage): void {
+    if (msg.evt === 'writer-granted') this._setMode('writer')
+    else if (msg.evt === 'writer-lost') this._setMode('readonly')
+    for (const cb of this.changeCbs) { try { cb(msg) } catch {} }
+  }
+
+  _handleRpcReply(msg: CoreMessage): void {
+    const p = this.pending.get(msg.id!)
+    if (!p) return
+    this.pending.delete(msg.id!)
+    if (p.timer) clearTimeout(p.timer)
+    if (msg.ok) p.resolve(msg.result)
+    else p.reject(Object.assign(new Error(msg.error), { code: msg.code, ...(msg.humanPaths !== undefined ? { humanPaths: msg.humanPaths } : {}), ...(msg.auditGap !== undefined ? { auditGap: msg.auditGap } : {}) }))
+  }
+
+  _onQueryMessage(msg: CoreMessage): void {
+    if (msg.id === undefined) return
+    const p = this.qPending.get(msg.id)
+    if (!p) return
+    this.qPending.delete(msg.id)
+    if (msg.ok) p.resolve(msg.result)
+    else p.reject(Object.assign(new Error(msg.error), { code: msg.code }))
+  }
+
+  _rpc<T = unknown>(op: string, args: Record<string, unknown>, { opId, timeout }: { opId?: string; timeout?: number } = {}): Promise<T> {
+    const id = ++this.seq
+    return new Promise<T>((resolve, reject) => {
+      const entryResolve = resolve as (v: unknown) => void
+      const timer = timeout
+        ? setTimeout(() => {
+            // 超时重试一次：同 opId 幂等（fs-core 对已知 opId 返回既有结果）
+            if (opId && !this._retried) {
+              const retryId = ++this.seq
+              this.pending.set(retryId, { resolve: entryResolve, reject, timer: setTimeout(() => { this.pending.delete(retryId); reject(new Error(op + ' timeout (after retry)')) }, timeout) })
+              this.pending.delete(id)
+              this.core.postMessage({ id: retryId, op, args, opId })
+            } else {
+              this.pending.delete(id)
+              reject(new Error(op + ' timeout'))
+            }
+          }, timeout)
+        : null
+      this.pending.set(id, { resolve: entryResolve, reject, timer })
+      this.core.postMessage({ id, op, args, opId })
+    })
+  }
+
+  _qrpc<T = unknown>(op: string, args: Record<string, unknown>): Promise<T> {
+    const id = ++this.seq
+    return new Promise<T>((resolve, reject) => {
+      this.qPending.set(id, { resolve: resolve as (v: unknown) => void, reject })
+      this.query.postMessage({ id, op, args })
+    })
+  }
+
+  _writeOp<T = unknown>(op: string, args: Record<string, unknown>): Promise<T> {
+    return this._rpc<T>(op, args, { opId: crypto.randomUUID(), timeout: WRITE_TIMEOUT_MS })
+  }
+
+  // ── 写 API（{actor:'human'|'agent', turnId, ifMatch} 透传）──
+  write(path: string, content: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('write', { path, content, ...opts }) }
+  edit(path: string, old: string, next: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('edit', { path, old, next, ...opts }) }
+  rm(path: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('rm', { path, ...opts }) }
+  mv(from: string, to: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('mv', { from, to, ...opts }) }
+  mkdir(path: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('mkdir', { path, ...opts }) }
+  checkpoint(opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('checkpoint', { ...opts }) }
+  /** opts: {baseGen?, force?} 透传给 fs-core（§4.7 restore 冲突策略）；baseGen 缺省时
+   * fs-core 从 checkpoint 自身记录的 gen 推导。 */
+  restore(cpId: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('restore', { cpId, ...opts }) }
+  compact(): Promise<unknown> { return this._rpc('compact', {}, { timeout: 30000 }) }
+
+  // ── P4 turn 能力：铸造（附带 checkpoint 锚）→ agent 写执法 → 撤销 ──
+  turnBegin(turnId: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('turnBegin', { turnId, ...opts }) }
+  turnEnd(turnId: string): Promise<unknown> { return this._writeOp('turnEnd', { turnId }) }
+  /** 该 turn 的改动清单（WAL actor/turnId 审计标注免费提供）。 */
+  diff(turnId?: string): Promise<DiffResult> { return this._rpc<DiffResult>('diff', { turnId }) }
+
+  /** W4 纵深加固令牌门（docs/k3-terminal-split-plan.md §6 替代方案 A / §8.3）：特权方法，只应
+   * 由内核（kernel.js createKernel）在 boot 早期调用一次，把只有内核持有的随机令牌交给 fs-core；
+   * 此后 actor:'agent' 的写类 op 必须在 opts 里携带匹配的 agentToken（fs-core 侧强制，见
+   * fs-core.worker.js checkTurn/armAgentToken）。无 opId/超时重试——一次性 admin 调用，非写路径
+   * 幂等本就由 fs-core 的 armAgentToken 自身保证（同令牌重放 ok，不同令牌拒绝）。 */
+  armAgentTokenGate(token: string): Promise<{ armed: boolean; idempotent?: boolean }> { return this._rpc('armAgentTokenGate', { token }) }
+
+  // ── 读 API：小读走 core（权威），查询/快照走 query（不占写路径）──
+  read(path: string): Promise<{ content: string; rev?: number; gen: number }> { return this._rpc('read', { path }) }
+  ls(): Promise<{ paths: string[]; gen: number }> { return this._rpc('ls', {}) }
+  status(): Promise<StatusResult> { return this._rpc<StatusResult>('status', {}) }
+  snapshot(opts: { gen?: number } = {}): Promise<{ files: Record<string, string>; gen: number; stale: boolean }> { return this._qrpc('snapshot', opts) }
+  grep(pattern: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._qrpc('grep', { pattern, ...opts }) }
+  glob(pattern: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._qrpc('glob', { pattern, ...opts }) }
+  queryRead(path: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._qrpc('read', { path, ...opts }) }
+
+  /** 空项目时批量写入种子文件；非空则跳过。返回 {seeded, count}。 */
+  async seed(files: Record<string, string>): Promise<{ seeded: boolean; count: number }> {
+    const { paths } = await this.ls()
+    if (paths.length) return { seeded: false, count: paths.length }
+    const entries = Object.entries(files)
+    for (let i = 0; i < entries.length; i += 50) {
+      await Promise.all(entries.slice(i, i + 50).map(([p, c]) => this.write(p, c, { actor: 'human' })))
+    }
+    return { seeded: true, count: entries.length }
+  }
+
+  onChange(cb: (evt: CoreMessage) => void): () => void {
+    this.changeCbs.add(cb)
+    return () => this.changeCbs.delete(cb)
+  }
+
+  /** 当前单写者状态：starting(HELLO 未回)|writer(持写者租约)|readonly(排队中或已交出)|
+   * draining(worker 侧过渡态，client 不会长时间观察到——见 fs-core.worker.js onBroadcast，
+   * 收敛为 readonly 再广播事件)|dead(FATAL，worker 已不可用)。由 WELCOME 与
+   * writer-granted/writer-lost 事件驱动，供宿主向用户呈现"另一个标签页持有写权"之类提示。 */
+  get mode(): Mode { return this._mode }
+
+  _setMode(mode: Mode): void {
+    if (this._mode === mode) return
+    this._mode = mode
+    for (const cb of this.modeCbs) { try { cb(mode) } catch {} }
+  }
+
+  /** 订阅 mode 变化（writer ⇄ readonly ⇄ dead）；返回退订函数。 */
+  onModeChange(cb: (mode: Mode) => void): () => void {
+    this.modeCbs.add(cb)
+    return () => this.modeCbs.delete(cb)
+  }
+
+  destroy(): void {
+    clearInterval(this.pingTimer)
+    this._setMode('dead')
+    this.core.terminate()
+    this.query.terminate()
+  }
+}

package/src/disk-mirror.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Contract tests for `createDiskMirror`'s lifecycle bookkeeping — the actual
+ * disk I/O only runs in a real Chromium window, so these exercise the pure
+ * scheduling/guard logic (pick(handle), dispose(), overlapping-sync pending
+ * re-arm) against fake FileSystemDirectoryHandle/FileHandle doubles and a
+ * fake `fs.snapshot()` source, using vitest's fake timers to control the 2s
+ * debounce deterministically.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createDiskMirror } from './disk-mirror.js'
+
+/** Minimal in-memory stand-in for a FileSystemFileHandle: buffers writes
+ * until `close()`, matching the real API's write-then-close contract. */
+class FakeFileHandle {
+  content = ''
+  private buf = ''
+  async createWritable() {
+    return {
+      write: async (data: string) => {
+        this.buf = data
+      },
+      close: async () => {
+        this.content = this.buf
+      },
+    }
+  }
+}
+
+/** Minimal in-memory stand-in for a FileSystemDirectoryHandle: supports the
+ * three calls disk-mirror.js makes (getDirectoryHandle/getFileHandle/removeEntry)
+ * over a nested tree, plus a `read(path)` test helper to inspect mirrored content. */
+class FakeDirHandle {
+  name: string
+  private dirs = new Map<string, FakeDirHandle>()
+  private fileHandles = new Map<string, FakeFileHandle>()
+  constructor(name = '') {
+    this.name = name
+  }
+  async getDirectoryHandle(name: string, opts?: { create?: boolean }): Promise<FakeDirHandle> {
+    let d = this.dirs.get(name)
+    if (!d) {
+      if (!opts?.create) throw new Error(`not found: ${name}`)
+      d = new FakeDirHandle(name)
+      this.dirs.set(name, d)
+    }
+    return d
+  }
+  async getFileHandle(name: string, opts?: { create?: boolean }): Promise<FakeFileHandle> {
+    let f = this.fileHandles.get(name)
+    if (!f) {
+      if (!opts?.create) throw new Error(`not found: ${name}`)
+      f = new FakeFileHandle()
+      this.fileHandles.set(name, f)
+    }
+    return f
+  }
+  async removeEntry(name: string): Promise<void> {
+    if (this.fileHandles.delete(name)) return
+    if (this.dirs.delete(name)) return
+    throw new Error(`not found: ${name}`)
+  }
+  /** Test helper: reads mirrored content at a '/'-joined path, or undefined if absent. */
+  read(path: string): string | undefined {
+    const parts = path.split('/')
+    const dir = parts.slice(0, -1).reduce<FakeDirHandle | undefined>(
+      (d, seg) => d?.dirs.get(seg),
+      this,
+    )
+    return dir?.fileHandles.get(parts[parts.length - 1] as string)?.content
+  }
+}
+
+/** Fake `fs` source whose `snapshot()` call count and blocking can be
+ * controlled from the test, to force a real overlap between an in-flight
+ * `syncAll()` and a subsequent `schedule()`. */
+function makeFs(initialFiles: Record<string, string>) {
+  let files = { ...initialFiles }
+  let gen = 0
+  let calls = 0
+  let blockOnCall = -1
+  let releaseBlock: (() => void) | null = null
+  const snapshot = vi.fn(async () => {
+    calls++
+    // Capture synchronously (before any `await`) so a mutation the test makes
+    // *after* this call returns control is never smeared into this round's
+    // snapshot — exactly mirroring how a real snapshot is a point-in-time read.
+    const captured = { files: { ...files }, gen: ++gen }
+    if (calls === blockOnCall) {
+      await new Promise<void>((resolve) => {
+        releaseBlock = resolve
+      })
+    }
+    return captured
+  })
+  return {
+    fs: { snapshot },
+    setFiles(next: Record<string, string>) {
+      files = { ...next }
+    },
+    callCount: () => calls,
+    /** Makes the Nth `snapshot()` call block (after capturing) until `release()` is called. */
+    blockCall(n: number) {
+      blockOnCall = n
+    },
+    release() {
+      const r = releaseBlock
+      releaseBlock = null
+      r?.()
+    },
+  }
+}
+
+describe('createDiskMirror', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('pick(handle) uses the injected handle directly, skipping showDirectoryPicker', async () => {
+    const { fs } = makeFs({ 'a.txt': '1' })
+    const mirror = createDiskMirror(fs)
+    const dir = new FakeDirHandle('root')
+
+    const r = await mirror.pick(dir as unknown as FileSystemDirectoryHandle)
+
+    expect(r.name).toBe('root')
+    expect(dir.read('a.txt')).toBe('1')
+    expect(mirror.active).toBe(true)
+  })
+
+  it('dispose() cancels the pending debounce timer and short-circuits later syncAll calls', async () => {
+    const { fs, callCount } = makeFs({ 'a.txt': '1' })
+    const mirror = createDiskMirror(fs)
+    const dir = new FakeDirHandle('root')
+    await mirror.pick(dir as unknown as FileSystemDirectoryHandle)
+    const callsAfterPick = callCount()
+
+    mirror.schedule() // arms the 2s debounce timer
+    mirror.dispose()
+    expect(mirror.active).toBe(false)
+
+    await vi.advanceTimersByTimeAsync(5000)
+    // The cleared timer never fires syncAll again.
+    expect(callCount()).toBe(callsAfterPick)
+
+    // Defense in depth: even a direct syncAll() call after dispose is a no-op.
+    const r = await mirror.syncAll()
+    expect(r).toBeNull()
+    expect(callCount()).toBe(callsAfterPick)
+  })
+
+  it('re-arms and mirrors a change that happened while a sync was already in flight', async () => {
+    const { fs, setFiles, callCount, blockCall, release } = makeFs({ 'a.txt': '1' })
+    const mirror = createDiskMirror(fs)
+    const dir = new FakeDirHandle('root')
+
+    await mirror.pick(dir as unknown as FileSystemDirectoryHandle) // snapshot call #1
+    expect(dir.read('a.txt')).toBe('1')
+
+    // Round 2: block after the snapshot for call #2 is captured, simulating a
+    // sync still "in flight" (syncing === true) while further changes land.
+    blockCall(2)
+    mirror.schedule()
+    await vi.advanceTimersByTimeAsync(2000) // fires the timer -> syncAll() call #2 starts and blocks
+
+    // While round 2 is in flight, a new change arrives and schedule() is called
+    // again. Assert schedule() does NOT arm a fresh timer while syncing is
+    // true (it must set `pending` instead): advancing time here, while call #2
+    // is still blocked/in-flight, must NOT produce any further snapshot() call.
+    // The old implementation unconditionally re-armed a timer here, which
+    // would fire into `syncAll()`'s own `syncing` guard and silently drop the
+    // update forever (no retry is ever scheduled after a guard-drop).
+    setFiles({ 'a.txt': '2' })
+    mirror.schedule()
+    await vi.advanceTimersByTimeAsync(2000)
+    expect(callCount()).toBe(2) // still just call #2, blocked — no drop, no premature retry
+
+    release() // let call #2 finish; it writes the *old* ('1') snapshot it had captured
+    await vi.waitFor(() => expect(dir.read('a.txt')).toBe('1'))
+
+    // The finally-block pending re-arm should have scheduled a fresh 2s timer
+    // only once call #2 actually finished.
+    await vi.advanceTimersByTimeAsync(2000) // fires -> syncAll() call #3, captures the new value
+
+    expect(dir.read('a.txt')).toBe('2')
+    expect(callCount()).toBe(3)
+  })
+})

package/src/disk-mirror.ts

@@ -0,0 +1,119 @@
+/**
+ * 本地磁盘镜像（P5，Chromium only）—— showDirectoryPicker() 授权一个真实磁盘目录，
+ * 把项目树 write-through 镜像过去：用户在访达/资源管理器里能看到自己的项目。
+ * 这是"持久化到磁盘"的字面回答（架构文档 §4 出口 1）。
+ *
+ * 策略：fs-change 防抖 2s 全量比对同步（内容不变的文件跳过 —— 内容比对在内存，
+ * 磁盘只写变更）；删除按上次镜像记录清理。授权需要用户手势，无授权时静默不动。
+ */
+
+/** Structural shape disk-mirror.js actually calls on a directory handle —
+ * deliberately looser than the DOM lib's `FileSystemDirectoryHandle` (which
+ * also requires `resolve`/`isSameEntry`) so any handle-like object a consumer
+ * already holds — a real FSA handle, or a project's own narrower wrapper type
+ * — can be injected via `pick(handle)` without a structural mismatch. */
+export interface DiskMirrorDirectoryHandle {
+  name: string
+  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<DiskMirrorDirectoryHandle>
+  getFileHandle(name: string, options?: { create?: boolean }): Promise<{
+    createWritable(): Promise<{ write(data: unknown): Promise<void>; close(): Promise<void> }>
+  }>
+  removeEntry?(name: string, options?: { recursive?: boolean }): Promise<void>
+}
+
+// showDirectoryPicker isn't in TS's shipped DOM lib yet (real Chromium-only API).
+declare global {
+  interface Window {
+    showDirectoryPicker?(options?: { mode?: 'read' | 'readwrite' }): Promise<DiskMirrorDirectoryHandle>
+  }
+}
+
+/** Only the one ProjectFsClient method disk-mirror actually calls. */
+export interface DiskMirrorFs {
+  snapshot(): Promise<{ files: Record<string, string>; gen: number }>
+}
+
+export function createDiskMirror(fs: DiskMirrorFs) {
+  let dir: DiskMirrorDirectoryHandle | null = null
+  let last = new Map<string, string>() // path -> content（上次已镜像的内容）
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let syncing = false
+  let pending = false // syncAll 运行期间又发生了变更，结束后需要再镜像一轮
+
+  /** @param handle 已获取授权的目录句柄；传了就直接用（跳过
+   * showDirectoryPicker 弹窗），调用方自行负责获取授权（例如复用宿主已有的句柄）。 */
+  async function pick(handle?: DiskMirrorDirectoryHandle) {
+    if (handle) {
+      dir = handle
+    } else {
+      if (!window.showDirectoryPicker) throw new Error('showDirectoryPicker 不可用（需要 Chromium）')
+      dir = await window.showDirectoryPicker({ mode: 'readwrite' })
+    }
+    last = new Map()
+    const r = await syncAll()
+    return { name: dir.name, ...r }
+  }
+
+  /** 停用镜像：取消挂起的防抖定时器，清空目录句柄与镜像记账，使后续任何 syncAll
+   * 调用（包括仍在飞行中的定时器回调）在入口处天然短路。 */
+  function dispose() {
+    clearTimeout(timer)
+    dir = null
+    last = new Map()
+  }
+
+  async function syncAll(): Promise<{ written: number; removed: number; gen: number } | null> {
+    if (!dir || syncing) return null
+    syncing = true
+    try {
+      const snap: { files: Record<string, string>; gen: number } = await fs.snapshot()
+      let written = 0
+      for (const [p, content] of Object.entries(snap.files)) {
+        if (last.get(p) === content) continue
+        const parts = p.split('/')
+        let d = dir
+        for (const seg of parts.slice(0, -1)) d = await d.getDirectoryHandle(seg, { create: true })
+        const fh = await d.getFileHandle(parts[parts.length - 1] as string, { create: true })
+        const w = await fh.createWritable()
+        await w.write(content)
+        await w.close()
+        last.set(p, content)
+        written++
+      }
+      let removed = 0
+      for (const p of [...last.keys()]) {
+        if (p in snap.files) continue
+        try {
+          const parts = p.split('/')
+          let d = dir
+          for (const seg of parts.slice(0, -1)) d = await d.getDirectoryHandle(seg)
+          await d.removeEntry?.(parts[parts.length - 1] as string)
+        } catch { /* 目录已不在等：忽略 */ }
+        last.delete(p)
+        removed++
+      }
+      return { written, removed, gen: snap.gen }
+    } finally {
+      syncing = false
+      if (pending && dir) {
+        pending = false
+        schedule()
+      }
+    }
+  }
+
+  function schedule() {
+    if (!dir) return
+    if (syncing) {
+      // 一轮 syncAll 正在进行中：这次变更不能被这轮同步捕获（快照已在读取途中），
+      // 也不能立刻并发再跑一轮（syncAll 自身会在入口处丢弃）。记一个 pending，
+      // 交给上面 syncAll 的 finally 在这轮结束后重新排期，保证不丢更新。
+      pending = true
+      return
+    }
+    clearTimeout(timer)
+    timer = setTimeout(() => { syncAll().catch(() => {}) }, 2000)
+  }
+
+  return { pick, syncAll, schedule, dispose, get active() { return !!dir } }
+}