# 整体架构

<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)
- [next.config.ts](file://next.config.ts)
- [package.json](file://package.json)
- [src/app/layout.tsx](file://src/app/layout.tsx)
- [src/app/page.tsx](file://src/app/page.tsx)
- [src/components/layout/app-layout.tsx](file://src/components/layout/app-layout.tsx)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/forge-data.ts](file://src/lib/forge-data.ts)
- [src/app/api/chat/route.ts](file://src/app/api/chat/route.ts)
- [src/app/api/sessions/route.ts](file://src/app/api/sessions/route.ts)
- [src/app/api/workspaces/route.ts](file://src/app/api/workspaces/route.ts)
- [README.md](file://README.md)
</cite>

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

## 引言
本文件系统化阐述 Forge 的三层架构设计与实现：Electron 主进程负责应用生命周期与系统集成（窗口管理、原生能力桥接、子进程服务器启动），Next.js 前端提供用户界面与交互（页面布局、视图切换、实时事件流），Node.js 服务器承载业务逻辑与 API 服务（数据库访问、会话处理、IM 桥接、定时任务等）。文档将解释各层职责分离与协作机制，详述应用启动流程、窗口管理与服务器启动过程，并讨论架构优势、可扩展性、性能与安全设计。

## 项目结构
- Electron 主进程与预加载脚本位于 electron/，负责窗口创建、原生能力暴露、开发/生产模式下的服务器启动策略。
- Next.js 应用位于 src/，采用 App Router，页面与布局在 src/app 下，UI 组件与业务逻辑在 src/components 与 src/lib 中。
- 构建配置通过 next.config.ts 控制输出为 standalone，便于 Electron 打包；package.json 定义开发与打包脚本。
- README.md 提供技术栈、项目结构与运行方式概览。

```mermaid
graph TB
subgraph "桌面层Electron"
EM["electron/main.ts<br/>应用生命周期/窗口/服务器启动"]
EP["electron/preload.ts<br/>上下文桥接/IPC句柄"]
end
subgraph "前端层Next.js"
NL["next.config.ts<br/>standalone 输出/外部依赖"]
RL["src/app/layout.tsx<br/>根布局/主题/国际化"]
PG["src/app/page.tsx<br/>首页入口"]
AL["src/components/layout/app-layout.tsx<br/>主布局/视图/事件流"]
end
subgraph "服务层Node.js API"
CHAT["src/app/api/chat/route.ts<br/>聊天/会话/权限/SSE"]
SESS["src/app/api/sessions/route.ts<br/>会话列表/创建"]
WS["src/app/api/workspaces/route.ts<br/>工作区注册/读取"]
DB["src/lib/db.ts<br/>SQLite/迁移/索引"]
FD["src/lib/forge-data.ts<br/>数据目录/上传目录"]
end
EM --> EP
EM --> NL
EM --> RL
EM --> PG
EM --> AL
AL --> CHAT
AL --> SESS
AL --> WS
CHAT --> DB
SESS --> DB
WS --> DB
CHAT --> FD
SESS --> FD
WS --> FD
```

图表来源
- [electron/main.ts:1-311](file://electron/main.ts#L1-L311)
- [electron/preload.ts:1-24](file://electron/preload.ts#L1-L24)
- [next.config.ts:1-13](file://next.config.ts#L1-L13)
- [src/app/layout.tsx:1-39](file://src/app/layout.tsx#L1-L39)
- [src/app/page.tsx:1-8](file://src/app/page.tsx#L1-L8)
- [src/components/layout/app-layout.tsx:1-566](file://src/components/layout/app-layout.tsx#L1-L566)
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)
- [src/lib/db.ts:1-499](file://src/lib/db.ts#L1-L499)
- [src/lib/forge-data.ts:1-104](file://src/lib/forge-data.ts#L1-L104)

章节来源
- [README.md:343-382](file://README.md#L343-L382)
- [package.json:13-26](file://package.json#L13-L26)
- [next.config.ts:1-13](file://next.config.ts#L1-L13)

## 核心组件
- Electron 主进程（electron/main.ts）
  - 职责：应用生命周期管理、窗口创建与显示、原生能力 IPC 暴露、开发/生产模式下独立 Node.js 服务器启动、文件系统监听、剪贴板与路径操作。
  - 关键点：开发模式直连本地 3000 端口；生产模式使用打包资源中的 standalone server.js 并通过系统 Node 启动，避免 ABI 兼容问题。
- 预加载脚本（electron/preload.ts）
  - 职责：通过 contextBridge 将受限原生能力暴露到渲染进程，统一 IPC 接口。
- Next.js 根布局与页面（src/app/layout.tsx, src/app/page.tsx）
  - 职责：全局样式、主题与国际化包裹，首页直接渲染主布局组件。
- 主布局组件（src/components/layout/app-layout.tsx）
  - 职责：多视图容器、侧边栏、编辑器面板、实时事件流（SSE）、视图间状态同步、权限与思考模式会话级覆盖。
- 数据与存储（src/lib/db.ts, src/lib/forge-data.ts）
  - 职责：SQLite 数据库初始化与迁移、WAL 模式、索引与外键约束、表结构与种子数据、数据目录与上传目录管理。
- API 层（src/app/api/*）
  - 聊天接口（/api/chat）：SSE 流式响应、权限桥接、附件解析与回传、消息持久化、令牌用量统计。
  - 会话接口（/api/sessions）：会话列表与创建、自动清理过期会话。
  - 工作区接口（/api/workspaces）：工作区注册、存在性检查、最近打开时间更新、默认模板初始化。

章节来源
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)
- [src/app/layout.tsx:22-38](file://src/app/layout.tsx#L22-L38)
- [src/app/page.tsx:5-7](file://src/app/page.tsx#L5-L7)
- [src/components/layout/app-layout.tsx:34-566](file://src/components/layout/app-layout.tsx#L34-L566)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:20-103](file://src/lib/forge-data.ts#L20-L103)
- [src/app/api/chat/route.ts:74-342](file://src/app/api/chat/route.ts#L74-L342)
- [src/app/api/sessions/route.ts:6-33](file://src/app/api/sessions/route.ts#L6-L33)
- [src/app/api/workspaces/route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)

## 架构总览
三层架构以“桌面层-前端层-服务层”清晰分层，职责边界明确：
- 桌面层（Electron 主进程）：负责系统集成、窗口生命周期、原生能力桥接、独立服务器启动与健康检查。
- 前端层（Next.js App Router）：负责 UI 呈现、视图编排、实时事件订阅、用户交互与状态管理。
- 服务层（Next.js API 路由 + Node.js 运行时）：负责业务逻辑、数据持久化、外部 SDK 集成、IM 桥接与定时任务。

```mermaid
graph TB
subgraph "桌面层"
M["electron/main.ts"]
P["electron/preload.ts"]
T["src/types/electron.d.ts"]
end
subgraph "前端层"
L["src/app/layout.tsx"]
H["src/app/page.tsx"]
A["src/components/layout/app-layout.tsx"]
end
subgraph "服务层"
C["src/app/api/chat/route.ts"]
S["src/app/api/sessions/route.ts"]
W["src/app/api/workspaces/route.ts"]
D["src/lib/db.ts"]
F["src/lib/forge-data.ts"]
end
M --> P
M --> L
M --> H
P --> A
A --> C
A --> S
A --> W
C --> D
S --> D
W --> D
C --> F
S --> F
W --> F
```

图表来源
- [electron/main.ts:1-311](file://electron/main.ts#L1-L311)
- [electron/preload.ts:1-24](file://electron/preload.ts#L1-L24)
- [src/types/electron.d.ts:1-20](file://src/types/electron.d.ts#L1-L20)
- [src/app/layout.tsx:1-39](file://src/app/layout.tsx#L1-L39)
- [src/app/page.tsx:1-8](file://src/app/page.tsx#L1-L8)
- [src/components/layout/app-layout.tsx:1-566](file://src/components/layout/app-layout.tsx#L1-L566)
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)
- [src/lib/db.ts:1-499](file://src/lib/db.ts#L1-L499)
- [src/lib/forge-data.ts:1-104](file://src/lib/forge-data.ts#L1-L104)

## 详细组件分析

### 应用启动流程与窗口管理
- 开发模式：Electron 主进程等待 Next.js 开发服务器就绪后，创建窗口并加载 http://localhost:3000。
- 生产模式：主进程查找系统 Node 或打包内嵌 Node，启动 standalone/server.js，监听 127.0.0.1:PORT，等待服务就绪后创建窗口。
- 窗口特性：最小尺寸、标题栏样式、背景色、首次 ready-to-show 再显示、外部链接在系统浏览器打开、关闭时释放引用。
- 文件系统监听：支持递归监听指定目录变更，防抖后向渲染进程发送 fs:changed 事件，用于刷新文件树。

```mermaid
sequenceDiagram
participant OS as "操作系统"
participant Main as "electron/main.ts"
participant Child as "Node.js 子进程(standalone)"
participant Win as "BrowserWindow"
participant Renderer as "Next.js 渲染进程"
OS->>Main : 启动应用
Main->>Main : 注册IPC句柄/文件监听/剪贴板/路径
alt 开发模式
Main->>Win : 创建窗口(localhost : 3000)
else 生产模式
Main->>Child : spawn 独立服务器
Child-->>Main : stdout/stderr 日志
Main->>Main : 等待服务就绪(HTTP HEAD)
Main->>Win : 创建窗口(127.0.0.1 : PORT)
end
Win->>Renderer : 加载URL
Renderer-->>Win : ready-to-show
Win->>Win : 显示窗口
```

图表来源
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/main.ts:141-175](file://electron/main.ts#L141-L175)
- [electron/main.ts:191-219](file://electron/main.ts#L191-L219)

章节来源
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/main.ts:141-175](file://electron/main.ts#L141-L175)
- [electron/main.ts:191-219](file://electron/main.ts#L191-L219)

### 原生能力桥接与类型声明
- 预加载脚本通过 contextBridge 暴露受限 API，包括目录选择、文件系统监听、剪贴板读写、数据目录查询、路径打开等。
- 类型声明文件定义 window.electronAPI 的接口，确保 TypeScript 在渲染进程中正确感知可用方法。

```mermaid
classDiagram
class ElectronAPI {
+platform
+homeForgePath
+forgeDataPath
+openDirectoryDialog()
+watchDirectory(dirPath)
+onFsChanged(callback)
+readClipboardFiles()
+showInFolder(filePath)
+copyToClipboard(text)
+getDataPath()
+openPath(targetPath)
}
class Preload {
+exposeInMainWorld()
}
ElectronAPI <.. Preload : "由预加载脚本暴露"
```

图表来源
- [src/types/electron.d.ts:1-20](file://src/types/electron.d.ts#L1-L20)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)

章节来源
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)
- [src/types/electron.d.ts:1-20](file://src/types/electron.d.ts#L1-L20)

### 前端布局与实时事件流
- 主布局组件负责视图切换、侧边栏与编辑器面板、字体与代码主题变量注入、拖拽行为拦截、SSE 订阅（/api/im-events）。
- SSE 事件用于 IM 消息到达、命令触发、会话切换等场景，连接断开后自动重连，使用 ref 保持回调闭包最新值。

```mermaid
flowchart TD
Start(["进入主布局"]) --> Init["初始化设置/语言/主题"]
Init --> CheckWS{"是否已选择工作区?"}
CheckWS --> |否| ShowProject["显示项目选择页"]
CheckWS --> |是| RenderMain["渲染主内容区域"]
RenderMain --> SSE["建立 /api/im-events SSE 连接"]
SSE --> Event{"收到事件?"}
Event --> |im:message| RefreshSess["刷新会话列表/加载消息"]
Event --> |im:command| RefreshSess
Event --> |im:session-changed| SwitchSess["切换活动会话/加载消息"]
Event --> |错误| Reconnect["3秒后重连"]
RefreshSess --> SSE
SwitchSess --> SSE
Reconnect --> SSE
```

图表来源
- [src/components/layout/app-layout.tsx:188-244](file://src/components/layout/app-layout.tsx#L188-L244)

章节来源
- [src/components/layout/app-layout.tsx:34-566](file://src/components/layout/app-layout.tsx#L34-L566)

### 聊天与会话处理（服务层）
- 聊天接口（POST /api/chat）：
  - 参数校验、权限模式与思考模式解析、历史归档与会话清理、SSE 流式返回、附件解析与回传、消息持久化、令牌用量统计。
  - 支持会话恢复失败降级为全新会话，避免锁冲突。
- 会话接口（GET/POST /api/sessions）：
  - 列出活跃会话、创建新会话、启动时自动清理过期会话。
- 工作区接口（GET/POST /api/workspaces）：
  - 列出工作区、注册新工作区、存在性检查、默认模板初始化。

```mermaid
sequenceDiagram
participant UI as "主布局组件"
participant API as "/api/chat"
participant DB as "SQLite(会话/消息)"
participant SDK as "Claude Agent SDK"
participant SSE as "SSE响应"
UI->>API : POST /api/chat(消息/权限/思考模式/附件)
API->>DB : 校验会话/保存用户消息/归档旧记忆
API->>SDK : 创建查询(可选权限桥/恢复会话)
SDK-->>API : 流式消息块
API->>DB : 保存助手消息/更新会话
API-->>SSE : data : 事件(文本/附件/完成)
UI-->>UI : 解析事件/渲染/更新令牌用量
```

图表来源
- [src/app/api/chat/route.ts:74-342](file://src/app/api/chat/route.ts#L74-L342)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

章节来源
- [src/app/api/chat/route.ts:74-342](file://src/app/api/chat/route.ts#L74-L342)
- [src/app/api/sessions/route.ts:6-33](file://src/app/api/sessions/route.ts#L6-L33)
- [src/app/api/workspaces/route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)

### 数据模型与存储
- 数据库采用 SQLite（better-sqlite3），WAL 模式提升并发读性能；启用外键约束保证一致性。
- 表结构覆盖会话、消息、设置、技能、代理、MCP 服务器、IM 通道、定时任务、任务执行、钩子、工作区、API 提供商、频道绑定、审计日志与去重等。
- 迁移逻辑兼容旧版本 schema，自动修复约束与列缺失；支持从 Claude Code 配置同步 MCP 服务器。

```mermaid
erDiagram
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
}
SETTINGS {
text key PK
text value
}
SKILLS {
text id PK
text name
text description
text scope
int enabled
text content
text created_at
text updated_at
}
AGENTS {
text id PK
text name
text description
text model
text permission_mode
int is_main
text parent_id
int enabled
text instructions
text soul
text identity
text tools_config
text created_at
text updated_at
}
MCP_SERVERS {
text id PK
text name
text protocol
text config
int enabled
text status
text created_at
text updated_at
}
IM_CHANNELS {
text id PK
text type
int enabled
text status
text credentials
text dm_policy
text group_policy
text trigger_mode
text group_whitelist
text sender_whitelist
text created_at
text updated_at
}
CRON_TASKS {
text id PK
text name
text schedule
text action
text action_type
text agent_name
text skill_name
text workspace_id
int enabled
int is_heartbeat
text config
text last_run_at
text last_run_result
text created_at
text updated_at
}
TASK_EXECUTIONS {
text id PK
text task_id FK
text task_name
text result
text status
text session_id
text executed_at
}
HOOKS {
text id PK
text name
text event
text tool_pattern
text action
text command
int enabled
text created_at
}
WORKSPACES {
text id PK
text path
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
int is_active
text status
text status_error
text created_at
text updated_at
}
CHANNEL_BINDINGS {
text id PK
text channel_id FK
text chat_id
text chat_name
text workspace
text created_at
}
CHANNEL_OUTBOUND_REFS {
text id PK
text channel_type
text chat_id
text internal_id
text platform_msg_id
text created_at
}
CHANNEL_AUDIT_LOGS {
text id PK
text channel_type
text chat_id
text action
text details
text created_at
}
CHANNEL_DEDUPE {
text hash PK
text channel_type
text chat_id
text created_at
}
SESSIONS ||--o{ MESSAGES : "拥有"
AGENTS ||--o{ AGENT_SKILLS : "拥有"
SKILLS ||--o{ AGENT_SKILLS : "被绑定"
IM_CHANNELS ||--o{ CHANNEL_BINDINGS : "拥有"
CRON_TASKS ||--o{ TASK_EXECUTIONS : "产生"
```

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

章节来源
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

## 依赖关系分析
- 构建与打包
  - Next.js 输出为 standalone，禁用压缩以避免 SSE 缓冲问题；serverExternalPackages 外部化 better-sqlite3 与 larksuiteoapi，保留原生 WebSocket 行为。
  - Electron 主进程在生产模式使用系统 Node 启动 standalone/server.js，避免 ABI 不兼容导致的原生模块重建。
- 开发与调试
  - package.json 提供 dev:next、dev:electron、dev:electron:compile、dev 等脚本，支持并行启动 Next.js 开发服务器与 Electron。
- 系统边界
  - 桌面层与前端层通过 IPC 与 contextBridge 通信；前端层通过 HTTP(SSE) 与服务层交互；服务层通过 better-sqlite3 访问本地数据库。

```mermaid
graph LR
Dev["开发脚本(package.json)"] --> NextDev["Next.js 开发服务器"]
Dev --> ElectronDev["Electron 主进程"]
ElectronDev --> Standalone["standalone/server.js"]
Standalone --> SSE["SSE 事件流"]
NextDev --> UI["Next.js 前端"]
UI --> SSE
UI --> API["/api/* 路由"]
API --> DB["SQLite 数据库"]
```

图表来源
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [package.json:13-26](file://package.json#L13-L26)
- [electron/main.ts:74-139](file://electron/main.ts#L74-L139)

章节来源
- [next.config.ts:1-13](file://next.config.ts#L1-L13)
- [package.json:13-26](file://package.json#L13-L26)
- [electron/main.ts:74-139](file://electron/main.ts#L74-L139)

## 性能考量
- SSE 流式传输：服务端使用 TransformStream 逐块写入，避免 Next.js 缓冲整包，降低延迟与内存占用。
- 数据库优化：WAL 模式、外键与索引、按需归档与清理，减少磁盘 IO 与查询开销。
- 原生模块兼容：生产模式使用系统 Node 启动独立服务器，避免 Electron ABI 与 better-sqlite3 等原生模块的重新编译。
- 压缩策略：禁用 gzip，避免 SSE 缓冲带来的额外开销。
- 文件监听：递归监听配合防抖，减少频繁刷新带来的 UI 抖动与 IO 压力。

章节来源
- [src/app/api/chat/route.ts:150-160](file://src/app/api/chat/route.ts#L150-L160)
- [src/lib/db.ts:22-23](file://src/lib/db.ts#L22-L23)
- [next.config.ts:5-5](file://next.config.ts#L5-L5)
- [electron/main.ts:80-83](file://electron/main.ts#L80-L83)

## 故障排查指南
- 服务器启动失败
  - 现象：弹窗提示服务器无法启动。
  - 排查：确认系统 Node 可用；查看控制台日志；检查 FORGE_DATA_DIR 与资源路径。
- SSE 无响应或断连
  - 现象：聊天无流式输出或 IM 事件不同步。
  - 排查：检查 /api/im-events 是否可达；确认 EventSource 连接与重连逻辑；查看浏览器网络面板。
- 权限与思考模式异常
  - 现象：工具调用未弹确认或思考模式不生效。
  - 排查：检查会话级覆盖与全局设置；确认 permission-bridge 与 provider thinking 设置。
- 数据迁移与目录权限
  - 现象：旧数据未迁移或上传目录不可写。
  - 排查：确认 FORGE_DATA_DIR 权限；查看迁移日志；手动复制数据库与上传文件。

章节来源
- [electron/main.ts:280-288](file://electron/main.ts#L280-L288)
- [src/components/layout/app-layout.tsx:188-244](file://src/components/layout/app-layout.tsx#L188-L244)
- [src/lib/forge-data.ts:52-103](file://src/lib/forge-data.ts#L52-L103)

## 结论
Forge 的三层架构以 Electron 为入口、Next.js 为界面、Node.js API 为业务中枢，实现了清晰的职责分离与高内聚低耦合。通过独立服务器、SSE 流式传输、SQLite 优化与原生模块兼容策略，系统在易用性、性能与可维护性之间取得平衡。未来可在微服务拆分、缓存层引入与可观测性增强方面进一步演进。

## 附录
- 技术栈与运行方式概览见 README 的“技术栈”与“开发命令”部分。
- 项目结构与打包产物说明见 README 的“项目结构”。

章节来源
- [README.md:343-382](file://README.md#L343-L382)
- [README.md:369-382](file://README.md#L369-L382)