Yuxi AgentPanel 文件预览来源身份与刷新生命周期设计解析【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/YuxiYuxi 知识智能体平台的前端 AgentPanel 需要同时预览「对话 Workdir」「用户个人 Workspace」「线程 Artifact」三类文件却曾因来源标记残留与无条件每秒轮询而出现接口读错、隐藏页面持续请求等缺陷。本文以 2026-08-21 决策记录 2026-08-21-agent-panel-filesystem-refresh.md 为骨架结合 AgentPanel.vue、agentPanelFilesystemPolling.js 等源码完整还原「来源身份 预览协议分流 可见性驱动轮询」的修复方案读者可据此理解文件树保活、缓存失效、轮询生命周期控制等实战设计。背景三类文件来源与两个根因缺陷AgentPanel 是对话页面中的右侧面板同时承载三种文件来源的浏览、搜索与预览来源语义路径形态Viewer Workdir当前对话的项目工作目录当前 Workdir scope如/fooUserWorkspace用户个人空间UserWorkspace scope如/fooThread Artifact线程产出的 runtime 产物跨 Project/User Data/Skills绝对 runtime 路径如/home/gem/...缺陷一读取接口只靠 tab 上可能残留的artifact布尔值选择。文件从 artifact 切回文件树时旧来源残留/outputs/...这类 Workdir 路径被发送到只接受 runtime 路径的 artifact 接口导致文件无法加载。缺陷二文件树在 AgentPanel 挂载期间固定每秒刷新不区分页面可见性、Run 状态或 keep-alive 页面状态页面隐藏时仍在持续请求后端。核心决策三种来源各自保留 owning wire identity修复的第一步是让三种文件来源在 wire 层保持各自的路径身份前端不再用单一布尔值猜来源Viewer tree/search 使用当前 Workdir scope/fooWorkspace tree/search 使用 UserWorkspace scope/fooThread artifact 使用/home/gem/...runtime 路径。前端 tab 固化workdir或workspace来源标记Viewer 与 Workspace 走结构化预览接口artifact 走原始字节接口。这一划分与同期的 preview-owner-separation、unified-workspace-runtime-identity 决策一脉相承。接口分流在源码中的落地viewer_filesystem.js 集中封装 Viewer 来源的全部接口均以thread_id path查询参数调用export const getViewerFileSystemTree (threadId, path /) { const query buildViewerQuery(threadId, path) return apiGet(/api/viewer/filesystem/tree?${query}) } export const getViewerFileContent (threadId, path) { const query buildViewerQuery(threadId, path) return apiGet(/api/viewer/filesystem/file?${query}, {}, true, blob) }其中getViewerFileContent以blob形式获取原始字节Workspace 来源则由 workspace_api.js 的getWorkspaceFileContent/downloadWorkspaceFile/searchWorkspaceFiles承担两者在 API 层天然隔离杜绝了「一个参数同时承载两种路径语义」的隐患。普通 JSON artifact 不再被误解释决策明确普通 JSON artifact 继续按原始文本渲染不把文件内容误解释为预览响应协议。这对应 file_preview.js 中normalizePreviewResponse的两级判断——先看响应content-type是否为application/json只有服务端预览 envelope 才按preview_type/kind/status解析否则走路径扩展名 内容类型推导JSON 文本文件会以text预览类型保留完整正文而不是被当作协议响应吞噬。读取与下载由来源标记决定缓存按来源隔离读取和下载接口由打开时固化的来源标记决定当前 Workdir 文件走 Viewer 接口用户目录文件走 Workspace 接口其余 runtime 路径走 artifact 接口。为保证「来源切换不读错缓存」同一路径的来源变化时前端失效旧缓存并重新加载Workspace 预览使用独立缓存前缀。AgentPanel.vue 中缓存键定义如下const previewCacheKey (filePath, threadId props.threadId) ${threadId}:${filePath} const workspacePreviewCacheKey (filePath) workspace:${filePath}Viewer 预览键{threadId}:{path}绑定当前对话线程Workspace 预览键workspace:{path}不依赖线程用户目录文件与对话无关因此个人空间文件可在切换对话后继续命中缓存。来源切换时的缓存清理由 agentPanelFilesystemPolling.js 的invalidatePreviewCacheEntryBeforeReload负责删除缓存条目若条目处于ready且持有previewUrlBlob URL则先revokeObjectURL释放内存再通过reloadPreviewAfterOrderedCacheEntryInvalidation依次「失效缓存 → 通知预览变化 → 重新加载」。replacePreviewCacheEntryIfCurrent与settlePreviewCacheLoad则保证并发加载下只有「仍是当前请求」的条目才能发布到缓存避免过期响应覆盖新来源。文件树保活对话目录与个人空间同屏切换文件树工具栏提供「对话目录 / 个人空间」两个 scope切换时两棵树的展开状态互不重置const treeScopes [ { key: thread, label: 对话目录 }, { key: workspace, label: 个人空间 } ] const activeTreeScope ref(thread)对话目录getViewerFileSystemTree(threadId, path)加载空目录的outputs/uploads不展示见下节预取逻辑个人空间getWorkspaceTree(path)加载拥有独立的workspaceTreeData/workspaceExpandedKeys/workspaceSelectedKeys状态。两个目录分别调用 Viewer 与 Workspace 搜索接口由searchActiveTreeFiles按当前 scope 分流const searchActiveTreeFiles (query) activeTreeScope.value workspace ? searchWorkspaceFiles(query) : searchViewerFiles(props.threadId, query)搜索结果打开预览时同样固化来源标记emit(open-preview, { ...entry, type: file, workdir: true }, false)对话目录或{ ..., workdir: false, workspace: true }个人空间这正是「来源身份随 tab 固化」的关键一环。刷新生命周期可见性驱动Run 终态兜底文件系统的刷新策略从「挂载即每秒轮询」改为状态机驱动文件树或 Viewer 文件 Section 变为可见时执行一次刷新仅在页面可见 面板打开 当前 Run 执行期间轮询间隔仍为 1 秒页面隐藏、组件deactivated、面板关闭、切换到 artifact 或子智能体 Section、Run 进入completed/failed/cancelled/interrupted时停止轮询并对当前线程补一次刷新若已有 Viewer 刷新在途则在其结束后补刷同一轮已预取目录不再重复刷新。每秒轮询的最小实现agentPanelFilesystemPolling.js 将轮询封装为可测试的纯函数间隔常量FILESYSTEM_REFRESH_INTERVAL_MS 1000export const startAgentPanelFilesystemPolling ({ refresh, setIntervalFn window.setInterval.bind(window), clearIntervalFn window.clearInterval.bind(window) }) { const timer setIntervalFn(() { void refresh() }, FILESYSTEM_REFRESH_INTERVAL_MS) return () clearIntervalFn(timer) }轮询启停由 AgentPanel.vue 的syncFilesystemRefreshPolling统一裁决——三个条件缺一即停止轮询const syncFilesystemRefreshPolling () { stopFilesystemRefreshPolling() if ( !componentActive.value || !props.filesystemPollingActive || (activeSection.value?.type file-tree activeTreeScope.value ! thread) ) { return } stopFilesystemPolling startAgentPanelFilesystemPolling({ refresh: () refreshFileSystem({ silent: true }) }) }即组件被 keep-alive 停用componentActive为 false、面板未激活filesystemPollingActive为 false、或当前处于个人空间 scope 时都不再每秒请求。props.visible、runActive等外部信号通过filesystemPollingActive计算属性传导实现「隐藏不请求、空闲不请求、离页不请求」。刷新门闸与补刷语义createFilesystemRefreshGate以线程为粒度防止重复刷新与过期提交export const createFilesystemRefreshGate () { const inFlightThreads new Set() const pendingThreads new Set() return { begin(threadId, { ensure false } {}) { const key String(threadId || ) if (!key) return false if (inFlightThreads.has(key)) { if (ensure) pendingThreads.add(key) return false } inFlightThreads.add(key) return true }, finish(threadId) { const key String(threadId || ) inFlightThreads.delete(key) return pendingThreads.delete(key) }, canCommit(requestedThreadId, currentThreadId) { return Boolean(requestedThreadId) requestedThreadId currentThreadId } } }begin(threadId, { ensure: true })同一线程刷新在途时把「补刷请求」记入pendingThreads返回 false 让本次调用直接退出finish结束在途刷新并取出待补刷标记若返回 truerefreshFileSystem的finally会再次以silent: true发起刷新——这正是「Run 终态补刷在途刷新结束后执行」的实现canCommit提交前校验请求线程与当前线程一致防止切换对话后旧线程响应覆盖新线程的树。refreshFileSystem在提交前还会检查requestedGeneration ! filesystemRefreshGeneration用世代号 线程双重校验拦截过期响应。同轮预取目录去重为避免展开的outputs/uploads目录在同一轮被重复请求AgentPanel.vue 在根目录刷新时预取关键子目录并让refreshExpandedTree跳过已预取键const PREFETCH_DIRECTORY_NAMES [outputs, uploads] const HIDE_WHEN_EMPTY_NAMES [outputs, uploads]nodes await refreshExpandedTree( nodes, expandedKeys.value, (directoryPath) loadDirectoryChildren(directoryPath, requestedThreadId), prefetchedKeys // 已预取的目录展开时不再重复加载 )refreshExpandedTree将展开键按路径深度升序排序父目录先于子目录跳过alreadyLoadedKeys与树中不存在的键单目录加载失败时保留上一轮 children避免清空整棵已展开树。预览内容按秒检测变化运行中的 Viewer 文件仍按秒检测元数据变化shouldRefreshActivePreview对比size与modified_atexport const shouldRefreshActivePreview (currentFile, latestFile) { if (!currentFile) return false if (!latestFile) return false return ( Number(currentFile.size ?? -1) ! Number(latestFile.size ?? -1) || String(currentFile.modified_at || ) ! String(latestFile.modified_at || ) ) }文件被 Agent 更新后前端据此判定需要重载预览Run 结束或中断后文件树读取最终持久字节保证用户看到的是落盘后的最终内容。Workspace 树的刷新时机Workspace 树在以下时机刷新重新进入该 scope、组件重新激活、保存 artifact、Run 终态后。setTreeScope切换回「个人空间」时调用refreshWorkspaceTree({ force: workspaceLoaded.value, refreshPreview: true })force让已加载过的树也重新读取最新事实workspaceRefreshInFlight/workspaceRefreshPending双标志合并并发刷新请求。操作差异Viewer 不显示「保存到工作区」由于 Viewer scope 已位于当前 Workdir界面不显示「保存到工作区」操作而 runtime artifact 保留复制到 User Datasaved_artifacts的操作。这一边界在 2026-08-26-artifact-save-destination.md 的保存目标决策中延续——保存动作的目标由来源身份决定避免把 Workdir 文件重复拷贝回自身。被否决的替代方案决策记录给出了四个被否决的替代方案理解它们有助于把握最终设计的取舍保留双路径身份 前端拼接转换树节点同时携带 scope 与 runtime 两种路径前端按tree_root_dir拼接、按前缀分流再由后端反解析。问题一次请求要转换两次身份且artifact布尔残留问题依旧依赖 merge 清理防御治标不治本。放宽 artifact API 接受/outputs/...让一个参数同时承载 Workdir scope 与 runtime path。问题掩盖调用方来源错误把缺陷固化进协议。只把轮询间隔从一秒调大仍会在隐藏、空闲和离页状态持续请求没有修复生命周期边界。隐藏时卸载整个 AgentPanel会中止已打开子智能体 Section 的 SSE破坏现有面板生命周期契约——这也是「AgentPanel 保持挂载、轮询独立启停」设计的原因。工程验证与验收矩阵决策以验收主张表驱动落地逐项映射语义 Owner 与证据来源验收主张失败面语义 Owner直接证据 / 命令负向案例当前结果Viewer、Workspace 与 artifact 保持各自 wire identity 和预览协议scope/runtime 混用或原始 JSON artifact 被解释为 envelopeviewer_filesystem_service.py、AgentPanel.vue、file_preview.js后端相关 unit前端目标 unitViewer runtime 路径被拒绝artifact scope 被拒绝普通 JSON artifact 保留完整正文Passed读取与下载接口由 Workdir、Workspace 或 artifact 来源决定来源标记残留或分流错误导致读错接口AgentChatComponent.vue、AgentPanel.vue源码装配检查前端 lint/buildworkdir/workspace变化失效缓存三类下载分别命中 owning APIInspected文件树仅在页面可见的运行期文件视图中轮询所有 Run 终态保证补一次刷新隐藏、空闲或 deactivated 后仍请求或 interrupted/终态竞态丢失最终刷新AgentChatComponent.vue、AgentPanel.vue前端 helper unit源码装配检查前端 lint/buildcompleted 与 interrupted 都触发刷新在途 Viewer 刷新结束后补刷InspectedWorkspace 树重新进入后读取最新事实保存 artifact 或离页期间的变化永久停留在旧快照AgentPanel.vue真实页面验证首次加载后新增文件切回用户目录即可见Not run每轮已预取目录最多读取一次展开的 outputs/uploads 同轮重复请求agentPanelFilesystemPolling.js前端目标 unitoutputs 已预取且展开时加载函数只调用嵌套未加载目录Passed前端静态检查、构建与工程契约有效装配错误或决策生命周期无效web/与工程 gatepnpm run lint:check、pnpm run build、python3 scripts/verify_engineering_contracts.py、python3 -m unittest scripts.test_verify_engineering_contracts删除来源判定、轮询 guard 或记录接线后检查失败Passed本地真实页面目录切换、展开与预览行为DOM 或请求仍与单元契约不一致本地 Compose 页面Playwright 打开/agent/{thread_id}并保留截图覆盖目录切换、loading、empty、error、预览和窄视口Not run后端 Ruff 与文档构建 gatePython 风格或文档链接/构建错误只在 CI 暴露backend/pyproject.toml、docs/ruff check、ruff format --check、pnpm run build不适用Not run其中「轮询每秒、停止清理」「刷新按线程隔离、过期响应不可提交」「ensure 补刷排队」三条关键行为已由前端单元测试 agentPanelFilesystemPolling.test.js 固化例如startAgentPanelFilesystemPolling注入setIntervalFn/clearIntervalFn后断言间隔为 1000ms、stop 清除定时器createFilesystemRefreshGate验证同一线程二次begin返回 false、跨线程canCommit返回 false、finish返回 pending 标记。小结本决策以「来源身份」为锚点把三类文件来源的路径、接口、缓存、操作差异全部固化下来读取与下载由打开时固化的来源标记分派缓存按threadId/workspace前缀隔离来源变化时先失效旧缓存再重载刷新则从「无差别每秒轮询」收敛为「可见才刷、运行才轮、终态必补」的生命周期状态机配合线程级刷新门闸与预取去重既保证 Agent 运行中的文件变化能被秒级感知又让隐藏、空闲、离页页面零请求同时不触碰子智能体 Section 的 SSE 生命周期。这一设计把预览来源与刷新时机两个正交问题分别收敛到 wire identity 与可见性状态机是理解 Yuxi 前端面板生命周期管理的关键样本。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考