多窗口与多根工作区：puppyone 桌面版窗口架构设计完整指南

puppyone 桌面版（puppyone-desktop）是一款本地优先（local-first）的 AI 桌面编辑器，支持在一个应用实例中打开多个独立工作窗口。本文将带你完整看懂 puppyone 的多窗口与多根工作区窗口架构设计：为什么一个应用能安全地并行打开多个项目窗口、每个窗口如何隔离自己的状态，以及底层内核如何用同一套模型支撑从 0 到 N 个文件夹的工作区组合。

🧩 为什么需要多窗口与多根工作区？

真实的开发场景往往是"同时和两个项目打交道"：一个窗口里让 Agent 跑测试，另一个窗口自己读代码；或者前后端两个仓库需要对照着改。puppyone 桌面版的答案是：一个应用实例 + 多个原生窗口，每个窗口拥有完全独立的工作区状态。

当前产品层刻意保留了两条简单直观的约束：

• 一个仓库（repo）同一时间最多只能在一个 puppyone 窗口中打开；
• 一个 puppyone 窗口同一时间最多持有一个活动仓库。

但要注意：这是产品发布边界，不是内核的能力上限。在内核层面，一个窗口的工作区早已是"0 个、1 个或 N 个文件夹"的有序组合——多根工作区的地基已经就位，只是还没有向 UI 开放。

🪟 多窗口架构：一个应用实例，多个原生窗口

主进程统一维护跨窗口状态

Electron 主进程是全局状态的唯一持有者，维护着三个关键索引：

• windowsById：webContents.id到每个BrowserWindow的映射；
• windowStateById：每个窗口的WindowWorkspaceState，包含有序的文件夹组合与最后聚焦时间；
• workspaceWindowByPath：规范化工作区路径到"拥有它的窗口"的映射，是防止重复窗口的权威索引。

所有路径在比较前都会先做realpath规范化，因此通过符号链接打开同一个底层文件夹，不会意外创建出第二个窗口。窗口状态的实现见 window-workspace-state.mjs。

重复打开仓库时自动聚焦已有窗口

所有"打开工作区"的路径都必须经过主进程命令（如window:get-initial-workspace、workspace:open-current、workspace:open-new-window），每条命令只有三种结果：分配给请求窗口、创建新窗口、或聚焦已拥有的窗口（返回focused-existing）。渲染进程从不自己猜测别的窗口是否已经打开了这个工作区——收到focused-existing时，它只把动作视为"由另一个窗口完成的完成态"，不改变当前窗口。

挂载事务对重复路径的处理非常直接：路径若已被别的窗口拥有，就直接revealWindow聚焦过去。完整事务见 window-workspace-composition.mjs。

渲染进程状态完全按窗口隔离

每个BrowserWindow都挂载独立的 React 树，因此编辑器选中、预览缓存、Git 状态、Cloud 路由状态、侧边栏状态、终端 UI 状态永远不会在原生窗口之间共享。关闭一个仓库窗口，不会误伤其他窗口的终端、watcher 与状态。

原生窗口的几何同样有固定契约：最小宽度 640、最小高度 520，见 window-layout-contract.mjs。

🧱 多根工作区内核：一套模型支撑 0 到 N 个文件夹

三层身份模型

内核刻意拆出三个彼此独立的身份，避免"工作区 = 文件夹 = 文件"的混用：

WorkbenchWorkspace —— 一个原生窗口内 0/1/N 个文件夹的有序组合 WorkspaceFolder —— 一个已挂载的本地（或未来云端）根目录 ResourceUri —— 一个全局无歧义的文件或目录身份

单根行为就是folders.length === 1，而不是单独一条 reducer、一套 IPC、一张缓存图或一个"兼容模式"。当前 UI 只是把folders[0]投影成旧字段。类型定义见 workbenchWorkspace.ts。

资源 URI：同名文件不再"撞车"

多根场景下，两个文件夹里很可能都有src/App.tsx。内核给每个文件一个稳定的逻辑身份：

puppyone-local://workspace/<folder-id>/src/App.tsx

编辑器把身份（id/resourceUri）与展示（label、工作区相对路径）彻底分开：两个文件夹可以同时打开同名相对路径，而不会共享同一个编辑器 ID；旧的"只存路径"编辑器记录会在解析时自动迁移。URI 的构造与路径穿越防护见 resourceUri.ts。

挂载与移除：事务化的文件夹变更

挂载（attach）是一条严格流水线：候选选择 → 主进程规范化与符号链接策略 → 稳定 Folder 身份 → 跨窗口所有权检查 → provider 准备 → 发布不可变快照 → 发出onDidChange(added)。

移除（detach）则先发onWillChange(removed)，让脏的工作副本、Agent 会话、终端资源登记"持久化屏障"；屏障全部完成后才发布新 revision，并只吊销该文件夹的权限、只销毁该文件夹的服务。发布前任何一步失败，旧快照仍然是权威状态——不存在半成品。

🔒 权限边界：渲染进程不能"自封"工作区

多根带来的最大风险是权限扩散，puppyone 的防线是"fail closed"：

• 渲染进程只能复述主进程分配给它的根目录，不能铸造新的本地根权限，双方路径都会 realpath 后比对，见 workspace-authorization.mjs；
• 挂载了多个根却没指定目标根时，请求直接失败（An explicit Workspace Folder root is required），没有隐式默认值；
• 最近使用历史、Cloud 项目、资源管理器里可见的行，统统只是元数据，永远不能变成授权凭证。

🧹 窗口关闭时的资源清理策略

窗口关闭的清理严格按webContents.id作用域进行：关闭该窗口的终端会话、退订该窗口的 workspace watcher（watcher 只在无剩余订阅者时才关闭）、释放该窗口的所有权。

更细一层，清理还是按文件夹作用域的：终端会话与 Agent 会话各自记录自己的规范化 Workspace Root，移除 Folder A 只回收 A 的资源，绝不触碰 Folder B——这正是"移除一个根永不重置兄弟根资源"这条不变量的落地。

📁 架构文档与源码路径速查

小结

puppyone 桌面版的窗口架构可以浓缩成三句话：

1. 主进程独占全局窗口状态，渲染进程只负责本窗口展示，跨窗口防重复靠主进程的唯一索引裁决；
2. 多根工作区不是第二套内核，而是同一套 0/1/N 文件夹模型的天然扩展——单根只是folders.length === 1；
3. 一切文件夹变更都是事务化的快照发布，权限边界清晰、清理按作用域隔离。

理解了这套设计，你就理解了 puppyone 为什么既能"一窗一仓"地简单稳定地运行，又已经为多根工作区预留好了完整的地基。