Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* useFileTree — workdir file tree state + main-process integration.
*
* Lazy expansion model:
* - Tree is a Map<relPath, DirEntry[]> keyed by parent folder relative path.
* '' (empty string) = workdir root. Sub-folders only get listed when
* toggled open by the user.
* - `expanded: Set<string>` tracks which folders are open (also keyed by
* relPath; '' is always open implicitly).
*
* chokidar push events:
* - 'add'/'unlink'/'change' on a file at relPath X → invalidate the dir
* containing X by re-listing it (cheap, <12ms even for huge folders).
* - 'addDir'/'unlinkDir' similarly.
* - The watcher is started on first mount per (workdir, options), stopped
* on last unmount (ref-counted).
*
* Selection (which file is open in the body view) is intentionally NOT here;
* it lives in caller (URL search param ?file= for doc mode, plugin state for
* RSB file-browser tabs).
*
* The hook is NOT generic — it's specifically tied to electronAPI.fileBrowser.*
* IPC. If we ever need a non-electron build this hook becomes the seam.
*
* ── 共享 store 设计(2026-07-01) ─────────────────────────────────────────────
* 早期 useFileTree 是 per-instance React state——同一 workdir 的多个 caller
* (doc 模式 sidebar / 多个 RSB file-browser tab)各自持一份 entries / expanded /
* loadingPaths,toggle 一个目录不会同步到其它 caller,反直觉。
*
* 现在改成模块级 store(stores Map<key, FileTreeStore>),按 `workdir + 配置`
* 分片。所有 useFileTree({workdir, ...}) 共享同一份 state——任何 caller
* toggle / collapseAll / refresh / expandToPath 都立刻反映到所有订阅者(useSyncExternalStore)。
*
* 生命周期:
* - 首个挂载触发 init(initial listDir root + 恢复 expanded localStorage +
* 启动 chokidar watcher)
* - refCount 归 0 时触发 cleanup(stopWatch + 从 stores Map 移除)
* - 切 workdir / 卸载组件 → refCount-- → 视情况 cleanup
*
* watcher / IPC token 等"非 React state"挂在 FileTreeStore 自身,
* 不进 React state,避免 setState 触发不必要的订阅者重渲。
*/
import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
import { createLogger } from '@/lib/logger';
import { useDeviceLinkReconnectEpoch } from '@/features/device-link/useDeviceLinkReconnectEpoch';
import {
deviceSupportsRevealIgnoredDirs,
fileBrowserApiFor,
isDeviceTooOldError,
onFileTreeEventFor,
startWatchFor,
stopWatchFor,
} from '@/lib/fileBrowserTransport';
import { loadExpandedSet, saveExpandedSet } from '../lib/expandedStore';
import {
BUILTIN_IGNORE_ALWAYS,
BUILTIN_IGNORE_REVEALABLE,
} from '../../../../../shared/ignoreNames';
const log = createLogger('useFileTree');
export interface DirEntry {
name: string;
relPath: string;
type: 'file' | 'directory';
size: number;
mtimeMs: number;
}
interface UseFileTreeOptions {
workdir: string;
/**
* 非空 = SSH remote 会话:listDir 经 main 路由到远端 file-service;
* 本地 watcher 不启动(远端暂无 watch,P4 计划事件推回),树的时效性靠
* refresh() 手动/聚焦刷新兜底。
*/
remoteHostId?: string | null;
/**
* 非空 = device-link 远程会话(被控设备):全部操作经隧道在被控端执行,
* watch 走 fs-watch topic 订阅。与 remoteHostId 互斥(嵌套时 deviceId 优先,
* SSH 二跳由被控端处理)。
*/
deviceId?: string | null;
/** default true — Unity .meta files cut ~47% of typical entries */
hideMetaFiles?: boolean;
/**
* Doc mode: only doc/config text files (md/txt/json/yaml/...); only
* directories with at least one such descendant. Filtering happens in
* main; watcher events trigger refetch of the full ancestor chain (a
* new/deleted doc file can change which dirs appear at any depth above).
*/
docMode?: boolean;
/**
* 用户开关「显示被忽略的目录」:列出依赖 / 构建产物 / 缓存目录
* (build / dist / out / node_modules / Library ...)。
*
* 进 store key:切换开关会换一份 store(listDir 与 watcher 都用新 matcher
* 重建),已展开目录的缓存在新 store 里重建。
*/
showIgnoredDirs?: boolean;
}
export interface UseFileTreeReturn {
/** Entries per folder, keyed by relPath ('' = root). */
entries: ReadonlyMap<string, readonly DirEntry[]>;
/** Set of expanded folder relPaths. '' (root) is always expanded implicitly. */
expanded: ReadonlySet<string>;
/** Folder paths still loading (after expand). */
loadingPaths: ReadonlySet<string>;
/** True until the root listDir() call returns the first time. */
initialLoading: boolean;
/** root 加载失败标记(device-too-old = 对方设备版本过旧);见 store 注释。 */
loadError: 'device-too-old' | 'load-failed' | null;
/** 树身份(workdir + 远端/设备,不含显示模式段)。切项目 / 换远端才变 —— 滚动
* 锚点继承靠它区分「同树换视口」(可继承位置)与「换树」(位置不得跨树泄漏)。 */
treeIdentityKey: string;
/**
* 「显示被忽略的目录」在当前会话是否真的生效:
* - true 本地 / SSH / 支持该字段的被控端;
* - false device-link 连到老 Desktop —— 它的 listDir 静默忽略这个字段,
* 开关看起来按下去了、树里什么也不变;
* - null device 会话首帧,能力探测还没回来(非 device 会话恒为 true)。
* 标题行据此把开关渲染成不可用 + 说明原因;树本身在 false 时已经按隐藏态
* 建 store(不向老端发一个无效字段)。
*/
/** 探测未完成时是 null;上游合入的测试夹具不提供该字段(可选)。 */
showIgnoredDirsSupported?: boolean | null;
/** 当前 store 的稳定标识(workdir + hideMetaFiles + showIgnoredDirs + host/device)。
* 切「显示被忽略的目录」会换一份 store,这个值跟着变;同一 store 内因 snapshot
* 更新造成的重渲染不会变 —— 需要区分"换视图"与"同一视图刷新"的地方(如滚动
* 锚点、DOM 复用判定)用它,而不是靠对象引用。 */
storeKey: string;
toggleFolder: (relPath: string) => void;
/** Collapse every folder back to root. Also clears persisted state. */
collapseAll: () => void;
refresh: () => Promise<void>;
/**
* 展开 relPath 的所有祖先目录(让该文件可见),触发未 cache 的目录 lazy fetch,
* 返回 Promise 等所有 listDir 完成。
*
* 用于"筛选文件 / 搜索 / 跳转"等需要把目标文件在树里露出来的场景 —— 上层调
* 完 expandToPath 再调 FileTreeView 的 scrollToPath 把那一行滚进视口,visual
* 节奏稳(虚拟化后由 virtualizer.scrollToIndex 完成)。
*
* Root 文件(relPath 不含 '/')直接 no-op return —— 它已经在根级,无需展开。
*/
expandToPath: (relPath: string) => Promise<void>;
}
const ROOT_KEY = '';
const EVENT_COALESCE_MS = 50;
/**
* 结构等价判定 —— name/type/relPath 完全相同(顺序也相同, listDir 是稳定排序),
* 只有 mtime/size 变化时返回 true。
*
* 用途:setEntries 前的去重。chokidar/parcel 对我们自己 writeFile 的原子 rename
* 也会推 change 事件 → 触发 fetchDir 拿到一组对象引用全新但内容结构没变的
* DirEntry[]。如果直接 setEntries(new Map)会让 flattenTree useMemo 重算 +
* 所有 FileTreeRow 重渲, 视觉上"刷一下"。
*
* 当前所有 entries 消费者(FileTreeView, WorkdirBrowseSidebar.findEntryByRelPath)
* 都不读 mtime/size, 所以跳过更新无功能影响。如果未来加了"按 mtime 排序"
* / "显示文件大小"之类的 UI, 这里要相应放宽比较。
*/
function entriesStructurallyEqual(
a: readonly DirEntry[],
b: readonly DirEntry[],
): boolean {
if (a.length !== b.length) return false;
for (let i = 0; i < a.length; i++) {
const x = a[i];
const y = b[i];
if (x.relPath !== y.relPath) return false;
if (x.name !== y.name) return false;
if (x.type !== y.type) return false;
}
return true;
}
/**
* 模块级共享 store。
*
* snapshot 字段是给 useSyncExternalStore 返回的稳定 readonly 视图(immutable
* 引用,变化时整体替换),React 据此判断是否触发重渲。其余字段是 store 自管的
* 非 React state(IPC token / watcher off / listener set / refCount)。
*
* 任何 mutation 必须 (a) new 一个新的 snapshot 对象 (b) 调 emit() 通知订阅者。
*/
interface FileTreeStore {
readonly key: string;
readonly workdir: string;
readonly remoteHostId: string | null;
readonly deviceId: string | null;
readonly hideMetaFiles: boolean;
readonly docMode: boolean;
readonly showIgnoredDirs: boolean;
snapshot: {
entries: ReadonlyMap<string, readonly DirEntry[]>;
expanded: ReadonlySet<string>;
loadingPaths: ReadonlySet<string>;
initialLoading: boolean;
/**
* root listDir 失败的稳定错误标记:'device-too-old' = 对方设备版本过旧
* (老被控端无 remote-op channel);'load-failed' = 其它失败。非 null 时
* FileBrowserBody 渲染错误占位而不是永远空树。
*/
loadError: 'device-too-old' | 'load-failed' | null;
};
/** 本 store 的 entries 是否还是从兄弟 scope **借来**的 seed 数据(切换开关的
* 过渡窗口)。借来的树一旦根请求失败就不代表当前视图,留着会让失败看起来像
* 加载成功(评审 P2)。 */
seeded: boolean;
/** seed 窗口里仍属「借来的」条目路径:这些列表不能当剪枝证据 —— 借来的列表
* 缺路径 ≠ 本 scope 的展开位过期(评审 P2:第二次 root 刷新借种子子列表剪掉
* 并覆盖持久记录)。真实列表每次落地时逐路径移除,清空后恢复精确剪枝。 */
borrowedDirs: Set<string>;
/** 本 scope **自己持久化过**的展开位(创建时从 localStorage 读出的那份)。
* seed 窗口收尾的 root 剪枝要继续豁免它们:那时子目录列表可能还是兄弟 scope
* 借来的,列表缺路径 ≠ 本 scope 的展开位过期(评审:切开关丢失展开记录)。 */
readonly persistedExpanded: ReadonlySet<string>;
/** 同一 relPath 的并发 listDir,latest 赢:每次开 listDir 前 bump,resolve
* 时比对 —— 不一致就丢结果。 */
tokens: Map<string, number>;
/** Single-flight directory requests plus one dirty bit for a trailing scan. */
inFlight: Map<string, DirectoryRefresh>;
/** Parent directories observed by the IPC listener in the current turn. */
pendingEventParents: Set<string>;
eventFlushTimer: ReturnType<typeof setTimeout> | null;
/** chokidar listener 取消函数。首个挂载时挂、refCount 归 0 时调。 */
watcherOff: (() => void) | null;
/** ref count + listeners 用来驱动 lifecycle 和重渲订阅。 */
refCount: number;
listeners: Set<() => void>;
}
interface DirectoryRefresh {
promise: Promise<void>;
trailing: boolean;
/** At most one trailing scan may be queued for this refresh lifecycle. */
trailingScheduled: boolean;
}
/** 全局 stores 表。key 由 storeKey() 算,同 (workdir, options) 共享同一份。 */
const stores = new Map<string, FileTreeStore>();
function storeKey(opts: Required<UseFileTreeOptions>): string {
const remote = opts.remoteHostId ? `::remote=${opts.remoteHostId}` : '';
const device = opts.deviceId ? `::device=${opts.deviceId}` : '';
const reveal = opts.showIgnoredDirs ? '::reveal' : '';
return `${opts.workdir}::doc=${opts.docMode}::hideMeta=${opts.hideMetaFiles}${reveal}${remote}${device}`;
}
function treeIdentityKey(
workdir: string,
remoteHostId: string | null,
deviceId: string | null,
): string {
const remote = remoteHostId ? `::remote=${remoteHostId}` : '';
const device = deviceId ? `::device=${deviceId}` : '';
return `${workdir}${remote}${device}`;
}
function emit(store: FileTreeStore): void {
for (const l of store.listeners) l();
}
/**
* 隐藏态会忽略的一级目录名。名单从 @cindy/file-browser-core/ignoreNames 单源
* 导入(经 shared 转发),只覆盖内置项 —— `.gitignore` / `.p4ignore` 里的自定义
* 条目 renderer 拿不到,要等新 matcher 的数据回来才消失。
*
* 名单与比较都折叠大小写:matcher 的 `ignore` 包默认 `ignorecase=true`,大小写
* 变体(`DIST` / `BUILD`)在隐藏态同样不可见,不折叠会让它们在首帧多留一拍。
*/
const HIDDEN_VIEW_DIR_NAMES = new Set(
[...BUILTIN_IGNORE_ALWAYS, ...BUILTIN_IGNORE_REVEALABLE]
.filter((name) => name.endsWith('/'))
.map((name) => name.slice(0, -1).toLowerCase()),
);
/**
* 关开关的首帧过滤:把 reveal 态树里「隐藏态会被忽略」的目录行**逐列表**拿掉
* —— 不只是根列表。被忽略目录可能嵌在已展开的普通目录下面
* (`packages/foo/node_modules`):只滤根列表的话它会一直挂在展开的父目录下,
* 而 pruneExpandedForCurrentTree 会拿**过期的 reveal 子列表**当可达性依据、
* 把它判成可达,于是永久保留到手动刷新。
*
* 同时**丢掉被移除目录的整棵缓存**(不只是那一行):它们不再可达,但 refresh()
* 是「按 entries 的 key 逐个 listDir」—— 留着会让隐藏态下一次刷新给 node_modules
* 子树白发数百个 listDir(本地卡顿,SSH / device-link 上就是数百条 RPC)。
*
* 逐列表过滤同时修好 prune 的判据:父列表里已经没有那一行,可达性自然为假。
* 其余子树缓存与展开集合整体不动(不可达的分支本来就不渲染),不重拉任何目录 ——
* 「整体一次性消失」的观感不变。
*
* 只覆盖内置名单:`.gitignore` / `.p4ignore` 的自定义条目 renderer 拿不到
* (不读盘),要等新 matcher 的数据回来才消失。
*/
function filterSeedTreeForHiddenView(
entries: ReadonlyMap<string, readonly DirEntry[]>,
): ReadonlyMap<string, readonly DirEntry[]> {
const droppedRoots = new Set<string>();
const next = new Map<string, readonly DirEntry[]>();
for (const [dir, list] of entries) {
const kept = list.filter((entry) => {
if (entry.type === 'directory' && HIDDEN_VIEW_DIR_NAMES.has(entry.name.toLowerCase())) {
droppedRoots.add(entry.relPath);
return false;
}
return true;
});
next.set(dir, kept.length === list.length ? list : kept);
}
if (droppedRoots.size === 0) return entries;
for (const dir of [...next.keys()]) {
if (dir === ROOT_KEY) continue;
// 逐级向上查:key 落在被移除目录自己或它的子树里就丢。
for (let probe = dir; probe !== ''; ) {
if (droppedRoots.has(probe)) {
next.delete(dir);
break;
}
const cut = probe.lastIndexOf('/');
probe = cut < 0 ? '' : probe.slice(0, cut);
}
}
return next;
}
/**
* 切换「显示被忽略的目录」会换一份 store(key 含 reveal 位),新 store 若从
* 空快照 + initialLoading 起步,FileTreeView 会把整棵树替换成占位(本地
* <300ms 连 spinner 都没有,就是空白),视觉上闪一下;同一 workdir 的另一半
* reveal scope 的 store 此刻通常还在表里 —— 旧 store 的 refCount 归零发生在
* 本次 commit 的 effect cleanup,晚于 render 期间的 useMemo —— 借它
* **整棵可见的树**(entries + expanded)当首帧内容,新 matcher 的 listDir 回来
* 后再整体替换。
*
* 为什么整棵借、而不是只借根列表:只借根列表会把消失动作拆成两段 —— 子行先因
* expanded 掉落而消失(父行还在),root 数据回来再拿掉父行 —— 多级展开时看起来
* 就是「从最子级逐级折叠回去」。整棵借过来,关闭开关的动作是一次性的:树先保持
* 不动,数据回来整体切换。
*
* 代价是过渡窗口(reveal → hidden)里旧 matcher 的行还会短暂可见 —— 窗口就是
* 一次 listDir(本地 <12ms;慢通道到数据回来为止)。这是有意的取舍:全量、一次性
* 地消失,比先闪空再重建、或逐级折叠都更接近直觉。
*
* 借来的 expanded 是**过渡态**:initStore 不据此 warm(免得给被忽略路径白发
* listDir),root 数据回来时由 pruneExpandedForCurrentTree 按新树剪掉不可达路径
* —— 否则它们会落进 hidden scope 的 localStorage,下次启动白拉一批。
*
* 「刷新」按钮没有这个问题:它在同一份 store 上原地 refetch,从不经过空态。
*/
function findRevealSiblingSnapshot(
opts: Required<UseFileTreeOptions>,
): FileTreeStore['snapshot'] | null {
const siblingKey = storeKey({ ...opts, showIgnoredDirs: !opts.showIgnoredDirs });
return stores.get(siblingKey)?.snapshot ?? null;
}
/**
* root 数据回来后,把「过渡期借来的、在当前树上不可达的展开路径」剪掉。
*
* 切开关时 seed 会把另一半 reveal scope 的整棵可见树带过来(见
* findRevealSiblingSnapshot)。hidden 树下 node_modules / Library 这类路径已经
* 不在 root 列表里,但它们的展开态还挂在 expanded 上 —— 留着会让用户在 hidden
* 态做下一次操作时把它们写进 hidden scope 的 localStorage,下次启动就白发一批
* listDir。逐级查父链:任一级不在对应父列表里即不可达。
*
* 查不到祖先列表(缓存被清 / 还没拉过)时保守保留 —— 宁可留一个 stale 展开位,
* 也不能把用户真实的展开态删掉。
*
* 剪枝后**同步回写持久化**(评审 P2):过渡窗口里 root 数据还没到时,用户若做过
* 一次 toggleFolder,那次 saveExpandedSet 会把继承来的 reveal-only 路径一并
* 写进本 scope —— 不回写就会把它们固化进 localStorage,下次挂载按这些路径逐个
* listDir(上限 200 个,SSH / device-link 上代价明显)。
*
* `keep`:目标 scope **自己持久化过**的展开位,豁免剪枝。回写是整份覆盖,调用方
* 必须先把这些路径并进 `snapshot.expanded` 再调本函数,否则它们会被这次回写抹掉
* (评审 P1:借来的树只能当过渡内容,不能拿它否定本 scope 自己的记录)。
*/
function pruneExpandedForCurrentTree(
store: FileTreeStore,
opts?: { keep?: ReadonlySet<string> },
): void {
if (!store.snapshot.entries.has(ROOT_KEY)) return;
const reachable = (relPath: string): boolean => {
const parts = relPath.split('/');
let parent = ROOT_KEY;
for (const part of parts) {
const list = store.snapshot.entries.get(parent);
// 没有列表,或(ROOT 以下的)列表还是 seed 借来的:证据不足,宁可保留
// (借来的子列表缺路径 ≠ 本 scope 的展开位过期;真实列表落地后这段自然
// 恢复精确判断。root 例外:创建期首剪正是靠借来的 root 列表裁掉 reveal-only
// 顶层目录,且 root 请求通常最先落地,语义保持不变)。
if (!list) return true;
if (parent !== ROOT_KEY && store.borrowedDirs.has(parent)) return true;
const child = parent === ROOT_KEY ? part : `${parent}/${part}`;
if (!list.some((entry) => entry.relPath === child)) return false;
parent = child;
}
return true;
};
const next = new Set<string>();
let changed = false;
for (const relPath of store.snapshot.expanded) {
if (relPath === ROOT_KEY || opts?.keep?.has(relPath) || reachable(relPath)) next.add(relPath);
else changed = true;
}
if (!changed) return;
store.snapshot = { ...store.snapshot, expanded: next };
emit(store);
saveExpandedSet(store.workdir, next, { showIgnoredDirs: store.showIgnoredDirs });
}
function getOrCreateStore(opts: Required<UseFileTreeOptions>): FileTreeStore {
const key = storeKey(opts);
const existing = stores.get(key);
if (existing) return existing;
// 切开关路径:借另一半 reveal scope 的整棵树当首帧内容,不经过 initialLoading
// 空白;首次挂载(无兄弟 store)仍走原来的 loading 路径。
const seed = findRevealSiblingSnapshot(opts);
// 本 scope 自己持久化过的展开位:seed 是**过渡内容**,而下面的剪枝会同步回写
// 本 scope 的 localStorage —— 不先读出来并进快照,「借来的树里不可达」就会
// 连带抹掉本 scope 原有记录(评审 P1:切回隐藏态后目录无故全部折叠)。
const persistedExpanded = loadExpandedSet(opts.workdir, {
showIgnoredDirs: opts.showIgnoredDirs,
});
// 兄弟 store 可能还卡在首次 listDir 上(慢通道):没有可显示内容时不得冒充
// 「已加载」—— 否则 FileTreeView 会把 initialLoading:false + 空 rows 渲染成
// 「此文件夹为空」,而不是延迟 loading 态。终态错误可显示(渲染错误占位)。
const seedDisplayable = !!seed && (seed.entries.size > 0 || seed.loadError !== null);
const store: FileTreeStore = {
key,
workdir: opts.workdir,
remoteHostId: opts.remoteHostId,
deviceId: opts.deviceId,
hideMetaFiles: opts.hideMetaFiles,
docMode: opts.docMode,
showIgnoredDirs: opts.showIgnoredDirs,
borrowedDirs: new Set(
// 只在 reveal 方向豁免:借来的 hidden 列表天然缺被忽略目录,缺路径 ≠
// 过期(评审 P2)。hidden 方向的种子列表已按新视图就地过滤
//(filterSeedTreeForHiddenView),对「隐藏视图可达与否」是权威证据 ——
// 再豁免会把被剪掉的被忽略目录展开位保下来、还倒逼缺缓存补拉去扫它
//(复审 P1)。
seedDisplayable && seed && opts.showIgnoredDirs ? seed.entries.keys() : [],
),
snapshot:
seedDisplayable && seed
? {
// 关开关的首帧就滤掉内置忽略目录(避免慢通道下它们在新数据回来前
// 还挂在「已隐藏」的视图里),见 filterSeedTreeForHiddenView。
entries: opts.showIgnoredDirs
? seed.entries
: filterSeedTreeForHiddenView(seed.entries),
// 借来的过渡展开态 + 本 scope 已有的持久记录(见上方 persistedExpanded)。
expanded: new Set([...seed.expanded, ...persistedExpanded]),
// 新 store 自己还没有 in-flight 请求,seed 的 loadingPaths 不继承。
loadingPaths: new Set(),
initialLoading: false,
// 错误态一并继承:首帧直接是错误占位,而不是先闪一帧空树再变错误。
loadError: seed.loadError,
}
: {
entries: new Map(),
expanded: new Set([ROOT_KEY]),
loadingPaths: new Set(),
initialLoading: true,
loadError: null,
},
seeded: seedDisplayable && !!seed,
persistedExpanded,
tokens: new Map(),
inFlight: new Map(),
pendingEventParents: new Set(),
eventFlushTimer: null,
watcherOff: null,
refCount: 0,
listeners: new Set(),
};
// 继承来的展开集合要按**(可能已过滤的)**树剪一次:剪枝那条路径挂在 fetch
// 成功分支上,根请求失败时根本不会执行 —— 而 reveal-only 路径一旦被写进本
// scope 的 localStorage(用户在错误恢复前操作目录、或 expandToPath 等路径),
// 下次挂载就会变成最多 200 次无用 listDir(评审 P2)。剪完顺带回写本 scope。
// `keep` = 本 scope 自己的持久记录:借来的树只能判「借来的路径」,不能否定本
// scope 的展开位(评审 P1)。
pruneExpandedForCurrentTree(store, { keep: persistedExpanded });
stores.set(key, store);
return store;
}
/** 把 fetchDir 抽成 store 方法 —— 所有订阅者(无论挂在哪个 hook 实例)共享同
* 一份 entries / loadingPaths 状态。 */
async function fetchDirOnce(store: FileTreeStore, relPath: string): Promise<void> {
const myToken = (store.tokens.get(relPath) ?? 0) + 1;
store.tokens.set(relPath, myToken);
// loadingPaths 设置
try {
const list = await fileBrowserApiFor(store.deviceId).listDir({
workdir: store.workdir,
remoteHostId: store.remoteHostId,
relPath,
hideMetaFiles: store.hideMetaFiles,
docMode: store.docMode,
showIgnoredDirs: store.showIgnoredDirs,
});
if (store.tokens.get(relPath) !== myToken) return; // stale
// 这份列表已是本 store 自己请求的真实数据:从「借来的」证据集合里摘除,
// 之后 prune 恢复用它做精确可达性判断(见 borrowedDirs 注释)。
store.borrowedDirs.delete(relPath);
if (store.snapshot.loadError) {
store.snapshot = { ...store.snapshot, loadError: null };
}
// 根请求**成功**(无论后面是否结构等价而跳过替换)都代表「借来的树」窗口
// 结束:之后任何一次根刷新失败都不能再把已属于本 scope 的树当成借来的清掉
// (评审 P1;结构等价的路径同样要落定,否则会长久停在"借来"态)。
// wasSeeded 必须在清标志前捕获:seed 窗口收尾的这次 root 剪枝,子目录列表
// 可能还是兄弟 scope 借来的(root 先回、子目录后回)—— 借来的列表缺路径 ≠
// 本 scope 的展开位过期,要继续豁免本 scope 自己的持久记录;等后续 root
// 刷新(entries 已全属本 scope)再做精确剪枝(评审:切开关丢失展开记录)。
const wasSeeded = store.seeded;
if (relPath === ROOT_KEY) store.seeded = false;
// 结构等价 → 跳过 setEntries,避免子组件无意义重渲(参见函数顶部注释)。
// root 仍要 prune 一次:seed 的 root 可能与新 root 结构一致而展开态还是借的。
const prevList = store.snapshot.entries.get(relPath);
if (prevList && entriesStructurallyEqual(prevList, list)) {
if (relPath === ROOT_KEY) {
pruneExpandedForCurrentTree(store, wasSeeded ? { keep: store.persistedExpanded } : undefined);
}
return;
}
const nextEntries = new Map(store.snapshot.entries);
nextEntries.set(relPath, list);
store.snapshot = { ...store.snapshot, entries: nextEntries };
emit(store);
// 过渡期(seed)借来的展开态在新树里可能已不可达,root 数据落地即剪。
if (relPath === ROOT_KEY) {
pruneExpandedForCurrentTree(store, wasSeeded ? { keep: store.persistedExpanded } : undefined);
}
} catch (err) {
log.warn(`listDir failed for ${relPath}`, err);
// root 失败要可见:空树 + 无提示会被读成"项目是空的"。device-link 的
// 版本偏差(老被控端无 remote-op channel)单独标记,渲染升级提示。
if (relPath === ROOT_KEY) {
const seededEntries = store.seeded;
store.seeded = false;
store.snapshot = {
...store.snapshot,
// seed 过渡:借来的树一旦根请求失败就不代表当前视图,留着会让「开关已按下
// + 树还是隐藏态旧数据」看起来像加载成功(错误占位只在 entries 为空时显示,
// 见 FileBrowserBody)。清掉它让失败可见且可重试;只清一次,之后恢复既有
// 「保留旧树」语义(那时 entries 确实属于当前视图)(评审 P2)。
entries: seededEntries ? new Map() : store.snapshot.entries,
loadError: isDeviceTooOldError(err) ? 'device-too-old' : 'load-failed',
};
// 借来的展开态在空树下不可达,剪枝与回写由**创建时**那次
// pruneExpandedForCurrentTree(getOrCreateStore)完成;root 首次失败时
// snapshot.entries 已被清空,再调 prune 会因缺 ROOT_KEY 直接早退,不重复。
emit(store);
}
// Keep prior state; user can refresh manually.
}
}
function setDirectoryLoading(store: FileTreeStore, relPath: string, loading: boolean): void {
const alreadyLoading = store.snapshot.loadingPaths.has(relPath);
if (alreadyLoading === loading) return;
const nextLoading = new Set(store.snapshot.loadingPaths);
if (loading) nextLoading.add(relPath);
else nextLoading.delete(relPath);
store.snapshot = { ...store.snapshot, loadingPaths: nextLoading };
emit(store);
}
/**
* Fetch one directory at a time. Calls made while the request is running set
* one trailing bit; the request loop consumes that bit after the current
* result is applied. The trailing budget is capped at one scan per lifecycle,
* so a watcher storm cannot keep the loop alive indefinitely.
*/
function fetchDir(store: FileTreeStore, relPath: string): Promise<void> {
const current = store.inFlight.get(relPath);
if (current) {
if (!current.trailingScheduled) {
current.trailingScheduled = true;
current.trailing = true;
}
return current.promise;
}
const refresh: DirectoryRefresh = {
promise: Promise.resolve(),
trailing: false,
trailingScheduled: false,
};
refresh.promise = (async () => {
do {
refresh.trailing = false;
await fetchDirOnce(store, relPath);
} while (refresh.trailing);
})().finally(() => {
if (store.inFlight.get(relPath) === refresh) {
store.inFlight.delete(relPath);
}
setDirectoryLoading(store, relPath, false);
});
store.inFlight.set(relPath, refresh);
setDirectoryLoading(store, relPath, true);
return refresh.promise;
}
function parentPath(relPath: string): string {
const slashIdx = relPath.lastIndexOf('/');
return slashIdx < 0 ? ROOT_KEY : relPath.slice(0, slashIdx);
}
function addDocModeAncestors(
store: FileTreeStore,
parent: string,
targets: Set<string>,
): void {
let cursor: string | null = parent;
while (cursor !== null) {
// An ancestor can still be warming during initial restore. Include an
// in-flight directory as a target so a watcher event arriving in that
// window gets a trailing refresh instead of being lost before the first
// result is committed.
if (store.snapshot.entries.has(cursor) || store.inFlight.has(cursor)) {
targets.add(cursor);
}
if (cursor === ROOT_KEY) break;
cursor = parentPath(cursor);
}
}
/**
* Coalesce synchronous IPC deliveries by parent directory. The IPC contract
* intentionally remains one event per changed path; only tree refresh work is
* merged here. In doc mode every cached ancestor is retained because a
* directory can disappear when its last visible descendant is removed.
*/
function queueEventRefresh(store: FileTreeStore, eventRelPath: string): void {
store.pendingEventParents.add(parentPath(eventRelPath));
if (store.eventFlushTimer) return;
store.eventFlushTimer = setTimeout(() => {
store.eventFlushTimer = null;
const parents = [...store.pendingEventParents];
store.pendingEventParents.clear();
if (store.refCount === 0) return;
const targets = new Set<string>();
for (const parent of parents) {
if (store.docMode) {
addDocModeAncestors(store, parent, targets);
} else if (store.snapshot.entries.has(parent) || store.inFlight.has(parent)) {
targets.add(parent);
}
}
for (const target of targets) void fetchDir(store, target);
}, EVENT_COALESCE_MS);
}
/** 首次挂载触发:initial fetch + 恢复 localStorage expanded + 启动 watcher。
* 幂等:重复调用直接 no-op(refCount 已 >0)。 */
async function initStore(store: FileTreeStore): Promise<void> {
// 恢复 localStorage 持久化的 expanded 集合(workdir × 视图模式共享,见
// expandedStore 的 scope 说明)。seed 带来的展开集合是过渡态(见
// findRevealSiblingSnapshot):先一并留着让整树平滑替换,root 数据回来时
// pruneExpandedForCurrentTree 按新树剪掉不可达路径。
const restored = loadExpandedSet(store.workdir, { showIgnoredDirs: store.showIgnoredDirs });
const nextExpanded = new Set<string>([ROOT_KEY, ...restored, ...store.snapshot.expanded]);
store.snapshot = { ...store.snapshot, expanded: nextExpanded };
emit(store);
// watcher 监听:per workdir 启停。共享 store 后只挂一次,所有订阅者共享。
// doc 模式 / 默认模式的差异在 onEvent handler 里按 store.docMode 分支处理。
// 三路同语义:本地 chokidar / SSH 远端 daemon fs.watch / device-link 被控端
// watch(fs-watch topic 订阅驱动)——事件 payload 完全同形,handler 无分支。
{
void startWatchFor(store.deviceId, {
workdir: store.workdir,
remoteHostId: store.remoteHostId,
hideMetaFiles: store.hideMetaFiles,
showIgnoredDirs: store.showIgnoredDirs,
}).catch((err) => log.warn('startWatch failed', err));
store.watcherOff = onFileTreeEventFor(store.deviceId, (event) => {
if (event.workdir !== store.workdir) return;
queueEventRefresh(store, event.relPath);
});
}
// Initial root fetch + 已 restore expanded 目录的并行 lazy fetch。每个 listDir
// <12ms,即使 50 个 restored 也能在 <1s 内 warm 完。
//
// seed 带来的展开父目录(不在 restored 里的那些)按**方向**分别处理:
// - 切到 reveal:hidden 态的数据缺了被忽略目录,不重拉就永远看不到
// node_modules / build(评审 P2),所以按新 matcher 重拉一遍;
// - 切到 hidden:reveal 态的数据多出被忽略项,首帧已由
// filterSeedTreeForHiddenView 就地滤掉,不再白发一轮 listDir。
const inheritedExpanded = [...store.snapshot.expanded].filter(
(p) => p !== ROOT_KEY && !restored.has(p),
);
// reveal 方向全量重拉(旧 matcher 的列表缺被忽略目录);hidden 方向的种子已由
// filterSeedTreeForHiddenView 就地滤过、缓存齐备,但「展开请求还在半路就切开关」
// 的目录在种子快照里没有缓存(旧请求只会写回旧 store),不补拉会一直「展开但
// 空白」(评审 P1)—— 只补拉缺缓存的目录。
const refetchInherited = store.showIgnoredDirs
? inheritedExpanded
: inheritedExpanded.filter((p) => !store.snapshot.entries.has(p));
invalidateBorrowedCollapsedEntries(store);
await Promise.all([
fetchDir(store, ROOT_KEY),
...[...restored].map((p) => fetchDir(store, p)),
...refetchInherited.map((p) => fetchDir(store, p)),
]);
store.snapshot = { ...store.snapshot, initialLoading: false };
emit(store);
}
/**
* 切到 reveal 态时,让「借来且当前收起」的目录条目失效。
*
* seed 借的是另一半 scope 的 entries 快照。展开中的目录会被 refetchInherited 按新
* matcher 重拉;但「展开过又收起」的目录不在 expanded 里,既不会被重拉,
* toggleFolder 又见 entries.has() 就跳过请求 —— 那条缓存仍是 hidden 态的结果,
* 缺 packages/dist 这类被忽略目录,之后展开也补不回来(评审 P1)。
*
* 只在「借来的 + reveal 态」清理:首次挂载的 store 没有陈旧条目可清;切回 hidden
* 态时 seed 已由 filterSeedTreeForHiddenView 就地滤掉,不受影响。
*/
function invalidateBorrowedCollapsedEntries(store: FileTreeStore): void {
if (!store.seeded || !store.showIgnoredDirs) return;
const expanded = store.snapshot.expanded;
const entries = new Map(store.snapshot.entries);
let dropped = 0;
for (const path of [...entries.keys()]) {
if (path === ROOT_KEY || expanded.has(path)) continue;
entries.delete(path);
dropped++;
}
if (dropped === 0) return;
store.snapshot = { ...store.snapshot, entries };
}
/** 最后一个订阅者离开:停 watcher、从 stores 表移除。store 对象被回收。 */
function disposeStore(store: FileTreeStore): void {
if (store.eventFlushTimer) clearTimeout(store.eventFlushTimer);
store.eventFlushTimer = null;
store.pendingEventParents.clear();
store.inFlight.clear();
if (store.watcherOff) {
store.watcherOff();
store.watcherOff = null;
}
void stopWatchFor(store.deviceId, {
workdir: store.workdir,
remoteHostId: store.remoteHostId,
}).catch(() => {});
stores.delete(store.key);
}
// ── Public actions (store-level,跟 UseFileTreeReturn 的同名方法对应) ────────
function toggleFolder(store: FileTreeStore, relPath: string): void {
if (relPath === ROOT_KEY) return;
const prev = store.snapshot.expanded;
const next = new Set(prev);
if (next.has(relPath)) {
next.delete(relPath);
} else {
next.add(relPath);
if (!store.snapshot.entries.has(relPath)) {
void fetchDir(store, relPath);
}
}
saveExpandedSet(store.workdir, next, { showIgnoredDirs: store.showIgnoredDirs });
store.snapshot = { ...store.snapshot, expanded: next };
emit(store);
}
function collapseAll(store: FileTreeStore): void {
const nextExpanded = new Set([ROOT_KEY]);
const prevEntries = store.snapshot.entries;
const nextEntries = new Map<string, readonly DirEntry[]>();
const rootEntries = prevEntries.get(ROOT_KEY);
if (rootEntries) nextEntries.set(ROOT_KEY, rootEntries);
saveExpandedSet(store.workdir, new Set(), { showIgnoredDirs: store.showIgnoredDirs });
store.snapshot = {
...store.snapshot,
expanded: nextExpanded,
entries: nextEntries,
};
emit(store);
}
async function refresh(store: FileTreeStore): Promise<void> {
// 根目录必须恒在请求列表里:根请求失败会清空 entries(含 ROOT_KEY),
// 而只遍历现有键时根就永远不会被重试,连接恢复后点「重试 / 刷新」也没用。
// 展开目录同样恒在:根失败清 entries 会把刚取得的子目录一并清掉,只遍历
// 现有键会让它们永远不再被请求 —— 重试后目录「已展开但空」(评审 P1)。
const targets = new Set<string>([
ROOT_KEY,
...store.snapshot.entries.keys(),
...store.snapshot.expanded,
]);
await Promise.all([...targets].map((p) => fetchDir(store, p)));
}
async function expandToPath(store: FileTreeStore, relPath: string): Promise<void> {
if (!relPath) return;
const parts = relPath.split('/');
if (parts.length < 2) return; // root 级文件
const ancestors: string[] = [];
for (let i = 1; i < parts.length; i++) {
ancestors.push(parts.slice(0, i).join('/'));
}
// 一次性写 expanded set
const nextExpanded = new Set(store.snapshot.expanded);
for (const a of ancestors) nextExpanded.add(a);
saveExpandedSet(store.workdir, nextExpanded, { showIgnoredDirs: store.showIgnoredDirs });
store.snapshot = { ...store.snapshot, expanded: nextExpanded };
emit(store);
// 未 cache 的祖先并行 fetch
const toFetch = ancestors.filter((a) => !store.snapshot.entries.has(a));
await Promise.all(toFetch.map((a) => fetchDir(store, a)));
}
// ── Hook ────────────────────────────────────────────────────────────────────
export function useFileTree({
workdir,
remoteHostId = null,
deviceId = null,
hideMetaFiles = true,
docMode = false,
showIgnoredDirs = false,
}: UseFileTreeOptions): UseFileTreeReturn {
// device 会话:探测被控端是否支持 showIgnoredDirs。老端的 listDir 会静默忽略
// 这个字段 —— 开关看起来按下去了、树里什么也不变。
//
// 探到不支持就按“隐藏态”建 store(不给老端发无效字段),并把结论 expose 给
// 标题行(开关渲染成不可用 + 说明原因)。非 device 会话恒为 true。
//
// 瞬态失败(隧道不可达 / 重连中)保持「未知」而不是落定成 false:把一次网络抖动
// 显示成「对方版本过旧」并把开关禁掉,连接恢复后也不会自愈。重探由
// reconnectEpoch 驱动 —— relay 或目标设备恢复 online 时它自增。
const revealReconnectEpoch = useDeviceLinkReconnectEpoch(deviceId ?? undefined);
const [deviceRevealSupported, setDeviceRevealSupported] = useState<boolean | null>(null);
/** 上次探测结论归属的设备;换设备不留用旧结论(重连不清,避免开关闪一下)。 */
const revealProbedDeviceRef = useRef<string | null>(null);
useEffect(() => {
if (!deviceId) {
revealProbedDeviceRef.current = null;
setDeviceRevealSupported(null);
return;
}
if (revealProbedDeviceRef.current !== deviceId) {
revealProbedDeviceRef.current = deviceId;
setDeviceRevealSupported(null);
}
let cancelled = false;
// reconnectEpoch 在这里只负责「何时重问」;缓存代次由 transport 自己按全局
// reconnect 流记账 —— hook 卸载期间的重连它也能看到(见 fileBrowserTransport)。
void deviceSupportsRevealIgnoredDirs(deviceId, workdir).then((supported) => {
if (cancelled) return;
// null = 瞬态失败:保持现状(首帧仍是「未知」,已有结论也不推翻),
// 等下一次 reconnectEpoch 或重新挂载时再问一次。
if (supported === null) return;
setDeviceRevealSupported(supported);
});
return () => {
cancelled = true;
};
}, [deviceId, workdir, revealReconnectEpoch]);
// 探测未返回时(device 首帧)沿用用户偏好:猜错只多一次重建,不会发出无法
// 兑现的用户可见承诺。
const effectiveShowIgnoredDirs = showIgnoredDirs && deviceRevealSupported !== false;
// store 实例按 (workdir + options) 共享 —— 多个 hook 实例订阅同一份。
// memo 用 dep 化 options,确保 workdir 切换会换 store。
const store = useMemo(
() => getOrCreateStore({
workdir,
remoteHostId,
deviceId,
hideMetaFiles,
docMode,
showIgnoredDirs: effectiveShowIgnoredDirs,
}),
[workdir, remoteHostId, deviceId, hideMetaFiles, docMode, effectiveShowIgnoredDirs],
);
// ref-count 生命周期:首挂触发 init(initial fetch + start watch),最后离开
// 触发 dispose(stop watch + 从 stores 表移除)。
useEffect(() => {
store.refCount += 1;
if (store.refCount === 1) {
void initStore(store);
}
return () => {
store.refCount -= 1;
if (store.refCount === 0) {
disposeStore(store);
}
};
}, [store]);
// 订阅 store snapshot 变化。useSyncExternalStore 保证多个订阅者 + concurrent
// mode 下 tearing-free。
const snapshot = useSyncExternalStore(
useCallback(
(cb) => {
store.listeners.add(cb);
return () => store.listeners.delete(cb);
},
[store],
),
() => store.snapshot,
() => store.snapshot,
);
// 把 store-level actions wrap 成跟 store 绑死的稳定引用。
const toggleFolderCb = useCallback((relPath: string) => toggleFolder(store, relPath), [store]);
const collapseAllCb = useCallback(() => collapseAll(store), [store]);
const refreshCb = useCallback(() => refresh(store), [store]);
const expandToPathCb = useCallback(
(relPath: string) => expandToPath(store, relPath),
[store],
);
return useMemo(
() => ({
entries: snapshot.entries,
expanded: snapshot.expanded,
loadingPaths: snapshot.loadingPaths,
initialLoading: snapshot.initialLoading,
loadError: snapshot.loadError,
// 非 device 会话恒 true;device 会话见上面探测注释。
showIgnoredDirsSupported: deviceId ? deviceRevealSupported : true,
storeKey: store.key,
treeIdentityKey: treeIdentityKey(workdir, remoteHostId, deviceId),
toggleFolder: toggleFolderCb,
collapseAll: collapseAllCb,
refresh: refreshCb,
expandToPath: expandToPathCb,
}),
[snapshot, deviceId, deviceRevealSupported, store, toggleFolderCb, collapseAllCb, refreshCb, expandToPathCb, workdir, remoteHostId],
);
}