edit | blame | history | raw

2026-06-11 macOS 14 兼容方案

用户目标

  • 新建分支，开始新版兼容性尝试。
  • 研究如何把 TagLauncher 兼容性提升到 macOS 14。
  • 拉 2 个架构师、2 个 QA、1 个代码审核员先讨论方案。

已完成事项

  • 已切换到新分支：codex/macos14-compatibility。
  • 已确认工作区有既有未纳入本轮的改动：docs/index.html、Docs/KM02-技术/，本轮未触碰。
  • 已启动并汇总 5 个只读子任务：
  • 应用架构：源码 API 兼容性、窗口/Space/热键风险。
  • 构建发布架构：target、Info.plist、App Store package 风险。
  • QA 路径：macOS 14 用户主路径和阻断标准。
  • 自动化 QA：可复用脚本和新增 macOS 14 门禁脚本。
  • 代码审核：改动边界、回归风险和验收证据。

关键结论

  • 当前 7.8.26 产物不是 macOS 14 兼容包：
  • src/build.sh 固定 TARGET="arm64-apple-macosx15.0"。
  • src/Apptag/Info.plist 固定 LSMinimumSystemVersion=15.0。
  • 现有 release pack 也按 Minimum macOS 15.0 记录。
  • 应用架构探针显示：用当前 SDK 对 src/Apptag 全部 Swift 源码做 arm64-apple-macosx14.0 和 x86_64-apple-macosx14.0 typecheck 均通过，暂未发现必须 @available(macOS 15, *) 保护的现有 API。
  • 主要风险不是编译 API，而是 macOS 14 上的行为兼容：
  • NSPanel overlay、全屏/Split View、Space 切换。
  • 菜单栏图标与 Dock/activationPolicy。
  • Quick Search 焦点、Esc、外部点击、子窗口层级。
  • 全局热键、Launch at Login、文件面板和 sandbox。
  • 当前构建仍是 arm64 only。是否支持 Intel macOS 14 是一个独立决策；源码 typecheck 能过不等于打包、签名、QA 已支持 universal。

建议方案

  1. 先做低风险 spike：
  • 同步把 build.sh target 和 Info.plist 最低系统改到 14.0。
  • 增加 macOS 14 typecheck/build metadata QA。
  • 不重写窗口、热键、搜索、数据层、SmartStart。
  1. 编译和元数据门禁：
  • Swift typecheck/build target 为 macosx14.0。
  • LSMinimumSystemVersion=14.0。
  • Mach-O LC_BUILD_VERSION minos=14.0。
  • 架构策略明确为 Apple Silicon only 或 universal。
  1. 行为 QA：
  • macOS 14 真机或 VM 启动、菜单栏、App Grid、Quick Search、Settings、导入导出、Smart Start、全屏/Split View、多显示器。
  • macOS 15 做同路径回归，避免现有正式版退化。
  1. 发布前：
  • 新建新的 macOS 14 release pack，历史 7.8.26 release archive 不重写。
  • 重新生成 App Store .pkg，重新做 profile、entitlements、quarantine、SHA256、App Store Connect 资料检查。

未决问题

  • 是否要支持 Intel macOS 14。如果要支持，后续需要新增 universal build、签名和 Intel 真机 QA。
  • 是否先交付 Apple Silicon macOS 14 兼容 spike，再根据反馈决定 universal 范围。

Spike 执行结果

  • 已将默认构建目标改为 macOS 14 / arm64：
  • src/build.sh 默认 MACOS_DEPLOYMENT_TARGET=14.0、TARGET_ARCH=arm64。
  • src/Apptag/Info.plist 的 LSMinimumSystemVersion 改为 14.0。
  • 已新增 macOS 14 门禁脚本：
  • src/Scripts/macos14_availability_typecheck_qa.sh
  • src/Scripts/macos14_build_metadata_qa.sh
  • 已修正 Quick Search QA 脚本的 Swift module cache 路径，避免受限环境写入 /Users/ar/.cache/clang/ModuleCache 失败。
  • 已验证：
  • macos14_availability_typecheck_qa.sh 默认 arm64 PASS。
  • TARGET_ARCHES=arm64,x86_64 macos14_availability_typecheck_qa.sh PASS。
  • bash build.sh 生成本地 TagLauncher.app 成功。
  • macos14_build_metadata_qa.sh PASS：LSMinimumSystemVersion=14.0、Mach-O minos=14.0、arches=arm64、签名校验通过。
  • Apple default apps、Apple default note policy、SmartStart catalog、Quick Search system app、Quick Search app-name QA 均 PASS。
  • 本轮未运行 window_logic_qa.sh，因为它会驱动真实 UI；macOS 14 行为兼容仍需真机/VM smoke 覆盖。

macOS 14 设置窗口显示修复

  • 用户在 MacBook Air M1 / macOS Sonoma 14.5 上反馈设置窗口顶部显示异常，标题栏和 TabView 分段标签发生挤压。
  • 根因判断：
  • PreferencesView 固定内容尺寸为 1000x480。
  • AppDelegate.prepareSettingsWindow 误把 1000x480 当作整个 window frame 尺寸强制设置。
  • macOS 14 标题栏占用 frame 高度后，实际 content area 小于 480，导致 SwiftUI TabView 顶部被压缩到标题栏区域。
  • 修复：
  • 新增统一的 settingsContentSize。
  • prepareSettingsWindow 改用 contentMinSize / contentMaxSize / setContentSize(_:)。
  • minSize / maxSize 改为根据 content size 计算出的 frame size。
  • 已验证：
  • macOS 14 availability typecheck PASS。
  • bash build.sh 成功，build 号 20260611.1413。
  • macos14_build_metadata_qa.sh PASS。
  • 已生成测试 DMG：src/build/TagLauncher-7.8.26-macOS14-settingsfix-build20260611.1413.dmg。
  • DMG hdiutil verify PASS，SHA256 为 279df754b8de25217c79dc7be77de7ae4d6ba642fb19befd46fb785a2446c588。

设置窗口补充 QA

  • 用户指出不能完全不自测就交给用户测试。
  • 已重新执行自动化：
  • src/Scripts/macos14_availability_typecheck_qa.sh PASS。
  • src/Scripts/macos14_build_metadata_qa.sh PASS。
  • src/Scripts/apple_default_apps_resource_qa.sh PASS。
  • src/Scripts/apple_default_note_policy_qa.sh PASS。
  • src/Scripts/smartstart_catalog_resource_qa.sh PASS。
  • src/Scripts/quick_search_system_app_qa.sh PASS。
  • src/Scripts/quick_search_app_name_qa.sh PASS。
  • 已做本机设置窗口 smoke：
  • 启动 src/build/TagLauncher.app。
  • 通过 TagLauncher App 菜单点击 Settings… 打开设置窗口。
  • System Events 读到设置窗口：name=通用、position=355,316、size=1000x568。
  • 修复前代码把整个 window frame 强制成 1000x480；补测读到 1000x568，说明当前 frame 已包含标题栏高度，内容区域不再被压缩成 480。
  • 截图证据未保存；截图权限未继续申请，避免重复打扰。当前可复核证据为 AX 窗口尺寸和自动化结果。
  • 测试后已关闭本机 TagLauncher 测试进程。