NotchRail v1.0.1: Swift 6.4 工具链与并发隔离升级

🚀 NotchRail v1.0.1

✨ 维护与升级内容

1. Swift 6.4 现代工具链对齐：
   • Package 清单升级至 // swift-tools-version: 6.4；
   • 对齐 Swift 6 Complete Concurrency 严格并发隔离契约。
2. 并发与底层系统桥接加固：
   • 适配系统 C 全局变量 kAXTrustedCheckOptionPrompt 跨线程访问；
   • 规范 PermissionManager 异步轮询闭包为 @MainActor @Sendable 区域隔离。
3. CI 与项目整洁度：
   • 升级 GitHub Actions actions/checkout@v6 最新稳定版；
   • 清理历史废弃草稿与本地临时缓存。

---

📦 安装与分发

• DMG 镜像: NotchRail-v1.0.1.dmg
• 压缩包: NotchRail-v1.0.1.zip

NotchRail v1.0.0: 全局快捷键呼出、现代设置中心与多屏焦点移交闭环

🚀 NotchRail v1.0.0

✨ 核心特性与升级

1. 全局快捷键呼出与收起 (Global HotKey)：

   • 默认支持 ⌥ ~\ (Option + Tilde) 快速一键呼出/收起灵动岛；
   • 快捷键录制组件（HotKeyRecorderView），支持自定义快捷键录制、按键排他与冲突检测；
   • 严格遵循 ADR 0017 单前台活动屏独占公理，在当前前台活动屏幕上就近触发，无溢出项时展开呈现空状态提示并提供触觉微动反馈。

2. macOS 原生 HIG 现代设置中心：

   • 全链路设置项前后依赖自洽（“仅主屏”模式禁用跨屏同步选项并附说明；“仅点击”模式禁用悬停延迟滑块）；
   • 应用管理 Tab 双分区实时看板（“灵动岛展示项 (已溢出)” vs “原生菜单栏可见项”）；
   • 纯只读观察者架构，彻底杜绝设置中心与后台截图管线的冲突与锁死。

3. 多屏活动焦点移交 (Focus Handoff) 与按需视口装载闭环：

   • 设置面板支持跨屏随意拖拽与点击，灵动岛与前台活动屏无感实时跟随；
   • 视口按需装载（ensurePanel），彻底根除外接平直屏因常态折叠隐形导致的切屏死锁；
   • 快照防退化覆盖保护与切屏就绪缓冲，根治切屏时图标占位化与应用信息瞬态丢失。

---

📦 安装与分发

• DMG 镜像: NotchRail-v1.0.0.dmg
• 压缩包: NotchRail-v1.0.0.zip

NotchRail v0.0.12

💡 核心更新亮点

1. 多屏非活动待命界面静默收拢（彻底消除空白灵动岛）

• 内建刘海屏待命态：当焦点处于外接屏时，内置刘海屏左耳翼平滑收拢至 0 宽，黄色徽标与加载环自动隐藏，纯黑底座贴合物理刘海硬件边缘（防白边），并严格锁定切断悬停展开；仅当用户切换前台至该屏时平滑恢复耳翼与交互响应。
• 外接平直显示器：严格恪守“折叠常态 100% 隐形穿透、绝对无紧凑态”的架构不变量（紧凑宽设为 0.0，彻底消除假胶囊）；待命态切断顶部热区悬停展开，杜绝向用户暴露未光栅化的空白岛。

2. 设置中心应用管理单前台自适应跟随

• 废除手动分段选择器：彻底移除应用管理 Tab 的多屏手动 Segmented Picker，自适应绑定用户当前正在工作的前台活动屏幕（ScreenManager.shared.currentGeometry）。
• 实时活动状态指示：顶部常驻展示“🟢 当前前台活动屏幕：[名称]”与光栅化激活状态指示条，用户在任一显示器点击切换窗口，设置面板毫秒级自适应流转刷新。

3. 设置项交互逻辑与前后依赖对齐

• 选项依赖禁用：当打开方式为“仅鼠标点击”（.click）时，移入展开防抖延迟滑块自动置灰禁用并附带明确说明。
• 设置打开活动权确立：点击灵动岛展开态齿轮按钮打开偏好设置前，自动执行 FocusHandoff 确立目标屏活动菜单栏。

4. 架构契约加固与 12 处审查质量修复

• 存储 Fail-Fast：彻底移除 PRIMARY_DISPLAY_KEY 和 BUILTIN_DISPLAY_KEY 虚假分区常量及多层级联兜底，未命中直接返回空数组；旧版单数组配置向后兼容平滑迁移至共享分区。
• 状态机单入口收敛：外接平直屏点击移除外部私自判断与 triggerExpand，统一收敛委托至状态机唯一入口 handleCapsuleTap（ADR 0016）。
• 交互与生命周期闭环：胶囊点击增加 respondsToCapsuleTap 门禁（防仅悬停模式误触抢焦）；外部点击收起移除冗余焦点还原；修复 macOS 14+ 焦点还原 API 废弃警告。

---

📦 制品下载

• DMG 安装镜像：NotchRail-v0.0.12.dmg（拖拽即可安装）
• 独立应用压缩包：NotchRail-v0.0.12.zip
• 代码签名状态：已使用永久开发证书签名，TCC 辅助功能与屏幕录制权限永久生效。

NotchRail v0.0.11

⚠️ 版本说明：本版本为开发版 (Development Build)，闭环于 GitHub Issue #56。核心是落实「macOS 状态栏单前台活动屏独占公理（ADR 0017）」、零降级按屏图元取图隔离、排序偏好独立存储与 Focus Handoff 活动权移交。

✨ v0.0.11 核心更新与修复

1. 🏛️ 落实单前台活动屏独占公理与 Focus Handoff（ADR 0017）

   • 证伪“非活动屏无需移交焦点即可独立自采自派”的不实假设；确立 macOS 状态栏系统服务单前台独占不变量；
   • 建立交互驱动的焦点移交机制（FocusHandoff）：悬停展开严格保持纯视觉原位展开（恪守零抢焦，绝不打扰前台打字），用户在胶囊或图标上发生物理点击时无感移交活动菜单栏，交互收起后自动平滑还原此前的前台应用。

2. 🖼️ 零降级原生位图截取与按屏图元隔离（ADR 0013）

   • 彻底拆除 appAssetVault 与跨屏持久缓存，图元键强绑定 displayID（复合键 disp_{displayID}_win_{windowID}），杜绝跨屏借用图元；
   • 修复窗口服务器重构时的图元失配，AXExtrasMenuBar 条目池严格绑定活动屏，非活动屏采用 kCGWindowName 镜像判据。

3. 🗂️ 偏好排序按屏独立分区存储与跨屏同步（ADR 0014）

   • UserPreferences 新增 customItemOrdersByDisplay: [String: [String]] 与 syncItemOrderAcrossDisplays: Bool = false；
   • 排序偏好默认按屏完全独立，并提供向后兼容迁移；设置中心提供“跨显示器同步排序”可选开关。

4. ⚙️ 设置中心多屏状态指示与独立排序管理联动

   • 设置面板应用管理添加「● 活动中 / ○ 待命」视觉指示；搜索、列表装配、重置默认按钮与拖拽重排与所选屏幕作用域强绑定；
   • 手动重新扫描前通过 Focus Handoff 确保目标屏幕就位。

5. 🧼 代码清理与工程卫生

   • 彻底切除调试文件后门、调试日志与模拟点击探针，保持生产路径纯粹零侵入；
   • 文档体系全面收敛，check_docs.sh 6/6 项校验 100% 通过；真实硬件诊断（Spike）24 个用例全绿通过。

📦 资产下载

• DMG 镜像安装包: NotchRail-v0.0.11.dmg
• ZIP 绿色压缩包: NotchRail-v0.0.11.zip

NotchRail v0.0.10

⚠️ 版本说明：本版本为开发版 (Development Build)，闭源于 GitHub Issue #55。核心是多屏视口注册表化、设置项与实现对齐、状态项身份与点击派发修复、设置窗口启动路径根治与文档唯一归属闸门。

✨ v0.0.10 核心更新与修复

1. 🖥️ 多屏视口注册表化（屏幕数不设上限）

   • 废除 primaryPanel / externalPanel 双槽位模型与 externalOwnedDisplayID；视口与交互状态机一律按 displayID 注册，第三块屏起不再静默失效（ADR 0009）。

2. ⚙️ 设置项与实现对齐

   • 删除名不副实的选项：多显示器策略第三档（与保留档行为完全等价）与「点击图标后自动收起」开关（代码本就恒定收起）；固化「无遮挡时不渲染」语义（ADR 0015）。
   • 胶囊点击恒为展开/收起切换：三档唤出方式语义收敛为唯一定义，修复「点开之后收不起来」（ADR 0016）。

3. 🖱️ 状态项身份解析与点击派发修复

   • 派发目标恒取状态项窗口 owner，与事件携带的「鼠标下窗口」字段同进程，修复第三方项点击被静默丢弃（ADR 0010）。
   • 空间配对基准由窗口左边缘改为水平中心（实测存在 1pt 系统偏移，个别项达 7pt）。
   • 辅助点击改走会话事件流 + 目标窗口字段路由：右键可精确送达被刘海挤占、未被合成的项（ADR 0011）。
   • 响应判定不再排除本进程：修复「自家溢出图标菜单已弹出却被判无响应、岛屿抖动且不收起」（ADR 0012）。

4. 🚀 设置窗口启动路径根治

   • 放弃 SwiftUI App 自动建窗，改由 AppKit 手动启动，从根源消除「声明即建窗」的启动空白面板；设置面板改为侧边栏版式。

5. 📚 文档唯一归属与一致性闸门

   • 建立「每类事实恰好一处权威定义」的归属矩阵，其余文档只准引用、不得复制；一切数值常量以代码具名常量为唯一出处。
   • 落地 scripts/check_docs.sh 六类一致性闸门（已删符号残留、旧双槽位模型回退、受管数值内联、禁用别名外泄、ADR 编号连续性、版本号口径一致）。

6. 🧹 工程卫生

   • 修复设置面板「应用管理」列表图标不随图标解析完成刷新；PreferenceKey 可变静态存储属性改为计算属性。

⏳ 已知未交付（移交 v0.0.11，issue #56）

ADR 0013「按屏独立取图（废除跨屏图元共享层）」与 ADR 0014「排序偏好默认按屏独立」两项决议已立、实现待办，受两条前置卡点阻塞：非活动屏原位派发的可达性未取证（须走应用内诊断运行器），屏幕稳定标识待定案（displayID 在插拔后不稳定）。

规则与代码的过渡态已在 AGENTS.md §2.0 显式标注，两份 ADR 状态横幅与 docs/DOMAIN_MODEL.md §6 同步标记 —— 读到与文档不符的代码时，以文档为准则、以代码为现状。

📦 资产下载

• DMG 镜像安装包: NotchRail-v0.0.10.dmg
• ZIP 绿色压缩包: NotchRail-v0.0.10.zip

NotchRail v0.0.9 (开发版): 双屏独立面板架构、全局图元注册表与流体拖拽排序

⚠️ 版本说明：本版本为开发版 (Development Build)，闭源于 GitHub Issues #50 + #51~#54。核心是将单例聚焦跟随架构升级为双屏物理独立的多实例面板拓扑，并建立全局应用图元注册表以根治非激活屏图标空白，同时完成事件驱动扫描管线与灵动岛内流体拖拽排序。

✨ v0.0.9 核心更新与修复

1. 🖥️ 双屏多实例独立面板架构与物理隔离状态机 (Ticket #53)：

   • 主屏常驻 primaryPanel，外接屏按需装载独立 externalPanel，各自搭载物理隔离的 IslandStateMachine，心跳由 MenuBarSyncCoordinator 集中聚合；
   • IslandWindowCoordinator 收口 isPrimaryDisplay / externalOwnedDisplayID 单一事实来源，第三块及以上屏幕无归属面板时 Fail-Fast 返回 nil，彻底杜绝跨屏抢夺、徽标闪烁与窗口误锚定。

2. 🗄️ 全局应用图元注册表 (Application Asset Vault)，根治非激活屏图标空白：

   • WindowServer 在非聚焦屏为节能会暂停菜单项光栅化（截图返回全透明）。IconResolver 维护以 bundleIdentifier 为索引的全局注册表，任一激活屏成功截取真实位图即登记入库；
   • 非激活屏展开灵动岛时凭本轨确凿 Bundle ID 直出真实超清位图，0 延迟、0 兜底、0 错配；
   • resolveCachedIcon(for:) 收口「本屏内存 → 全局注册表 → 跨窗持久缓存」三层合法图元查找唯一入口，消除多处 ?? 级联的语义漂移。

3. ⚡ 事件驱动极速扫描管线，根治发热卡顿 (Ticket #51 / #52)：

   • 以进程生命周期与窗口层级事件驱动替代后台高频心跳轮询，消除高频事件下的堆分配抖动；
   • MenuBarAXResolver 空间映射缓存 TTL 收敛为具名常量 MAPPING_CACHE_TTL = 60.0，由进程事件定向失效；
   • 批量窗口提取与增量扫描，日常刷新耗时稳定控制在毫秒级。

4. 🖱️ 灵动岛内流体拖拽重排图标 (Ticket #54)：

   • 支持在灵动岛内直接拖拽重排溢出的状态项顺序，并持久化至 customItemOrder；
   • 剔除误触发的非预期右键操作，拖拽判定与点击分发严格互斥。

5. 🎯 外接屏顶边缘热区契约对齐：

   • isPointInExternalCenterHotZone 的垂直阈值由「可选值 + 状态栏高度兜底」改为显式契约默认值 4.0pt，杜绝「单测验默认分支、生产传另一阈值」的语义脱漂，防误触时序精确可控。

6. 🧹 架构清理：

   • 按指令从项目内彻底移除状态项隐藏功能（ignoredBundleIDs 及其 7 层实现），保留无溢出隐藏胶囊、全屏隐退、⌘H 应用级隐藏等同名但无关的能力。

---

🔧 补丁更新（2026-09-11，安装包资产已重新构建）

• 修复「启动即弹出空白设置面板」：只要声明了 SwiftUI 场景，macOS 会在应用启动时自动创建并显示该场景的窗口。v0.0.9 的 Settings 场景渲染的是 EmptyView，因此启动即弹出一个空白窗口；自建设置窗口一关闭，它就暴露出来。现已弃用 SwiftUI App 协议、改由 AppKit 手动启动，该窗口彻底消失。
• 偏好设置面板改用侧边栏版式：TabView + .tabItem 在 macOS 上会渲染成传统的顶部标签栏，现改为 List(selection:) + .listStyle(.sidebar) 分区导航。
• 设置窗口生命周期加固：只复用当前可见的窗口，关闭时释放引用并剥离托管视图。

---

📦 资产下载

• DMG 镜像安装包: NotchRail-v0.0.9.dmg
• ZIP 绿色压缩包: NotchRail-v0.0.9.zip

NotchRail v0.0.8 (开发版): 扩展屏聚焦流转与展开动效打磨、溢出纯几何判定、设置体验升级

⚠️ 版本说明：本版本为开发版 (Development Build)，重构多显示器拓扑与交互模型，彻底剥离外接平直显示器的虚拟假刘海，实现扩展屏动态菜单几何碰撞判定、聚焦视口流转、仿真展开动效与现代化设置面板体验全面升级。

✨ v0.0.8 核心更新与修复

1. 🖥️ 剥离平直外接屏 160pt 虚拟假刘海，折叠常态 100% 隐形穿透：

   • 彻底废除平直屏硬编码的 160pt 假刘海，physicalNotchRect 严格归零；
   • 平直外接屏折叠常态下完全隐形（alpha = 0.0 且 ignoresMouseEvents = true），底层应用（如 Chrome 标签栏、书签栏及操作）100% 物理直通，零视觉干扰。

2. 📐 扩展屏动态菜单碰撞判定与前台 App 菜单探测：

   • 内置刘海屏：维持刘海右边缘安全过渡区几何不变量（notchRightEdge + 12pt）；
   • 平直外接屏：通过 MenuBarAXResolver 探测前台 App 菜单最右端坐标，基于 appMenuRightEdge + 12pt 纯几何碰撞判定溢出；
   • 彻底消除平直大屏短菜单跨过中点被误判为全量溢出的“幽灵溢出”问题。

3. 🔄 单例视口聚焦跟随架构与展开平滑流转：

   • 全局单例 IslandPanel 视口随用户聚焦屏幕（点击屏幕或激活应用）自然流转；
   • 聚焦在外接屏时窗口常驻外接屏（折叠常态隐形穿透），触碰顶部中央热区即时原位展开，收起后原位淡出，杜绝跨屏跳动与耳翼徽标闪烁。

4. 🎨 展开态仿真灵动岛设计与经典外展喇叭弧：

   • 平直外接屏展开态保持与刘海屏灵动岛一致的纯黑吸光底座、微光渐变描边与顶部标志性外展喇叭弧（topEarRadius = 5.0pt），观感自然沉浸。

5. ⚙️ 偏好设置面板与交互体验升级：

   • 打开方式默认升级：默认触发模式升级为 悬停或点击（默认推荐）；
   • 设置文案精炼：全面梳理润色各配置项描述与分组 Header，词义达意、功能精准对应；
   • 顶栏 TabBar 布局加固：精炼 TabBar 标签，放宽设置窗口尺寸至 600 × 480，彻底根除 macOS 系统的工具栏溢出折叠。

---

📦 资产下载

• DMG 镜像安装包: NotchRail-v0.0.8.dmg
• ZIP 绿色压缩包: NotchRail-v0.0.8.zip

NotchRail v0.0.7 (开发版): 双轨架构解耦、切屏0ms直出与焦点防冲突

⚠️ 版本说明：本版本为开发版 (Development Build)，重点攻克切屏与设置面板聚焦冲突、实现双轨解耦与切屏 0ms 瞬间直出。

✨ v0.0.7 核心更新与修复

1. ⚡ 双轨架构解耦（切屏 0ms 瞬间直出）：

   • 彻底切断 .activeDisplayChanged 屏幕切换事件对底层扫描与逐窗截图管线的触发；
   • 灵动岛切屏跟随纯化为表现层视口平移（0ms 纯 UI 动画），直接呈现内存中已预热的多屏隔离快照，彻底消灭切换屏幕时的假加载旋转环与 500ms 强制延时锁；
   • 修复副屏条件恒真全量重扫的 Bug，仅在副屏尚未建立过初始快照时进行初次预热，日常心跳不再持续触发副屏录制，彻底解决系统屏幕录制指示灯常亮问题。

2. 🛡️ 排除应用自身获焦引发的自激循环：

   • 在 MouseMonitor 与 ScreenManager 的 didActivateApplicationNotification 监听中均增加自身 PID 守卫，排除 NotchRail 自身激活；
   • 点击、聚焦或在 NotchRail 设置面板中交互时，不再错误触发全屏空间判定与 250ms 延时屏幕重排工作项，彻底解耦设置面板与工作区屏幕焦点。

3. 🏎️ AX 进程发现过滤无 UI 守护进程：

   • 在 discoverMenuBarPIDs 中自动跳过 .prohibited 激活策略的后台系统守护进程，并将 IPC 超时收敛至 30ms；
   • 避免对数十个系统无 UI 服务轮询，显著提升菜单项反查效率。

4. 🖥️ 设置面板应用管理支持多屏分段切换：

   • 在连接多台显示器时，“应用管理”页面顶部新增多屏分段选择器（Segmented Picker）；
   • 数据源稳定绑定至所选显示器快照，光标划过不同屏幕时列表不再神经质跳变。

5. 🎯 刘海物理过渡区安全余量优化：

   • 调整溢出安全余量计算，确保贴近刘海边缘的状态项准确归入岛内展示，溢出计算准确率达 100%。

NotchRail v0.0.6 (开发版): 菜单栏管线提速与多屏隔离加固

⚠️ 版本说明：本版本为开发版 (Development Build)，重点攻克多屏切换、AX 辅助功能扫描管线性能与多显示器状态隔离。

✨ v0.0.6 核心更新与修复

1. 🚀 菜单栏 AX 反查扫描提速与子进程超时熔断：

   • 增加对已知高延迟子进程（WebKit.WebContent、renderer、helper、gpu 等）及自身进程的过滤，彻底根除单进程 1.5s+ 的 IPC 超时；
   • 引入 50ms/80ms 严格 AX 消息时限（AXUIElementSetMessagingTimeout），杜绝任何三方僵死进程卡死扫描；
   • 建立增量进程 PID 缓存池（knownMenuBarPIDs），日常刷新扫描耗时降至毫秒级。

2. 🛡️ 纯物理隔离与切屏死锁彻底阻断：

   • 严格执行多屏物理隔离（AGENTS.md 2.1），彻底移除跨屏借用快照（snapshotsByDisplay[displayID] ?? latestSnapshot）的旧逻辑兜底，消除跨屏 WindowID 污染；
   • 优化静默心跳与重扫调度时序，避免后台扫描未完成时被心跳持续抢占造成的无限重扫死循环；
   • 移除设置面板应用管理渲染期对 NSRunningApplication 的同步阻塞查询，彻底解决切屏时点击面板卡死在捕获中的问题。

3. 🎨 图标解析管线与统一加载原子闭环：

   • 修复 isFullyTransparent 中对纯黑/深色单色图标的误判，防止深色图标被错误标记全透明并进入冷却黑名单；
   • 规范黑名单与未命中项的状态管理，显式标记 .failed 静态弱化态，杜绝界面悬空回退 .pending 呼吸脉动；
   • 确保灵动岛统一加载状态结束时，岛内图标 100% 呈现真实截图。

NotchRail v0.0.5 (开发版): 全屏沉浸协同与空间适配

⚠️ 版本说明：本版本为开发版本（Development Build），包含全屏空间沉浸式协同与顶边缘碰顶唤醒核心功能，目前仍有部分多屏边缘场景在持续改善优化中。

✨ v0.0.5 开发版核心特性

1. 🌌 全屏沉浸协同与顶边缘碰顶唤醒：

   • 采用纯几何识别原生 macOS 全屏空间（Full-Screen Spaces）；
   • 在全屏应用（Xcode、全屏视频、幻灯片等）下自动隐退视口（alpha = 0 且 100% 物理穿透，零遮挡）；
   • 光标碰触屏幕顶边缘 2pt 时随系统菜单栏平滑淡入，移出后平滑隐退，兼顾极致沉浸与随时呼出；
   • 全屏下点击展开项触发动作后自动淡退回全屏隐退态，归还完整沉浸感。

2. 📱 极简应用管理面板与现代化 UI 质感重塑：

   • 彻底移除冗余的手动黑名单输入框，聚焦纯粹清晰的状态栏镜像展示；
   • 增加现代化胶囊搜索框（带放大镜、清空按钮及实时统计徽章）；
   • 应用条目重塑为高级半透明圆角卡片，自适应长方形/正方形图标容器（高对比度深色衬底 + 1px 细微光描边）；
   • 极简双档状态徽标：岛内展示 (溢出) 与 原生可见。

3. 🛡️ 纯几何溢出判定与基准稳定对齐：

   • 采用纯物理坐标与边缘容差计算溢出项，杜绝全屏切换时菜单项被误判全量溢出；
   • 代码全面对齐稳定基准版本，TCC 永久开发证书签名。