# Round0 状态收口

> 日期：2026-05-29
> 范围：Round0 技术基础建设当前状态
> 当前源码根：`03-O/C1.source/`
> 当前 Git 根：`03-O/`

## 已完成

- Git 仓库根固定为 `03-O/`。
- SwiftPM / Xcode 工程根固定为 `03-O/C1.source/`。
- App 名为 `Aligner`，Bundle ID 为 `com.ar.Aligner`。
- 目标平台为 macOS 26+ Apple Silicon only。
- Round0 空壳 App 可构建、可测试、可打包、可双击启动。
- Round0 偏好 Schema 已定义，覆盖最小化窗口、全屏窗口、主题、语言和 Space 显示策略。
- 权限窗口已进入 Round0，覆盖 Accessibility 和 Screen Recording。
- 权限请求先触发系统 TCC 注册，再跳转系统设置，避免用户在系统列表中找不到 Aligner。
- 打包脚本优先使用稳定本地签名身份；无本地身份时才 ad-hoc fallback，并提示 TCC 权限可能失效。
- 打包脚本生成研发/QA 用的当前 `Aligner.app`，并在当前发布包目录内生成 `Aligner-<Version>-build<YYYYMMDD.HHMM>.dmg`。
- 旧 build 成果自动移入 `03-O/C2.builds/X-旧版build成果/`，不存旧 `.app`。
- `round0-qa.sh` 已成为 Round0 一键 QA 入口。
- `window-logic-qa.swift` 已成为 WindowLogic QA 辅助工具。
- `check-signing.sh` 已成为本地签名身份检查工具。
- `Round0DebugOverlayController` 已提供仅供 QA 使用的 debug overlay 入口，支持运行态检查 overlay 打开/关闭、Settings child 挂载/卸载和前台 App 不变；全屏 Space 不切换当前为 Round0 代理验证，真实全屏 App Space 回归后续继续做。
- Round0 / Round1 不包含 Quick Layout 实现。

## 当前验收命令

```bash
cd /Users/ar/Projects/Aligner/03-O/C1.source
swift build
swift test
```

```bash
cd /Users/ar/Projects/Aligner/03-O
./C3.tools/check-signing.sh
./C3.tools/package-app.sh
./C3.tools/round0-qa.sh
```

说明：`round0-qa.sh` 会重新执行 `package-app.sh`。只需要验证当前包时运行 `round0-qa.sh` 即可；需要单独生成产物时再运行 `package-app.sh`。

## 当前产物

- 当前研发/QA App：`03-O/C2.builds/Z-研发中间产物/current/Aligner.app`
- DMG 命名规则：`Aligner-<Version>-build<YYYYMMDD.HHMM>.dmg`
- 当前最新 DMG 以当前发布包目录为准：`03-O/C2.builds/Aligner-<Version>-build<YYYYMMDD.HHMM>/`
- 历史 build 成果：`03-O/C2.builds/X-旧版build成果/`

## 已知后续风险

- Screen Recording 最终开关需要 Boss 使用 Touch ID 或密码授权；自动化和代理不得代替用户打开该开关。
- 未来切换正式 Developer ID / Team ID 后，TCC 代码身份会变化，必须重新做权限回归。
- 当前本机使用 `VoiceSnap Local Code Signing` 作为稳定本地签名身份。长期建议创建并固定 `Aligner Local Code Signing`，或在环境中显式设置 `ALIGNER_CODE_SIGN_IDENTITY`。
- `03-O/README.md` 当前写明 `C2.builds/` 进入 git。`.dmg` 属于二进制产物，是否长期纳入 git 需要在正式协作前再裁决。
- `window-logic-qa.swift` 当前覆盖 Round0 基础窗口快照；`OverlayWindowPolicy` 单测已覆盖 Quick Switch overlay 的层级策略和不压 Force Quit 的静态约束；`round0-qa.sh` 已通过 Round0 debug overlay 覆盖运行态打开、Settings child 挂载、自动隐藏后无残留、前台 App 不变。真实全屏 App Space 的 active Space 回归仍需后续测试场景。
- `TriggerEventPolicy` 已固化默认 `Alt+Tab`、后续可配置快捷键、Quick Switch 事件消费边界和 Force Quit 放行规则；`ManualTriggerService` 已提供可测试触发服务。真实全局监听后续应优先走 CGEventTap 这类可条件放行的路线；Carbon `RegisterEventHotKey` 会全局占用快捷键，不符合“overlay 不可见时放行”的口径。
- `SpaceEnumerationPolicy` 已覆盖私有 API 原始 Space 记录到项目模型的归一化：CGS type 映射、全屏 Space 保留、连续编号、`"Main"` 共享 Space 降级和物理显示器标记注入。真实 CGS/SkyLight 调用仍需放在 PrivateAPI 边界内接入。
- `WindowEnumerationPolicy` 已覆盖窗口发现后的纳入/过滤规则：regular app、CGWindowID、尺寸、AX subrole、最小化保留、隐藏 App 过滤、幽灵窗口过滤、全屏窗口保留和 Space ID 传递。真实 AXObserver / CGWindow 数据源仍需后续接入。
- `ScreenCaptureKitScreenshotProvider` 已实现窗口真实截图 provider；自动化使用 mock 捕获器，不触发 Screen Recording 弹窗。真实权限和真实窗口截图还需要在授权环境回归。
- `NativeSkeletonThumbnailProvider` 已实现 7 类原生骨架缩略图和标题叠加，作为 Finder/Browser 可读骨架与无截图权限 fallback 的基础。
- `WorkspaceAppIconProvider` 已通过 `NSWorkspace` 实现应用图标获取，解析不到应用或图标无效时回退到系统 application bundle 图标。
- Layout Preset / Quick Layout 相关偏好和 schema 已按 Boss 最新口径顺延到 Round2 / Round3。

## 下一批建议

1. 固定本项目专用本地签名身份 `Aligner Local Code Signing`。
2. 明确 `C2.builds/*.dmg` 是否进入 git，或改为只保留本地/发布制品。
3. 继续实现真实 Quick Switch 前的底层服务切片：CGS/SkyLight SpaceEnumerator、CGWindow/AX WindowService 实际接入，以及 CGEventTap 全局快捷键监听和真实按键回归。