五层架构一览

一条铁律：依赖方向只能向下。 上层可以调用下层，下层永不反向依赖上层。

分层总览

┌───────────────────────────────────────────────┐
 App 层      入口 / 单实例保护 / CLI 解析
├───────────────────────────────────────────────┤
 Widget 层   MainWindow（瘦壳）/ 对话框 / 面板 / Manager
├───────────────────────────────────────────────┤
 Service 层  业务逻辑 + 数据校验（单例服务）
├───────────────────────────────────────────────┤
 Core 层     Entity / Plugin / Config / EventBus / Logger
├───────────────────────────────────────────────┤
 Utils 层    File / String / Gui / Json / Date 工具
└───────────────────────────────────────────────┘

层	职责
App	AgileApplication 启动流程、命令行解析、单实例保护。
Widget	UI 骨架。MainWindow 只搭菜单 / 工具栏 / Dock / 状态栏，业务逻辑下放到 Manager。
Service	业务逻辑与数据校验，网络 / 加密 / 脚本 / AI / 更新等单例服务。
Core	框架核心基础设施：实体、插件、配置类型系统、事件总线、命令栈、日志。
Utils	无状态工具函数，谁都能用。

数据流

用户交互 → Widget（MainWindow / Dialog）
            ↓ 信号
        Manager（ActionManager / ThemeManager…）
            ↓ 调用
        Service（业务逻辑 + 校验）
            ↓ 调用
        Core（Entity / Repository / QueryBuilder）
            ↓ SQL
        Database（内存库 ← 高频读 | 磁盘库 ← 持久化）

Manager 拆分：拒绝 God Object

借鉴 QOwnNotes，MainWindow 是「瘦壳」，职责拆进独立 Manager—— ThemeManager · LayoutManager · ActionManager · PluginManager · SessionManager。 每个 Manager 只管一摊事，MainWindow 超过 500 行就该拆。

跨模块通信：EventBus

Manager 之间不互相摸内部状态，而是通过 EventBus 发布 / 订阅解耦：

模块 A ──publish──→ EventBus ──notify──→ 模块 B（订阅者）
                              ──notify──→ 模块 C（订阅者）

平台隔离

平台相关代码（#ifdef Q_OS_WIN / MACOS / LINUX）只允许出现在 platform/ 目录， 上层一律通过 PlatformHelper 接口调用——这保证了跨平台一致性。