iTerm2 Floating Panes 设计剖析打破严格平铺假设的架构路线图【免费下载链接】iTerm2iTerm2 is a terminal emulator for Mac OS X that does amazing things.项目地址: https://gitcode.com/gh_mirrors/it/iTerm2导读本文以 iTerm2 仓库中的设计文档 docs/floating-panes-design.md 为核心骨架系统解析浮动窗格Floating Pane这一功能的完整设计蓝图——从打破平铺树核心假设的动机、Metal 渲染决策分叉点到数据模型、尺寸反演、交互模型、序列化与自动化兼容策略再到分阶段实施计划与 tmux 上游集成的时间表。读完本文你将理解 iTerm2 标签页视图层PTYTab / SessionView / PTYSession / PseudoTerminal的既有约束、浮动窗格所需的底层改造点以及一份可复用的渐进式重构路线。0. 背景一次打破核心假设的架构挑战iTerm2 的每个标签页Tab中所有窗格pane都是一棵严格平铺的NSSplitView树的叶子节点。浮动窗格Floating Pane的目标是让一个终端会话悬浮在平铺布局之上自由定位、自由缩放、拥有 z 轴层叠顺序可以与邻居重叠甚至可以部分悬挂在标签页内容区域之外。设计文档明确指出这是在不重写视图层的前提下最大的结构性变更之一因为一个单一假设被写死在了数十处调用点中一个标签页的会话恰好是PTYTab.root_这棵分割树的所有叶子这些叶子平铺标签页没有重叠、没有缝隙、没有 z 轴顺序。这一假设同时被三个不变量固化在源码中详见 sources/TerminalView/PTYTab.m树范式Tree normal formcheckInvariants:PTYTab.m:2006要求非根分割节点至少有两个子节点、方向按深度交替、单一根子节点必须是SessionViewcleanupAfterRemove:PTYTab.m:2033还会主动重写树以维持该范式。精确划分Exact partitionresizeSubviewsOfSplitView:PTYTab.m:6542、_recursiveSize:PTYTab.m:2581等实现中帧是推导出来的而非任意的子视图无重叠地填满父视图。几何推导的顺序Geometry-derived orderingorderedSessionsPTYTab.m:1052以及邻居引擎PTYTab.m:1446-1600 区间假设矩形互不重叠并且完全没有层叠顺序z-order的概念。值得注意的是iTerm2 已经拥有大量可复用的部件能够在不杀死 PTY 的情况下重新父级化reparent活跃SessionView的机制、跨窗口重父级会话的拖放系统、带装饰的可移动可缩放覆盖层以及圆角边框视图。因此设计文档的结论是真正需要提前敲定的未知点只有一个——浮动窗格如何渲染在 Metal 支持的窗格之上这个答案将分叉整个架构见第 3 节其余大部分工作只是组装。1. 现状标签页视图树与三个被打破的不变量1.1 今天的视图树结构一个标签页的视图树形如NSTabViewItem.view └─ (可选) flexibleView_ ← 仅 tmux 会话使用 └─ root_PTYSplitView └─ 嵌套 NSSplitView └─ SessionView 叶子会话的枚举通过递归遍历这棵树完成_recursiveSessions:atNode:PTYTab.m:1649与_recursiveSessionViews:PTYTab.m:1673。分割视图拥有每个帧子视图以仅带分隔条间隙的方式划分父视图的矩形。设计文档用一张 ASCII 图直观对比了严格平铺与加入浮动窗格后的差异今天严格平铺 引入浮动窗格重叠 z 序 -------------------- -------------------- | A | B | | A | B | | | | | --------- | -------------------- -----| float |----- | C | | --------- | | | | C | -------------------- ---------------------1.2 三个不变量逐一失效树范式浮动窗格不在分割树内枚举、广播、全部关闭、布局保存arrangement和 API 都看不到它cleanupAfterRemove:的重写逻辑也不知道它的存在。精确划分浮动窗格的帧是用户直接指定的天然与子视图填满父视图且无重叠冲突。几何派生顺序阅读顺序与方向导航建立在互不重叠的矩形之上重叠区域没有明确的邻居定义也没有 z 轴平局裁决规则。2. 浮动窗格会打破什么六大受影响面设计文档逐一列出了浮动窗格对既有机制的破坏枚举Enumeration-sessions与-sessionViews只能看到树。好消息是这两个访问器已经针对最大化暂存区maximize stash即idMap_做了分叉PTYTab.m:1633-1646 与 1665-1671这正是引入第二个会话群体的天然挂载点。从源码可见当idMap_存在时-sessions直接返回idMap_的所有值否则才递归树。尺寸Sizing窗格的网格grid由标签页强加的帧推导而来浮动窗格反转了这一方向——用户先选帧网格跟随帧见第 5 节。焦点与命中测试Focus hit-testing激活机制假设任意坐标点上只有一个SessionView例如textViewDidBecomeFirstResponderPTYSession.m:13226焦点跟随鼠标逻辑 PTYSession.m:19946。重叠场景需要最顶层获胜topmost-wins的裁决。导航Navigation方向选择与交换PTYTab.m:1446-1600 区间基于平铺邻接与活动计数器平局裁决重叠没有可定义的邻居也没有 z 平局裁决。序列化Serialization布局保存Arrangement、可恢复状态restorable state、Python / gRPC API 编码的都是分割器或会话的严格二叉树没有第三种节点的位置见第 8 节。tmux布局语法无法表达浮动窗格在上游格式落地前tmux 标签页必须排除或禁止浮动窗格见附录。3. 决定性决策Metal 之上如何渲染浮动窗格设计文档反复强调在所有真正设计工作开始之前必须先回答一个问题——浮动窗格如何渲染在 Metal 支持的窗格之上3.1 为什么这个问题是分叉点今天两个活跃的 Metal 窗格永远不会重叠分割视图是平铺的而最大化功能刻意把非活跃窗格强制回退到传统渲染器PTYTab.m:7138 附近的逻辑。因此一个活跃 Metal 终端合成在另一个活跃 Metal 终端之上这一场景完全未被验证过。源码中那些吓人的注释PTYTab.m:7158、PTYSession.m:9092讨论的是父级位于 alpha 隐藏的PTYTextView内部的NSView而非 Metal 图层无法进行 z 合成。有利的证据是每一块窗格装饰chrome都已经能正确绘制在CAMetalLayer之上但这并不能证明不透明 Metal 互相重叠这一场景可行。部署下限是 macOS 12可以依赖现代 layer 行为。3.2 方案 A窗口内视图覆盖in-window view overlay一个浮动窗格是一个真实的SessionView从分割树中提升出来放入root_之上的一个浮动层。() 单一坐标空间复用SessionView已有的 z 序合成器addSubviewBelowFindView:SessionView.m 中多次使用如第 266、358、1140 行等。() 天然裁剪到标签页内容区域。(-) 必须直接面对 Metal-over-Metal 的问题。(-) 无法悬浮到标签页栏tab bar或工具带toolbelt之上——标签页内容在 z 序上位于它们之下。3.3 方案 B每个浮动窗格一个子 NSWindowchild NSWindow per float每个浮动窗格是一个无边框子窗口承载完整的SessionView并跟踪父窗口。() 每个浮动窗格拥有自己的不透明表面Metal、z 序、自由定位、阴影都直接可用。() 有先例热键窗口hotkey windowiTermProfileHotKey.m、会话预览session preview、mention picker。(-) 真实的窗口簿记工作父窗口移动、缩放、切换 Space 时需重定位全屏处理key-window 交接裁剪到标签页。3.4 建议路径先做一次性原型throwaway spike验证方案 A 的 Metal 问题把一个不透明的 MetalSessionView放到另一个之上确认能合成且保持活跃。如果结果干净方案 A 更自然且让一切保持在单一坐标空间如果不稳定回退到方案 B以窗口管理成本换取渲染问题的回避。在答案揭晓之前不要设计其余部分——它决定了容器模型、命中测试方式以及浮动窗格几何是标签页相对还是窗口相对。4. 数据模型floatingPanes 集合与枚举器分叉PTYTab需要新增一个floatingPanes集合其成员存在于root_之外。每个条目携带会话及其SessionView一个帧按第 3 节的结论标签页相对或窗口相对一个 z 索引。关键设计复用idMap_分叉模式。-sessions与-sessionViews已在最大化暂存区上分叉因此把浮动集合折叠进同样的访问器就能让大多数枚举器免费获得浮动窗格。从源码看idMap_是一个NSMutableDictionaryNSNumber *, SessionView *PTYTab.m:211在最大化时保存所有被暂存的视图枚举访问器在idMap_非空时直接返回其值。平铺遍历必须学会豁免浮动窗格checkInvariants:、cleanupAfterRemove:、resizeSubviewsOfSplitView:、_recursiveSize:、分割视图约束回调PTYTab.m:6204 与 6224 附近以及分割门控计数hasMultipleSessions、canSplitVertically:。降级的设计对冲早期想法是让浮动窗格承载整个布局子树不止一个窗格。但 tmux v2 格式只允许浮动标记出现在叶子窗格上绝不允许出现在容器上因此 tmux 浮动窗格永远是单个窗格。为了让原生模型与 tmux 对齐保持浮动窗格为单个SessionView浮动窗格内再分割可以作为后续 iTerm 独有的差异化功能添加不与 tmux 模型冲突。5. 尺寸反演从树定帧到帧定网格平铺窗格的几何流向是标签页 → 会话分割视图规定SessionView的帧PTYSession从帧推导行数与列数PTYSession.m:2619-2633 与setSize:PTYSession.m:2719。一个PTYSession只存储行数与列数从不拥有原点或帧。浮动窗格反转了这一切用户选定帧网格跟随帧所以浮动窗格拥有自己的几何。这正是布局保存 schema 需要新增每浮动窗格几何的原因——今天它只持久化COLUMNS和ROWSPTYSession.m:6932 附近的编码逻辑。6. 交互模型z 序、移动缩放、把手、创建转换层叠顺序是显式的浮动窗格携带 z 索引最前在前且浮动窗格永远位于平铺基底之上z 0最前 [ float: 编辑器 ] z 1 [ float: 日志 ] bottom [ 平铺基底分割树 ]四项交互能力全部有可复用部件移动与缩放复用极简输入器minimal composer的事件循环——trackEventsMatchingMask:拖拽移动加拖拽把手缩放配圆角装饰iTermMinimalComposerViewController.m。抓取把手SessionTitleView已经能把标题栏拖拽变成移动此窗格SessionTitleView.m只需从拖出到窗口扩展为标签页内拖拽。创建与转换复用MovePaneControllerMovePaneController.m它已经能重父级活跃会话并在跨窗口点亮放置目标新增一个在此浮动float here目标以及浮动⇄平铺的双向转换。边框与阴影复用iTermActivePaneBorderViewiTermActivePaneBorderView.swift逐角圆角边框与ContentNavigationShortcut.swift中的阴影模式。7. 焦点、命中测试与激活点击激活只要最前的浮动窗格是最顶层子视图默认的 AppKit 命中测试即可工作——SessionView没有重写hitTest:。焦点跟随鼠标FFM与鼠标下是哪个会话将从平面的划分变为依赖 z 序因此setActiveSession:与 FFM 路径必须尊重层叠顺序。方向导航需要明确策略要么把浮动窗格从方向导航中排除并给它们一个专门的循环要么扩展邻居引擎增加 z 平局裁决。设计文档的建议是v1 中把浮动窗格排除在方向平铺导航之外另设一个循环浮动窗格cycle floating panes动作。8. 序列化与自动化加法兄弟规则Additive-Sibling Rule布局保存、可恢复状态与 API 都编码分割器或会话的严格二叉树。Swift 重建器与内置的 Python 客户端都把非会话当作必为嵌套节点api/library/python/iterm2/iterm2/session.py 与 iTermSplitTreeRebuilder.swift。加法兄弟规则把浮动窗格作为与树并行的加法兄弟字段/键携带绝不作为树内部的新节点类型。新节点类型会被每个递归遍历器遗漏甚至更糟——被静默地误认为会话破坏旧版读取器与旧 Python 客户端。表面今天新增布局字典Arrangement dictPTYTab.m:78-103Root/Subviews/View Type树顶层Floating Panes键仿照已有Maximized键可恢复状态StateRestoration/复用布局编码器免费继承新键为浮动窗格分配稳定 ID避免增量编码器抖动API protoproto/api.protoSplitTreeNodeTab.rootTab上新增repeated FloatingPane与minimized_sessions并列绝不是新的oneof分支Python 客户端Splitter/SessionTab.floating_panes访问器保留旧from_node的 else 分支安全性通知重发ListSessionsResponse确保浮动窗格的创建、移动、缩放、关闭触发 iTermAPIHelper.m:680-721 的观察者从 proto/api.proto 可以看到现状SplitTreeNode第 1579-1589 行用oneof在SessionSummary与嵌套SplitTreeNode之间二选一而ListSessionsResponse.Tab第 1601-1620 行已有repeated SessionSummary minimized_sessions 6作为树外会话的平行先例——repeated FloatingPane正是沿着这条路线走。旧构建读取新布局时会忽略未知的顶层键因此浮动窗格优雅降级消失而非崩溃。任何 proto 变更后需重新生成Api.pbobjc.*与api_pb2.py。9. 横切边界情况最大化Maximize需要产品决策——浮动窗格保持置顶、隐藏还是在存在浮动窗格时禁用最大化。整窗背景图textViewRelativeFramePTYSession.m:12848假设每个窗格拥有互不重叠的独立切片重叠浮动窗格会采样重叠区域需要处理。标签页缩略图_recursiveDrawSplit:PTYTab.m:2749合成树也必须按 z 序绘制浮动窗格。广播输入按 GUID 迭代浮动窗格自动包含只有广播边框绘制假设了平铺视图。无障碍Accessibility基本免费——AppKit 从实时视图层级派生无障碍树可考虑设置accessibilityChildren顺序让 VoiceOver 对层叠窗格的遍历可预测。10. 可复用部件清单需求复用还缺什么活跃视图重父级、保存/恢复状态最大化暂存区PTYTab.m:5509 / 5596、idMap_视觉部分没有浮动或 z 序。复用状态而非根节点替换带装饰的移动/缩放循环极简输入器iTermMinimalComposerViewController.m承载的是文本控件而非活跃会话仅垂直拖拽拖出、放下以重父级活跃会话MovePaneController.m没有同标签页内浮动目标抓取把手SessionTitleView.m今天语义是提取到窗口需扩展为重新定位圆角边框与阴影iTermActivePaneBorderView、ContentNavigationShortcut.swift无直接可用悬浮到整个窗口之上热键窗口iTermProfileHotKey.m窗口簿记仅方案 BMetal 可见性握手iTermMetalDisabling、metalAllowed:PTYSession.m:9007无论方案 A 还是 B都必须扩展以支持重叠11. 影响面Blast Radius最高风险区域按风险从高到低区域锚点风险邻居与阅读顺序引擎PTYTab.m:1044-1600高定义标签页的会话的树遍历器PTYTab.m:1641 / 1665高平铺、缩放与不变量PTYTab.m:1981、2542、6413高Metal over Metal方案 APTYTab.m:7138、SessionView Metal 路径高序列化布局、proto、python第 8 节中拖放、分割选择MovePaneController.m、SessionView中尺寸反演PTYSession.m:2619-2633中背景图、缩略图、广播第 9 节低tmuxv1 排除sources/tmux/低无障碍视图层级派生低12. 分阶段实施计划设计文档要求小而可评审的提交每步带测试Spike一次性回答 Metal-over-Metal 问题决定方案 A 还是 B。这是所有后续工作的门禁。数据模型新增floatingPanes集合分叉枚举访问器让平铺与不变量遍历豁免浮动窗格。让一个静态浮动窗格上屏验证枚举、关闭与终止生命周期。交互拖拽移动、边缘缩放、升降 z 序、创建、浮动⇄平铺转换。复用 MovePaneController 与 SessionTitleView。尺寸与焦点浮动窗格拥有自己的帧网格由它推导修正重叠场景的命中测试与焦点跟随鼠标。持久化布局键与可恢复状态带往返测试旧构建优雅降级。自动化proto 字段、处理器、Python 客户端与通知。边界情况方向导航策略、最大化交互、背景图切片、标签页缩略图、广播边框。tmux 对接推迟到上游格式落地见附录。13. 待决产品决策详细设计前需要产品拍板的三个问题浮动窗格的边界裁剪到标签页内容还是可以自由悬浮到标签页栏、工具带与标题之上这直接驱动方案 A 与 B 的选择及容器模型。导航方向窗格导航与选择窗格 N是否包含浮动窗格还是浮动窗格只能通过专门循环触达最大化交互平铺窗格最大化时浮动窗格是保持置顶、隐藏还是在存在浮动窗格时禁用最大化附录tmux 集成已推迟上游契约仍在湿水泥状态。tmux 也在添加浮动窗格但 iTerm2 依赖的那一块——控制模式序列化——是最不稳定的部分设计文档声明已对照 tmux 仓库核实核心浮动窗格已随 3.7 发布最新 3.7c但功能极少仅支持鼠标移动与缩放。完整交互已合入 master目标 3.8未发布move-pane、resize-pane、split-in-float、break-pane 与 join-pane 用于转换、swap、模态窗格。v2 线格式不在 master 上它位于layout-custom-format分支且已重新设计为 JSON相对早期紧凑语法的变更由 opt-in 控制模式标志CLIENT_CONTROL_NEWLAYOUTS开启。客户端选择加入前tmux 发出旧格式并把浮动窗格渲染为普通平铺窗格因此旧版 iTerm2 不会崩溃。display-popup 将在 3.9 中变为浮动窗格分支no_more_overlays。观察项只有当 v2 格式合入 master 或随 3.8 发布时才重新审视 tmux 侧。届时应阅读layout-custom.c头部的权威格式文档并从发布源码中确认真实标志名而非轻信分支注释。一个 tmux 浮动窗格映射为一个单窗格的原生浮动窗格。延伸阅读本文的设计骨架取自 docs/floating-panes-design.md核心实现锚点位于 PTYTab.m枚举、不变量、缩放、最大化暂存、SessionView.mz 序合成、MovePaneController.m拖放重父级、iTermSplitTreeRebuilder.swift布局树重建与 proto/api.protoAPI 线格式。对既有平铺 最大化架构感兴趣的读者可直接在这些文件中追踪idMap_、checkInvariants:、_recursiveSize:等关键符号的完整生命周期。【免费下载链接】iTerm2iTerm2 is a terminal emulator for Mac OS X that does amazing things.项目地址: https://gitcode.com/gh_mirrors/it/iTerm2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 iTerm2 Floating Panes 设计剖析：打破严格平铺假设的架构路线图
iTerm2 Floating Panes 设计剖析打破严格平铺假设的架构路线图【免费下载链接】iTerm2iTerm2 is a terminal emulator for Mac OS X that does amazing things.项目地址: https://gitcode.com/gh_mirrors/it/iTerm2导读本文以 iTerm2 仓库中的设计文档 docs/floating-panes-design.md 为核心骨架系统解析浮动窗格Floating Pane这一功能的完整设计蓝图——从打破平铺树核心假设的动机、Metal 渲染决策分叉点到数据模型、尺寸反演、交互模型、序列化与自动化兼容策略再到分阶段实施计划与 tmux 上游集成的时间表。读完本文你将理解 iTerm2 标签页视图层PTYTab / SessionView / PTYSession / PseudoTerminal的既有约束、浮动窗格所需的底层改造点以及一份可复用的渐进式重构路线。0. 背景一次打破核心假设的架构挑战iTerm2 的每个标签页Tab中所有窗格pane都是一棵严格平铺的NSSplitView树的叶子节点。浮动窗格Floating Pane的目标是让一个终端会话悬浮在平铺布局之上自由定位、自由缩放、拥有 z 轴层叠顺序可以与邻居重叠甚至可以部分悬挂在标签页内容区域之外。设计文档明确指出这是在不重写视图层的前提下最大的结构性变更之一因为一个单一假设被写死在了数十处调用点中一个标签页的会话恰好是PTYTab.root_这棵分割树的所有叶子这些叶子平铺标签页没有重叠、没有缝隙、没有 z 轴顺序。这一假设同时被三个不变量固化在源码中详见 sources/TerminalView/PTYTab.m树范式Tree normal formcheckInvariants:PTYTab.m:2006要求非根分割节点至少有两个子节点、方向按深度交替、单一根子节点必须是SessionViewcleanupAfterRemove:PTYTab.m:2033还会主动重写树以维持该范式。精确划分Exact partitionresizeSubviewsOfSplitView:PTYTab.m:6542、_recursiveSize:PTYTab.m:2581等实现中帧是推导出来的而非任意的子视图无重叠地填满父视图。几何推导的顺序Geometry-derived orderingorderedSessionsPTYTab.m:1052以及邻居引擎PTYTab.m:1446-1600 区间假设矩形互不重叠并且完全没有层叠顺序z-order的概念。值得注意的是iTerm2 已经拥有大量可复用的部件能够在不杀死 PTY 的情况下重新父级化reparent活跃SessionView的机制、跨窗口重父级会话的拖放系统、带装饰的可移动可缩放覆盖层以及圆角边框视图。因此设计文档的结论是真正需要提前敲定的未知点只有一个——浮动窗格如何渲染在 Metal 支持的窗格之上这个答案将分叉整个架构见第 3 节其余大部分工作只是组装。1. 现状标签页视图树与三个被打破的不变量1.1 今天的视图树结构一个标签页的视图树形如NSTabViewItem.view └─ (可选) flexibleView_ ← 仅 tmux 会话使用 └─ root_PTYSplitView └─ 嵌套 NSSplitView └─ SessionView 叶子会话的枚举通过递归遍历这棵树完成_recursiveSessions:atNode:PTYTab.m:1649与_recursiveSessionViews:PTYTab.m:1673。分割视图拥有每个帧子视图以仅带分隔条间隙的方式划分父视图的矩形。设计文档用一张 ASCII 图直观对比了严格平铺与加入浮动窗格后的差异今天严格平铺 引入浮动窗格重叠 z 序 -------------------- -------------------- | A | B | | A | B | | | | | --------- | -------------------- -----| float |----- | C | | --------- | | | | C | -------------------- ---------------------1.2 三个不变量逐一失效树范式浮动窗格不在分割树内枚举、广播、全部关闭、布局保存arrangement和 API 都看不到它cleanupAfterRemove:的重写逻辑也不知道它的存在。精确划分浮动窗格的帧是用户直接指定的天然与子视图填满父视图且无重叠冲突。几何派生顺序阅读顺序与方向导航建立在互不重叠的矩形之上重叠区域没有明确的邻居定义也没有 z 轴平局裁决规则。2. 浮动窗格会打破什么六大受影响面设计文档逐一列出了浮动窗格对既有机制的破坏枚举Enumeration-sessions与-sessionViews只能看到树。好消息是这两个访问器已经针对最大化暂存区maximize stash即idMap_做了分叉PTYTab.m:1633-1646 与 1665-1671这正是引入第二个会话群体的天然挂载点。从源码可见当idMap_存在时-sessions直接返回idMap_的所有值否则才递归树。尺寸Sizing窗格的网格grid由标签页强加的帧推导而来浮动窗格反转了这一方向——用户先选帧网格跟随帧见第 5 节。焦点与命中测试Focus hit-testing激活机制假设任意坐标点上只有一个SessionView例如textViewDidBecomeFirstResponderPTYSession.m:13226焦点跟随鼠标逻辑 PTYSession.m:19946。重叠场景需要最顶层获胜topmost-wins的裁决。导航Navigation方向选择与交换PTYTab.m:1446-1600 区间基于平铺邻接与活动计数器平局裁决重叠没有可定义的邻居也没有 z 平局裁决。序列化Serialization布局保存Arrangement、可恢复状态restorable state、Python / gRPC API 编码的都是分割器或会话的严格二叉树没有第三种节点的位置见第 8 节。tmux布局语法无法表达浮动窗格在上游格式落地前tmux 标签页必须排除或禁止浮动窗格见附录。3. 决定性决策Metal 之上如何渲染浮动窗格设计文档反复强调在所有真正设计工作开始之前必须先回答一个问题——浮动窗格如何渲染在 Metal 支持的窗格之上3.1 为什么这个问题是分叉点今天两个活跃的 Metal 窗格永远不会重叠分割视图是平铺的而最大化功能刻意把非活跃窗格强制回退到传统渲染器PTYTab.m:7138 附近的逻辑。因此一个活跃 Metal 终端合成在另一个活跃 Metal 终端之上这一场景完全未被验证过。源码中那些吓人的注释PTYTab.m:7158、PTYSession.m:9092讨论的是父级位于 alpha 隐藏的PTYTextView内部的NSView而非 Metal 图层无法进行 z 合成。有利的证据是每一块窗格装饰chrome都已经能正确绘制在CAMetalLayer之上但这并不能证明不透明 Metal 互相重叠这一场景可行。部署下限是 macOS 12可以依赖现代 layer 行为。3.2 方案 A窗口内视图覆盖in-window view overlay一个浮动窗格是一个真实的SessionView从分割树中提升出来放入root_之上的一个浮动层。() 单一坐标空间复用SessionView已有的 z 序合成器addSubviewBelowFindView:SessionView.m 中多次使用如第 266、358、1140 行等。() 天然裁剪到标签页内容区域。(-) 必须直接面对 Metal-over-Metal 的问题。(-) 无法悬浮到标签页栏tab bar或工具带toolbelt之上——标签页内容在 z 序上位于它们之下。3.3 方案 B每个浮动窗格一个子 NSWindowchild NSWindow per float每个浮动窗格是一个无边框子窗口承载完整的SessionView并跟踪父窗口。() 每个浮动窗格拥有自己的不透明表面Metal、z 序、自由定位、阴影都直接可用。() 有先例热键窗口hotkey windowiTermProfileHotKey.m、会话预览session preview、mention picker。(-) 真实的窗口簿记工作父窗口移动、缩放、切换 Space 时需重定位全屏处理key-window 交接裁剪到标签页。3.4 建议路径先做一次性原型throwaway spike验证方案 A 的 Metal 问题把一个不透明的 MetalSessionView放到另一个之上确认能合成且保持活跃。如果结果干净方案 A 更自然且让一切保持在单一坐标空间如果不稳定回退到方案 B以窗口管理成本换取渲染问题的回避。在答案揭晓之前不要设计其余部分——它决定了容器模型、命中测试方式以及浮动窗格几何是标签页相对还是窗口相对。4. 数据模型floatingPanes 集合与枚举器分叉PTYTab需要新增一个floatingPanes集合其成员存在于root_之外。每个条目携带会话及其SessionView一个帧按第 3 节的结论标签页相对或窗口相对一个 z 索引。关键设计复用idMap_分叉模式。-sessions与-sessionViews已在最大化暂存区上分叉因此把浮动集合折叠进同样的访问器就能让大多数枚举器免费获得浮动窗格。从源码看idMap_是一个NSMutableDictionaryNSNumber *, SessionView *PTYTab.m:211在最大化时保存所有被暂存的视图枚举访问器在idMap_非空时直接返回其值。平铺遍历必须学会豁免浮动窗格checkInvariants:、cleanupAfterRemove:、resizeSubviewsOfSplitView:、_recursiveSize:、分割视图约束回调PTYTab.m:6204 与 6224 附近以及分割门控计数hasMultipleSessions、canSplitVertically:。降级的设计对冲早期想法是让浮动窗格承载整个布局子树不止一个窗格。但 tmux v2 格式只允许浮动标记出现在叶子窗格上绝不允许出现在容器上因此 tmux 浮动窗格永远是单个窗格。为了让原生模型与 tmux 对齐保持浮动窗格为单个SessionView浮动窗格内再分割可以作为后续 iTerm 独有的差异化功能添加不与 tmux 模型冲突。5. 尺寸反演从树定帧到帧定网格平铺窗格的几何流向是标签页 → 会话分割视图规定SessionView的帧PTYSession从帧推导行数与列数PTYSession.m:2619-2633 与setSize:PTYSession.m:2719。一个PTYSession只存储行数与列数从不拥有原点或帧。浮动窗格反转了这一切用户选定帧网格跟随帧所以浮动窗格拥有自己的几何。这正是布局保存 schema 需要新增每浮动窗格几何的原因——今天它只持久化COLUMNS和ROWSPTYSession.m:6932 附近的编码逻辑。6. 交互模型z 序、移动缩放、把手、创建转换层叠顺序是显式的浮动窗格携带 z 索引最前在前且浮动窗格永远位于平铺基底之上z 0最前 [ float: 编辑器 ] z 1 [ float: 日志 ] bottom [ 平铺基底分割树 ]四项交互能力全部有可复用部件移动与缩放复用极简输入器minimal composer的事件循环——trackEventsMatchingMask:拖拽移动加拖拽把手缩放配圆角装饰iTermMinimalComposerViewController.m。抓取把手SessionTitleView已经能把标题栏拖拽变成移动此窗格SessionTitleView.m只需从拖出到窗口扩展为标签页内拖拽。创建与转换复用MovePaneControllerMovePaneController.m它已经能重父级活跃会话并在跨窗口点亮放置目标新增一个在此浮动float here目标以及浮动⇄平铺的双向转换。边框与阴影复用iTermActivePaneBorderViewiTermActivePaneBorderView.swift逐角圆角边框与ContentNavigationShortcut.swift中的阴影模式。7. 焦点、命中测试与激活点击激活只要最前的浮动窗格是最顶层子视图默认的 AppKit 命中测试即可工作——SessionView没有重写hitTest:。焦点跟随鼠标FFM与鼠标下是哪个会话将从平面的划分变为依赖 z 序因此setActiveSession:与 FFM 路径必须尊重层叠顺序。方向导航需要明确策略要么把浮动窗格从方向导航中排除并给它们一个专门的循环要么扩展邻居引擎增加 z 平局裁决。设计文档的建议是v1 中把浮动窗格排除在方向平铺导航之外另设一个循环浮动窗格cycle floating panes动作。8. 序列化与自动化加法兄弟规则Additive-Sibling Rule布局保存、可恢复状态与 API 都编码分割器或会话的严格二叉树。Swift 重建器与内置的 Python 客户端都把非会话当作必为嵌套节点api/library/python/iterm2/iterm2/session.py 与 iTermSplitTreeRebuilder.swift。加法兄弟规则把浮动窗格作为与树并行的加法兄弟字段/键携带绝不作为树内部的新节点类型。新节点类型会被每个递归遍历器遗漏甚至更糟——被静默地误认为会话破坏旧版读取器与旧 Python 客户端。表面今天新增布局字典Arrangement dictPTYTab.m:78-103Root/Subviews/View Type树顶层Floating Panes键仿照已有Maximized键可恢复状态StateRestoration/复用布局编码器免费继承新键为浮动窗格分配稳定 ID避免增量编码器抖动API protoproto/api.protoSplitTreeNodeTab.rootTab上新增repeated FloatingPane与minimized_sessions并列绝不是新的oneof分支Python 客户端Splitter/SessionTab.floating_panes访问器保留旧from_node的 else 分支安全性通知重发ListSessionsResponse确保浮动窗格的创建、移动、缩放、关闭触发 iTermAPIHelper.m:680-721 的观察者从 proto/api.proto 可以看到现状SplitTreeNode第 1579-1589 行用oneof在SessionSummary与嵌套SplitTreeNode之间二选一而ListSessionsResponse.Tab第 1601-1620 行已有repeated SessionSummary minimized_sessions 6作为树外会话的平行先例——repeated FloatingPane正是沿着这条路线走。旧构建读取新布局时会忽略未知的顶层键因此浮动窗格优雅降级消失而非崩溃。任何 proto 变更后需重新生成Api.pbobjc.*与api_pb2.py。9. 横切边界情况最大化Maximize需要产品决策——浮动窗格保持置顶、隐藏还是在存在浮动窗格时禁用最大化。整窗背景图textViewRelativeFramePTYSession.m:12848假设每个窗格拥有互不重叠的独立切片重叠浮动窗格会采样重叠区域需要处理。标签页缩略图_recursiveDrawSplit:PTYTab.m:2749合成树也必须按 z 序绘制浮动窗格。广播输入按 GUID 迭代浮动窗格自动包含只有广播边框绘制假设了平铺视图。无障碍Accessibility基本免费——AppKit 从实时视图层级派生无障碍树可考虑设置accessibilityChildren顺序让 VoiceOver 对层叠窗格的遍历可预测。10. 可复用部件清单需求复用还缺什么活跃视图重父级、保存/恢复状态最大化暂存区PTYTab.m:5509 / 5596、idMap_视觉部分没有浮动或 z 序。复用状态而非根节点替换带装饰的移动/缩放循环极简输入器iTermMinimalComposerViewController.m承载的是文本控件而非活跃会话仅垂直拖拽拖出、放下以重父级活跃会话MovePaneController.m没有同标签页内浮动目标抓取把手SessionTitleView.m今天语义是提取到窗口需扩展为重新定位圆角边框与阴影iTermActivePaneBorderView、ContentNavigationShortcut.swift无直接可用悬浮到整个窗口之上热键窗口iTermProfileHotKey.m窗口簿记仅方案 BMetal 可见性握手iTermMetalDisabling、metalAllowed:PTYSession.m:9007无论方案 A 还是 B都必须扩展以支持重叠11. 影响面Blast Radius最高风险区域按风险从高到低区域锚点风险邻居与阅读顺序引擎PTYTab.m:1044-1600高定义标签页的会话的树遍历器PTYTab.m:1641 / 1665高平铺、缩放与不变量PTYTab.m:1981、2542、6413高Metal over Metal方案 APTYTab.m:7138、SessionView Metal 路径高序列化布局、proto、python第 8 节中拖放、分割选择MovePaneController.m、SessionView中尺寸反演PTYSession.m:2619-2633中背景图、缩略图、广播第 9 节低tmuxv1 排除sources/tmux/低无障碍视图层级派生低12. 分阶段实施计划设计文档要求小而可评审的提交每步带测试Spike一次性回答 Metal-over-Metal 问题决定方案 A 还是 B。这是所有后续工作的门禁。数据模型新增floatingPanes集合分叉枚举访问器让平铺与不变量遍历豁免浮动窗格。让一个静态浮动窗格上屏验证枚举、关闭与终止生命周期。交互拖拽移动、边缘缩放、升降 z 序、创建、浮动⇄平铺转换。复用 MovePaneController 与 SessionTitleView。尺寸与焦点浮动窗格拥有自己的帧网格由它推导修正重叠场景的命中测试与焦点跟随鼠标。持久化布局键与可恢复状态带往返测试旧构建优雅降级。自动化proto 字段、处理器、Python 客户端与通知。边界情况方向导航策略、最大化交互、背景图切片、标签页缩略图、广播边框。tmux 对接推迟到上游格式落地见附录。13. 待决产品决策详细设计前需要产品拍板的三个问题浮动窗格的边界裁剪到标签页内容还是可以自由悬浮到标签页栏、工具带与标题之上这直接驱动方案 A 与 B 的选择及容器模型。导航方向窗格导航与选择窗格 N是否包含浮动窗格还是浮动窗格只能通过专门循环触达最大化交互平铺窗格最大化时浮动窗格是保持置顶、隐藏还是在存在浮动窗格时禁用最大化附录tmux 集成已推迟上游契约仍在湿水泥状态。tmux 也在添加浮动窗格但 iTerm2 依赖的那一块——控制模式序列化——是最不稳定的部分设计文档声明已对照 tmux 仓库核实核心浮动窗格已随 3.7 发布最新 3.7c但功能极少仅支持鼠标移动与缩放。完整交互已合入 master目标 3.8未发布move-pane、resize-pane、split-in-float、break-pane 与 join-pane 用于转换、swap、模态窗格。v2 线格式不在 master 上它位于layout-custom-format分支且已重新设计为 JSON相对早期紧凑语法的变更由 opt-in 控制模式标志CLIENT_CONTROL_NEWLAYOUTS开启。客户端选择加入前tmux 发出旧格式并把浮动窗格渲染为普通平铺窗格因此旧版 iTerm2 不会崩溃。display-popup 将在 3.9 中变为浮动窗格分支no_more_overlays。观察项只有当 v2 格式合入 master 或随 3.8 发布时才重新审视 tmux 侧。届时应阅读layout-custom.c头部的权威格式文档并从发布源码中确认真实标志名而非轻信分支注释。一个 tmux 浮动窗格映射为一个单窗格的原生浮动窗格。延伸阅读本文的设计骨架取自 docs/floating-panes-design.md核心实现锚点位于 PTYTab.m枚举、不变量、缩放、最大化暂存、SessionView.mz 序合成、MovePaneController.m拖放重父级、iTermSplitTreeRebuilder.swift布局树重建与 proto/api.protoAPI 线格式。对既有平铺 最大化架构感兴趣的读者可直接在这些文件中追踪idMap_、checkInvariants:、_recursiveSize:等关键符号的完整生命周期。【免费下载链接】iTerm2iTerm2 is a terminal emulator for Mac OS X that does amazing things.项目地址: https://gitcode.com/gh_mirrors/it/iTerm2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考