# 技术架构

<cite>
**本文引用的文件**
- [electron/main.ts](file://electron/main.ts)
- [electron/preload.ts](file://electron/preload.ts)
- [src/app/layout.tsx](file://src/app/layout.tsx)
- [next.config.ts](file://next.config.ts)
- [package.json](file://package.json)
- [README.md](file://README.md)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/forge-data.ts](file://src/lib/forge-data.ts)
- [src/lib/provider.ts](file://src/lib/provider.ts)
- [src/lib/sdk/client.ts](file://src/lib/sdk/client.ts)
- [src/lib/sdk/agents-loader.ts](file://src/lib/sdk/agents-loader.ts)
- [src/lib/sdk/mcp-loader.ts](file://src/lib/sdk/mcp-loader.ts)
- [src/lib/sdk/permission-bridge.ts](file://src/lib/sdk/permission-bridge.ts)
- [src/lib/sdk/message-mapper.ts](file://src/lib/sdk/message-mapper.ts)
- [src/lib/sdk/system-prompt.ts](file://src/lib/sdk/system-prompt.ts)
- [src/lib/im/bridge-manager.ts](file://src/lib/im/bridge-manager.ts)
- [src/lib/im/channel-router.ts](file://src/lib/im/channel-router.ts)
- [src/lib/im/conversation-engine.ts](file://src/lib/im/conversation-engine.ts)
- [src/lib/im/delivery.ts](file://src/lib/im/delivery.ts)
- [src/lib/im/commands.ts](file://src/lib/im/commands.ts)
- [src/lib/im/policy.ts](file://src/lib/im/policy.ts)
- [src/lib/im/streaming-state.ts](file://src/lib/im/streaming-state.ts)
- [src/lib/im/types.ts](file://src/lib/im/types.ts)
- [src/lib/cron/engine.ts](file://src/lib/cron/engine.ts)
- [src/lib/cron/executor.ts](file://src/lib/cron/executor.ts)
- [src/lib/cron/cron-parser.ts](file://src/lib/cron/cron-parser.ts)
</cite>

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

## 引言
本文件系统化梳理 Forge 的技术架构与实现，重点覆盖三层协作模式：Electron 主进程负责应用生命周期与本地服务启动；Next.js 前端承载 UI 与 API 路由；Node.js 服务器在生产环境以独立进程运行，通过 IPC、SSE 与 HTTP API 实现跨层通信。文档还阐述了从用户输入到 AI 响应的完整数据流、技术决策权衡、系统边界与第三方依赖、可扩展性与部署拓扑，以及安全、监控与灾难恢复等横切关注点。

## 项目结构
- Electron 主进程与预加载脚本：负责应用窗口、系统对话框、文件系统监听、剪贴板与路径操作，并在生产环境启动 Next.js 独立服务器。
- Next.js 应用：采用 App Router，提供页面、布局与 API 路由，配置为“standalone”输出，禁用压缩以适配 SSE 流。
- 核心库与业务域：
  - 数据层：SQLite（better-sqlite3）持久化会话、消息、设置、技能、代理、IM 渠道、定时任务等。
  - SDK 集成：Claude Agent SDK 客户端、代理加载器、MCP 工具加载、权限桥接、消息映射与系统提示。
  - IM 桥接：Feishu/Telegram/Discord 出入站消息、路由、并发控制、投递与策略。
  - 定时引擎：解析表达式、调度执行、心跳与通知。
  - 提供商解析：统一解析 Anthropic 及多家兼容提供商的认证与端点。

```mermaid
graph TB
subgraph "桌面层Electron"
EM["electron/main.ts<br/>应用生命周期/子进程/端口探测"]
EP["electron/preload.ts<br/>上下文桥接/IPC暴露"]
end
subgraph "前端层Next.js App Router"
NL["next.config.ts<br/>standalone/禁用压缩/SSE友好"]
RL["src/app/layout.tsx<br/>主题/国际化根布局"]
end
subgraph "服务层Node.js 服务器"
DB["src/lib/db.ts<br/>SQLite/WAL/迁移/索引"]
FD["src/lib/forge-data.ts<br/>.forge 数据目录/迁移"]
PR["src/lib/provider.ts<br/>提供商解析/CLI认证"]
SDKC["src/lib/sdk/client.ts<br/>Agent SDK 客户端"]
AG["src/lib/sdk/agents-loader.ts<br/>代理定义加载"]
MCPL["src/lib/sdk/mcp-loader.ts<br/>MCP 工具加载"]
PERM["src/lib/sdk/permission-bridge.ts<br/>权限桥接"]
MSG["src/lib/sdk/message-mapper.ts<br/>消息映射"]
SYS["src/lib/sdk/system-prompt.ts<br/>系统提示生成"]
IMBM["src/lib/im/bridge-manager.ts<br/>IM 桥接管理"]
IMCR["src/lib/im/channel-router.ts<br/>渠道路由"]
IMCE["src/lib/im/conversation-engine.ts<br/>对话引擎"]
IMD["src/lib/im/delivery.ts<br/>消息投递"]
IMCMD["src/lib/im/commands.ts<br/>IM 命令解析"]
IMP["src/lib/im/policy.ts<br/>策略/白名单"]
IMSS["src/lib/im/streaming-state.ts<br/>流状态"]
IMT["src/lib/im/types.ts<br/>IM 类型定义"]
CRON["src/lib/cron/engine.ts<br/>定时引擎"]
CEXEC["src/lib/cron/executor.ts<br/>执行器"]
CRONP["src/lib/cron/cron-parser.ts<br/>表达式解析"]
end
EM --> NL
EP --> RL
EM --> NL
NL --> DB
NL --> PR
NL --> SDKC
SDKC --> AG
SDKC --> MCPL
SDKC --> PERM
SDKC --> MSG
SDKC --> SYS
SDKC --> IMBM
IMBM --> IMCR
IMBM --> IMCE
IMBM --> IMD
IMBM --> IMCMD
IMBM --> IMP
IMBM --> IMSS
IMBM --> IMT
SDKC --> CRON
CRON --> CEXEC
CRON --> CRONP
```

**图表来源**
- [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/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)
- [src/lib/provider.ts:1-201](file://src/lib/provider.ts#L1-L201)
- [src/lib/sdk/client.ts](file://src/lib/sdk/client.ts)
- [src/lib/sdk/agents-loader.ts](file://src/lib/sdk/agents-loader.ts)
- [src/lib/sdk/mcp-loader.ts](file://src/lib/sdk/mcp-loader.ts)
- [src/lib/sdk/permission-bridge.ts](file://src/lib/sdk/permission-bridge.ts)
- [src/lib/sdk/message-mapper.ts](file://src/lib/sdk/message-mapper.ts)
- [src/lib/sdk/system-prompt.ts](file://src/lib/sdk/system-prompt.ts)
- [src/lib/im/bridge-manager.ts](file://src/lib/im/bridge-manager.ts)
- [src/lib/im/channel-router.ts](file://src/lib/im/channel-router.ts)
- [src/lib/im/conversation-engine.ts](file://src/lib/im/conversation-engine.ts)
- [src/lib/im/delivery.ts](file://src/lib/im/delivery.ts)
- [src/lib/im/commands.ts](file://src/lib/im/commands.ts)
- [src/lib/im/policy.ts](file://src/lib/im/policy.ts)
- [src/lib/im/streaming-state.ts](file://src/lib/im/streaming-state.ts)
- [src/lib/im/types.ts](file://src/lib/im/types.ts)
- [src/lib/cron/engine.ts](file://src/lib/cron/engine.ts)
- [src/lib/cron/executor.ts](file://src/lib/cron/executor.ts)
- [src/lib/cron/cron-parser.ts](file://src/lib/cron/cron-parser.ts)

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

## 核心组件
- Electron 主进程：负责应用启动、窗口创建、系统对话框、文件系统监听、剪贴板与路径操作；在生产环境启动 Next.js 独立服务器并通过随机端口暴露服务；通过 IPC 暴露受限系统能力给渲染进程。
- 预加载脚本：通过 contextBridge 暴露受控 API 给渲染进程，包括目录选择、文件系统监听回调、剪贴板读写、打开路径等。
- Next.js 应用：App Router 布局与页面，配置为 standalone 输出，禁用压缩以避免缓冲影响 SSE 流；开发与生产模式分别走本地 3000 或 127.0.0.1:port。
- 数据层：SQLite 数据库（WAL 模式），初始化表结构与索引，支持多版本迁移；提供上传目录与数据目录管理；自动同步 MCP 服务器配置。
- SDK 集成：封装 Claude Agent SDK 使用方式，负责代理加载、MCP 工具接入、权限桥接、消息映射与系统提示生成。
- IM 桥接：面向 Feishu/Telegram/Discord 的出入口消息处理，包含路由、并发控制、投递、命令解析、策略与流状态管理。
- 定时引擎：解析 Cron 表达式，驱动任务执行与心跳通知。
- 提供商解析：统一解析 Anthropic 及多家兼容提供商的认证与端点，支持 API Key 与 CLI OAuth 两种模式。

**章节来源**
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)
- [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-103](file://src/lib/forge-data.ts#L20-L103)
- [src/lib/provider.ts:108-180](file://src/lib/provider.ts#L108-L180)
- [src/lib/sdk/client.ts](file://src/lib/sdk/client.ts)
- [src/lib/im/bridge-manager.ts](file://src/lib/im/bridge-manager.ts)
- [src/lib/cron/engine.ts](file://src/lib/cron/engine.ts)

## 架构总览
Forge 采用“桌面 + 前端 + 服务”的三层协作模式：
- Electron 主进程：管理应用生命周期、窗口与系统交互；生产环境启动 Next.js 独立服务器，绑定 127.0.0.1 的随机端口。
- Next.js 前端：App Router 页面与 API 路由，布局包含主题与国际化提供者；在开发模式直接连接本地 3000，在生产模式连接主进程启动的服务。
- Node.js 服务器：在生产环境由 Electron 子进程运行，提供 API 与内部服务；开发模式由 Next.js 自身运行。

通信机制：
- IPC：主进程与渲染进程之间的双向调用，用于系统级能力（文件系统监听、剪贴板、路径打开等）。
- SSE：前端通过 Server-Sent Events 接收流式响应，next.config.ts 禁用压缩以保证流稳定性。
- HTTP API：Next.js API 路由作为后端接口，供前端调用；IM 桥接与定时任务等内部模块通过 HTTP 或本地子进程调用。

系统边界与集成：
- 外部依赖：Claude Agent SDK、better-sqlite3、@larksuiteoapi/node-sdk、多种模型提供商（Anthropic 及多家兼容端点）、IM 平台（Feishu/Telegram/Discord）。
- 第三方集成：IM 平台均使用出站连接，无需公网 IP 或端口暴露；MCP 服务器可从 Claude Code 配置自动同步。

部署拓扑：
- 开发：Next.js 在 3000，Electron 同时启动；或 Electron 编译后等待 3000 再启动。
- 生产：Electron fork 一个独立的 Next.js standalone 服务器，绑定 127.0.0.1 的随机端口，仅本地访问。

**章节来源**
- [electron/main.ts:74-139](file://electron/main.ts#L74-L139)
- [electron/main.ts:272-288](file://electron/main.ts#L272-L288)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [README.md:343-382](file://README.md#L343-L382)
- [package.json:27-41](file://package.json#L27-L41)

## 详细组件分析

### Electron 主进程与预加载通信
- 主进程职责：查找 Node 二进制、寻找空闲端口、启动 Next.js standalone 服务器、等待就绪、创建窗口、注册 IPC 处理器（目录选择、文件系统监听、剪贴板、路径打开等）、清理资源。
- 预加载脚本：通过 contextBridge 暴露受限 API，渲染进程通过 ipcRenderer 调用主进程能力。
- 通信流程：渲染进程调用预加载暴露的方法 -> 主进程 ipcMain.handle 分发 -> 执行系统调用 -> 返回结果或事件（如 fs:changed）。

```mermaid
sequenceDiagram
participant R as "渲染进程"
participant P as "预加载脚本"
participant M as "主进程(electron/main.ts)"
participant S as "Next.js 服务器"
R->>P : 调用 "openDirectoryDialog()"
P->>M : ipcRenderer.invoke("dialog : openDirectory")
M->>M : 打开系统目录对话框
M-->>P : 返回选中路径
P-->>R : 返回结果
R->>P : 调用 "watchDirectory(dir)"
P->>M : ipcRenderer.invoke("fs : watch", dir)
M->>M : watch(dir) 并去抖发送 "fs : changed"
M-->>P : 发送 "fs : changed"
P-->>R : 触发回调
```

**图表来源**
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/preload.ts:9-15](file://electron/preload.ts#L9-L15)

**章节来源**
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/preload.ts:5-23](file://electron/preload.ts#L5-L23)

### Next.js 前端布局与 API 路由
- 布局：RootLayout 包含主题与国际化提供者，确保全局样式与语言切换可用。
- API 路由：位于 src/app/api/*，覆盖代理、提供商、聊天、IM、市场、工作区、任务执行、上传等子域。
- 配置：next.config.ts 设置 output 为 standalone，images.unoptimized=true，禁用压缩以适配 SSE。

```mermaid
graph LR
L["src/app/layout.tsx"] --> P1["src/app/api/agents/..."]
L --> P2["src/app/api/api-providers/..."]
L --> P3["src/app/api/chat/..."]
L --> P4["src/app/api/im-channels/..."]
L --> P5["src/app/api/marketplace/..."]
L --> P6["src/app/api/workspaces/..."]
L --> P7["src/app/api/cron-tasks/..."]
L --> P8["src/app/api/upload/..."]
L --> NCFG["next.config.ts"]
```

**图表来源**
- [src/app/layout.tsx:22-38](file://src/app/layout.tsx#L22-L38)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)

**章节来源**
- [src/app/layout.tsx:17-38](file://src/app/layout.tsx#L17-L38)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)

### 数据层：SQLite 与迁移
- 初始化：首次访问创建数据库文件，启用 WAL 与外键约束，建立会话、消息、设置、技能、代理、MCP、IM 渠道、定时任务、钩子、工作区、API 提供商等表及索引。
- 迁移：支持从旧目录迁移数据库与上传文件；对历史表结构进行兼容性修复（如 CHECK 约束、列缺失等）。
- 自动同步：从 Claude Code 的 ~/.claude.json 读取 MCP 服务器配置并插入数据库。

```mermaid
flowchart TD
Start(["初始化数据库"]) --> CheckOld["检查旧目录迁移"]
CheckOld --> |存在| Migrate["复制数据库文件与上传目录"]
CheckOld --> |不存在| InitTables["创建表与索引"]
Migrate --> InitTables
InitTables --> Seed["种子数据：提供商/IM渠道/心跳任务"]
Seed --> SyncMCP["从 ~/.claude.json 同步MCP服务器"]
SyncMCP --> End(["完成"])
```

**图表来源**
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:52-103](file://src/lib/forge-data.ts#L52-L103)

**章节来源**
- [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)

### SDK 集成与权限桥接
- 客户端封装：统一调用 Claude Agent SDK，结合代理加载器、MCP 工具加载、消息映射与系统提示生成。
- 权限桥接：根据代理权限模式（确认/全量）决定是否拦截工具调用，支持 per-action 审批。
- 提供商解析：支持 Anthropic API Key 与 CLI OAuth，以及多家兼容提供商的 Bearer Token 认证。

```mermaid
classDiagram
class ProviderResolver {
+resolveProvider(model) ResolvedProvider
+hasCredentials(providerId) boolean
+hasApiKey(providerId) boolean
}
class AgentSdkClient {
+createSession(...)
+sendMessage(...)
+streamResponse(...)
}
class PermissionBridge {
+requireApproval(toolCall) boolean
+applyMode(mode) void
}
class AgentsLoader {
+loadAgent(agentId) AgentConfig
}
class McpLoader {
+syncFromClaudeCode() void
}
class MessageMapper {
+toSdkMessage(msg) SDKMessage
+fromSdkMessage(evt) Message
}
ProviderResolver --> AgentSdkClient : "提供认证与端点"
AgentSdkClient --> PermissionBridge : "使用权限模式"
AgentSdkClient --> AgentsLoader : "加载代理配置"
AgentSdkClient --> McpLoader : "加载MCP工具"
AgentSdkClient --> MessageMapper : "消息映射"
```

**图表来源**
- [src/lib/provider.ts:108-180](file://src/lib/provider.ts#L108-L180)
- [src/lib/sdk/client.ts](file://src/lib/sdk/client.ts)
- [src/lib/sdk/permission-bridge.ts](file://src/lib/sdk/permission-bridge.ts)
- [src/lib/sdk/agents-loader.ts](file://src/lib/sdk/agents-loader.ts)
- [src/lib/sdk/mcp-loader.ts](file://src/lib/sdk/mcp-loader.ts)
- [src/lib/sdk/message-mapper.ts](file://src/lib/sdk/message-mapper.ts)

**章节来源**
- [src/lib/provider.ts:108-180](file://src/lib/provider.ts#L108-L180)
- [src/lib/sdk/permission-bridge.ts](file://src/lib/sdk/permission-bridge.ts)
- [src/lib/sdk/agents-loader.ts](file://src/lib/sdk/agents-loader.ts)
- [src/lib/sdk/mcp-loader.ts](file://src/lib/sdk/mcp-loader.ts)
- [src/lib/sdk/message-mapper.ts](file://src/lib/sdk/message-mapper.ts)

### IM 桥接：入站/出站与流式状态
- 入站：Feishu/Telegram/Discord 通过出站连接推送消息；ChannelRouter 将消息路由至对应会话；ConversationEngine 解析命令与上下文；Commands 提供 IM 命令集。
- 出站：Delivery 将 Agent 的响应与文件按平台格式投递；StreamingState 管理流式状态，Policy 控制白名单与触发模式。
- 并发与去重：Concurrency 控制并行度；Dedup 防止重复处理。

```mermaid
sequenceDiagram
participant U as "IM 用户"
participant CH as "ChannelRouter"
participant CE as "ConversationEngine"
participant CMD as "Commands"
participant SDK as "AgentSdkClient"
participant DEL as "Delivery"
U->>CH : 发送消息
CH->>CE : 路由到会话
CE->>CMD : 解析命令/上下文
CMD->>SDK : 创建/续写会话并发送消息
SDK-->>DEL : 流式响应片段
DEL-->>U : 平台格式投递
```

**图表来源**
- [src/lib/im/channel-router.ts](file://src/lib/im/channel-router.ts)
- [src/lib/im/conversation-engine.ts](file://src/lib/im/conversation-engine.ts)
- [src/lib/im/commands.ts](file://src/lib/im/commands.ts)
- [src/lib/sdk/client.ts](file://src/lib/sdk/client.ts)
- [src/lib/im/delivery.ts](file://src/lib/im/delivery.ts)

**章节来源**
- [src/lib/im/bridge-manager.ts](file://src/lib/im/bridge-manager.ts)
- [src/lib/im/channel-router.ts](file://src/lib/im/channel-router.ts)
- [src/lib/im/conversation-engine.ts](file://src/lib/im/conversation-engine.ts)
- [src/lib/im/delivery.ts](file://src/lib/im/delivery.ts)
- [src/lib/im/commands.ts](file://src/lib/im/commands.ts)
- [src/lib/im/policy.ts](file://src/lib/im/policy.ts)
- [src/lib/im/streaming-state.ts](file://src/lib/im/streaming-state.ts)

### 定时引擎与心跳
- Cron 引擎：解析表达式，维护任务与执行记录；Executor 驱动执行，支持一次性、分钟级、小时/日/周/月等周期；Heartbeat 默认每 30 分钟运行一次，可配置通知渠道。
- 与 IM 集成：执行结果可通过 IM 通道通知用户；每个执行创建新会话以便追溯。

```mermaid
flowchart TD
Parse["解析 Cron 表达式"] --> Schedule["加入调度队列"]
Schedule --> Tick["定时触发"]
Tick --> Exec["Executor 执行任务"]
Exec --> Notify["按配置通知 IM/邮件"]
Exec --> NewSession["创建会话记录执行详情"]
```

**图表来源**
- [src/lib/cron/cron-parser.ts](file://src/lib/cron/cron-parser.ts)
- [src/lib/cron/engine.ts](file://src/lib/cron/engine.ts)
- [src/lib/cron/executor.ts](file://src/lib/cron/executor.ts)

**章节来源**
- [src/lib/cron/engine.ts](file://src/lib/cron/engine.ts)
- [src/lib/cron/executor.ts](file://src/lib/cron/executor.ts)
- [src/lib/cron/cron-parser.ts](file://src/lib/cron/cron-parser.ts)

## 依赖分析
- 运行时依赖：Next.js、React、Claude Agent SDK、better-sqlite3、@larksuiteoapi/node-sdk、Tailwind CSS、Lucide 图标等。
- 构建与打包：Electron、electron-builder、tsup、wait-on；生产构建输出 standalone，禁用压缩。
- 外部集成：IM 平台均使用出站连接，无需公网暴露；MCP 服务器从 Claude Code 配置同步。

```mermaid
graph TB
Pkg["package.json 依赖"] --> NX["Next.js"]
Pkg --> R["React"]
Pkg --> SDK["@anthropic-ai/claude-agent-sdk"]
Pkg --> DB["better-sqlite3"]
Pkg --> LSKY["@larksuiteoapi/node-sdk"]
Pkg --> EB["electron-builder"]
Pkg --> TSUP["tsup"]
Pkg --> WAIT["wait-on"]
```

**图表来源**
- [package.json:27-68](file://package.json#L27-L68)

**章节来源**
- [package.json:27-68](file://package.json#L27-L68)
- [README.md:343-382](file://README.md#L343-L382)

## 性能考量
- SSE 流稳定性：next.config.ts 禁用 gzip 压缩，避免缓冲导致的流中断。
- 数据库并发：SQLite 使用 WAL 模式提升并发读性能；索引覆盖消息查询与任务执行排序。
- 文件系统监听：预加载脚本对快速变更进行去抖，减少频繁刷新。
- 本地服务：生产环境由 Electron fork 的 Node 进程运行独立服务器，避免原生模块 ABI 问题与更好的性能隔离。

**章节来源**
- [next.config.ts:5-5](file://next.config.ts#L5-L5)
- [src/lib/db.ts:22-23](file://src/lib/db.ts#L22-L23)
- [electron/preload.ts:204-215](file://electron/preload.ts#L204-L215)
- [electron/main.ts:80-83](file://electron/main.ts#L80-L83)

## 故障排查指南
- 服务器未就绪：主进程在启动后轮询 HEAD 请求直到返回 OK，超时会报错并弹窗提示安装 Node 并重试。
- 文件系统监听无效：确认传入目录非空；忽略 node_modules/.git/.next/dist/out/__pycache__ 等目录；检查权限与路径有效性。
- 剪贴板文件读取失败：macOS 下 Finder 复制文件使用特定格式，过滤临时与缓存路径；异常时返回空数组。
- 数据目录迁移：首次访问自动尝试从旧目录迁移；若新位置已有有效数据库则跳过迁移。
- 提供商认证：优先使用 API Key；若为 Anthropic 则可使用 CLI OAuth；否则抛出错误提示配置。

**章节来源**
- [electron/main.ts:55-71](file://electron/main.ts#L55-L71)
- [electron/main.ts:272-288](file://electron/main.ts#L272-L288)
- [electron/preload.ts:192-219](file://electron/preload.ts#L192-L219)
- [electron/preload.ts:222-250](file://electron/preload.ts#L222-L250)
- [src/lib/forge-data.ts:52-103](file://src/lib/forge-data.ts#L52-L103)
- [src/lib/provider.ts:108-180](file://src/lib/provider.ts#L108-L180)

## 结论
Forge 通过 Electron + Next.js + Node.js 服务器的分层架构，实现了本地桌面应用的强交互与强大的 AI 工作流能力。主进程负责系统级能力与本地服务启动，前端通过 API 路由与 SSE 获取实时响应，后端以 SQLite 与 SDK 集成为核心，辅以 IM 桥接与定时引擎，形成完整的本地 AI 工作站。技术决策在易用性、安全性与性能之间取得平衡：出站连接避免公网暴露，禁用压缩保障 SSE 流稳定，WAL 提升并发读写，迁移逻辑确保数据连续性。

## 附录
- 开发命令：dev:next、dev:electron、dev、build:next、build:electron、build、package 等。
- 部署拓扑：开发模式本地 3000，生产模式 Electron fork 独立服务器并在 127.0.0.1 随机端口运行。
- 第三方依赖：详见 package.json 与 README 中的技术栈与项目结构说明。

**章节来源**
- [package.json:13-25](file://package.json#L13-L25)
- [README.md:343-382](file://README.md#L343-L382)