edit | blame | history | raw

TagLauncher CODEGRAPH

最后更新：2026-06-25

用途：本文件是 TagLauncher 的长期工程地图。修改用户可见行为、状态模型、构建/发布入口、核心源码或 QA 入口前，应先读本文件，再读指向的真实源码。若本文件与源码不一致，以源码为准，并在同一任务内更新本文件。

项目边界

  • 仓库根目录：/Users/ar/Projects/Taglauncher
  • 唯一源码根目录：/Users/ar/Projects/Taglauncher/src
  • macOS App 源码：src/Apptag/
  • 构建入口：src/build.sh
  • DMG 打包入口：src/make_dmg.sh
  • 发布资料：src/Release/
  • QA 脚本：src/Scripts/

核心入口

  • src/Apptag/ApptagApp.swift
  • TagLauncherApp：SwiftUI App 入口。
  • AppDelegate：菜单栏状态项、Dock 显示策略、热键注册、窗口打开、Quick Search 触发、App 生命周期。
  • 支持从标签导航双击进入设置页的 Tags tab。
  • src/Apptag/OverlayWindowController.swift
  • OverlayPanel / OverlayWindowController：AppGrid 浮层窗口与显示/隐藏控制。
  • src/Apptag/ContentView.swift
  • ContentView：AppGrid 主界面、标签导航、编辑模式、拖拽处理、Quick Search 数据刷新、使用技巧浮层入口。
  • 读取 appGridThemeID 并负责 AppGrid 全屏主题背景渲染。
  • 编辑模式使用 runtime theme override：任何主题下进入编辑都临时显示默认浅色毛玻璃。
  • 使用最近一次完整 AppLibrarySnapshot 先渲染 AppGrid，再后台刷新，避免启动/重开时立刻显示转圈。
  • 使用技巧关闭提醒由 ContentView 统一弹 modal 并写入 hideUsageTips / skipUsageTipsCloseReminder。
  • src/Apptag/PreferencesView.swift
  • PreferencesView：设置窗口、语言、通用、主题、快捷键、标签、数据、关于等设置页。
  • Theme tab 只写视觉偏好 appGridThemeID，不得改变标签、排序、备注或分类数据。

AppGrid 显示与交互

  • src/Apptag/AppGridCollectionView.swift
  • AppGridCollectionView：SwiftUI 到 AppKit NSCollectionView 的桥接。
  • AppGridCollectionHostView：滚动容器、背景/使用技巧层、空白拖放处理。
  • AppGridGroupCollectionItem / AppGridGroupCardView：分组容器、图标布局、分组标题、hover/高亮、容器内拖放。
  • AppGridIconNSView：应用图标单元、点击、hover 气泡、拖拽起点。
  • 底部使用技巧是原生 AppKit overlay，不允许改成 SwiftUI；必须拦截自身点击区域。
  • 不拥有 AppGrid 全屏渐变背景，只接收 theme 推导出的玻璃和文本可读性 token。
  • src/Apptag/AppGridTheme.swift
  • AppGrid 主题事实源：theme id、localization key、设置页 swatch、全屏渐变背景、玻璃明暗、编辑模式 token。
  • 持久化 key：appGridThemeID。
  • src/Apptag/AppGridSupport.swift
  • 图标气泡、基础 metrics、气泡 placement 支撑。
  • src/Apptag/TagNavigationView.swift
  • AppKit 标签导航栏，支持标签 hover 滚动、选中、拖放、双击进入标签设置页。
  • src/Apptag/AppDragCoordinator.swift
  • 全局拖拽目标注册、命中判断、容器间拖放、容器外空白移除标签。
  • 拖到容器外/容器之间空白区域时显示 Core Animation 碎纸预览；容器内部空白不触发解除标签预览。

数据层

  • src/Apptag/DataLayer.swift
  • AppInfo：应用模型。
  • AppDisplayNameResolver：多语言应用显示名解析。
  • AppIndexer：扫描 /Applications 等应用来源，处理 bundle / wrapper / localized display name。
  • TagGroup / TagColor：标签分组与颜色。
  • TagDatabase：标签、备注、隐藏状态、分类方案、导入导出、备份和持久化。
  • TagEditor：把数据库中的标签/备注/隐藏状态标注回扫描到的 App 列表。
  • src/Apptag/AppLibraryController.swift
  • App 刷新、SmartStart 应用、系统分类方案应用、重置未分类等业务入口。
  • 持有最近一次完整 AppLibrarySnapshot，供新建 overlay 立即复用。
  • src/Apptag/AppDefaults.swift
  • UserDefaults 默认值注册与 schema 默认处理。
  • 旧 useDarkAppGrid=true 在没有新 theme key 时迁移到 appGridThemeID=deepBlue。
  • hideUsageTips 默认 false；skipUsageTipsCloseReminder 默认 false。

Quick Search 与快捷键

  • src/Apptag/QuickSearch.swift
  • LauncherHotkey / LauncherHotkeyKind：主面板和 Quick Search 快捷键定义。
  • LauncherHotkeyRegistrationStore：快捷键注册状态持久化。
  • QuickSearchDocument / QuickSearchEngine：搜索索引与排序。
  • QuickSearchPanelPresentationView / QuickSearchOverlayView / QuickSearchResultListHostView：Quick Search 浮层 UI 与结果列表。

智能分类与 Apple 默认应用资料

  • src/Apptag/SmartCategorization/SmartCategory.swift
  • 内置智能分类定义。
  • src/Apptag/SmartCategorization/SmartCategorizationDraft.swift
  • 智能分类草稿、默认备注 provenance、未分配应用和 warning 模型。
  • src/Apptag/SmartCategorization/SmartStartService.swift
  • SmartStart 初始化、catalog/notes 快照加载、分类结果生成。
  • src/Apptag/AppleDefaultAppCatalog.swift
  • Apple 自带应用分类和本地化备注 catalog 加载。
  • src/Apptag/SmartStartNoticeOverlay.swift
  • 首次智能整理提示弹窗。

本地化与文档

  • src/Apptag/L10n.swift
  • 语言选择、translation JSON 加载、帮助文档入口。
  • src/Apptag/Localization/*.json
  • App UI 本地化文案。新增用户可见文案时必须覆盖全部 29 个语言文件，并验证 JSON 合法。
  • src/Apptag/Resources/
  • SmartStart、Apple default catalog、帮助文档等运行时资源。
  • src/Docs/Requirements/
  • 需求 todo、工作日志、QA 记录和重要实现结论。

构建与发布

  • src/Apptag/Info.plist
  • App 版本、build、bundle metadata。
  • src/Apptag/TagLauncher.entitlements
  • App sandbox / entitlement 配置。
  • src/build.sh
  • 构建 .app 的主入口。
  • src/make_dmg.sh
  • 生成 DMG 的主入口。
  • src/Release/
  • 发布归档、App Store Connect metadata、审核说明、QA 证据。

主要 QA 入口

  • src/Scripts/macos14_availability_typecheck_qa.sh
  • macOS 14 API 可用性/typecheck 检查。
  • src/Scripts/macos14_build_metadata_qa.sh
  • build metadata 检查。
  • src/Scripts/apple_default_apps_resource_qa.sh
  • Apple 默认应用 catalog 资源检查。
  • src/Scripts/apple_default_note_policy_qa.sh
  • Apple 默认备注语言/策略检查。
  • src/Scripts/apple_default_note_migration_qa.sh
  • Apple 默认备注迁移检查。
  • src/Scripts/smartstart_catalog_resource_qa.sh
  • SmartStart catalog 资源检查。
  • src/Scripts/quick_search_app_name_qa.sh
  • Quick Search 应用显示名回归。
  • src/Scripts/quick_search_system_app_qa.sh
  • Quick Search 系统应用回归。
  • src/Scripts/tag_navigation_hover_scroll_qa.sh
  • 标签导航 hover 滚动回归。
  • src/Scripts/tag_double_click_preferences_qa.sh
  • 标签双击进入标签设置页回归。
  • src/Scripts/theme_settings_qa.sh
  • 8 个主题、Theme tab、旧深色偏好迁移、编辑模式默认浅色 override、29 语种主题文案回归。
  • src/Scripts/appgrid_startup_loading_qa.sh
  • AppGrid 快照复用和延迟转圈回归。
  • src/Scripts/usage_tips_qa.sh
  • AppGrid 使用技巧 AppKit 横幅、主题可读性、防穿透、关闭按钮、29 语种文案回归。
  • src/Scripts/usage_tips_close_reminder_qa.sh
  • 使用技巧关闭提醒、modal 防穿透、设置页预览、29 语种文案回归。
  • src/Scripts/window_logic_qa.sh
  • 窗口层级、显示隐藏、Dock/菜单栏相关逻辑回归。
  • src/Scripts/app_ordering_data_qa.sh
  • App 排序数据持久化回归。

受保护行为

  • 不得擅自改变源码根目录边界：App 源码只在 src/ 下维护。
  • 不得把主题、视觉偏好、窗口状态混入 TagDatabase 的分类/标签业务数据。
  • 主题变化只允许影响 AppGrid 视觉，不得改变标签数据、排序、备注、SmartStart/category scheme、Quick Search、拖拽语义或导入导出。
  • 默认主题必须保留原浅色毛玻璃 AppGrid。
  • 黑色主题背景必须为 100% 纯黑；深蓝和黑色使用深色玻璃；粉色、紫色、绿色、蓝色、炫彩使用浅色玻璃以保证明亮和可读。
  • 单个 AppGrid 容器保持统一半透明玻璃面板，不做容器内部渐变。
  • 编辑模式无论当前主题是什么，都临时渲染为默认浅色毛玻璃，退出编辑后恢复用户主题。
  • 旧用户 useDarkAppGrid=true 必须迁移到 deepBlue 主题。
  • AppGrid 启动或重开不应因为新 ContentView 初始 allApps.isEmpty 立刻显示转圈；应先复用最近一次完整快照，并延迟显示 loading。
  • Quick Search 显示标题应优先使用解析后的 AppInfo.displayName，内部 bundle 名只作为搜索字段。
  • Apple 默认应用备注必须按当前语言显示，不允许 A 语言出现 B 语言备注。
  • 标签导航单击必须立即滚动；hover 必须保持受控自动滚动；长按排序必须保留；双击可以打开标签设置页但不得替代前三者。
  • 容器外空白拖放才可触发解除标签；容器内部空白不算解除标签。
  • 拖到解除标签区域的碎纸预览只能是视觉反馈，不能跳过放手后的原确认流程。
  • AppGrid 使用技巧浮层必须拦截自身点击，不能穿透到底层应用图标，也不能导致 AppGrid 消失。
  • 使用技巧必须保持原生 AppKit overlay，不改为 SwiftUI；只有箭头 hit 区域能翻页。
  • 使用技巧标题/正文在默认、深色、亮色主题下都必须可读，且 29 语种文案完整。
  • 关闭使用技巧时应先显示提醒；确认后才写入隐藏状态；“不再提醒”只在用户明确勾选并确认后生效。
  • 设置页应避免依赖不同 macOS 版本表现不一致的 SwiftUI 默认 TabView 外观。
  • macOS 14 兼容是当前发布目标之一，新增 API 或 UI 技术选择必须考虑 macOS 14。

修改提醒

  • 改 ContentView.swift 通常会影响 AppGrid 主流程、编辑模式、Quick Search 数据刷新或浮层层级，必须做对应 smoke。
  • 改 AppGridCollectionView.swift 通常会影响 AppGrid 布局、拖拽、hover、使用技巧、容器显示和性能，必须扩大视觉/交互回归。
  • 改 AppGridTheme.swift 必须验证全部主题、编辑模式 override、亮/暗玻璃可读性和设置页文案。
  • 改 DataLayer.swift 通常会影响应用扫描、显示名、标签数据、导入导出和迁移，必须补数据 QA。
  • 改 PreferencesView.swift 通常需要检查 29 个本地化 JSON、设置持久化和 macOS 14 UI 表现。
  • 改 ApptagApp.swift 或 OverlayWindowController.swift 必须回归菜单栏、Dock 图标策略、热键、窗口层级、全屏/Split View 行为。