Tolaria 轻量化 AI 工作区独立窗口基于 ADR-0128 的架构决策与源码级实现解析【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本篇技术指南以 Tolaria 仓库的架构决策记录 ADR-0128Lightweight AI workspace window 为骨架深入讲解 AI 工作区如何从完整 App 壳层 系统原生交通灯的重型方案演进为轻量渲染路由 应用级设置元数据的独立弹窗架构。读完本文你将掌握该窗口的启动链路URL 上下文传递、无边框透明窗口的拖拽/关闭/停靠设计以及ai_workspace_conversations元数据存储的边界约定并能在源码中定位每一处关键实现。背景ADR-0127 留下的三个问题在 ADR-0128 之前ADR-0127Native AI workspace window 已经决定把 AI 工作区从主窗口内的右侧面板升级为渲染器持有的AiWorkspace组件可停靠主窗口或运行在独立 Tauri webview 窗口标签ai-workspace。但第一版原生窗口实现存在明显短板ADR-0128 正是针对这三处痛点的修正启动慢弹窗走了完整的App启动路径需要加载 vault/editor 壳层导致 pop-out 感觉迟滞启动工作重复独立窗口重复执行了主窗口已经做过的 vault 索引与编辑器挂载工作依赖主窗口状态AI 对话路由chat route需要等主窗口 vault 加载完成后才能运行 agent 轮次窗口之间耦合过深。此外AI 工作区还需要一份安装级installation-local的聊天元数据让用户可见的聊天标题与归档状态在停靠/弹窗切换后依然存在且不写入 vault。决策核心轻量渲染路由 应用设置元数据ADR-0128 的最终决策可以概括为一句话AI 工作区弹窗使用一个轻量级渲染器路由并由应用设置app settings元数据支撑。具体拆解为两条主线启动链路openAiWorkspaceWindow()打开ai-workspaceTauri webviewURL 携带?windowai-workspace与当前 vault 上下文参数App路由检测到该窗口后直接渲染AiWorkspaceWindowApp只加载设置、AI agent 状态与 vault AI 指引不挂载完整的 vault/editor 壳层窗口外观与控制该窗口无系统装饰undecorated且透明transparent依赖AiWorkspace自身头部提供拖拽区域并提供独立的关闭与停靠两个控件——关闭仅销毁弹窗停靠则先向主窗口发出 dock 请求再关闭弹窗。启动链路拆解URL 上下文与窗口选项1. 构建窗口 URL窗口 URL 由 src/utils/openAiWorkspaceWindow.ts 中的buildAiWorkspaceWindowUrl()生成核心逻辑是把活动对话 ID 与 vault 上下文编码进查询参数export const AI_WORKSPACE_WINDOW_LABEL ai-workspace export function buildAiWorkspaceWindowUrl( windowLabel AI_WORKSPACE_WINDOW_LABEL, context: AiWorkspaceWindowContext {}, ): string { const params new URLSearchParams({ window: ai-workspace, windowLabel, }) if (context.activeConversationId) params.set(activeConversationId, context.activeConversationId) if (context.vaultPath) params.set(vault, context.vaultPath) if (context.vaultPaths?.length) params.set(vaultPaths, JSON.stringify(context.vaultPaths)) return /?${params.toString()} }URL 参数一览参数类型说明windowstring固定为ai-workspace供渲染端路由识别windowLabelstring窗口标签默认ai-workspaceactiveConversationIdstring可选弹窗打开时要激活的对话 IDvaultstring可选当前活动 vault 的绝对路径vaultPathsstringJSON 数组可选多工作区场景下全部 vault 路径反方向由readAiWorkspaceWindowContext()从window.location.search解析出AiWorkspaceWindowContext供窗口内部使用vaultPaths采用JSON.parse 字符串数组过滤的方式容错解析失败时安全返回undefined见parseVaultPathsParam。2. 窗口创建参数aiWorkspaceWindowOptions()中定义了弹窗的 Tauri 窗口参数这是无边框透明浮窗的关键return { url: buildRuntimeAiWorkspaceWindowUrl(AI_WORKSPACE_WINDOW_LABEL, context), title: Tolaria AI, width: 560, height: 680, minWidth: 420, minHeight: 420, center: true, resizable: true, minimizable: false, alwaysOnTop: false, decorations: false, // 无系统装饰无标题栏/无交通灯 shadow: false, // 不启用系统阴影 transparent: true, // 窗口透明 backgroundColor: #00000000, visible: options.visible ?? true, }关键点decorations: false去掉了 macOS 的系统交通灯这正是 ADR-0128 与 ADR-0127 的差异之一transparent: truebackgroundColor: #00000000让圆角工作区外壳由前端绘制决定浮窗可见圆角的是AiWorkspace自身的壳层样式。3. 窗口模式的识别渲染端通过 src/utils/windowMode.ts 的isAiWorkspaceWindow()判断当前是否处于 AI 工作区窗口export function isAiWorkspaceWindow(): boolean { const params new URLSearchParams(window.location.search) if (params.get(window) ai-workspace) return true if (getCurrentWindowLabel() ! AI_WORKSPACE_WINDOW_LABEL) return false try { return localStorage.getItem(AI_WORKSPACE_WINDOW_STORAGE_KEY) true } catch { return false } }双保险URL 参数优先Webview 重建后参数丢失时回退到 Tauri 当前窗口标签 localStorage 标记判断。与之配套的preloadAiWorkspaceWindow()/closePreloadedAiWorkspaceWindow()支持后台预创建 显式显示模式进一步压缩用户可感知的弹出时间raiseAiWorkspaceWindowAboveMain()则通过临时置顶150ms 后自动恢复把浮窗提到主窗口之上。轻量路由如何绕开完整 App 壳层1. 路由分叉点src/App.tsx 的顶层分叉极其简洁function App() { const noteWindowParams useMemo(() isNoteWindow() ? getNoteWindowParams() : null, []) const aiWorkspaceWindow useMemo(() isAiWorkspaceWindow(), []) if (aiWorkspaceWindow) return AiWorkspaceWindowApp / return MainApp noteWindowParams{noteWindowParams} / }当isAiWorkspaceWindow()为真时直接返回AiWorkspaceWindowApp完全跳过MainApp的 vault 加载、侧边栏、编辑器、Git 状态等重型初始化——这就是弹窗启动接近即时close to instant的结构基础。2. 轻量窗口组件加载了什么src/components/AiWorkspaceWindowApp.tsx 是独立窗口的唯一入口组件它只组合了以下状态源useSettings()应用设置含 AI 模型提供商、对话元数据useAiAgentsStatus()已安装本地 AI agent 的状态useVaultAiGuidanceStatus()vault 级 AI 指引状态如CLAUDE.md、AGENTS.md相关指引是否就绪useAppPreferences()默认 agent / 默认 target 等偏好共享上下文aiWorkspaceWindowSharedContextSnapshot从主窗口桥接过来的活动条目、笔记内容、打开的标签页、note list 等只读快照。随后将以上数据组装为AppAiWorkspaceSurfacemodewindow完成对话界面渲染。对比完整App壳层它不做vault 全量扫描、编辑器挂载、Git 后台任务、vault watcher 等这些仍由主窗口承担。3. 与主窗口的事件桥弹窗与主窗口之间通过 Tauri 事件通信事件名定义于 src/utils/aiPromptBridge.tstolaria:ai-workspace-open-note-requested弹窗请求主窗口打开某篇笔记tolaria:ai-workspace-dock-requested弹窗请求停靠回主窗口ai-workspace-context-updated定义于openAiWorkspaceWindow.ts主窗口向弹窗推送更新后的 vault/对话上下文另有文件创建、文件修改、vault 切换事件均由弹窗emitTo(main, ...)转发给主窗口处理。无边框透明窗口的交互实现拖拽、缩放、关闭与停靠1. 透明背景与边缘缩放AiWorkspaceWindowApp挂载时通过useTransparentWindowBackground()将documentElement与body背景置为透明并加ai-workspace-native-window类。由于没有系统边框窗口缩放由前端模拟useAiWorkspaceFrameResize()在#root边缘 18pxRESIZE_EDGE范围内捕获 mousedown计算 8 个方向North/East/South/West 及其组合后调用 Tauri 的appWindow.startResizeDragging(direction)启动原生缩放useAiWorkspaceFrameCursor()同步切换ns-resize、ew-resize、nesw-resize、nwse-resize光标。两个 hook 都通过isInteractiveResizeTarget()排除按钮、输入框、下拉菜单等交互元素避免边缘拖拽与内部控件冲突。2. 关闭与停靠的语义区分窗口头部提供两个独立控件语义完全不同const handleDock useCallback(() { void dockCurrentAiWorkspaceWindow().catch(/* ... */) }, []) const handleClose useCallback(() { void closeCurrentAiWorkspaceWindow().catch(/* ... */) }, [])closeCurrentAiWorkspaceWindow()定义于openAiWorkspaceWindow.ts直接调用getCurrentWindow().close()只关闭弹窗不触碰主窗口dockCurrentAiWorkspaceWindow()先requestDockAiWorkspace()派发本地事件让主窗口恢复停靠状态再emitTo(main, AI_WORKSPACE_DOCK_REQUESTED_EVENT)通知主窗口最后关闭弹窗——先停靠、后销毁的顺序保证停靠过渡不丢会话 UI。3. 复用而非重复创建openAiWorkspaceWindow()具备完整的窗口复用逻辑先WebviewWindow.getByLabel(ai-workspace)查找现有窗口若存在且 context key 匹配则直接revealAiWorkspaceContext()设置透明背景、show()、unminimize()、setFocus()并推送最新上下文只有 context 变化或窗口不存在时才新建。这与preloadAiWorkspaceWindow()的预加载机制配合把再次唤起的开销降到接近零。聊天元数据边界ai_workspace_conversations1. 存储什么settings.ai_workspace_conversations是应用设置写入手级settings.json中的一项只存储聊天侧边栏元数据。类型定义见 src/types.tsexport interface AiWorkspaceConversationSetting { archived?: boolean | null // 是否已归档 id: string // 对话 ID格式 ai-chat-timestamp-随机段 model_id?: string | null // 对话使用的模型 ID可空 target_id?: string | null // 显式目标覆盖agent/model providernull 表示跟随默认目标 title: string // 用户可见的聊天标题 }字段语义的关键点在target_id当用户显式切换过对话目标时写入非空值否则保持null由useConversations的updateDefaultConversationTargets让所有跟随默认的对话随全局默认 target 一起更新见 src/components/aiWorkspaceConversations.ts 的conversationsToSettings()与retargetConversationState()。2. 不存储什么ADR 明确划定了边界——以下内容绝不允许进入应用设置提示词文本prompt text对话完整记录/转录transcripts笔记内容模型凭据model credentialsvault 本地配置。理由ai_workspace_conversations是有意为之的 metadata-only设计。对话标题、归档状态属于安装级 UI 偏好会随用户在同一台机器上的弹窗/停靠切换而存续但不该跟随 vault 迁移而提示词、转录等属于内容数据需要另行决策存储方案。3. 持久化时机持久化由useConversationSettingsPersistence同样位于aiWorkspaceConversations.ts驱动当settingsReady为真且conversations变化时把AiConversation[]序列化为AiWorkspaceConversationSetting[]并回调saveSettings弹窗组件通过useAiWorkspaceSettingsSaver合并进整个Settings对象保存。恢复路径则相反conversationsFromSettings()从设置还原对话列表按archived状态分组并用initialActiveConversationIdURL 参数传入或首条未归档对话作为初始激活项。备选方案对比为什么是轻量路由ADR-0128 在决策前评估了三种方案可从实现角度相互印证方案优点缺点结论轻量 AI 路由选定弹窗启动只聚焦 AI 状态显式向 agent 控制器传递 vault 上下文需要路由/窗口模式管道windowMode、URL 参数、事件桥结构上成立ADR 采用完整App路由默认功能对等度最高重复 vault/editor 启动工作延迟一个本应只含 AI 工作区的窗口否决vault 存储聊天元数据元数据随 vault 迁移聊天标题与归档是安装级 UI 偏好而非 vault 内容混入 vault 会污染笔记库否决从代码看轻量方案最终落地为App.tsx一行分叉 AiWorkspaceWindowApp的组合代价集中在 src/utils/openAiWorkspaceWindow.ts 与 src/utils/windowMode.ts 的窗口生命周期管理以及 src/utils/aiPromptBridge.ts 的事件桥约定上这与 ADR 的requires route/window-mode plumbing and explicit dock events判断一致。后果与后续演进ADR-0128 记录的后果在源码中均有对应实现启动性能弹窗启动避免完整笔记图加载webview 创建后应接近即时——由App路由直接返回AiWorkspaceWindowApp支撑src/App.tsx无系统交通灯窗口以decorations: falsetransparent: true创建可见角落由圆角工作区外壳定义关闭/停靠走头部独立控件src/utils/openAiWorkspaceWindow.ts安装级持久化聊天标题、归档状态、目标覆盖持久化在安装级settings.json的ai_workspace_conversations字段src/types.ts明确边界未来的对话转录持久化必须另立存储决策ai_workspace_conversations有意保持 metadata-only——这一约定同时约束着useConversations的状态机归档/恢复/重命名/派生会话等状态变换只操作元数据不触碰对话内容本身src/components/aiWorkspaceConversations.ts。对于希望深挖的读者推荐按此顺序阅读ADR-0128决策→ ADR-0127演进前身→ openAiWorkspaceWindow.ts窗口生命周期→ AiWorkspaceWindowApp.tsx轻量入口→ aiWorkspaceConversations.ts元数据状态机即可完整还原 Tolaria 的轻量化 AI 工作区窗口从决策到落地的全貌。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考