# 应用生命周期

<cite>
**本文引用的文件**
- [electron/main.ts](file://electron/main.ts)
- [electron/preload.ts](file://electron/preload.ts)
- [src/types/electron.d.ts](file://src/types/electron.d.ts)
- [scripts/build-electron.mjs](file://scripts/build-electron.mjs)
- [electron-builder.json](file://electron-builder.json)
- [next.config.ts](file://next.config.ts)
- [package.json](file://package.json)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/forge-data.ts](file://src/lib/forge-data.ts)
- [src/hooks/use-settings.ts](file://src/hooks/use-settings.ts)
- [src/app/api/settings/route.ts](file://src/app/api/settings/route.ts)
- [src/lib/cron/engine.ts](file://src/lib/cron/engine.ts)
- [src/lib/im/bridge-manager.ts](file://src/lib/im/bridge-manager.ts)
- [src/lib/im/adapters/telegram.ts](file://src/lib/im/adapters/telegram.ts)
- [src/lib/sdk/permission-bridge.ts](file://src/lib/sdk/permission-bridge.ts)
- [src/components/layout/app-layout.tsx](file://src/components/layout/app-layout.tsx)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件系统性梳理该 Electron 应用的生命周期管理，覆盖应用启动序列、窗口激活与关闭流程、服务器启动时机与资源清理；解释多窗口激活、后台运行与系统集成行为；阐述应用状态持久化、配置管理与用户偏好存储；并提供生命周期事件监控、性能优化与稳定性保障方案。

## 项目结构
- 主进程入口：electron/main.ts 负责应用生命周期事件、窗口创建、IPC 注册、本地服务器启动与清理。
- 预加载脚本：electron/preload.ts 暴露受限 API 到渲染进程，提供数据目录、文件系统监听、剪贴板与路径操作等能力。
- 类型定义：src/types/electron.d.ts 声明暴露给渲染进程的 API 接口。
- 构建与打包：scripts/build-electron.mjs 执行 Electron 主进程与预加载脚本构建、打包 Node 运行时、修复 pnpm hoisting、剥离开发机路径、复制模板与静态资源；electron-builder.json 定义打包目标、权限与签名配置。
- Next.js 配置：next.config.ts 输出独立可执行服务（standalone），禁用压缩以适配 SSE 流。
- 数据与配置：src/lib/db.ts 初始化数据库与迁移；src/lib/forge-data.ts 统一数据目录来源；src/hooks/use-settings.ts 与 /api/settings 提供设置读写与跨实例同步。
- 实时 IM 桥接：src/lib/im/bridge-manager.ts 管理通道连接、重连与电路保护；适配器层（如 Telegram）实现轮询与指数退避。
- 应用布局：src/components/layout/app-layout.tsx 处理视图切换、SSE 订阅、拖拽阻止与全局事件监听。

```mermaid
graph TB
subgraph "主进程"
M["electron/main.ts"]
P["electron/preload.ts"]
end
subgraph "渲染进程"
L["src/components/layout/app-layout.tsx"]
end
subgraph "构建与打包"
B["scripts/build-electron.mjs"]
EB["electron-builder.json"]
NC["next.config.ts"]
end
subgraph "数据与配置"
DB["src/lib/db.ts"]
FD["src/lib/forge-data.ts"]
S1["src/hooks/use-settings.ts"]
S2["src/app/api/settings/route.ts"]
end
M --> P
M --> L
B --> M
EB --> M
NC --> M
L --> S1
S1 --> S2
L --> DB
DB --> FD
```

**图表来源**
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)
- [scripts/build-electron.mjs:381-399](file://scripts/build-electron.mjs#L381-L399)
- [electron-builder.json:1-126](file://electron-builder.json#L1-L126)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:20-26](file://src/lib/forge-data.ts#L20-L26)
- [src/hooks/use-settings.ts:10-55](file://src/hooks/use-settings.ts#L10-L55)
- [src/app/api/settings/route.ts:36-48](file://src/app/api/settings/route.ts#L36-L48)

**章节来源**
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)
- [scripts/build-electron.mjs:381-399](file://scripts/build-electron.mjs#L381-L399)
- [electron-builder.json:1-126](file://electron-builder.json#L1-L126)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:20-26](file://src/lib/forge-data.ts#L20-L26)
- [src/hooks/use-settings.ts:10-55](file://src/hooks/use-settings.ts#L10-L55)
- [src/app/api/settings/route.ts:36-48](file://src/app/api/settings/route.ts#L36-L48)

## 核心组件
- 主进程生命周期与窗口管理：注册 IPC、创建窗口、处理窗口关闭与激活事件、启动本地服务器、清理资源。
- 预加载桥接：在隔离上下文中暴露受控 API，统一数据目录、文件系统监听、剪贴板与路径操作。
- 本地服务器：生产环境使用独立 Node.js 进程运行 Next.js standalone 服务，避免原生模块 ABI 兼容问题。
- 数据与配置：统一数据目录、数据库初始化与迁移、设置读写与跨实例同步。
- 实时 IM 桥接：通道管理、指数退避重连、电路保护、会话活动清理与审计日志。
- 应用布局与事件：视图切换、SSE 订阅、拖拽阻止、全局事件分发与订阅。

**章节来源**
- [electron/main.ts:177-311](file://electron/main.ts#L177-L311)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:20-26](file://src/lib/forge-data.ts#L20-L26)
- [src/hooks/use-settings.ts:10-55](file://src/hooks/use-settings.ts#L10-L55)
- [src/lib/im/bridge-manager.ts:531-634](file://src/lib/im/bridge-manager.ts#L531-L634)
- [src/components/layout/app-layout.tsx:187-244](file://src/components/layout/app-layout.tsx#L187-L244)

## 架构总览
应用采用“主进程 + 渲染进程 + 独立本地服务器”的三层架构：
- 主进程负责应用生命周期、窗口与 IPC、本地服务器启动与清理。
- 渲染进程承载 UI 逻辑与业务视图，通过预加载桥接访问受限系统能力。
- 本地服务器提供 Next.js standalone 服务，渲染进程通过 HTTP 与之交互；IM 桥接通过 SSE 实时同步消息。

```mermaid
graph TB
A["Electron 主进程<br/>electron/main.ts"] --> W["BrowserWindow<br/>窗口"]
A --> S["本地服务器<br/>Next.js standalone"]
A --> I["IPC 通道<br/>electron/preload.ts"]
I --> R["渲染进程 UI<br/>src/components/layout/app-layout.tsx"]
R --> API["设置 API<br/>/api/settings"]
API --> DB["数据库<br/>src/lib/db.ts"]
DB --> DATA["数据目录<br/>~/.forge<br/>src/lib/forge-data.ts"]
R --> IM["IM 桥接 SSE<br/>实时事件"]
IM --> BM["BridgeManager<br/>重连/电路保护"]
```

**图表来源**
- [electron/main.ts:141-175](file://electron/main.ts#L141-L175)
- [electron/main.ts:272-289](file://electron/main.ts#L272-L289)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)
- [src/components/layout/app-layout.tsx:187-244](file://src/components/layout/app-layout.tsx#L187-L244)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:20-26](file://src/lib/forge-data.ts#L20-L26)
- [src/lib/im/bridge-manager.ts:531-634](file://src/lib/im/bridge-manager.ts#L531-L634)

## 详细组件分析

### 启动序列与服务器启动时机
- 开发模式：主进程就绪后直接加载本地 3000 端口。
- 生产模式：主进程启动独立 Node.js 子进程运行 standalone server.js，等待服务就绪后再创建窗口。
- 服务器启动前扩展 PATH，确保 SDK 可发现外部 CLI；设置数据目录与资源路径环境变量；捕获子进程输出与退出事件；超时检测保证可用性。

```mermaid
sequenceDiagram
participant App as "Electron 应用"
participant Main as "主进程 main.ts"
participant Child as "子进程 Node"
participant Win as "BrowserWindow"
App->>Main : "app.whenReady()"
Main->>Main : "findNodeBinary()/getFreePort()"
Main->>Child : "spawn(server.js)"
Child-->>Main : "stdout/stderr 回调"
Main->>Main : "waitForServer(url)"
Main->>Win : "createWindow(serverUrl)"
Win-->>App : "ready-to-show 显示"
```

**图表来源**
- [electron/main.ts:74-139](file://electron/main.ts#L74-L139)
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [scripts/build-electron.mjs:214-292](file://scripts/build-electron.mjs#L214-L292)

**章节来源**
- [electron/main.ts:74-139](file://electron/main.ts#L74-L139)
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [scripts/build-electron.mjs:214-292](file://scripts/build-electron.mjs#L214-L292)

### 窗口激活流程与多窗口行为
- 窗口创建：设置最小尺寸、标题栏样式、背景色、预加载脚本与安全参数；首次 ready-to-show 时显示。
- 外链处理：拦截新窗口请求，统一通过系统默认浏览器打开。
- 窗口关闭：监听 closed 事件，清空主窗口引用。
- 激活事件：macOS 在无窗口时通过 activate 事件重建窗口，确保单实例行为一致。

```mermaid
flowchart TD
Start(["应用就绪"]) --> Create["创建 BrowserWindow"]
Create --> Ready["ready-to-show 显示"]
Ready --> Open["外链统一由系统打开"]
Open --> Closed{"窗口关闭?"}
Closed --> |是| NullRef["清空主窗口引用"]
Closed --> |否| Active{"系统激活?"}
Active --> |是| Rebuild["重建窗口"]
Active --> |否| Idle["保持状态"]
```

**图表来源**
- [electron/main.ts:141-175](file://electron/main.ts#L141-L175)
- [electron/main.ts:291-299](file://electron/main.ts#L291-L299)

**章节来源**
- [electron/main.ts:141-175](file://electron/main.ts#L141-L175)
- [electron/main.ts:291-299](file://electron/main.ts#L291-L299)

### 服务器启动与资源清理
- 服务器启动：独立子进程运行 standalone/server.js，注入环境变量（数据目录、资源路径、PATH 扩展）；捕获 stdout/stderr 并忽略 EPIPE；监听 exit 事件回收引用。
- 资源清理：before-quit 时关闭文件系统监听器、终止子进程，避免僵尸进程与句柄泄漏。

```mermaid
flowchart TD
A["before-quit 事件"] --> C1["关闭文件系统监听器"]
A --> C2["终止子进程"]
C2 --> Exit["子进程退出回调清理引用"]
```

**图表来源**
- [electron/main.ts:301-310](file://electron/main.ts#L301-L310)
- [electron/main.ts:120-135](file://electron/main.ts#L120-L135)

**章节来源**
- [electron/main.ts:301-310](file://electron/main.ts#L301-L310)
- [electron/main.ts:120-135](file://electron/main.ts#L120-L135)

### 窗口关闭事件处理与退出策略
- 单窗口应用：window-all-closed 时调用 app.quit，确保退出。
- 多窗口场景：当前实现仅维护一个主窗口；若未来扩展为多窗口，需在每个窗口 closed 时判断是否需要退出。

**章节来源**
- [electron/main.ts:291-293](file://electron/main.ts#L291-L293)

### 系统集成与后台运行
- macOS 激活：activate 事件用于重建窗口，符合平台行为。
- 外链处理：统一通过系统默认浏览器打开，避免渲染进程导航。
- 文件系统监听：通过 IPC 将变更事件推送到渲染进程，支持去抖与忽略特定目录。

**章节来源**
- [electron/main.ts:295-299](file://electron/main.ts#L295-L299)
- [electron/main.ts:165-170](file://electron/main.ts#L165-L170)
- [electron/main.ts:191-219](file://electron/main.ts#L191-L219)

### 应用状态持久化与配置管理
- 数据库：初始化 WAL 模式与外键约束，创建核心表与索引，并执行多版本迁移；提供 MCP 服务器同步与审计日志表。
- 数据目录：统一从环境变量或用户主目录获取，自动迁移旧目录数据。
- 设置：渲染侧通过自定义事件跨实例同步；API 层支持批量 upsert。

```mermaid
erDiagram
SETTINGS {
text key PK
text value
}
SESSIONS {
text id PK
text title
text workspace
text model
text status
text created_at
text updated_at
}
MESSAGES {
text id PK
text session_id FK
text role
text content
text created_at
}
WORKSPACES {
text id PK
text path UNQ
text last_opened_at
text created_at
}
API_PROVIDERS {
text id PK
text name
text provider
text api_key
text base_url
text model_name
text status
text status_error
text created_at
text updated_at
}
SESSIONS ||--o{ MESSAGES : "包含"
WORKSPACES ||--o{ SESSIONS : "拥有"
```

**图表来源**
- [src/lib/db.ts:25-224](file://src/lib/db.ts#L25-L224)

**章节来源**
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:20-26](file://src/lib/forge-data.ts#L20-L26)
- [src/hooks/use-settings.ts:10-55](file://src/hooks/use-settings.ts#L10-L55)
- [src/app/api/settings/route.ts:36-48](file://src/app/api/settings/route.ts#L36-L48)

### 用户偏好存储与跨实例同步
- 渲染侧：useSettings 提供获取、更新与跨实例同步（DOM 自定义事件）。
- API 侧：/api/settings 支持批量写入，事务性保证一致性。

**章节来源**
- [src/hooks/use-settings.ts:10-55](file://src/hooks/use-settings.ts#L10-L55)
- [src/app/api/settings/route.ts:36-48](file://src/app/api/settings/route.ts#L36-L48)

### 生命周期事件监控与性能优化
- SSE 订阅：渲染侧建立一次 EventSource 连接，使用 ref 避免闭包陈旧；异常时自动重连。
- 性能优化：Next.js standalone 关闭压缩以适配 SSE；窗口最小尺寸与 ready-to-show 控制首屏体验；文件系统监听去抖减少频繁通知。

**章节来源**
- [src/components/layout/app-layout.tsx:187-244](file://src/components/layout/app-layout.tsx#L187-L244)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)

### 稳定性保障与错误恢复策略
- IM 桥接：指数退避重连、电路保护（连续失败触发暂停）、会话活动清理与审计日志。
- 任务调度：Cron 引擎失败记录到任务执行表，便于诊断与回溯。
- 服务器健康：超时检测与 EPIPE 安全处理，避免崩溃。

```mermaid
flowchart TD
E["连接异常/错误"] --> Cnt["累计连续错误次数"]
Cnt --> |达到阈值| CB["电路保护：暂停N分钟"]
Cnt --> |未达阈值| Backoff["指数退避重试+抖动"]
CB --> Resume["到期后半开试探"]
Backoff --> Success{"重连成功?"}
Success --> |是| OK["恢复运行"]
Success --> |否| Backoff
```

**图表来源**
- [src/lib/im/bridge-manager.ts:555-601](file://src/lib/im/bridge-manager.ts#L555-L601)
- [src/lib/im/adapters/telegram.ts:283-318](file://src/lib/im/adapters/telegram.ts#L283-L318)
- [src/lib/sdk/permission-bridge.ts:224-261](file://src/lib/sdk/permission-bridge.ts#L224-L261)
- [src/lib/cron/engine.ts:91-120](file://src/lib/cron/engine.ts#L91-L120)

**章节来源**
- [src/lib/im/bridge-manager.ts:531-634](file://src/lib/im/bridge-manager.ts#L531-L634)
- [src/lib/im/adapters/telegram.ts:283-318](file://src/lib/im/adapters/telegram.ts#L283-L318)
- [src/lib/sdk/permission-bridge.ts:224-261](file://src/lib/sdk/permission-bridge.ts#L224-L261)
- [src/lib/cron/engine.ts:91-120](file://src/lib/cron/engine.ts#L91-L120)

## 依赖关系分析
- 构建阶段：build-electron.mjs 负责 Electron 主进程与预加载脚本构建、Node 运行时打包、原生模块重建、symlink 解析与 hoisting 修复、路径剥离与模板复制。
- 打包阶段：electron-builder.json 定义输出目录、额外资源、asar、签名与平台目标。
- 运行时：Next.js standalone 作为本地服务器，主进程通过子进程管理；预加载桥接提供受限系统能力。

```mermaid
graph LR
TS["electron/main.ts"] --> JS["dist-electron/main.js"]
PT["electron/preload.ts"] --> PJ["dist-electron/preload.js"]
BE["scripts/build-electron.mjs"] --> TS
BE --> PT
EB["electron-builder.json"] --> Out["release/"]
BE --> Stand["standalone/"]
EB --> Stand
```

**图表来源**
- [scripts/build-electron.mjs:6-32](file://scripts/build-electron.mjs#L6-L32)
- [scripts/build-electron.mjs:381-399](file://scripts/build-electron.mjs#L381-L399)
- [electron-builder.json:19-55](file://electron-builder.json#L19-L55)

**章节来源**
- [scripts/build-electron.mjs:6-32](file://scripts/build-electron.mjs#L6-L32)
- [scripts/build-electron.mjs:381-399](file://scripts/build-electron.mjs#L381-L399)
- [electron-builder.json:19-55](file://electron-builder.json#L19-L55)

## 性能考量
- 首屏体验：窗口 ready-to-show 再显示，避免白屏；最小尺寸限制保证可用区域。
- SSE 适配：禁用压缩以避免缓冲与流中断。
- 文件监听：递归监听配合去抖与忽略列表，降低事件风暴。
- 服务器健康：超时检测与 EPIPE 容错，避免主进程阻塞。

**章节来源**
- [electron/main.ts:161-163](file://electron/main.ts#L161-L163)
- [next.config.ts:5](file://next.config.ts#L5)
- [electron/main.ts:204-215](file://electron/main.ts#L204-L215)
- [electron/main.ts:120-135](file://electron/main.ts#L120-L135)

## 故障排查指南
- 服务器启动失败：检查 Node 版本与 PATH 扩展；查看子进程 stderr 日志；确认端口占用与防火墙。
- 窗口无法重建：确认 macOS activate 事件处理；检查 serverUrl 是否已设置。
- 文件监听无效：确认目录路径有效且不在忽略列表中；检查去抖时间与权限。
- 设置不同步：确认 DOM 自定义事件是否正确派发与接收；检查 /api/settings 返回状态。
- IM 桥接断连：查看连续错误计数与电路保护状态；检查网络与凭证；观察指数退避日志。

**章节来源**
- [electron/main.ts:272-289](file://electron/main.ts#L272-L289)
- [electron/main.ts:295-299](file://electron/main.ts#L295-L299)
- [electron/main.ts:191-219](file://electron/main.ts#L191-L219)
- [src/hooks/use-settings.ts:28-48](file://src/hooks/use-settings.ts#L28-L48)
- [src/lib/im/bridge-manager.ts:555-601](file://src/lib/im/bridge-manager.ts#L555-L601)

## 结论
该应用通过清晰的主进程职责划分、稳定的本地服务器运行模式、完善的生命周期事件处理与资源清理机制，实现了可靠的桌面应用体验。结合数据库迁移、设置同步与 IM 桥接的稳定性策略，整体具备良好的可维护性与扩展性。

## 附录
- 预加载 API 暴露清单：平台信息、数据目录、目录选择对话框、文件系统监听、剪贴板读取/写入、路径打开与显示。
- 构建与打包关键点：独立 Node 运行时、原生模块重建、symlink 解析、hoisting 修复、路径剥离、模板与静态资源复制。

**章节来源**
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)
- [scripts/build-electron.mjs:214-292](file://scripts/build-electron.mjs#L214-L292)
- [scripts/build-electron.mjs:294-336](file://scripts/build-electron.mjs#L294-L336)
- [scripts/build-electron.mjs:338-379](file://scripts/build-electron.mjs#L338-L379)
- [scripts/build-electron.mjs:157-202](file://scripts/build-electron.mjs#L157-L202)
- [electron-builder.json:19-55](file://electron-builder.json#L19-L55)