crazy-macs/aligner.git

			@@ -1,12 +1,12 @@
			# Aligner CODEGRAPH

			最后更新：2026-06-28
			最后更新：2026-08-14

			## 用途

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

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

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

			- 功能系列：`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/Aligner2/03-O`
			- SwiftPM 根目录：`/Users/ar/Projects/Aligner2/03-O/C1.source`
			- codebase-memory 共享产物：`/Users/ar/Projects/Aligner2/03-O/.codebase-memory/graph.db.zst`
			- codebase-memory 项目名：`Users-ar-Projects-Aligner2-03-O`
			- codebase-memory 索引范围：`C1.source`、`C3.tools`
			- codebase-memory 当前规模：`3988` nodes / `12382` edges
			- 当前可核对 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

			## 更新触发

			@@ -59,6 +60,7 @@
			\| `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/` \|

			@@ -109,6 +111,37 @@
			- `../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

			@@ -230,6 +263,7 @@
			- 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 不做磁性放大动效，只保留稳定状态切换。