# Aligner CODEGRAPH

最后更新：2026-08-14

## 用途

这是 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.13-build20260814.0445`
- 最近本地验收候选包：`0.1.13 / 20260814.0445`
- 当前开发变更：`0.1.14 / 20260814.2230` 本地性能诊断包，尚未形成新的冻结基线。
- 最后冻结前验证：2026-08-14，`swift build`、`swift test`、`round1-app-shelf-fixture-qa.sh`、DMG 挂载元数据检查和 mounted App `codesign --verify --deep --strict` 通过；用户实测两行 App Shelf 遮挡问题已解决。
- 发布事实：`0.1.13` 是本地验收通过的代码冻结 / rollback baseline；不是正式官网 release，Developer ID、notarization、staple、Gatekeeper、下载源和正式发布 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 当前状态：refreshed；`03-O/.codebase-memory/artifact.json` 指向项目 `Users-ar-Projects-Aligner-03-O` 和源码 commit `21e9dd7c95e3f58a19a7c7342ff3d6584eb9097e`。
- codebase-memory 预期索引范围：`C1.source`、`C3.tools`
- codebase-memory 当前产物规模：`4041` nodes / `12465` 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` |
| `Diagnostics.PerformanceExport` | 性能事件循环日志、跨机器诊断包导出和归档结构 | `Sources/Aligner/DevelopmentDiagnostics.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: Diagnostics.PerformanceExport

职责：

- 保留最近的结构化性能事件，并在用户遇到卡顿后导出本地 zip 诊断包。
- 汇总版本、硬件、显示器、权限、偏好、最近 Quick Switch 阶段耗时，以及应用名称和窗口数量。

核心文件：

- `Sources/Aligner/DevelopmentDiagnostics.swift`
- `Sources/Aligner/PerformanceDiagnosticsExporter.swift`
- `Sources/Aligner/QuickSwitchSessionController.swift`
- `Sources/AlignerCore/Diagnostics/PerformanceDiagnosticArchiveWriter.swift`

关键入口：

- `AlignerApplicationDelegate.exportPerformanceDiagnostics()`
- `QuickSwitchSessionController.performanceDiagnosticSummary()`
- `PerformanceDiagnosticArchiveWriter.write(...)`

已保护行为：

- 导出使用最近一次已加载的 Quick Switch 快照；不得为了导出再次触发窗口枚举、截图或 Space 查询。
- 诊断包允许包含应用名称、bundle identifier、进程 ID 和窗口聚合数量；不包含窗口标题、窗口截图或键入内容。
- 日志写入与归档在 UI 主线程之外执行，且沿用已有 10MB 循环日志上限。

QA 入口：

- `Tests/AlignerCoreTests/AlignerCoreTests.swift`
- `swift test`

## 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 Shelf 两行布局必须按真实行高预留完整 shelf 高度；首行不得被 Space Lane 裁挡，且 Waterfall 仍保留固定顶间距。
- 鼠标停留在 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 根目录执行：

```bash
swift build
swift test
```

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

macOS 14 兼容验证入口：

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

打包入口：

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

主要 QA 脚本目录：

- `../C3.tools/`

主要 QA 报告目录：

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

## 冻结规则

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

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

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