big-AGI LiveFile 功能详解文档与代码块的本地文件实时双向同步【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGILiveFile 是 big-AGI 内置的一项文件同步特性它通过浏览器 File System Access API 将聊天中的文档附件与 AI 生成的代码块同本地磁盘文件建立配对Pairing实现「本地改、应用刷新应用改、磁盘落盘」的双向同步。读完本文你将掌握 LiveFile 的启用方式、附件与代码块两种配对路径、差异监控与保存覆盖的完整操作流程并了解其底层 store 实现、浏览器能力检测与目录递归集成的源码原理。一、LiveFile 是什么核心能力与适用场景LiveFileLive File实时文件是 big-AGI 中一个面向桌面浏览器的文件同步功能核心思路是在 big-AGI 与本地磁盘文件之间建立一条双向连接。其定位可从官方文档docs/help-feature-livefile.md与源码 src/common/livefile/store-live-file.ts 中相互印证。它主要提供五类能力配对Pair把聊天中的文档附件或代码块与本地文件绑定监控Monitor监听本地文件的修改并将变更同步到 big-AGI 界面刷新Refresh用本地文件最新内容替换 chat 附件中的旧内容保存Save把在 big-AGI 中编辑后的内容写回本地文件存储Store让 AI 生成的代码与内容可以直接落盘到本地。典型场景包括开发者把本地.md/.js/.py文件拖入对话让 AI 分析随后在 AI 修改后一键保存回原文件或是将 AI 生成的一段代码直接配对到项目文件形成「AI 协作编辑本地代码」的工作流。二、环境要求与使用限制官方文档明确列出了运行前提详见 docs/help-feature-livefile.md 的 Requirements 一节这些约束也与源码中的能力检测逻辑完全一致维度要求 / 限制浏览器Google Chrome、Microsoft Edge桌面版操作系统仅桌面平台移动端iOS / Android因浏览器限制不支持文件类型面向文本类文件设计如.txt、.md、.js、.py性能可高效处理数十个文件源码注释称测试可达数百个文件大小单个文本文件上限10 MB配对持久性配对连接不跨会话保留刷新页面后需重新配对保存行为在 big-AGI 中保存会整体覆盖整个文件需自行用外部工具做版本控制或增量备份值得说明的是「浏览器与平台限制」并非空话——源码 src/common/livefile/store-live-file.ts 中的isLiveFileSupported()是这样实现的export function isLiveFileSupported(): boolean { return FileSystemFileHandle in window typeof FileSystemFileHandle function !Is.OS.Android !Is.OS.iOS !Is.Browser.Safari; }即只有当浏览器存在FileSystemFileHandle构造函数、且运行环境不是 Android / iOS / Safari 时才判定为支持这正是文档中「Chrome/Edge 桌面版 非移动端」要求的源码级体现。三、启用 LiveFile自动配对与手动配对LiveFile 的启用分为自动与手动两种路径覆盖附件与代码块两种内容形态。3.1 自动配对Automatic Pairing当你在输入框中Attach添加、Drop拖放或 Paste粘贴一个本地文件到聊天消息时LiveFile 会自动为该附件启用无需任何额外配置即可开始监控与刷新。源码层面附件管道通过 src/common/attachment-drafts/attachment.livefile.ts 判断来源是否携带文件系统句柄export function attachmentSourceSupportsLiveFile(source: AttachmentDraftSource): boolean { return source.media file !!source.fileWithHandle.handle typeof source.fileWithHandle.handle.getFile function; }只有拖放/选择进来的、携带FileSystemFileHandle的文件才支持 LiveFile之后调用liveFileCreateOrThrow(source.fileWithHandle.handle)创建或复用一个 LiveFile 记录。这正是「拖入即自动配对」的实现依据。3.2 手动配对附件Pairing Attachments对于已存在但没有 LiveFile 的附件例如在其他设备上创建的会话可以手动配对选中附件点击聊天中的附件在预览器中打开发起配对点击Pair File按钮——如果当前已有打开的 LiveFile 会直接列出供选择也可以从本地文件系统选择新文件授予权限按浏览器提示允许 big-AGI 访问该文件。3.3 手动配对代码块Pairing Code Blocks对于没有关联文件的 AI 生成代码片段打开代码块操作区点击代码块展开带有操作项的头部发起配对点击Pair File按钮从已打开的 LiveFile 中选择或选择新文件确认配对按提示授予权限。代码块的配对入口在增强代码渲染组件中实现参见 src/modules/blocks/enhanced-code/EnhancedRenderCode.tsx 中的liveFileButton其逻辑来自 src/modules/blocks/enhanced-code/livefile-patch/useLiveFilePatch.tsx它提供WorkspaceLiveFilePicker标签 Apply ...可复用工作区中已打开的 LiveFile也可通过fileOpen()选择磁盘上的新文件handleSelectFilePicker或直接接收拖入的FileSystemFileHandlehandleSelectFileSystemFileHandle配对成功后还会调用workspaceActions().liveFileAssign(workspaceId, newId)把该 LiveFile 挂到当前工作区。3.4 Pair File 按钮的三种状态从 src/apps/chat/components/message/fragments-attachment-doc/livefile-sync/LiveFileControlButton.tsx 可以看清按钮在三种状态下的行为状态按钮文案点击行为悬停提示未配对Pair File打开文件选择器Set up live file pairing也支持直接把文件拖到按钮上已配对、未加载内容Enable Sync加载/启用同步Sync and monitor file changes已配对、已有内容Refresh从磁盘重载并比对Reload and compare file contents此外该按钮本身还是一个拖放目标通过useDragDropDataTransfergetFirstFileSystemFileHandlesrc/common/util/fileSystemUtils.ts可以从DataTransfer中取出第一个文件句柄直接完成配对。四、使用 LiveFile监控变更与保存回写4.1 监控本地文件变更自动监控LiveFile 会监视已配对本地文件的变化。若文件在 big-AGI 之外被修改例如你在 IDE 中改了同一份代码LiveFile 状态栏会提示差异并显示变更的行数概览手动刷新点击Replace with File可将配对文件的最新内容加载进 big-AGI。有趣的是同步实现中还包含一个「窗口重新聚焦自动刷新」机制src/apps/chat/components/message/fragments-attachment-doc/livefile-sync/useLiveFileSync.tsx 订阅了WindowFocusObserver当浏览器窗口重新获得焦点且配对有效、内容已加载时会自动触发一次_handleReloadFileContent()让「切到 IDE 改完再切回来」的操作无需手动点刷新。4.2 差异计算状态栏如何告诉你文件变了当磁盘内容与当前缓冲区不一致时useLiveFileSync使用diff库的diffLines计算增删行数useLiveFileSync.tsxfunction _computeLineDiffStats(fromText: string, toText: string): LinesDiffSummary { return (diffLines(fromText, toText) || []).reduce((acc, part) { if (part.added) acc.insertions part.count ?? 1; if (part.removed) acc.deletions part.count ?? 1; return acc; }, { insertions: 0, deletions: 0 }); }状态栏据此显示类似「File has 3 added and 1 removed lines.」的提示并仅在存在差异时展示两个操作按钮Replace with file把磁盘内容写回聊天缓冲区handleLoadFromDisk→onSetBufferText(fileContent)Save to file把当前内容写回磁盘handleSaveToDisk→contentWriteAndReload。当内容完全一致时显示 No changes.加载失败/写入失败时状态栏会切换为错误信息并显示警告图标。4.3 把编辑保存回配对文件编辑附件点击附件打开预览器选择 Edit 修改内容编辑代码块在聊天消息上选择 Edit 更新代码块保存点击Save to File用当前内容整体覆盖本地文件。点击前会弹出 Overwrite File 确认对话框按住Shift点击可跳过确认确认文案为 Are you sure you want to overwrite the file with the current contents?。保存动作最终落到 store 的contentWriteAndReloadsrc/common/livefile/store-live-file.ts底层使用fsHandle.createWritable()→writable.write(newContent)→writable.close()完成写入随后就地更新内存中的内容与lastModified时间戳。五、源码原理LiveFile 的数据结构与状态管理LiveFile 的核心是一个基于 zustand 的全局 storesrc/common/livefile/store-live-file.ts配合 React Hooksrc/common/livefile/useLiveFileContent.tsx供 UI 订阅。5.1 LiveFile 数据模型类型定义见 src/common/livefile/liveFile.types.tsexport interface LiveFile { readonly id: LiveFileId; // LiveFile 唯一标识 readonly fsHandle: FileSystemFileHandle; // 文件系统句柄用于文件操作 content: string | null; // 最近一次从磁盘加载的内容null 表示未加载/加载失败 name: string; // 文件名 type: string; // MIME 类型 size: number; // 文件字节数 lastModified: number; // 文件最后修改时间戳 created: number; // LiveFile 创建时间戳 isLoading: boolean; // 是否正在加载 isSaving: boolean; // 是否正在保存 error: string | null; // 最近一次操作错误信息 }其中fsHandle是整个特性的基石LiveFileMetadata则从中挑选出id/name/type/size/lastModified/created并附加isPairingValid字段供列表类 UI 使用。5.2 添加与复用isSameEntry 去重addLiveFilestore-live-file.ts在创建新 LiveFile 前会遍历既有记录用fileSystemFileHandle.isSameEntry(otherLiveFile.fsHandle)判断是否指向同一个磁盘文件若已存在则直接返回既有 ID——避免同一文件被重复配对。随后执行10 MB 大小检查const file await fileSystemFileHandle.getFile(); if (file.size MAX_PER_TEXT_FILE_SIZE) throw new Error(Text file too large: ${file.size} bytes. Unsupported.);其中MAX_PER_TEXT_FILE_SIZE 10 * 1024 * 1024源码注释「10 MB - this would be a LOT of text, and its likely an error」。注意创建时不会自动读取内容content保持null真正的读取由后续的contentReloadFromDisk触发。5.3 读取与状态并发控制contentReloadFromDiskstore-live-file.ts通过fsHandle.getFile()读取最新文件并用file.text()解析文本同时用isLoading/isSaving标志位合并并发调用——例如isLoading为真时直接返回null避免多次重复读取。5.4 持久化与无效配对回收store 配置了persist中间件存储键名agi-live-file。但由于FileSystemFileHandle不可序列化刷新页面后持久化的只是残缺对象onRehydrateStorage会在恢复时执行 GC过滤掉checkPairingValid(file)为 false 的记录typeof file.fsHandle?.getFile function这正是文档所述「配对连接不跨会话保留刷新后需重新配对」的根源。源码注释还指出了未来的改进方向——改用可序列化的 IndexedDB 存储文件句柄。5.5 React 侧的订阅封装useLiveFileContent(liveFileId)src/common/livefile/useLiveFileContent.tsx用useShallow订阅 store解构出fsHandle之外的稳定数据并暴露三个方法liveFileContentClose关闭/卸载内容、liveFileContentReloadFromDisk从磁盘重载、liveFileContentWriteAndReload写盘并刷新内存。UI 层附件面板、代码块通过它统一获取文件状态与操作能力配合同目录下的 livefile.theme.ts 定义的状态栏样式。六、与附件系统的深度集成递归目录与拖放LiveFile 并不仅仅处理单个文件它还深度接入了 big-AGI 的附件管道src/common/attachment-drafts/attachment.pipeline.ts 与 attachment.livefile.ts目录递归官方文档指出 LiveFile「与 Big-AGI 附件系统协同支持递归添加目录」。文件系统工具 src/common/util/fileSystemUtils.ts 的getAllFilesFromDirectoryRecursively会遍历FileSystemDirectoryHandle的values()逐层下钻为每个文件补上FileWithHandle.handle即FileSystemFileHandle从而让目录内的每个文本文件都具备 LiveFile 能力遍历中遇到NotAllowedError如 Edge 141 的严格文件权限策略issue #845会跳过该文件并继续而非中断整个目录。拖放解析getDataTransferFilesOrPromisesfileSystemUtils.ts会在异步处理前一次性提取DataTransfer 中的句柄/文件这些对象在异步操作中会过期优先使用item.getAsFileSystemHandle()无句柄时回退到getAsFile()。七、最佳实践官方文档给出的两条核心建议在代码实现中均有呼应监控外部变更若本地文件在 big-AGI 之外被修改及时在应用内刷新内容。除手动点击 Replace with File 外窗口重新聚焦时的自动刷新见 4.1可显著减少遗漏使用版本控制系统对关键文件如源码、配置建议使用 Git 等版本控制工具跟踪变更、作者与历史。因为 LiveFile 的保存是整体覆盖见 store-live-file.ts 的createWritable写盘路径一旦覆盖即无法在应用内回退版本控制是最可靠的兜底。八、故障排查Troubleshooting看不到 LiveFile 选项确认使用的是受支持的桌面浏览器Chrome / Edge且已更新到最新版 big-AGI同时确认非 Safari、非移动端对照isLiveFileSupported()的判定条件权限问题确认已授予 big-AGI 访问文件的权限检查浏览器设置是否允许文件访问若目录遍历时文件被跳过多半是浏览器返回了NotAllowedError可到浏览器站点权限设置中重新授权保存/加载失败状态栏会直接展示错误信息Error saving File: ... / Error reading: ...可据此判断是权限、句柄失效还是文件过大 10 MB 的文件在配对阶段即会被拒绝。九、关于 Beta 状态官方文档明确标注该功能处于Beta阶段存在若干已知限制与待改进点主要是配对不持久、整体覆盖保存等但这些限制已被源码实现明确承载见 store 的持久化 GC 逻辑与写盘路径。在 Chrome/Edge 桌面环境下它已经可以稳定支撑「本地文件 ⇄ AI 对话」的日常协作场景是 big-AGI 中连接本地开发环境与 AI 工作流的高频特性。【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
