OpenChamber 文件系统视图源码解析：目录树加载、可见性与 Artifact 预览机制

• AI Agent
• 人工智能
• 代码智能体
• 交互助手

OpenChamber 是一款基于 OpenCode AI Agent 的智能体开发环境，其文件浏览能力由FilesView（主文件视图）与SidebarFilesTree（侧边栏文件树）两大组件承担。本文以 packages/ui/src/components/views/files/DOCUMENTATION.md 为核心骨架，结合源码与测试，深入讲解 OpenChamber 文件树在「加载编排、快照一致性、可见性控制、滚动性能、Artifact 预览」五个维度的工程实现。读完本文，你将掌握这套文件系统 UI 的并发请求合并策略、Git 状态索引构建方式、隐藏面板的状态保留机制，以及图片/音视频/表格/二进制等非文本文件的预览渲染链路，可直接用于理解或复刻同类 Agent IDE 的文件浏览架构。

一、整体架构：两类文件表面的职责划分

OpenChamber 的文件浏览能力由两个组件共同提供：

• FilesView（packages/ui/src/components/views/FilesView.tsx）：桌面端与移动端的主文件视图，负责目录树、打开文件标签页、文本编辑、Artifact 预览的完整体验。
• SidebarFilesTree（packages/ui/src/components/layout/SidebarFilesTree.tsx）：侧边栏的轻量文件树，聚焦目录展开/折叠、Git 状态标记与右键操作。

两个组件都把目录快照保存在各自的组件 state 中（如FilesView中的childrenByDir），而不是全局 store——这意味着目录数据天然与组件的生命周期绑定：组件卸载即清空，重挂载即重新读取。

从源码看（FilesView.tsx#L780-L796），文件树的启用与否由两个条件决定：

const treeEnabled = isMobile || mode === 'full'; const treeActive = treeEnabled && visible;

• 桌面端editor-only模式（如上下文面板中嵌入的文件编辑器）：既不加载、也不构建未使用的目录树；
• 移动端：始终保留目录树；
• full模式：完整渲染文件树。

visible属性由外层（上下文面板等）传入，体现「实际可见性」——包含面板的打开状态、当前激活的标签页以及编辑器的开关状态，都会传递给每一个文件表面。这个设计直接支撑了后文要讲的「隐藏面板的状态保留」机制。

二、目录加载的请求合并与换代管理

2.1DirectoryRequests：同路径请求合并

DirectoryRequests（packages/ui/src/components/views/files/directoryRequests.ts）是一个极简但关键的协调器：所有对同一目录的并发读取共享同一个 Promise。

export class DirectoryRequests { private pending = new Map<string, Promise<void>>(); has(path: string): boolean { return this.pending.has(path); } clear(): void { this.pending.clear(); } run(path: string, load: (isCurrent: () => boolean) => Promise<void>, force = false): Promise<void> { const existing = this.pending.get(path); if (existing && !force) return existing; const isCurrent = (): boolean => this.pending.get(path) === promise; const promise: Promise<void> = Promise.resolve().then(() => isCurrent() ? load(isCurrent) : undefined).finally(() => { if (isCurrent()) this.pending.delete(path); }); this.pending.set(path, promise); return promise; } }

其核心机制可以拆解为三点：

1. 合并：run(path)时若pending中已有同路径请求且未强制刷新，直接返回既有 Promise（if (existing && !force) return existing），重复调用者共享同一次网络读取；
2. 换代：显式的变更后刷新（force = true）会创建新请求替换旧请求，旧请求在完成时通过isCurrent()检查发现自己已被取代，于是放弃发布结果、也不删除新请求的槽位；
3. 作用域清理：作用域切换或组件卸载时调用clear()，清空整个协调器，使旧请求的完成回调无法再发布或删除新请求的槽位。

FilesView中该协调器以useMemo创建并在卸载时清理（FilesView.tsx#L940-L941）：

const directoryRequests = React.useMemo(() => new DirectoryRequests(), []); React.useEffect(() => () => directoryRequests.clear(), [directoryRequests]);

2.2 测试用例印证并发语义

directoryRequests.test.ts 用三个用例完整验证了上述行为：

• 同目录共享请求、不同目录独立加载：对/a的两次run返回同一个 Promise（expect(second).toBe(first)），对/b的读取不受阻塞，两个目录共产生 2 次实际加载调用；
• 强制刷新后旧完成不污染新槽位：旧请求在isCurrent()返回 false 时不会发布'old'结果，新请求正常发布'new'，且请求完成后pending槽位正确删除；
• 作用域变更拒绝旧完成、失败留下可重试槽位：clear()之后旧完成的published为false；一次失败的读取会 reject 但不会遗留pending槽位（expect(requests.has('/a')).toBe(false)），后续重试可正常进行。

值得注意的细节：DirectoryRequests使用Map<string, Promise<void>>作为底层结构，Map的插入顺序特性保证了「新请求替换旧请求」时的确定性；而失败请求在finally中通过isCurrent()判断后删除槽位，保证了失败后该目录可立即重试。

2.3 背景轮询 vs 显式刷新

文档明确了轮询与刷新的优先级规则：

• 后台轮询永远不会取代进行中的目录读取（避免轮询请求与用户展开目录的请求互相覆盖）；
• 文件变更后的显式刷新可以取代（force = true，如保存文件、新建/删除文件后）；
• 每个目录的读取失败是局部的：某目录读取失败只影响该目录，且保留其上一次成功的快照，不会因一次失败就清空已展示的内容。

三、快照一致性与 Git 状态索引

3.1 引用保持：减少不必要的重渲染

「目录数组保留其引用」是这套 UI 性能策略的基础：当渲染所需的每个字段与排序都一致时，数组引用保持不变。实现位于 fileTreeStatus.ts 的areDirectoryNodesEqual：

export const areDirectoryNodesEqual = (left, right) => ( left === right || (left.length === right.length && left.every((node, index) => { const other = right[index]; return node.name === other.name && node.path === other.path && node.type === other.type && node.extension === other.extension && node.relativePath === other.relativePath; })) );

name、path、type、extension、relativePath五个字段逐一比较，再加上left === right的引用短路，使得「无变化」的轮询结果可以原样复用旧数组，避免触发子组件重渲染。其测试（fileTreeStatus.test.ts）验证了：字段值变化、顺序颠倒、长度变化、类型变化都会导致不相等，而仅复制节点则判为相等。

3.2buildFileTreeStatusIndex：每个 Git 快照只构建一次索引

Git 状态（增删改）信息通过buildFileTreeStatusIndex处理（fileTreeStatus.ts#L22-L46），它为每个 Git 快照构建两类索引：

• statusByPath：文件路径 → 状态（git-added/git-deleted/git-modified/null），优先级规则为：index === 'A'或working_dir === '?'视为新增，index === 'D'视为删除，index === 'M'或working_dir === 'M'视为修改；首次命中即写入（if (!statusByPath.has(file.path))），重复路径取先到者；
• badgeByDir：目录路径 → 聚合徽标{ modified, added }，遍历路径的每一个祖先目录累加计数，用于在文件树目录行上展示「M2 +1」之类的变更徽标。

「一次快照、一次构建」的语义：该索引随 Git 状态数据一起生成并缓存，而打开文件集合（open tabs）的成员关系维护在独立的 store set 中（useFilesViewTabsStore的openPaths），因此切换标签页不会触发 Git 索引的重新构建——这是把「变化频繁的打开文件状态」与「低频变化的 Git 状态」解耦的典型做法。

从FilesView的 scope 设计还能看到更细的缓存边界（FilesView.tsx#L784-L790）：

const runtimeKey = useGitStore((state) => state.runtimeKey); const fileScope = JSON.stringify([runtimeKey, root]); // 文件读取作用域 const treeScope = JSON.stringify([runtimeKey, root, showHidden, showGitignored]); // 目录树作用域

runtimeKey（运行时切换）与root（当前目录）是文件读取的作用域键；目录树还额外纳入「显示隐藏文件」与「显示 gitignore 文件」两个开关——任一变化都会改变treeScope，从而触发树的重建，而文件读取缓存不受这两个开关影响。

四、可见性、状态保留与超时兜底

4.1 隐藏面板保留状态、停止轮询

OpenChamber 的上下文面板可以收起、切换标签页、关闭编辑器，但隐藏的文件表面会保留草稿内容、已加载的文件内容和滚动位置。其代价是：

• 隐藏期间停止目录与文件的元数据轮询；
• 重新打开时先做一次新鲜度检查，确认数据未过期后再恢复常规轮询；
• 自动保存（Autosave）与可见性完全无关——即使面板隐藏，草稿依然按既定规则自动保存（相关判定见 fileEditorAutosave.ts 中的shouldAllowFileDraftSave/shouldScheduleFileAutosave）。

滚动位置的保留在FilesView中由fileEditorPositions这个模块级Map承载（FilesView.tsx#L667-L711）：它只保存位置元数据（scroll、anchor、head）而不保存编辑器实例或文件内容，上限 100 条（MAX_FILE_EDITOR_POSITIONS），超出后淘汰最早记录——这样即使FilesView卸载也不会无限保留访问过的文件。

4.2 30 秒读取截止：杜绝无限 loading

服务端托管的文本读取与元数据请求统一设置30 秒截止时间（deadline），且包括响应体（response body）的读取——这样一旦请求卡死，会到达既有的错误处理分支，而不是让界面停留在 loading 状态。源码中可见该模式贯穿多处（useMarkdownLocalAssets.ts#L96 与 FilesView.tsx#L3257）：

const response = await runtimeFetch('/api/fs/raw', { query: readOptions(absolutePath), signal: AbortSignal.timeout(30_000), });

4.3 工作区外文件与原生文件授权

打开工作区之外的文件时（如用户从其他路径拖入或链接指向外部文件），FilesView直接通过当前激活的 runtime读取（resolveFileReadOptions计算allowOutsideWorkspace，见 FilesView.tsx#L898-L908），editor-only与完整模式行为一致。

同时文档强调：聊天（Chat）导航与文件加载不会请求原生文件授权（native file grants）——即通过聊天面板点击文件路径跳转、或加载文件内容，都不触发操作系统的文件访问授权弹窗，一切读取都经由 runtime 的文件服务完成。这保证了权限边界的一致性：只有显式的文件操作（如「在系统文件管理器中显示」）才涉及原生能力。

4.4 侧边栏树的作用域重挂载与模块缓存

侧边栏树的根目录或运行时变化会重挂载（remount）作用域内的树。其**有界模块缓存（bounded module cache）**为不同挂载之间提供连续性：

• 折叠路径的请求取消会停止排队中的批次（batch），
• 但已经开始读取的请求仍可填充同作用域的缓存，
• 运行时变化或卸载则会使这些进行中的读取失效。

这样既避免了重挂载后整棵树的目录数据全部重新拉取，又不会让过期的读取污染新的作用域。

五、侧边栏树的滚动性能：content-visibility: auto

侧边栏树的行渲染采用浏览器原生能力content-visibility: auto（SidebarFilesTree.tsx#L431-L436）：

<div className="group relative flex items-center typography-meta" style={{ contentVisibility: 'auto', // Keep skipped rows the same size after font changes. Expanded // child lists remain outside this single-line row's containment. blockSize: 'calc(max(1lh, 1rem) + 0.5rem)', }} ...

其作用与配套约束包括：

• 跳过离屏行的布局与绘制，但不卸载它们——DOM 结构保留，滚动、焦点、菜单操作照常工作；
• 显式行高由max(1lh, 1rem) + 0.5rem计算得出，跟随元信息行高、图标最小高度与垂直内边距；这样即使字体大小变化，浏览器记住的离屏尺寸也不会残留旧的字号，避免出现「滚回顶部时行高错位」的经典问题；
• 展开的子列表位于每行的 containment 之外——content-visibility的 containment 只包裹单行内容，展开的子节点不受其裁剪影响，因此展开、滚动、聚焦和菜单都保持既有的 DOM 结构；
• 重新打开仍会刷新目录内容——content-visibility只优化渲染，不改变数据新鲜度语义。

六、Artifact 预览体系

6.1 预览类型总览

previews/目录（packages/ui/src/components/views/files/previews）存放当查看器显示非纯文本内容时的各类预览组件：

6.2renderArtifactPreview：单一分发入口

FilesView.renderArtifactPreview是停靠（docked）与全屏（fullscreen）查看器共用的唯一分发开关（FilesView.tsx#L3181-L3231）。它按文件类型依次判断：图片（非 SVG 源码）→ PDF → 音视频 → 字体 → 其他二进制 → 表格 → Mermaid，最后返回null表示无 artifact 预览。这意味着停靠面板与全屏对话框渲染的是完全相同的预览逻辑，不会出现两套实现的行为漂移。

SVG、Mermaid（.mmd）与分隔符文件（CSV/TSV）本质是文本，但拥有 artifact 视图：

• 每个路径都有独立的「预览/源码」切换开关（previews各模式通过*ViewModeByPathRef按路径记忆，见 FilesView.tsx#L829-L835）；
• 无论文本优先设置如何，它们默认以预览模式打开——因为 Agent 产出的 artifact 打开就是为了「被查看」。

6.3 认证资源加载与字节范围流式播放

浏览器必须自持的非文本 artifact（PDF、音频、视频、字体）通过getRuntimeUrlResolver().authenticatedAsset('/api/fs/raw', …)加载（runtime-url.ts#L15-L16），携带作用域限定的 URL token（scoped URL token），并由useAssetAuthRefresh负责在 token 过期前主动刷新并重挂载资源（FilesView.tsx#L721-L768）。服务端以字节范围（byte range）流式返回，因此音视频可以拖动进度条 seek，PDF 可以分页加载。

而图片保持 object-URL />赞分享