# 8.0.0 App Grid 主题系统工作日志

## 2026-06-24

### 起点

- 分支：`codex/dark-glass-8.0.0`
- 基线：`v7.9.4-build20260619.2221`
- 目标：基于已认可方案实现 8 个高级渐变背景主题，并保留原浅色毛玻璃主题。
- 关键约束：主题切换只改 UI；不动标签、拖拽、排序、搜索、数据和 SmartStart 功能语义。

### 方案决策

- 8.0.0 先做“8 个高级渐变背景主题 + 自动玻璃适配”。
- 不做容器玻璃深浅的独立开关，降低设置复杂度和 QA 面。
- 默认主题使用浅色玻璃容器；深蓝和黑色使用深色半透明玻璃容器；粉色、紫色、绿色、蓝色、炫彩使用浅色玻璃容器，避免亮色主题被压成暗黑系。
- 渐变只在 App Grid 全屏背景层实现，单个容器内部不做独立渐变，避免视觉噪声。
- 炫彩主题取样自用户提供的 Meilang logo，使用青蓝、浅青、淡紫和粉色作为背景渐变来源，并降低饱和度保证可读性。

### 已完成实现

- 新增 `Apptag/AppGridTheme.swift`：
  - 主题枚举、存储 key、标题 key、背景渐变 token、预览色、玻璃适配策略。
- 修改 `AppDefaults.swift`：
  - 新增 `appGridThemeID` 默认值。
  - 将旧 `useDarkAppGrid=true` 迁移到 `deepBlue`。
- 修改 `ContentView.swift`：
  - App Grid 背景读取当前主题。
  - 默认主题保持原浅色视觉。
  - 黑色主题跳过毛玻璃背板，使用 100% 纯黑全屏背景。
  - 深蓝主题保留暗色渐变和轻暗化层。
  - 粉色、紫色、绿色、蓝色、炫彩使用更明亮的全屏渐变，不叠加暗化层。
- 修改 `AppGridCollectionView.swift`：
  - 容器、标题、分隔线按主题自动选择浅色/深色玻璃适配。
  - 深蓝和黑色为暗玻璃；亮色主题为浅玻璃。
  - 移除 AppKit 层旧的全屏背景渐变，避免 SwiftUI/AppKit 双背景叠加。
- 修改 `PreferencesView.swift`：
  - 新增“主题”tab。
  - 新增 8 个主题选择卡片和主题说明。
  - 移除 General 页旧“启用深色视图”入口。
- 更新 29 个 `Localization/*.json`：
  - 新增主题 tab、说明和 8 个主题名称。
  - 删除旧深色视图设置文案。
- 新增 `Scripts/theme_settings_qa.sh`。
- 新增根 `CODEGRAPH.md`，记录主题系统相关模块依赖。

### 2026-06-24 视觉反馈二次调色

- 用户反馈：默认和深蓝可接受；黑色需要纯黑；粉色和炫彩需要明亮、年轻；绿色需要像明亮草坪/绿树后的毛玻璃；紫色和蓝色需要与深蓝拉开差异。
- 调整结论：
  - 黑色：全屏背景为纯黑，不使用系统毛玻璃背板、不叠加渐变或暗化层。
  - 粉色：改为明亮粉、蜜桃和柔白高光，面向更年轻/少女取向。
  - 绿色：改为草坪绿、嫩绿和明亮高光，保持喜人而不沉闷。
  - 紫色：改为浅薰衣草到高饱和紫，和深蓝明显区分。
  - 蓝色：改为天空蓝、电光蓝和青色，和深蓝明显区分。
  - 炫彩：回到 Meilang logo 的青蓝、浅青、淡紫、亮粉取色方向，整体变亮。
  - 亮色主题统一改回浅色玻璃容器；深色玻璃仅保留给深蓝和黑色。

### QA 记录

- `bash build.sh`：PASS，生成 `src/build/TagLauncher.app`。
- `codesign --verify --deep --strict --verbose=2 src/build/TagLauncher.app`：PASS。
- 29 个 localization JSON 解析：PASS。
- `bash src/Scripts/theme_settings_qa.sh`：PASS，覆盖 8 主题、主题 tab、偏好迁移、纯黑策略、亮色主题浅玻璃策略和 29 语种文案。
- `bash src/Scripts/macos14_availability_typecheck_qa.sh`：PASS。
- `bash src/Scripts/macos14_build_metadata_qa.sh`：PASS。
- `bash src/Scripts/tag_navigation_hover_scroll_qa.sh`：PASS。
- `bash src/Scripts/usage_tips_qa.sh`：PASS。
- `bash src/Scripts/app_ordering_data_qa.sh`：PASS。
- `bash src/Scripts/quick_search_system_app_qa.sh`：PASS。
- `bash src/Scripts/quick_search_app_name_qa.sh`：SKIP，本机未安装 QA fixture `/Applications/贝锐向日葵被控.app`。

### 2026-06-24 15:06 二次调色 QA 与预览包

- Build：`20260624.1506`
- `bash Scripts/theme_settings_qa.sh`：PASS。
- `bash Scripts/macos14_build_metadata_qa.sh`：PASS。
- `bash Scripts/macos14_availability_typecheck_qa.sh`：PASS。
- `APP_BUILD=20260624.1506 bash build.sh`：PASS。
- `codesign --verify --deep --strict --verbose=2 build/TagLauncher.app`：PASS。
- 构建产物版本：`8.0.0 (20260624.1506)`，`LSMinimumSystemVersion=14.0`。
- `bash Scripts/usage_tips_qa.sh`：PASS。
- `bash Scripts/tag_navigation_hover_scroll_qa.sh`：PASS。
- `bash Scripts/app_ordering_data_qa.sh`：PASS。
- `bash Scripts/quick_search_system_app_qa.sh`：PASS。
- `bash Scripts/apple_default_apps_resource_qa.sh`：PASS。
- `hdiutil verify build/TagLauncher-8.0.0-theme-preview-build20260624.1506.dmg`：PASS。
- DMG：
  - `src/build/TagLauncher-8.0.0-theme-preview-build20260624.1506.dmg`
- SHA256：
  - `c2704c435ef0b0ba8e3ea17824cbd3ffe89c118f34a966547b98ab6db96ebac5`

### QA 基础设施备注

- `Scripts/window_logic_qa.sh` 在本机 GUI 自动化环境中出现间歇性失败：
  - Dock 点击或全局热键偶发未触发 overlay。
  - Codex/输入法类 App 偶发抢前台，导致旧的 frontmost app 名断言误报。
- 已对该脚本做两类非产品逻辑加固：
  - Quick Search 结果坐标识别不再依赖固定窗口宽度，并在失败时输出窗口列表。
  - 前台 app 名断言降级为诊断信息，核心仍由窗口层级断言覆盖。
  - 启动与热键触发增加重试等待。
- 该脚本仍建议后续单独作为 QA 基础设施任务继续稳定化；本轮主题功能不依赖其失败点。

### 当前结论

- 8.0.0 主题系统代码已实现。
- 确定性 QA 已覆盖主题模型、设置入口、偏好迁移、多语种文案、构建签名、macOS 14 元数据、标签 hover、使用技巧、App 排序数据和系统 Quick Search 名称回归。
- 下一步需要用户实际体验 8 个主题的视觉效果，再决定是否冻结和打包。

### 2026-06-24 15:53 编辑模式主题对比度修正

- 用户反馈：亮色主题和黑色主题进入编辑模式后，顶部按钮、说明文字、确认按钮、标签列表和页面文字可读性不足。
- 第一版修正策略：
  - 编辑层控件接入主题高对比 token，深色主题白字、亮色主题深字。
- Build 更新为：`20260624.1553`。

### 2026-06-24 15:53 QA 与预览包

- `bash Scripts/theme_settings_qa.sh`：PASS。
- `bash Scripts/macos14_build_metadata_qa.sh`：PASS。
- `bash Scripts/macos14_availability_typecheck_qa.sh`：PASS。
- `APP_BUILD=20260624.1553 bash build.sh`：PASS。
- `codesign --verify --deep --strict --verbose=2 build/TagLauncher.app`：PASS。
- `bash Scripts/usage_tips_qa.sh`：PASS。
- `bash Scripts/tag_navigation_hover_scroll_qa.sh`：PASS。
- `bash Scripts/app_ordering_data_qa.sh`：PASS。
- `bash Scripts/apple_default_apps_resource_qa.sh`：PASS。
- `bash Scripts/quick_search_system_app_qa.sh`：PASS。
- 包内版本：`8.0.0 (20260624.1553)`，`LSMinimumSystemVersion=14.0`。
- `hdiutil verify build/TagLauncher-8.0.0-theme-preview-build20260624.1553.dmg`：PASS。
- DMG：
  - `src/build/TagLauncher-8.0.0-theme-preview-build20260624.1553.dmg`
- SHA256：
  - `543a2f26676f3e57aac0edb26353a8f90d38d3e0290dfd1c951e62b1f3e409ea`

### 2026-06-24 16:32 编辑模式主题策略简化

- 用户反馈：继续按主题适配编辑态仍然复杂，要求做减法。
- 新策略：
  - 用户进入编辑模式时，不管当前选择深蓝、黑色、粉色、绿色、炫彩或其他主题，App Grid 运行态渲染主题都临时切换为默认浅色毛玻璃。
  - 不写入 `appGridThemeID`，不改变设置页选择；退出编辑模式后自动恢复用户原主题。
  - App Grid 背景、AppKit collection renderer、编辑页顶部、标签列表、应用选择项都读取 `renderedAppGridTheme`。
  - `theme_settings_qa.sh` 增加运行态主题 override 检查，防止编辑态重新跟随用户主题。
- Build 更新为：`20260624.1632`。

### 2026-06-24 16:32 QA 与预览包

- `bash Scripts/theme_settings_qa.sh`：PASS。
- `bash Scripts/macos14_availability_typecheck_qa.sh`：PASS。
- `APP_BUILD=20260624.1632 bash build.sh`：PASS。
- `bash Scripts/macos14_build_metadata_qa.sh`：PASS。
- `codesign --verify --deep --strict --verbose=2 build/TagLauncher.app`：PASS。
- `bash Scripts/usage_tips_qa.sh`：PASS。
- `bash Scripts/tag_navigation_hover_scroll_qa.sh`：PASS。
- `bash Scripts/app_ordering_data_qa.sh`：PASS。
- `bash Scripts/quick_search_system_app_qa.sh`：PASS。
- `bash Scripts/apple_default_apps_resource_qa.sh`：PASS。
- 包内版本：`8.0.0 (20260624.1632)`，`LSMinimumSystemVersion=14.0`。
- `hdiutil verify build/TagLauncher-8.0.0-theme-preview-build20260624.1632.dmg`：PASS。
- DMG：
  - `src/build/TagLauncher-8.0.0-theme-preview-build20260624.1632.dmg`
- SHA256：
  - `34962ce1f3114a0b4979125fa92cd788833593ac19173365434c717bd8f159bc`

### 2026-06-24 17:31 App Grid 启动加载体验修复

- 用户反馈：每次启动/打开 App Grid 都出现转圈等待，观感不好，且此前类似问题曾修过。
- 根因结论：
  - App 启动时只预热 `AppIndexer` 的进程内扫描缓存。
  - 每次显示 App Grid 都会新建 `OverlayWindow + ContentView`，新的 `ContentView.allApps` 初始为空。
  - 在后台 `AppLibraryController.refresh()` 返回前，空态直接显示 `ProgressView`，因此用户能看到转圈。
  - 旧修复解决的是“缓存已热但新 ContentView 跳过 hydrate 导致 spinner 不消失”，没有解决冷启动或新面板首屏空态可见。
- 本轮修复：
  - `AppLibraryController` 保存最近一次完整 `AppLibrarySnapshot`。
  - `ContentView.refreshAppsForOverlay()` / `refreshAppsForQuickSearch()` 先复用最近快照，再后台刷新。
  - AppGrid 和编辑 AppGrid 的空态 spinner 改成 250ms 延迟显示；如果快照或扫描快速返回，不再闪现转圈。
  - 新增 `Scripts/appgrid_startup_loading_qa.sh` 锁住快照复用与延迟 spinner 规则。

### 2026-06-24 18:15 QA 与验收候选包

- 包类型：验收候选包，仅供用户安装验证；本轮未做源码冻结、commit 或 tag。
- Build 更新为：`20260624.1815`。
- `bash Scripts/theme_settings_qa.sh`：PASS。
- `bash Scripts/appgrid_startup_loading_qa.sh`：PASS。
- `bash Scripts/macos14_availability_typecheck_qa.sh`：PASS。
- `APP_BUILD=20260624.1815 bash build.sh`：PASS。
- `/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' build/TagLauncher.app/Contents/Info.plist`：`8.0.0`。
- `/usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' build/TagLauncher.app/Contents/Info.plist`：`20260624.1815`。
- `codesign --verify --deep --strict --verbose=2 build/TagLauncher.app`：PASS。
- `bash Scripts/macos14_build_metadata_qa.sh`：PASS，`LSMinimumSystemVersion=14.0`，`minos=14.0`，`arches=arm64`。
- `hdiutil verify build/TagLauncher-8.0.0-build20260624.1815.dmg`：PASS。
- DMG：
  - `src/build/TagLauncher-8.0.0-build20260624.1815.dmg`
- SHA256：
  - `373355c87055680cb13e873bc5909abd84817d9ac2eaa98cc1ec2748be64bc80`