edit | blame | history | raw

Aligner CODEGRAPH

最后更新：2026-06-28

用途

这是 Aligner 自维护的轻量工程地图，用来减少后续任务的代码定位成本和上下文重建 token。它不是完整架构文档，也不是自动生成的调用图；它只记录稳定入口、影响面、QA 入口和已保护行为。

Aligner 同时维护两类代码地图：

  • codegraph：人工维护的本文件，记录模块边界、关键入口、受保护行为、QA 入口和最后验证基线。
  • codebase-memory：codebase-memory-mcp 生成的自动代码知识图谱，保存到 ../.codebase-memory/graph.db.zst，用于查询调用链、影响面、死代码候选和架构概览。

两者不互相替代。自动图谱结果必须回读源码、测试和 QA 证据。

使用规则：

  • 非平凡 Quick Switch 任务，先读本文件，再读节点指向的源码和 QA。
  • 本文件只做索引，不替代源码、测试和真实 QA。
  • 版本冻结时必须更新本文件，并在打 tag 前校验路径。
  • 每个节点保持短、硬、可核对；不要写成长篇说明。

当前基线：

  • 功能系列：0.1.x
  • 当前可核对 tag：v0.1.12-build20260625.2320
  • 最近本地验收候选包：0.1.12 / 20260625.2320
  • 最后冻结前验证：2026-06-28，swift build、swift test、round015-entitlement-fixture-qa.sh、round1-main-ui-qa.sh 通过；主 UI QA 日志目录 /tmp/aligner-round01-main-ui-qa-20260628_210821。
  • 发布事实：0.1.12 是本地 QA 候选代码冻结 / rollback baseline；不是正式官网 release，Developer ID、notarization、staple、Gatekeeper、macOS 14 Phase C、下载源和正式发布 manifest 仍未闭环。
  • Git 根目录：/Users/ar/Projects/Aligner/03-O
  • SwiftPM 根目录：/Users/ar/Projects/Aligner/03-O/C1.source
  • codebase-memory 共享产物：/Users/ar/Projects/Aligner/03-O/.codebase-memory/graph.db.zst
  • codebase-memory 当前状态：stale；03-O/.codebase-memory/artifact.json 仍指向旧项目名 Users-ar-Projects-Aligner2-03-O 和 commit 1fea9bfc8a7639bb3573a7cf2a449ab55065ab9e，不得作为当前代码事实源。
  • codebase-memory 预期索引范围：C1.source、C3.tools
  • codebase-memory 旧产物规模：3988 nodes / 12382 edges

更新触发

以下情况必须更新 CODEGRAPH：

  1. 用户要求“冻结版本”。
  2. 新增或修改用户可见交互。
  3. 修改 Quick Switch 状态模型、窗口枚举、Space 归属、激活、关闭、主题、视图切换或键盘导航。
  4. 新增、移动或删除核心 QA 脚本 / fixture / report 入口。
  5. 移动、重命名或拆分本文件记录的核心源码。
  6. 修复反复出现的高风险问题，并补充已保护行为。

节点索引

Node 负责范围 优先读取
QuickSwitch.Session overlay 生命周期、回调 wiring、提交窗口、Space 点击、关闭请求 Sources/Aligner/QuickSwitchSessionController.swift
QuickSwitch.View 三栏 UI、App Shelf、Waterfall、主题、键盘和鼠标交互 Sources/Aligner/QuickSwitchRootView.swift
QuickSwitch.Waterfall 纵栏 / 横栏瀑布、卡片、缩略图、对齐和过滤态动画 Sources/Aligner/QuickSwitchRootView.swift
QuickSwitch.Snapshot 窗口候选集、App 分组、窗口排序、Space 主归属 Sources/AlignerCore/Windows/QuickSwitchSnapshot.swift
QuickSwitch.ViewModel Space Lane / App Shelf / Waterfall 的展示模型和 Space 过滤投影 Sources/AlignerCore/Windows/QuickSwitchViewModel.swift
QuickSwitch.Focus 初始选择、方向键移动、视觉优先级 Sources/AlignerCore/Windows/QuickSwitchFocusPolicy.swift
QuickSwitch.Windows CG/AX 窗口枚举、激活、关闭、Finder 多页签 Sources/Aligner/Infrastructure/Windows/CGWindowAXWindowService.swift
QuickSwitch.Spaces Space 枚举、窗口 Space 归属、Space 激活 Sources/Aligner/Infrastructure/PrivateAPI/SkyLightSpaceEnumerator.swift
QuickSwitch.ThemeAndSettings 视图模式、主题、设置持久化、Settings 入口 Sources/AlignerCore/Preferences/AlignerPreferences.swift
QuickSwitch.TriggerAndPermissions 快捷键、权限、Force Quit 放行、权限窗口 Sources/Aligner/AlignerApplicationDelegate.swift
QuickSwitch.Screenshots 真实截图、ScreenCaptureKit、骨架 fallback Sources/AlignerCore/Screenshots/ScreenCaptureKitScreenshotProvider.swift
Commerce.Entitlement Round01.5 试用、授权、Pro feature gate 模型 Sources/AlignerCore/Commerce/

Node: QuickSwitch.Session

职责：

  • 打开 / 关闭 Quick Switch overlay。
  • 将 view 的用户动作接到 session 行为。
  • 处理窗口提交、Space filter、Space 激活、窗口关闭。
  • 控制截图刷新和 debug / QA report 状态。

核心文件：

  • Sources/Aligner/QuickSwitchSessionController.swift
  • Sources/Aligner/QuickSwitchOverlayHost.swift
  • Sources/Aligner/OverlayWindowController.swift
  • Sources/Aligner/WindowCoordinator.swift
  • Sources/Aligner/AlignerApplicationDelegate.swift

关键入口：

  • QuickSwitchSessionController.show(...)
  • QuickSwitchSessionController.hide(reason:)
  • QuickSwitchSessionController.commitSelection(_:source:)
  • QuickSwitchSessionController.handleSpaceLaneClick(_:clickCount:)
  • QuickSwitchSessionController.requestClose(_:)
  • AlignerApplicationDelegate.applicationShouldHandleReopen(_:hasVisibleWindows:)

已保护行为：

  • Option+Tab 打开后 view 必须成为 first responder，键盘立即可用。
  • Dock reopen 只负责打开 Quick Switch，复用 Option+Tab 的打开路径；不得改主题、视图模式或布局选择。
  • 提交窗口前先隐藏 Quick Switch overlay，再执行窗口激活。
  • Force Quit Command+Option+Esc 不得被 Aligner 阻挡。
  • 关闭窗口返回 .requested 时不做乐观删除；必须刷新验证目标是否真的消失。
  • 目标 stale / windowNotFound 时允许从当前展示中移除，避免用户继续点残留卡片。

QA 入口：

  • ../C3.tools/round1-quick-switch-entry-qa.sh
  • ../C3.tools/round1-trigger-session-qa.sh
  • ../C3.tools/round1-dock-reopen-fixture-qa.sh
  • ../C3.tools/round1-overlay-qa.sh
  • ../C3.tools/round1-main-ui-qa.sh
  • ../C3.tools/round1-close-fixture-qa.sh
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-trigger-session-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-dock-reopen-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-overlay-qa-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-close-card-confirmation-report.json

Node: QuickSwitch.Snapshot

职责：

  • 从原始窗口集合构造 Quick Switch 候选集。
  • 按 App 分组，按 Space / 标题 / window id 排序。
  • 计算窗口 primary Space。
  • 保留最小化和全屏窗口，过滤隐藏 App、幽灵窗口和系统浮层。

核心文件：

  • Sources/AlignerCore/Windows/QuickSwitchSnapshot.swift
  • Sources/AlignerCore/Windows/WindowEnumerationPolicy.swift
  • Sources/AlignerCore/Windows/FinderTabSpaceAttributionPolicy.swift
  • Sources/AlignerCore/Spaces/WindowSpaceMappingPolicy.swift
  • Sources/AlignerCore/Spaces/SpaceEnumerationPolicy.swift
  • Sources/Aligner/QuickSwitchSnapshotLoader.swift
  • Sources/Aligner/Infrastructure/Windows/CGWindowAXWindowService.swift

关键入口：

  • QuickSwitchSnapshotBuilder.snapshot(displays:windows:)
  • WindowEnumerationPolicy.window(from:)
  • FinderTabSpaceAttributionPolicy.attributedRecords(_:)
  • WindowSpaceMappingPolicy.mergedSpaceIDsByWindowID(...)
  • LiveQuickSwitchSnapshotLoader.load()

已保护行为：

  • 最小化窗口必须展示，选中后恢复。
  • 隐藏 App 窗口不展示。
  • 全屏 App 窗口必须可发现。
  • Finder Split View / 多页签必须优先用高置信 frame / host 关系补 Space 归属。
  • No-space 窗口不得无脑归属到当前 Space；只在数据层高置信时归属。
  • 窗口排序保持稳定：Space 顺序优先，其次标题，再次 window id。

QA 入口：

  • Tests/AlignerCoreTests/AlignerCoreTests.swift
  • ../C3.tools/round1-candidate-filter-fixture-qa.sh
  • ../C3.tools/round1-finder-tabs-live-qa.sh
  • ../C3.tools/round1-minimized-window-qa.sh
  • ../C3.tools/round1-session-snapshot-qa.sh
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-multi-page-activation-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-multi-page-close-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-minimized-window-qa-snapshot.json

Node: QuickSwitch.ViewModel

职责：

  • 把 snapshot 投影为三栏 UI 模型。
  • 生成 Space Lane、App Shelf、Waterfall 的展示数据。
  • 处理 Space filter 投影。
  • 识别“单全屏窗口 Space 直接激活”。
  • 为 Split View Space 输出左右 App 名称。

核心文件：

  • Sources/AlignerCore/Windows/QuickSwitchViewModel.swift
  • Sources/AlignerCore/Windows/QuickSwitchFocusPolicy.swift

关键入口：

  • QuickSwitchViewModelBuilder.viewModel(from:currentSpaceIDs:)
  • QuickSwitchSpaceFilterPolicy.projectedViewModel(from:lockedSpaceID:preferredSelection:)
  • QuickSwitchSpaceFilterPolicy.singleFullscreenSelection(inSpaceID:viewModel:)
  • QuickSwitchFocusPolicy.initialSelection(in:)
  • QuickSwitchFocusPolicy.nextSelection(from:in:direction:columnHistory:)

已保护行为：

  • Space filter 只影响 App Shelf + Waterfall，不过滤顶部 Space Lane。
  • 锁定 Space 后，App Shelf 只显示该 Space 下有窗口的 App。
  • No-space 窗口不进入 Space filter 结果，除非已有高置信 Space 归属。
  • 点击空 Space 后保持锁定并显示空态；再次点击同 Space 解锁。
  • 锁定后关闭最后一个窗口，不自动解锁。
  • 单全屏应用窗口 Space 不提供过滤；点击时直接激活对应全屏窗口，并释放原锁定。
  • Split View App 名称按窗口 frame 的左右顺序输出。

QA 入口：

  • Tests/AlignerCoreTests/AlignerCoreTests.swift
  • ../C3.tools/round1-space-filter-fixture-qa.sh
  • ../C3.tools/round1-space-lane-split-view-fixture-qa.sh
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-space-filter-switch-a2-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-space-filter-fullscreen-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-space-lane-split-view-fixture-report.json

Node: QuickSwitch.View

职责：

  • 绘制 Space Lane / App Shelf / Waterfall。
  • 处理鼠标 hover、点击、滚动和键盘输入。
  • 维护 hover、keyboard focus、selection、pending window shortcut filter 等 UI 状态。
  • 生成 debug / QA report。

核心文件：

  • Sources/Aligner/QuickSwitchRootView.swift

关键入口：

  • QuickSwitchRootView.keyDown(with:)
  • QuickSwitchRootView.performKeyboardCommand(_:)
  • QuickSwitchRootView.handleAppShelfIndexKey(_:)
  • QuickSwitchRootView.handleWindowIndexKey(symbol:)
  • QuickSwitchRootView.focusAppShelfItemForKeyboard(...)
  • QuickSwitchRootView.moveKeyboardAppFocus(cycleForward:)
  • QuickSwitchRootView.moveVerticalSelectionWithinFocusedColumn(_:)
  • QuickSwitchRootView.moveSelection(_:)
  • QuickSwitchRootView.commitCurrentSelection()
  • QuickSwitchRootView.makeDebugReport()

已保护行为：

  • App Shelf 序号为 1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ，最多 36 个一键入口。
  • App 序号键在纵栏和横栏瀑布下一视同仁，等效于 hover 到对应 App 图标。
  • App Shelf 鼠标 hover 只作用于真实 hover App：图标本身放大并轻微上浮，但不显示蓝色矩形底或蓝色矩形边框；纵栏瀑布和横栏瀑布下都适用。
  • 鼠标停留在 App 图标上不动时，即使 view-model / 截图刷新触发布局重建，真实 hover App 必须保持放大、上浮和 Waterfall 联动；不能自行恢复普通尺寸。
  • App Shelf hover 不做邻近 App 视觉跟随；左右邻居不放大、不上浮、不暴露 magneticNeighbor，也不触发 hover 语义、不显示 close button、不联动 Waterfall。
  • 用户开启 Reduce Motion 时，App Shelf 不做磁性放大动效，只保留稳定状态切换。
  • App Shelf 图标主体点击必须提交该 App 在当前 Waterfall 投影中的第一窗口；App close button 只能由明确的小热区触发，不能抢占图标主体点击。
  • 按住 Option 输入 App 序号后进入 0.8s 窗口序号 pending。
  • pending 第一键时，Waterfall 中该 App 的窗口保持亮度，其它窗口 dim；dim 只作用于 Waterfall 区。
  • 0.8s 内第二键命中窗口时直接 commit；提交前 report 记录 target pre-commit filter。
  • 若 App 当前可见 Waterfall 集合中只有一个窗口，第一键直接 commit，不等待第二键。
  • 横栏瀑布下 Enter 提交当前 App 对应的默认窗口。
  • 纵栏瀑布下左右键在 App Shelf 循环移动；上下键在当前 App column 内移动且不循环。
  • 横栏瀑布下方向键在卡片网格中移动，保留既有横栏交互。
  • close button 只在真实 hover 到 App / Window 卡片时显示，不因键盘 App focus 批量显示。

QA 入口：

  • ../C3.tools/round1-keyboard-navigation-fixture-qa.sh
  • ../C3.tools/round1-vertical-keyboard-app-focus-fixture-qa.sh
  • ../C3.tools/round1-mouse-interaction-fixture-qa.sh
  • ../C3.tools/round1-app-shelf-fixture-qa.sh
  • ../C3.tools/round1-horizontal-waterfall-fixture-qa.sh
  • ../C3.tools/round1-window-index-progressive-filter-fixture-qa.sh
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-keyboard-navigation-fixture-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-horizontal-waterfall-keyboard-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-app-shelf-fixture-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-app-shelf-horizontal-fixture-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-app-shelf-narrow-fixture-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-app-shelf-dark-fixture-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-app-shelf-hover-persist-vertical-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-app-shelf-hover-persist-horizontal-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-vertical-keyboard-window-shortcut-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-horizontal-waterfall-window-shortcut-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-window-index-progressive-filter-commit-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-window-index-progressive-filter-single-window-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-window-index-progressive-filter-horizontal-light-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-window-index-progressive-filter-horizontal-dark-report.json

Node: QuickSwitch.Waterfall

职责：

  • 维护纵栏瀑布和横栏瀑布两种 Waterfall 展示。
  • 处理 Space filter 后的整体居中和动画。
  • 控制 App hover 联动到对应 column / window 卡片。
  • 控制缩略图、骨架缩略图、标题栏、选中态和 hover 态。

核心文件：

  • Sources/Aligner/QuickSwitchRootView.swift
  • Sources/AlignerCore/Preferences/AlignerPreferences.swift

关键入口：

  • QuickSwitchRootView.setWaterfallViewMode(_:)
  • QuickSwitchRootView.rebuildWaterfallColumns()
  • QuickSwitchRootView.layoutLayers()
  • QuickSwitchRootView.ensureCurrentSelectionVisible(...)
  • QuickSwitchRootView.waterfallColumnVisualStates(for:)
  • QuickSwitchRootView.waterfallCardVisualStates(for:)

已保护行为：

  • 纵栏窗口卡片固定高度为 138 pt，卡片间距 12 pt，纵向排列步进 150 pt。
  • 横栏瀑布窗口卡片沿用同一固定高度和截图截取规则。
  • Space filter 后，剩余 columns / cards 作为整体居中，并使用丝滑位置动画。
  • 过滤态居中不能被选中 column 强行对齐 App Shelf 图标拉偏。
  • App 图标 hover 时，对应 App 的全部窗口标题栏联动高亮并产生阴影凸起。
  • 鼠标 hover App 图标时，column header 使用浅灰填充；该 column 第一张窗口卡片使用当前应用 column 第一个窗口高亮标准。
  • 切换视图时不能全部退化为骨架缩略图；已有截图应继续展示。

QA 入口：

  • ../C3.tools/round1-waterfall-fixture-qa.sh
  • ../C3.tools/round1-horizontal-waterfall-fixture-qa.sh
  • ../C3.tools/round1-app-column-alignment-fixture-qa.sh
  • ../C3.tools/round1-app-shelf-fixture-qa.sh
  • ../C3.tools/round1-view-mode-entry-qa.sh
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-waterfall-fixture-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-horizontal-waterfall-layout-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-horizontal-waterfall-filter-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-app-column-alignment-regular-hover-middle-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-view-mode-entry-horizontal-report.json

Node: QuickSwitch.Spaces

职责：

  • 枚举 Space。
  • 将窗口映射到 Space。
  • 渲染 Space Lane。
  • 处理 Space hover / lock / unlock / activate。

核心文件：

  • Sources/Aligner/Infrastructure/PrivateAPI/SkyLightSpaceEnumerator.swift
  • Sources/Aligner/Infrastructure/PrivateAPI/SkyLightOverlayScreenSpaceStateProvider.swift
  • Sources/Aligner/Infrastructure/PrivateAPI/PrivateSpaceActivationBridge.swift
  • Sources/Aligner/SpaceActivationService.swift
  • Sources/AlignerCore/Spaces/SpaceEnumerationPolicy.swift
  • Sources/AlignerCore/Spaces/WindowSpaceMappingPolicy.swift
  • Sources/Aligner/QuickSwitchSessionController.swift
  • Sources/Aligner/QuickSwitchRootView.swift

关键入口：

  • SpaceEnumerationPolicy.normalizedDisplays(from:knownPhysicalDisplayUUIDs:)
  • WindowSpaceMappingPolicy.mergedSpaceIDsByWindowID(...)
  • QuickSwitchSessionController.handleSpaceLaneClick(_:clickCount:)
  • QuickSwitchSessionController.activateLockedSpace(_:)
  • QuickSwitchRootView.visualStates(for:)
  • QuickSwitchRootView.spaceLaneDebugReports()

已保护行为：

  • App 窗口 hover 时，对应 App 图标和窗口所在 Space 都要高亮。
  • 空 Space tile 填充保持透明；hover/current/associated 反馈只走边框/阴影，不出现灰色渐变。
  • 深色主题下 Space tile hover / 浅色高亮态必须切换深色前景，避免浅底白字。
  • 直接双击任意普通 Space tile，或双击当前已锁定 Space：关闭 Quick Switch 并切到该 Space，不提交窗口、不激活 App。
  • 单击空白区域：如果当前有 Space filter 则退出 filter；否则保持原行为。
  • 单全屏窗口 Space 直接激活，不进入过滤。

QA 入口：

  • ../C3.tools/round1-space-filter-fixture-qa.sh
  • ../C3.tools/round1-space-lane-dark-hover-fixture-qa.sh
  • ../C3.tools/round1-space-lane-split-view-fixture-qa.sh
  • ../C3.tools/round1-three-zone-linkage-fixture-qa.sh
  • ../C3.tools/round1-obsidian-space-activation-qa.sh
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-space-dark-hover-light-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-space-dark-hover-split-base-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-three-zone-linkage-space-click-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-space-filter-lock-then-fullscreen-report.json

Node: QuickSwitch.Windows

职责：

  • CG / AX 窗口枚举。
  • 普通窗口、最小化窗口、全屏窗口、Finder 多页签的激活和关闭。
  • 多页签 / 非激活页签的精准激活与关闭。

核心文件：

  • Sources/Aligner/Infrastructure/Windows/CGWindowAXWindowService.swift
  • Sources/Aligner/Infrastructure/PrivateAPI/PrivateWindowActivationBridge.swift
  • Sources/Aligner/DebugWindowActivationService.swift
  • Sources/Aligner/DebugWindowCloseService.swift
  • Sources/Aligner/QuickSwitchCloseRequest.swift
  • Sources/AlignerCore/Protocols/ServiceProtocols.swift

关键入口：

  • CGWindowAXWindowService.visibleWindows(for:)
  • CGWindowAXWindowService.activate(window:)
  • CGWindowAXWindowService.close(window:)
  • CGWindowAXWindowService.close(app:)
  • PrivateWindowActivationBridge.activate(windowID:processIdentifier:)
  • PrivateAXWindowIDReader.windowID(for:)

已保护行为：

  • Finder 多页签 / Split View 下，非激活页签仍应能展示并尽量精准激活。
  • Finder CG-only / 多页签激活必须有边界：交互路径使用 1.5 秒预算，循环切 tab 兜底最多 5 轮；超过边界时快速失败，不继续 24 轮高耗时等待。
  • Finder 直接 AX / WindowServer 激活不能直接视为精准成功；必须校验 Finder 前台标题，标题不匹配时进入有预算的页签 fallback。
  • Quick Switch activation report 必须记录 lastActivationDurationMilliseconds，用于 QA 判断窗口提交耗时。
  • 窗口卡片点击命中必须跟随 CALayer presentation frame，动画中的视觉位置就是可点击位置；不得用旧 model frame 造成点到视觉卡片却提交错窗口。
  • App Shelf 图标主体点击优先打开该 App 的第一个窗口；关闭按钮只在明确命中自身视觉区域时触发，不得抢占图标主体点击。
  • Live 枚举不得把低置信 AX-only 普通窗口当成真实窗口：非最小化、非全屏且无高置信 Space 的 AX-only 候选应跳过。
  • 窗口卡片精准激活不得把 .appActivatedOnly 当成成功；该结果只表示 App 激活诊断，不证明目标窗口已前置。
  • 窗口激活明确失败、目标不存在或 unsupported 时，本次投影视图应抑制该 windowID，避免继续展示可重复点击的 stale 卡片。
  • 真实激活 / 关闭服务必须和 live snapshot 使用同源 SkyLight Space resolver，避免 Finder、多页签、跨 Space fallback 拿空 Space 数据。
  • 普通窗口激活应按目标窗口执行 AXFocusedWindow、AXMain、AXRaise，AX 短暂缺失或首次动作失败时允许一次短重读重试。
  • 多页签关闭不能把目标仍存在的卡片假移除；关闭请求后必须刷新验证。
  • 对不可关闭、已消失或 stale 的目标，应静默移除展示残留，不把技术诊断暴露给用户。
  • 关闭确认的“不再提醒”是全局偏好，不是单窗口或单 App 维度。

QA 入口：

  • ../C3.tools/round1-window-activation-fixture-qa.sh
  • ../C3.tools/round1-finder-tabs-live-qa.sh
  • ../C3.tools/round1-multi-page-identity-fixture-qa.sh
  • ../C3.tools/round1-mouse-interaction-fixture-qa.sh
  • ../C3.tools/round1-horizontal-waterfall-fixture-qa.sh
  • ../C3.tools/round1-obsidian-space-activation-qa.sh
  • ../C3.tools/round1-close-fixture-qa.sh
  • ../C3.tools/round1-main-ui-qa.sh
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-window-activation-normal-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-window-activation-failure-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-mouse-app-only-fixture-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-mouse-interaction-fixture-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-multi-page-activation-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-multi-page-close-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-close-card-optout-toggle-report.json

Node: QuickSwitch.ThemeAndSettings

职责：

  • 存储和应用浅色 / 深色主题。
  • 存储和应用纵栏 / 横栏瀑布视图模式。
  • 管理右上角主题切换和视图切换按钮。
  • 管理设置页入口和偏好写入。

核心文件：

  • Sources/AlignerCore/Preferences/AlignerPreferences.swift
  • Sources/Aligner/AlignerApplicationDelegate.swift
  • Sources/Aligner/SettingsWindowController.swift
  • Sources/Aligner/QuickSwitchRootView.swift

关键入口：

  • PreferenceKey.quickSwitchWaterfallViewMode
  • PreferenceKey.theme
  • UserDefaultsPreferenceStore.read()
  • UserDefaultsPreferenceStore.write(_:)
  • AlignerApplicationDelegate.setQuickSwitchWaterfallViewMode(_:)
  • AlignerApplicationDelegate.toggleQuickSwitchThemePreference()
  • QuickSwitchRootView.setTheme(_:)
  • QuickSwitchRootView.setWaterfallViewMode(_:)

已保护行为：

  • 视图切换实时生效。
  • 设置窗口使用 AppKit，不用 SwiftUI 绘制。
  • 深色主题保留渐变背景和暗色整体氛围。
  • 主题切换按钮使用一个按钮、两个状态图标；默认图标为半明半暗圆盘。
  • 深色模式下 Space tile hover 浅色高亮时，文字、数字、角标线必须同步改为深色前景。

QA 入口：

  • ../C3.tools/round1-theme-toggle-fixture-qa.sh
  • ../C3.tools/round1-view-mode-entry-qa.sh
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-theme-toggle-light-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-theme-toggle-dark-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-view-mode-entry-settings-report.json
  • ../C2.builds/Z-研发中间产物/qa-reports/round01-view-mode-entry-toggle-to-horizontal-report.json

Node: Commerce.Entitlement

职责：

  • 定义 Round01.5 官网直发 Pro 试用、授权、离线宽限和校验失败的基础状态模型。
  • 提供 windowShortcutActivation 的纯函数授权判定。
  • 支持 fixture-only 启动参数和 QA report，用于在接入真实支付前验证 Pro gate 口径。

核心文件：

  • Sources/AlignerCore/Commerce/EntitlementState.swift
  • Sources/Aligner/Diagnostics/Round015EntitlementLaunchOptions.swift
  • Sources/Aligner/QuickSwitchRootView.swift
  • Sources/Aligner/QuickSwitchSessionController.swift

关键入口：

  • EntitlementPolicy.evaluate(snapshot:feature:now:)
  • EntitlementPolicy.offlineGrace(lastAttemptAt:)
  • FixtureEntitlementProvider.entitlement(for:at:)
  • Round015EntitlementLaunchOptions.parse(arguments:)
  • QuickSwitchRootView.handleAppShelfIndexKey(_:)
  • QuickSwitchRootView.handleWindowIndexKey(symbol:)

已保护行为：

  • Round01.5 只 gate windowShortcutActivation：两键窗口码直达，以及单窗口 App 的 App 序号自动激活。
  • Quick Switch overlay 打开、普通 App 序号聚焦、鼠标点击窗口、方向键导航、Enter、Space filter、窗口枚举和截图不受 Pro gate 影响。
  • trialActive、proUnlocked、offlineGrace 允许窗口码；trialExpired、无有效试用下的 verifyFailed 拦截窗口码。
  • Pro gate 拦截后 overlay 不关闭，基础 Quick Switch 路径保持可用。
  • QA report / log 不输出明文 license key、instance id、邮箱或订单信息。

QA 入口：

  • Tests/AlignerCoreTests/EntitlementPolicyTests.swift
  • ../C3.tools/round015-entitlement-fixture-qa.sh
  • ../C2.builds/Z-研发中间产物/qa-reports/round015-entitlement-fixture-qa.json

基础验证入口

从 SwiftPM 根目录执行：

swift build
swift test

如需限制终端输出，使用执行工具的输出上限或写入日志文件；不要在标准验证命令后接 head -c，避免 SIGPIPE 141 被误判为 build / test 失败。

macOS 14 兼容验证入口：

../C3.tools/round015-macos14-compatibility-qa.sh

打包入口：

../C3.tools/package-app.sh

主要 QA 脚本目录：

  • ../C3.tools/

主要 QA 报告目录：

  • ../C2.builds/Z-研发中间产物/qa-reports/

冻结规则

用户要求“冻结版本”时，Agent 必须自动更新本文件，并在打 tag 前完成：

  • 路径存在性校验。
  • QA 入口存在性校验。
  • 已保护行为与本轮变更一致性校验。
  • 最后更新、当前基线、相关节点 QA 入口 与 已保护行为 更新。

如果用户只说 更新codegraph，只更新本文件，不改源码、不打包、不 tag；除非用户明确说 更新codegraph并提交。