window-browser.md

窗口浏览（Dock 悬停与键盘面板）

窗口浏览是 WindowShade 的附加入口，不替换系统 Dock。原生 Command-Tab 默认不接管；按窗口切换默认用 ⌥Tab， 设置里可以换成 ⌘Tab（见下文“按窗口切换”）。

入口

• 菜单栏 WindowShade 菜单 → 选择窗口…：打开可搜索、可用方向键选择的窗口面板。
• 设置 → 窗口浏览 → Dock 悬停查看窗口：开启后，鼠标停在已运行应用的 Dock 图标上会显示该应用的窗口面板。
• 设置 → 窗口浏览 → 独立快捷键：录制一个组合键后，按下打开面板、再次按下 关闭。默认不注册任何快捷键，避免抢占已有组合。

面板内：方向键按真实列数移动选中，Return 激活/展开，Escape 取消，Home/End 跳到 首尾。搜索框在键盘面板顶部，只匹配本机已发现的应用名与窗口标题，本地完成，不读 文档正文、不联网。卡片主体采用“按下—拖出取消—松开提交”：点击激活或展开窗口； 紧凑操作条（悬停或键盘选中时出现，空间始终预留）提供折叠/展开、置顶预览和新建窗口（悬停提示写着 Mac 上按 ⌘N）； 关闭窗口、最小化、进入全屏、新建窗口、让开这个 App、退出 App 与排布放在右键 菜单里，避免误触（进入全屏要有辅助功能权限；新建、让开和退出作用于窗口所属的那个 App， 退出会走系统自己的流程，有没保存的内容由那个 App 弹框问你）。

新建窗口（对 DockMate 的 “open a new window”；卡片的操作条上常驻一个按钮，悬停提示“新建窗口 ⌘N”，右键菜单里也有）：先在后台读那个 App 的菜单，按标题挑一项 （WindowBrowserNewWindowCommand）：

• 标题说的就是新开一扇窗的项：“新建窗口”“新建访达窗口”“打开新的窗口”“新建查看器窗口”“New Window”， 以及“新建窗口 ▸”子菜单里带 ⌘N 的那一项（终端的描述文件、带个人资料的 Safari）。几项都有时，快捷键是 只带 ⌘ 的 N 的优先，其次别的 N（VS Code 的 ⇧⌘N、邮件的 ⌥⌘N），再次别的快捷键；同级先看“文件”菜单。 无痕 / 隐私窗口、“把标签页移到新窗口”、“重新打开关掉的窗口”一律不算。
• 没有这种项时，文稿类 App 标题就是“新建 / New”的 ⌘N 也算（文本编辑、Pages：新建一份文稿就是新开一扇窗）。
• 只看快捷键不看标题的 ⌘N 不按：日历、提醒事项、备忘录、通讯录的 ⌘N 会新建日程、提醒、备忘录、名片， Xcode 的 ⌘N 会弹出新建文件的表单。这时说“这个 App 的菜单里没有新建窗口”。
• 菜单读不到（App 没响应、没有菜单栏）也不发 ⌘N：不知道它会做什么。这时说“没能让它新建窗口”。

挑到了才把那个 App 带到前面再按；没东西可按时什么都不动，被让开或隐藏的 App 不会被翻出来。 2.5 秒内多出一扇普通窗口才算完成，新窗口马上出现在列表里；没看到就提示“没看到新窗口出来”。 读屏播报只说“新建窗口完成”，不念被点那扇旧窗口的标题。

用关窗关掉一扇、或者它在别处被关掉时，它的卡片缩小淡出（约 0.16 秒），其余卡片同一段时间里补位， Dock 面板的尺寸也跟着走同一段动画。开启“减少动态效果”时不缩放、不滑动，整块列表 0.12 秒交叉淡化。 只有“确认窗口已经没了”的移出才这样做；搜索过滤、换 App、换显示方式照旧立即更新。关窗动作完成后 马上重新查一次那个 App，不等下一轮检查（面板开着时每 0.6 秒看一眼列表里的窗口还在不在）。

把卡片拖出面板去排布

iPad 从 Dock 把 App 拖到屏幕边就分屏；这里是把一张窗口卡片拖出面板：

• 贴着屏幕左边或右边（40 pt 以内）松手：左半屏 / 右半屏；贴着顶边（含菜单栏）松手：铺满屏幕。 落点只在贴边的地方，不再是整块的左右四分之一。 拖动中目标位置画一圈虚线轮廓（和排布预览同一种样子），松手后窗口排过去并带到前面，照样可以撤销。
• 拖到屏幕左右边上那一小块停一下：侧拉（和拖标题栏进侧拉是同一块、同一种提示，要停够才算）。
• 拖回面板、离面板不到 80 pt、停在屏幕中间或 Dock 上松手、或者按 Esc：什么都不做。面板贴着 Dock， Dock 在侧边、或停在靠边的图标上时，面板本身就挨着屏幕边；有这一圈，按原来“拖出取消”的习惯 把卡片拖出面板一点松手，窗口照样不动。
• 在面板里面拖动仍是原来的“拖出取消”：要拖出面板才开始。收起的窗口先展开，最小化的先还原； 拖动期间 Dock 面板不会收起，也不跟着换 App。只在有辅助功能权限时接手。
• 目前只有网格里的卡片能拖，列表行不能。

小程序窗口归到它的 App

有些 App 把一部分窗口交给自己包里的辅助进程画：微信的小程序窗口属于 WeChatAppEx （com.tencent.flue.WeChatAppEx，装在 WeChat.app/Contents/MacOS/ 里，LSUIElement，没有 Dock 图标）， QQ 的小程序、文档也一样（QQEXMiniProgram.app、QQEXDOC.app）。停在微信的 Dock 图标上时，这些窗口一起列出来， 显示成微信的；键盘面板里也列在微信名下。规则（WindowBrowserHelperApps）：

• 辅助进程没有自己的 Dock 图标（有图标的，窗口归它自己的图标）；
• 它的 .app 就装在那个 App 的 .app/Contents/ 里面（在同一个签名封装里，所以不另读签名的团队号）；
• 两者的 bundle ID 前两段相同（com.tencent）。带团队前缀的（如 QQ 截图插件 FN2V63AD2J.com.tencent…）不算。
• 这些窗口没有“让开这个 App / 退出 App”：那只会让开或退出看不见的辅助进程，不是你以为的那个 App。 “新建窗口”算在所属 App 上。所属 App 被排除时它们一起排除。

谁是谁只在打开面板（换 Dock 图标、打开键盘面板）时按正在运行的进程重算一次，不常驻监听； 每个进程的 .app 路径按 pid 记住，只解析新出现的进程。Chrome、Electron 的 Helper 同样装在 App 包里、 没有 Dock 图标，也会被归进来，但它们没有自己的窗口：没有普通层（layer 0）窗口的辅助进程不去问辅助功能接口。 辅助进程的查询都走后台队列，不和 Dock 图标那个 App 抢那条只跑一个任务的交互队列。 小程序如果在 Dock 里有自己的图标（网上的说法是可以“保留在 Dock 中”），停在那个图标上看到的是它自己的窗口； 那种图标背后是哪个进程还没在真机上核对过。

在 Dock 图标上右键、按住 Control 点或按住不放时，Dock 会弹出它自己的菜单：窗口浏览马上让开， 直到指针离开这个图标，不会挡住那个菜单。

调度中心里按 ⌘W / ⌘Q

调度中心（两下刘海，或系统自己的手势）打开时，系统没有把 ⌘W 交给谁——它会落到最前面那个 App 身上，于是你以为在关指针指着的那扇窗，实际关掉的是别的一扇。这里补上：调度中心开着时， ⌘W 关掉指针指着的那一扇，⌘Q 退出它的 App。

• 只在确认调度中心开着时才动手。判断依据是 WindowManager 铺的那层全屏遮罩（ExposeShieldWindow）， 不是"当前哪个 App 在最前"。
• 只挑普通层的窗口：Dock、调度中心自己、通知中心、菜单栏和我们自己的窗口都不算。指针底下没有 可操作的窗口时，这一下按键照样吃掉——放行的话它会落到最前面那个 App 身上，关掉一扇你没在看的窗。
• 只认 ⌘W / ⌘Q；带了 ⇧⌥⌃ 就不管。窗口号对不上（少数 App 不报窗口号）也不动手——宁可不做， 也不能关错一扇。
• 不在调度中心时完全不碰：这一个钩子只在"确实是调度中心"时才拦键，其它时候一律原样放行。
• 设置 → 窗口浏览 → 调度中心里按 ⌘W 关窗 可以关掉；关掉后不安装键盘钩子。

按窗口切换（对 Wins 的 Cmd-Tab Plus）

按住 ⌥ 连按 Tab（设置 → 窗口浏览 → 切换，可换成 ⌘Tab 或关掉）：

• 快速按一下就松手，直接切到上一扇窗，面板都不出来；按住 0.15 秒以上才出面板。
• 顺序是最近用过的：屏幕上的窗口按前后次序；卷帘条和刘海里收着的窗口排在后面，标着“收着”，挑它就放回来。
• 每张卡片有窗口画面、App 图标、标题，前九张左上角有数字；连按 Tab 往后、加 ⇧ 往回，←→ 也行，按数字直接切到那一扇。
• 用 ⌥ 时按 W 关掉选中的窗口、按 Q 退出它的 App（用 ⌘ 时是 ⌘W、⌘Q）；面板留着，接着挑。Esc 取消，鼠标点一张也行。
• 键盘钩子跑在自己的线程上，只认 Tab 和面板开着时的那几个键，别的按键原样放过。

再点一下 Dock 图标，让开这个 App

点 Dock 上最前面那个 App 的图标，而且它在这张桌面上有窗口露着：它让开（和 ⌘H 一样隐藏），再点一下系统照常显示回来。 这是 Windows 任务栏的老习惯（Wins 叫 Dock 窗口反转）。只在这一下本来什么都不做时才接：从 Dock 切到别的 App、点没有露着 窗口的 App、拖动图标都照系统原来的样子；只旁听，不拦截点击。设置 → 窗口浏览里能关。

排布与撤销

窗口卡片右键 → 排布 提供：左半屏、右半屏、四角、居中、填满可用区域、移到另一 块屏幕，以及 预览（只画目标轮廓）与 撤销上次排布。

• 执行前重新核对完整窗口身份、读取原 frame；写入后读回验证（容差 2 pt），验证 通过才登记撤销。
• 填满可用区域使用工作区域（不含菜单栏/Dock），与系统全屏不同，不搬运 Space。
• 已收起的窗口先走既有展开与恢复验证；展开未确认就停止，不继续排布。
• 撤销前确认窗口仍在排布完成时的位置；用户已经手动移动时拒绝回放并说明原因。

权限

• 辅助功能：识别 Dock 图标、激活/折叠/恢复/关闭/最小化窗口。缺少时两个入口都 不会执行写操作，面板会说明原因并提供系统设置入口。
• 屏幕录制：窗口缩略图与实时预览。缺少时仍然显示应用图标、标题和状态列表， 窗口操作照常可用。

悬停路径只查询当前授权状态，不会弹出授权对话框。

快捷键无法自动识别系统与其他应用的全部冲突；为此组合必须包含 Control 或 Option （例如 ⌃⌥W），这样不会抢占 ⌘C/⌘V/⌘A 这类全系统快捷键；单字母无修饰键、 仅 Shift 与纯 ⌘ 组合都会被拒绝。显示名按当前输入源的实际键盘布局生成， 切换输入源后请重新查看。

行为与限制

• 外观：设置 → 窗口浏览 → 面板背景 可选“跟随系统外观”或“不透明背景”。跟随系统时， macOS 26 及以上使用公开的 AppKit 玻璃控制层，旧系统使用系统原生材质，开启 “减少透明度”时改用不透明背景；开启“减少动态效果”时不位移、不缩放。

• 只是悬停、搜索或选中列表项不会展开窗口、激活应用或改变桌面布局；只有明确的 点击、Return 或菜单动作才会执行。

• 折叠使用原有折叠事务：兼容策略、恢复记录、隐藏验证、代理标题栏与失败回滚都 保留。面板关闭不会中断已经开始的恢复或折叠事务。

• 已收起的窗口的“展开并置顶预览”会先展开并等待真实验证，再启动置顶预览；展开 成功而捕获失败时窗口保持展开，并说明置顶预览失败。

• 暂停中的置顶会话不会因为悬停被恢复，也不会为它偷偷建立第二路视频流。

• 折叠与最小化窗口不会为了刷新缩略图被唤醒：优先显示已保存的最后画面并标为快照， 没有快照时显示应用图标与说明。

• 普通窗口实时预览默认关闭，选中约 0.4 秒后才建立一路低帧率（初始 8fps、 最大 640×400）预览；选择、目标切换、锁屏与权限变化时会停止它。

• 不跨 Space 搬运窗口，不启动未运行的应用，不处理文件夹、废纸篓、最近文档与 分隔符等 Dock 项目。原生标签页不会被当成独立窗口。

• 窗口身份以应用自己报告的辅助功能窗口列表为准。WindowServer 的 layer-0 窗口数 通常更多（实测 Safari 18 个、Drafts 9 个），但其中“有尺寸且有标题、像真实窗口” 的只有 3 个和 1 个，与应用报告的 4 个（含 1 个最小化窗口）和 1 个吻合—— 多出来的是辅助窗口、帮助窗口等无法可靠映射回原窗口的项。这类项目不会作为 “已验证窗口”出现，因此不会获得窗口级写操作。反过来，某些最小化、隐藏或不在 当前 Space 的窗口可能只在其中一个来源可见，暂时枚举不到不会删除已管理窗口的记录。

• 按应用排除清单只影响窗口浏览入口；被排除应用的折叠窗口仍可从原有菜单与 救援功能恢复。

• 新面板不添加淡入、缩放或位置动画，因此“减少动态效果”设置下没有额外动效需要 关闭；窗口缩略图只保存在内存，不写盘、不上传，也不记录窗口完整标题。 （面板出现使用约 160 ms 的淡入；开启减少动态效果时该时长归零。）

• 详细的行为/样式/材质回退说明见 窗口浏览改版说明， 性能数据见 性能报告，截图与实机验收步骤见 视觉验收，任务书 T01–T60 覆盖见 自动化覆盖对照。

未覆盖

• 原生 Command-Tab 改造、系统 Dock 替换、Dock 单击/滚轮拦截（标题栏上的两指手势后来单独做了，见 标题栏手势）、 窗口跨 Space 搬运、浏览器标签管理、插件市场与主题系统。
• 工作区分组、跨重启布局恢复、外接显示器插入后的“恢复原排布/保留当前”选择都不在 本轮范围；本轮只有可预览、可撤销的单次排布动作。
• 本轮没有把「最近使用顺序」当作窗口顺序：没有窗口级激活信息时不虚构使用历史。
• Dock 内部 AX 结构不是稳定公开协议。若当前系统上通知不可用，会退化为仅在 Dock 附近触发的节流鼠标命中检测；观察器失效时只停用 Dock 入口，菜单与快捷键 入口仍然可用。