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

2026-06-24 23:41 使用技巧横幅重设计

• 用户确认最终方案：
• 布局选“2 分区式教学横幅”。
• 亮色主题使用浅玻璃配色。
• 深色/黑色主题使用同样布局，但切换到深色玻璃材质和白色文字。
• 角色分工结论：
• 架构：继续使用原生 AppKit AppGridUsageTipsNSView，不引入 SwiftUI；tips 跟随 renderedAppGridTheme，编辑模式仍继承默认浅色主题 override。
• 代码审核：保留全宽透明 shield 和 local mouse monitor，避免点击穿透到底层 AppGrid；箭头只在命中区域触发翻页。
• QA：更新 usage_tips_qa.sh，覆盖分区式布局、主题配色、关闭按钮、全宽事件拦截、29 语种文案和 macOS 14 兼容。
• 本轮实现：
• 使用技巧横幅底部横向占满可用宽度。
• 左侧独立标题面板显示灯泡图标、技巧编号和标题。
• 中央正文区域展示两行动作说明，保留长文本横向滚动能力。
• 右侧固定上一条/下一条按钮，页点移动到箭头下方。
• 右上角新增弱视觉关闭按钮；默认半透明，hover/press 更清晰；点击后写入 hideUsageTips。
• updateColors() 按 AppGridTheme.usesDarkGlass 切换浅玻璃/深玻璃 token。
• 29 个语种新增 usageTips.close。
• QA：
• bash Scripts/usage_tips_qa.sh：PASS。
• bash Scripts/macos14_availability_typecheck_qa.sh：PASS。
• git diff --check：PASS。
• bash build.sh：PASS，生成 src/build/TagLauncher.app。
• bash Scripts/macos14_build_metadata_qa.sh：PASS，LSMinimumSystemVersion=14.0，minos=14.0，arches=arm64。
• codesign --verify --deep --strict --verbose=2 build/TagLauncher.app：PASS。
• 构建产物版本：8.0.2 (20260625.1322)。
• bash Scripts/theme_settings_qa.sh：PASS。
• bash Scripts/tag_navigation_hover_scroll_qa.sh：PASS。
• bash Scripts/macos14_availability_typecheck_qa.sh：PASS。
• APP_BUILD=20260624.2331 bash build.sh：PASS。

2026-06-25 使用技巧横幅 26.0625-2 视觉优化

• 需求来源：canvas/26.06-UI调整.excalidraw frame 26.0625-2。
• 用户标注问题：
• 标题区空间充裕但排版仍显拥挤。
• 标题字号偏小，需要适当放大并加粗，同时不能撑破 29 语种矩形空间。
• 标题字色需要按主题优化，必须保持清晰可读。
• 标题前 icon 不应固定为单一灯泡，需要按技巧类型变化。
• 正文超过一行时应采用 ordered list 样式。
• 第 1 条标题改为“编辑标签”，正文补充“打开设置切换到标签编辑”和“在标签列表双击标签快速进入标签编辑页”。
• 以上文案修改覆盖 29 个语种。
• 本轮实现：
• AppGridUsageTipsNSView 标题字号从 22 semibold 调整为 25 bold。
• 左侧标题面板宽度从 300-380pt 扩展为 350-460pt，降低长语种标题换行/挤压风险。
• 标题和 icon 改为按 AppGridTheme 取高对比 accent；深蓝/黑色主题继续使用白字优先。
• 按 tip id 切换语义 SF Symbol：编辑标签、套用标签、移动、复制、移除、排序、备注等不再共用灯泡 icon。
• 正文 formatter 保留分隔符转换规则，并在多段内容时自动渲染为 1. / 2. 编号步骤。
• 第 1 条使用技巧 29 个语种 title/detail 已同步更新。
• Scripts/usage_tips_qa.sh 增加标题字号、标题面板宽度、语义 icon、主题 accent、ordered list 和第 1 条双击标签说明检查。
• QA：
• bash Scripts/usage_tips_qa.sh：PASS。
• bash Scripts/macos14_build_metadata_qa.sh：PASS，LSMinimumSystemVersion=14.0，minos=14.0，arches=arm64。
• bash Scripts/appgrid_startup_loading_qa.sh：PASS。
• bash Scripts/app_ordering_data_qa.sh：PASS。
• bash Scripts/apple_default_note_policy_qa.sh：PASS。
• bash Scripts/apple_default_apps_resource_qa.sh：PASS。
• bash Scripts/quick_search_app_name_qa.sh：SKIP，本机没有 /Applications/贝锐向日葵被控.app fixture。
• bash Scripts/window_logic_qa.sh：未作为本轮通过项；脚本在 Dock tile 去重检查处失败，退出后无 TagLauncher 进程残留，判断为 GUI/Dock 可访问性环境或既有 QA 基础设施问题，和本轮使用技巧横幅代码路径无直接交集。
• 版本推进到：8.0.2 / 20260624.2341。