企业官网建设流程全解析

CodMate 是一款开源的 macOS 原生应用，用 SwiftUI 管理 Codex、Claude Code、Gemini CLI 三大 AI 命令行工具的会话历史。它采用经典的 MVVM 分层架构，并以 Swift 的 actor 并发模型保护全部 IO 服务，是一套可直接借鉴的 SwiftUI macOS 架构范例。

上面这张截图展示了 CodMate 的紧凑三栏布局：左侧是项目树 + 日历导航，中间是会话列表，右侧是会话概览（Activity 图表、Token 统计、Recent Sessions）。整个界面由纯 SwiftUI 驱动，背后的状态编排全部交给 MVVM 各层处理。

一、CodMate 分层架构全景：先看清 4 层职责

CodMate 在 AGENTS.md 中明确定义了四层 MVVM 结构，这也是整个代码库（300+ 个 Swift 文件）的组织准则：

这种"Services 做脏活、ViewModels 做编排、Views 纯渲染"的切分，是理解 CodMate 架构的钥匙 👇

二、MVVM 四层职责划分与模块路径速查

1️⃣ Models 层：数据契约与状态容器

Models 层有两类成员：

• 纯数据结构：如 SessionSummary、SessionEvent、DateDimension、SessionLoadScope，它们全部是值类型（struct/enum），跨线程传递安全；
• ViewModel：27 个标注@MainActor的ObservableObject类，例如核心编排者 SessionListViewModel.swift（约 5000 行）和 GlobalSearchViewModel。

ViewModel 的关键模式是用@Published + didSet把 UI 事件"防抖"成异步任务，例如searchText的didSet会调用scheduleFulltextSearchIfNeeded()，而不是直接触发搜索。

2️⃣ Services 层：actor 守护的 IO 边界

Services 层是架构上最有看点的一层——磁盘扫描、全文搜索、SQLite 缓存、网络请求、Git 操作全部封装在 actor 中。以会话索引器 SessionIndexer.swift 为例：

actor SessionIndexer { private let cache = NSCache<NSURL, CacheEntry>() private let sqliteStore: SessionIndexSQLiteStore private var isRefreshing = false // 防并发刷新闸门 ... }

它内部实现了多级缓存（NSCache 内存缓存 + SQLite 磁盘索引 + mtime 增量判断），保证"今天"范围的会话刷新可以在毫秒级完成。类似的 actor 服务还有：

• GlobalSearchService.swift：⌘F 全局搜索，内部驱动 ripgrep 子进程，按 token 打分排序；
• SessionRipgrepStore.swift：Token 用量/日历覆盖度的按需扫描缓存；
• UpdateService.swift：版本检查，static let shared单例 + actor 隔离；
• GitService.swift：Project Review（Git Changes）的 diff/stage/commit 操作。

通过 SessionProvider.swift 定义的SessionProvider协议（kind/label/load(context:)），Codex、Claude、Gemini 三个数据源被统一抽象成可插拔的 Provider，新增一个 CLI 数据源只需实现一个协议。

3️⃣ ViewModels 层：@MainActor 上的异步编排器

SessionListViewModel 标注了@MainActor，它是 UI 状态的唯一事实来源：

• 持有@Published var sections: [SessionDaySection]等 UI 状态；
• 通过await indexer.refreshSessions(...)把重活丢给 actor，结果回主线程更新；
• 用filterTask/refreshDebounceTask/scopedRefreshTasks等 Task 句柄实现作用域级防抖与去重（防止并发重复刷新）；
• 文件事件通过DirectoryMonitor监听后聚合，再触发增量刷新。

4️⃣ Views 层：只做声明式渲染

ContentView.swift 用NavigationSplitView搭建三栏骨架，@ObservedObject绑定 ViewModel。视图内只保留@State级别的瞬态 UI 状态（选区、Popover 尺寸等），任何"取数据、算数据"的逻辑都不允许出现。子视图按功能拆分到views/Content/（主界面）、views/GitChanges/（Review 面板）、views/Wizard/（AI 向导）等目录，单文件不超过几百行。

三、actor 并发实战：Swift 6 下的线程安全策略

CodMate 使用 Swift 6 工具链构建（见 Package.swift 的swift-tools-version: 6.0），并发安全策略可以总结为"双轨制"：

┌─────────────┐ await（跨隔离边界） ┌──────────────────┐ │ @MainActor │ ──────────────────────▶ │ actor 服务层 │ │ ViewModel │ ◀────────────────────── │ SessionIndexer │ │ (UI 状态) │ Sendable 值类型 │ GlobalSearch... │ └─────────────┘ └──────────────────┘

• 主线程轨：所有 ViewModel 标@MainActor，保证 UI 状态只在一个线程被读写，彻底避免"视图更新期间改状态"的 SwiftUI 经典坑；
• actor 轨：39 个 actor 服务各自持有独立的可变状态（缓存字典、进程句柄、SQLite 句柄），外部只能通过await串行访问，天然免锁；
• 边界只传值类型：跨边界传递的SessionProviderContext、SessionProviderResult、UpdateState等全部声明为Sendable，让编译器替你把关数据竞争。

这套组合拳的效果是：开发者几乎不需要手写锁，编译器 + 隔离模型就消除了绝大部分并发 Bug。

四、性能优化清单：防抖、缓存与任务取消

从 CodMate 源码中可以直接抄作业的 6 个性能技巧 ✨

1. 多级缓存：NSCache（内存）→ SQLite（SessionIndexSQLiteStore）→ 文件系统（最后兜底），mtime 未变则跳过重解析；
2. 作用域防抖合并：按刷新范围（scope）key 化任务，scopedRefreshTasks让短时间内的同类刷新请求自动合并；
3. 任务取消贯穿：长搜索循环中每批检查Task.isCancelled，用户关掉搜索面板即可立即终止 ripgrep 进程；
4. 增量 Diff 更新：allSessions变化时只计算 cwd 计数的 delta，走applyDelta增量更新路径树，避免整树重建；
5. 并发刷新闸门：actor 内部isRefreshing标志 +defer复位，重入请求直接返回缓存数据；
6. 首屏快：默认只加载"Today"范围（SessionLoadScope），日历点选某天时走 SQLite 单日快速路径。

这些策略共同支撑了 README 中"468 条会话毫秒级索引"的体验。

五、SwiftPM 构建体系与目录结构

CodMate 是SwiftPM-only 构建（无 Xcode 工程），Package.swift 声明了 3 个 target：

外部依赖只有两个：本地路径依赖的GhosttyKit（内嵌 GPU 加速终端，见 ghostty/ 子包）和 MCP Swift SDK。入口 CodMateApp.swift 还有一个值得注意的细节：用Window而非WindowGroup强制单实例窗口，配合MenuBarController实现菜单栏/Dock 双模式。

完整目录速览：

• 应用入口：CodMateApp.swift
• 架构约定：AGENTS.md
• 功能清单文档：docs/feature-inventory.md
• 构建脚本：scripts/BUILD.md

六、从 CodMate 学到的 6 条架构经验

1. 分层纪律比框架更重要——"Views 不写业务逻辑、Services 不碰 UI 状态"这条红线比选什么 UI 库更决定项目寿命；
2. actor 是 Swift 并发的主力——IO 密集服务用 actor 封装，比 GCD + 锁更省心、更可测试；
3. @MainActor ViewModel + Sendable 边界——把 UI 状态收敛到主线程，跨边界只传值类型，是 Swift 6 严格并发检查下的黄金组合；
4. 缓存要分级——内存 → 磁盘 → 源文件三级回退，配合 mtime 失效判断，慢 IO 也能做出即时感；
5. 防抖与取消是体验的一半——Task 句柄 +Task.isCancelled检查，让用户的每一次快速操作都不产生垃圾计算；
6. 协议抽象数据源——SessionProvider一个协议就让三套异构 CLI 存储格式（JSONL / 项目目录 / 临时文件）并轨，扩展成本极低。

无论你想做 macOS 原生应用还是 SwiftUI 桌面工具，CodMate 的这套 "MVVM 分层 + actor 服务层 + 多级缓存" 架构都值得逐层研读——它证明了纯 Swift 技术栈完全能撑起一个生产级桌面产品 🚀