# 开发指南

<cite>
**本文档引用的文件**
- [package.json](file://package.json)
- [README.md](file://README.md)
- [electron/main.ts](file://electron/main.ts)
- [next.config.ts](file://next.config.ts)
- [tailwind.config.ts](file://tailwind.config.ts)
- [electron-builder.json](file://electron-builder.json)
- [scripts/build-electron.mjs](file://scripts/build-electron.mjs)
- [src/app/layout.tsx](file://src/app/layout.tsx)
- [src/lib/types.ts](file://src/lib/types.ts)
- [tsconfig.json](file://tsconfig.json)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/hooks/use-sessions.ts](file://src/hooks/use-sessions.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. [附录](#附录)

## 简介
Forge 是一款基于桌面端的本地 AI 工作站应用，采用 Electron + Next.js（Turbopack）技术栈，结合 Claude Agent SDK 提供聊天、IM 桥接、定时任务与可视化工作区管理能力。本开发指南面向新加入的开发者，覆盖环境搭建、代码结构、开发流程、调试与日志、构建与打包、性能优化、安全与可靠性、贡献与代码评审等主题，帮助快速上手并高质量参与项目。

## 项目结构
项目采用“主进程 + 前端页面”的分层组织方式：
- electron：Electron 主进程与预加载脚本，负责应用生命周期、系统集成与本地服务启动
- src：Next.js 应用代码，包含页面路由、React 组件、自定义 Hook、核心逻辑库与类型定义
- scripts：构建脚本，负责 Electron 脚本编译、Next 独立服务器打包、原生模块处理与资源注入
- 配置文件：构建与打包配置、样式与类型配置、包管理器配置等

```mermaid
graph TB
subgraph "桌面应用层"
A["Electron 主进程<br/>electron/main.ts"]
B["预加载脚本<br/>electron/preload.ts"]
end
subgraph "前端应用层"
C["Next.js 应用<br/>src/app/*"]
D["页面与视图<br/>src/components/views/*"]
E["UI 组件与布局<br/>src/components/ui/*"]
F["自定义 Hook<br/>src/hooks/*"]
G["核心逻辑库<br/>src/lib/*"]
end
subgraph "构建与打包"
H["Next 配置<br/>next.config.ts"]
I["Tailwind 配置<br/>tailwind.config.ts"]
J["Electron 构建脚本<br/>scripts/build-electron.mjs"]
K["打包配置<br/>electron-builder.json"]
L["包管理与脚本<br/>package.json"]
end
A --> C
B --> C
C --> D
D --> E
D --> F
D --> G
J --> A
J --> C
K --> A
L --> A
L --> C
```

**图表来源**
- [electron/main.ts:1-311](file://electron/main.ts#L1-L311)
- [next.config.ts:1-13](file://next.config.ts#L1-L13)
- [tailwind.config.ts:1-36](file://tailwind.config.ts#L1-L36)
- [scripts/build-electron.mjs:1-399](file://scripts/build-electron.mjs#L1-L399)
- [electron-builder.json:1-126](file://electron-builder.json#L1-L126)
- [package.json:1-68](file://package.json#L1-L68)

**章节来源**
- [README.md:351-382](file://README.md#L351-L382)
- [package.json:13-26](file://package.json#L13-L26)

## 核心组件
- Electron 主进程：负责应用启动、窗口创建、系统对话框、文件系统监听、剪贴板与路径读取、本地独立服务器启动与健康检查、退出清理
- Next.js 应用：提供页面路由、主题与国际化提供者、全局样式与字体变量、视图组件与业务逻辑
- 数据库层：SQLite（better-sqlite3，WAL 模式），提供会话、消息、技能、代理、IM 渠道、定时任务、市场模板等表结构与迁移
- 类型系统：统一的数据模型与状态类型，贯穿前端 Hook、API 层与数据库层
- 构建脚本：负责 Electron 脚本编译、Next 独立服务器打包、符号链接解析、pnpm hoisting 修复、路径剥离、Node 运行时打包与原生模块重建、外部依赖补齐

**章节来源**
- [electron/main.ts:1-311](file://electron/main.ts#L1-L311)
- [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/types.ts:1-221](file://src/lib/types.ts#L1-L221)
- [scripts/build-electron.mjs:1-399](file://scripts/build-electron.mjs#L1-L399)

## 架构总览
桌面应用通过 Electron 主进程启动 Next.js 独立服务器，并在生产模式下使用内置 Node 运行时执行服务，避免 ABI 兼容问题；主进程提供 IPC 接口供渲染进程调用系统能力；前端通过 API 路由访问后端逻辑，数据库层提供持久化存储与迁移。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant NPM as "包管理脚本<br/>package.json"
participant Next as "Next.js 开发服务器"
participant Electron as "Electron 主进程"
participant Server as "Next 独立服务器"
participant DB as "SQLite 数据库"
Dev->>NPM : 执行开发命令
NPM->>Next : 启动 Next 开发服务器
NPM->>Electron : 启动 Electron 并等待 Next 就绪
Electron->>Next : 请求健康检查
Next-->>Electron : 返回就绪
Electron->>Server : 加载并运行独立服务器
Server->>DB : 初始化/迁移数据库
Electron-->>Dev : 显示应用窗口
```

**图表来源**
- [package.json:13-17](file://package.json#L13-L17)
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

## 详细组件分析

### Electron 主进程与窗口管理
- 负责应用生命周期事件、窗口创建与导航控制、系统对话框、文件系统监听、剪贴板与路径读取、数据目录查询、外部路径打开
- 生产模式下启动 Next 独立服务器，使用内置 Node 运行时以避免原生模块 ABI 不兼容
- 提供 IPC 处理函数，封装系统能力给渲染进程调用

```mermaid
flowchart TD
Start(["应用启动"]) --> CheckDev{"是否开发模式?"}
CheckDev --> |是| UseLocalhost["使用 http://localhost:3000"]
CheckDev --> |否| StartServer["启动 Next 独立服务器"]
StartServer --> WaitForReady["等待服务器就绪"]
WaitForReady --> Ready{"就绪?"}
Ready --> |是| CreateWindow["创建窗口并加载 URL"]
Ready --> |否| ShowError["显示错误并退出"]
UseLocalhost --> CreateWindow
CreateWindow --> RegisterIPC["注册 IPC 处理函数"]
RegisterIPC --> WatchFS["注册文件系统监听"]
WatchFS --> End(["运行中"])
```

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

**章节来源**
- [electron/main.ts:1-311](file://electron/main.ts#L1-L311)

### Next.js 应用与布局
- 根布局提供主题与国际化提供者，注入全局样式与字体变量
- 页面路由与视图组件分离，视图组件通过自定义 Hook 访问 API 与状态
- 使用 Tailwind CSS 定义主题色板与边框风格，支持暗/亮/系统主题

```mermaid
graph LR
Root["根布局<br/>src/app/layout.tsx"] --> Theme["主题提供者"]
Root --> I18n["国际化提供者"]
Root --> Body["全局样式与字体变量"]
Views["页面视图<br/>src/components/views/*"] --> Hooks["自定义 Hook<br/>src/hooks/*"]
Views --> Types["类型定义<br/>src/lib/types.ts"]
```

**图表来源**
- [src/app/layout.tsx:1-39](file://src/app/layout.tsx#L1-L39)
- [tailwind.config.ts:1-36](file://tailwind.config.ts#L1-L36)

**章节来源**
- [src/app/layout.tsx:1-39](file://src/app/layout.tsx#L1-L39)
- [tailwind.config.ts:1-36](file://tailwind.config.ts#L1-L36)

### 数据库与模型
- 使用 SQLite（better-sqlite3，WAL 模式）持久化会话、消息、技能、代理、IM 渠道、定时任务、市场模板等
- 提供多版本迁移策略，自动修复旧 schema 与约束差异
- 支持从 Claude Code 配置同步 MCP 服务器信息

```mermaid
erDiagram
SESSIONS {
string id PK
string title
string workspace
string model
string status
string created_at
string updated_at
}
MESSAGES {
string id PK
string session_id FK
string role
string content
string created_at
}
SKILLS {
string id PK
string name
string description
string scope
int enabled
string content
string created_at
string updated_at
}
AGENTS {
string id PK
string name
string description
string model
string permission_mode
int is_main
string parent_id
int enabled
string instructions
string soul
string identity
string tools_config
string created_at
string updated_at
}
IM_CHANNELS {
string id PK
string type
int enabled
string status
string credentials
string dm_policy
string group_policy
string trigger_mode
string group_whitelist
string sender_whitelist
string created_at
string updated_at
}
CRON_TASKS {
string id PK
string name
string schedule
string action
string action_type
string agent_name
string skill_name
string workspace_id
int enabled
int is_heartbeat
string config
string last_run_at
string last_run_result
string created_at
string updated_at
}
TASK_EXECUTIONS {
string id PK
string task_id FK
string task_name
string result
string status
string session_id
string executed_at
}
WORKSPACES {
string id PK
string path
string last_opened_at
string created_at
}
API_PROVIDERS {
string id PK
string name
string provider
string api_key
string base_url
string model_name
int is_active
string status
string status_error
string created_at
string updated_at
}
SESSIONS ||--o{ MESSAGES : "拥有"
AGENTS ||--o{ AGENT_SKILLS : "关联"
SKILLS ||--o{ AGENT_SKILLS : "关联"
IM_CHANNELS ||--o{ CHANNEL_BINDINGS : "拥有"
CHANNEL_BINDINGS ||--o{ CHANNEL_PERMISSION_LINKS : "拥有"
CRON_TASKS ||--o{ TASK_EXECUTIONS : "拥有"
```

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

**章节来源**
- [src/lib/db.ts:1-499](file://src/lib/db.ts#L1-L499)
- [src/lib/types.ts:1-221](file://src/lib/types.ts#L1-L221)

### 构建与打包流程
- 使用 esbuild 编译 Electron 主进程与预加载脚本
- Next.js 输出为 standalone，构建脚本进行符号链接解析、pnpm hoisting 修复、外部依赖补齐、路径剥离、Node 运行时打包与原生模块重建
- electron-builder 负责跨平台打包与签名配置

```mermaid
flowchart TD
BuildStart["开始构建"] --> Esbuild["esbuild 编译 Electron 脚本"]
Esbuild --> NextBuild["Next.js 构建 standalone"]
NextBuild --> Symlink["解析符号链接"]
Symlink --> HoistFix["修复 pnpm hoisting"]
HoistFix --> ExtDeps["补齐外部依赖"]
ExtDeps --> Strip["剥离开发机路径"]
Strip --> NodeRuntime["打包内置 Node 运行时"]
NodeRuntime --> RebuildNative["原生模块重建"]
RebuildNative --> Templates["复制模板到 standalone"]
Templates --> Assemble["组装打包产物"]
Assemble --> EB["electron-builder 打包"]
EB --> Release["生成安装包"]
```

**图表来源**
- [scripts/build-electron.mjs:1-399](file://scripts/build-electron.mjs#L1-L399)
- [electron-builder.json:1-126](file://electron-builder.json#L1-L126)

**章节来源**
- [scripts/build-electron.mjs:1-399](file://scripts/build-electron.mjs#L1-L399)
- [electron-builder.json:1-126](file://electron-builder.json#L1-L126)
- [package.json:13-26](file://package.json#L13-L26)

### API 调用与状态管理
- 自定义 Hook 封装 API 请求，如会话列表、创建、更新、删除与刷新
- 在布局组件中组合多个 Hook，协调视图切换、权限模式与思考模式、文件编辑器面板等

```mermaid
sequenceDiagram
participant UI as "视图组件"
participant Hook as "use-sessions Hook"
participant API as "API 路由"
participant DB as "数据库"
UI->>Hook : 调用创建/更新/删除/刷新
Hook->>API : 发起 HTTP 请求
API->>DB : 读写数据库
DB-->>API : 返回结果
API-->>Hook : 返回数据
Hook-->>UI : 更新状态
```

**图表来源**
- [src/hooks/use-sessions.ts:1-81](file://src/hooks/use-sessions.ts#L1-L81)
- [src/components/layout/app-layout.tsx:34-81](file://src/components/layout/app-layout.tsx#L34-L81)

**章节来源**
- [src/hooks/use-sessions.ts:1-81](file://src/hooks/use-sessions.ts#L1-L81)
- [src/components/layout/app-layout.tsx:1-566](file://src/components/layout/app-layout.tsx#L1-L566)

## 依赖关系分析
- 包管理与脚本：使用 pnpm，脚本涵盖开发、构建、打包与类型检查
- 依赖拆分：运行时依赖（React、Next、Claude SDK、better-sqlite3）、开发依赖（Electron、electron-builder、esbuild、tsup、Tailwind 等）
- 外部包处理：Next 配置将部分包标记为外部，避免被打包进客户端，同时在 standalone 中补齐缺失的传递依赖

```mermaid
graph TB
P["package.json 脚本"] --> Dev["开发脚本"]
P --> Build["构建脚本"]
P --> Package["打包脚本"]
subgraph "运行时依赖"
R1["@anthropic-ai/claude-agent-sdk"]
R2["react / react-dom"]
R3["next"]
R4["better-sqlite3"]
R5["@larksuiteoapi/node-sdk"]
end
subgraph "开发依赖"
D1["electron"]
D2["electron-builder"]
D3["esbuild / tsup"]
D4["tailwindcss / autoprefixer"]
D5["concurrently / wait-on"]
end
Build --> D3
Build --> D4
Build --> D5
Build --> R4
Build --> R5
```

**图表来源**
- [package.json:27-59](file://package.json#L27-L59)
- [next.config.ts:9-9](file://next.config.ts#L9-L9)

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

## 性能考虑
- Next.js 独立服务器输出禁用压缩，避免缓冲影响 SSE 流式传输
- SQLite 使用 WAL 模式提升并发读取性能
- 文件系统监听采用防抖与忽略规则，降低频繁变更带来的通知开销
- 原生模块通过内置 Node 运行时与预构建策略减少打包体积与启动时间
- Tailwind 仅扫描源码目录，避免不必要的样式扫描

**章节来源**
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [src/lib/db.ts:21-23](file://src/lib/db.ts#L21-L23)
- [electron/main.ts:34-35](file://electron/main.ts#L34-L35)
- [tailwind.config.ts:4-4](file://tailwind.config.ts#L4-L4)

## 故障排查指南
- 启动失败：检查 Node.js 是否可用、PATH 是否包含 CLI 工具路径、端口占用情况
- 服务器未就绪：确认 Next 开发服务器已监听，或 standalone 服务器已成功启动
- 数据库异常：查看迁移日志与表结构，确认 WAL 与外键 pragma 设置正确
- IM 桥接异常：检查通道状态与凭据，确认平台回调与去重机制正常
- 打包失败：核对 electron-builder 配置、签名脚本、Node 运行时版本与原生模块重建日志

**章节来源**
- [electron/main.ts:54-71](file://electron/main.ts#L54-L71)
- [src/lib/db.ts:226-437](file://src/lib/db.ts#L226-L437)
- [scripts/build-electron.mjs:294-336](file://scripts/build-electron.mjs#L294-L336)

## 结论
Forge 通过 Electron + Next.js 的组合实现了高性能、可扩展的本地 AI 桌面应用。清晰的分层架构、完善的构建与打包流程、稳健的数据库迁移与类型系统，为新开发者提供了良好的入门路径与长期维护基础。建议在开发过程中遵循本文档的规范与最佳实践，持续关注性能与安全性优化，确保高质量交付。

## 附录

### 开发环境搭建步骤
- 安装 Node.js 20+ 与 pnpm 9+
- 安装 Claude Code CLI 并完成认证
- 克隆仓库并安装依赖
- 启动开发服务器与 Electron 主进程

**章节来源**
- [README.md:42-56](file://README.md#L42-L56)
- [package.json:13-17](file://package.json#L13-L17)

### 代码规范与最佳实践
- TypeScript 严格模式与 bundler 解析，确保类型安全与模块解析一致性
- 统一的数据模型与状态类型，前后端一致
- 组件职责单一，Hook 抽象 API 交互
- Tailwind 仅扫描源码目录，保持样式构建高效
- 数据库迁移与约束演进需向后兼容

**章节来源**
- [tsconfig.json:1-24](file://tsconfig.json#L1-L24)
- [tailwind.config.ts:4-4](file://tailwind.config.ts#L4-L4)
- [src/lib/types.ts:1-221](file://src/lib/types.ts#L1-L221)
- [src/lib/db.ts:226-437](file://src/lib/db.ts#L226-L437)

### 调试技巧与日志
- 开发模式下使用 Next.js Turbopack，热更新与错误提示更友好
- Electron 主进程输出服务器日志与错误堆栈
- 使用浏览器开发者工具检查网络请求与组件状态
- 数据库层可通过迁移日志定位 schema 差异

**章节来源**
- [README.md:370-382](file://README.md#L370-L382)
- [electron/main.ts:120-135](file://electron/main.ts#L120-L135)

### 构建、跨平台打包与发布
- 本地构建：先构建 Next.js，再构建 Electron
- 跨平台打包：macOS（dmg/arm64）、Windows（NSIS/x64）、Linux（AppImage/x64）
- 打包配置：electron-builder，包含签名钩子、asar、asrUnpack、额外资源等
- 内置 Node 运行时：避免用户环境差异导致的原生模块不兼容

**章节来源**
- [package.json:18-25](file://package.json#L18-L25)
- [electron-builder.json:62-124](file://electron-builder.json#L62-L124)
- [scripts/build-electron.mjs:214-292](file://scripts/build-electron.mjs#L214-L292)

### 性能优化建议
- 保持 Next.js 独立服务器输出，避免不必要的压缩
- 使用 WAL 模式与索引优化高频查询
- 控制文件系统监听范围与频率，避免过度通知
- 优先使用内置 Node 运行时与预构建原生模块

**章节来源**
- [next.config.ts:5-5](file://next.config.ts#L5-L5)
- [src/lib/db.ts:50-50](file://src/lib/db.ts#L50-L50)
- [electron/main.ts:34-35](file://electron/main.ts#L34-L35)
- [scripts/build-electron.mjs:294-336](file://scripts/build-electron.mjs#L294-L336)

### 安全考虑与可靠性设计
- 硬化运行时与沙箱配置（macOS）
- 仅打包必要资源，剥离开发机路径，避免隐私泄露
- 外部包标记为外部并在 standalone 中补齐依赖
- 原生模块与 Node 版本匹配，避免 ABI 不兼容

**章节来源**
- [electron-builder.json:76-80](file://electron-builder.json#L76-L80)
- [scripts/build-electron.mjs:157-202](file://scripts/build-electron.mjs#L157-L202)
- [next.config.ts:9-9](file://next.config.ts#L9-L9)

### 贡献指南与代码评审标准
- 遵循现有文件组织与命名约定
- 新增功能需配套 API 路由与数据库迁移
- 提交前执行类型检查与构建验证
- 代码评审关注：可维护性、性能影响、安全性与兼容性

**章节来源**
- [tsconfig.json:1-24](file://tsconfig.json#L1-L24)
- [package.json:25-25](file://package.json#L25-L25)