# 快速开始

<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)
- [scripts/build-electron.mjs](file://scripts/build-electron.mjs)
- [electron-builder.json](file://electron-builder.json)
- [tsconfig.json](file://tsconfig.json)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/forge-data.ts](file://src/lib/forge-data.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)
- [src/lib/cron/executor.ts](file://src/lib/cron/executor.ts)
- [src/hooks/use-sessions.ts](file://src/hooks/use-sessions.ts)
</cite>

## 目录
1. [简介](#简介)
2. [系统要求与平台支持](#系统要求与平台支持)
3. [安装与运行](#安装与运行)
4. [开发环境与生产环境差异](#开发环境与生产环境差异)
5. [核心功能与使用示例](#核心功能与使用示例)
6. [架构概览](#架构概览)
7. [依赖关系分析](#依赖关系分析)
8. [性能与资源特性](#性能与资源特性)
9. [常见问题排查](#常见问题排查)
10. [跨平台打包与发布](#跨平台打包与发布)
11. [结语](#结语)

## 简介
Forge 是一款基于桌面端的本地 AI 工作站，以 Claude Agent SDK 为核心能力，提供聊天对话、IM 桥接、计划任务调度、可视化工作区管理等功能。它将 Next.js 与 Electron 结合，既能在桌面应用中提供流畅的交互体验，又保留了 Web 应用的可扩展性。

## 系统要求与平台支持
- Node.js：20+（构建与开发）
- 包管理器：pnpm 9+
- Claude Code CLI：需安装并完成登录认证（推荐）
- 平台支持：
  - macOS：原生支持（arm64；Intel Mac 可通过源码打包）
  - Windows：通过 nsis 安装包支持（x64）
  - Linux：通过 AppImage 支持（x64）

以上信息来源于项目脚本、构建配置与说明文档。

**章节来源**
- [README.md: 44–48:44-48](file://README.md#L44-L48)
- [package.json: 13–26:13-26](file://package.json#L13-L26)
- [electron-builder.json: 62–124:62-124](file://electron-builder.json#L62-L124)

## 安装与运行
- 下载发行版（最简路径）
  1) 安装并登录 Claude Code CLI
  2) 在 Releases 页面下载对应平台的安装包
  3) 启动应用，完成引导流程，选择项目目录
  4) 输入 /init 进行工作区初始化
- 从源码构建（开发者）
  1) 克隆仓库并进入目录
  2) 使用 pnpm 安装依赖
  3) 运行开发命令启动桌面应用（前端 + Electron 主进程）
  4) 生产构建与打包可使用内置脚本

开发与构建命令参考：
- 开发：同时启动 Next.js 与 Electron 主进程
- 构建：分别构建 Next.js 与 Electron 资源
- 打包：针对不同平台生成安装包

**章节来源**
- [README.md: 32–56:32-56](file://README.md#L32-L56)
- [package.json: 13–26:13-26](file://package.json#L13-L26)

## 开发环境与生产环境差异
- 开发模式
  - Electron 主进程直接加载本地前端服务（localhost:3000）
  - 便于热更新与调试
- 生产模式
  - Next.js 输出为独立服务器（standalone），由 Electron 子进程启动
  - 数据目录默认位于用户主目录下的 ~/.forge
  - 通过内嵌 Node.js 运行时避免宿主系统版本差异带来的问题

**章节来源**
- [electron/main.ts: 8, 272–289:8-8](file://electron/main.ts#L8-L8)
- [electron/main.ts: 272–289:272-289](file://electron/main.ts#L272-L289)
- [next.config.ts: 3–10:3-10](file://next.config.ts#L3-L10)
- [scripts/build-electron.mjs: 214–292:214-292](file://scripts/build-electron.mjs#L214-L292)

## 核心功能与使用示例
以下示例均基于内置 API 与桌面交互，无需编写额外代码。

- 创建第一个会话
  - 方法一：在聊天界面输入“/new”创建新会话
  - 方法二：调用后端接口创建会话（客户端 Hook 已封装）
    - 参考：[use-sessions.ts: 50–59:50-59](file://src/hooks/use-sessions.ts#L50-L59)
- 配置 IM 桥接（飞书/电报/Discord）
  - 在设置中添加各平台的机器人凭据
  - 启用通道后，桥接管理器自动连接并轮询消息
  - 参考：[bridge-manager.ts: 78–144:78-144](file://src/lib/im/bridge-manager.ts#L78-L144)
- 设置计划任务
  - 在“调度视图”创建任务，选择执行类型（运行代理/技能/自定义提示）
  - 引擎每分钟检查一次，匹配到即执行
  - 参考：
    - [engine.ts: 21–62:21-62](file://src/lib/cron/engine.ts#L21-L62)
    - [executor.ts: 26–47:26-47](file://src/lib/cron/executor.ts#L26-L47)
- 数据存储与迁移
  - 应用数据位于 ~/.forge（数据库、上传文件、模板等）
  - 支持从旧位置迁移数据
  - 参考：
    - [forge-data.ts: 20–26:20-26](file://src/lib/forge-data.ts#L20-L26)
    - [db.ts: 12–16:12-16](file://src/lib/db.ts#L12-L16)

**章节来源**
- [README.md: 178–242:178-242](file://README.md#L178-L242)
- [src/hooks/use-sessions.ts: 50–59:50-59](file://src/hooks/use-sessions.ts#L50-L59)
- [src/lib/im/bridge-manager.ts: 78–144:78-144](file://src/lib/im/bridge-manager.ts#L78-L144)
- [src/lib/cron/engine.ts: 21–62:21-62](file://src/lib/cron/engine.ts#L21-L62)
- [src/lib/cron/executor.ts: 26–47:26-47](file://src/lib/cron/executor.ts#L26-L47)
- [src/lib/forge-data.ts: 20–26:20-26](file://src/lib/forge-data.ts#L20-L26)
- [src/lib/db.ts: 12–16:12-16](file://src/lib/db.ts#L12-L16)

## 架构概览
下图展示了桌面应用的启动与运行时关键组件：

```mermaid
graph TB
subgraph "桌面应用"
A["Electron 主进程<br/>electron/main.ts"]
B["Next.js 独立服务器<br/>next.config.ts"]
C["数据库<br/>src/lib/db.ts"]
D["数据目录<br/>src/lib/forge-data.ts"]
end
subgraph "运行时服务"
E["IM 桥接管理器<br/>src/lib/im/bridge-manager.ts"]
F["计划任务引擎<br/>src/lib/cron/engine.ts"]
end
A --> B
A --> C
B --> C
B --> D
E --> B
F --> B
E --> C
F --> C
```

**图表来源**
- [electron/main.ts: 177–289:177-289](file://electron/main.ts#L177-L289)
- [next.config.ts: 3–10:3-10](file://next.config.ts#L3-L10)
- [src/lib/db.ts: 18–437:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts: 20–26:20-26](file://src/lib/forge-data.ts#L20-L26)
- [src/lib/im/bridge-manager.ts: 45–626:45-626](file://src/lib/im/bridge-manager.ts#L45-L626)
- [src/lib/cron/engine.ts: 16–120:16-120](file://src/lib/cron/engine.ts#L16-L120)

## 依赖关系分析
- 构建与打包
  - 使用 esbuild 编译 Electron 主进程与预加载脚本
  - 使用 electron-builder 进行多平台打包
  - 构建脚本负责符号链接解析、pnpm hoisting 修复、外部依赖补齐、隐私路径清理、Node 运行时内嵌与原生模块重建
- 运行时依赖
  - SQLite 数据库（better-sqlite3）与 WAL 模式
  - Claude Agent SDK 作为核心推理引擎
  - IM 适配器（飞书/电报/Discord）通过各自 SDK 实现

```mermaid
graph LR
P["package.json<br/>脚本与依赖"] --> S["scripts/build-electron.mjs<br/>构建与打包流水线"]
S --> EB["electron-builder.json<br/>打包配置"]
S --> N["内嵌 Node.js 运行时<br/>scripts/build-electron.mjs:214–292"]
S --> DB["SQLite 数据库<br/>src/lib/db.ts"]
EB --> OUT["产物：DMG/NSIS/AppImage"]
```

**图表来源**
- [package.json: 13–26:13-26](file://package.json#L13-L26)
- [scripts/build-electron.mjs: 1–399:1-399](file://scripts/build-electron.mjs#L1-L399)
- [electron-builder.json: 1–126:1-126](file://electron-builder.json#L1-L126)
- [src/lib/db.ts: 18–437:18-437](file://src/lib/db.ts#L18-L437)

**章节来源**
- [package.json: 13–26:13-26](file://package.json#L13-L26)
- [scripts/build-electron.mjs: 1–399:1-399](file://scripts/build-electron.mjs#L1-L399)
- [electron-builder.json: 1–126:1-126](file://electron-builder.json#L1-L126)
- [src/lib/db.ts: 18–437:18-437](file://src/lib/db.ts#L18-L437)

## 性能与资源特性
- 数据库
  - 使用 WAL 模式提升并发读取性能
  - 多表索引优化查询（如消息按会话与时间排序）
- 运行时
  - Electron 主进程通过子进程启动 Next.js 独立服务器，避免 ABI 不兼容
  - 内嵌 Node.js 运行时，减少宿主环境差异
- IM 与计划任务
  - IM 消息轮询与去重、权限请求异步化、并发控制与超时保护
  - 计划任务每分钟扫描，执行后记录结果与会话关联

**章节来源**
- [src/lib/db.ts: 22–224:22-224](file://src/lib/db.ts#L22-L224)
- [electron/main.ts: 74–139:74-139](file://electron/main.ts#L74-L139)
- [scripts/build-electron.mjs: 214–292:214-292](file://scripts/build-electron.mjs#L214-L292)
- [src/lib/im/bridge-manager.ts: 257–328:257-328](file://src/lib/im/bridge-manager.ts#L257-L328)
- [src/lib/cron/engine.ts: 21–62:21-62](file://src/lib/cron/engine.ts#L21-L62)

## 常见问题排查
- Claude CLI 未找到或未登录
  - 现象：启动失败或功能受限
  - 处理：安装并登录 Claude Code CLI，确认命令可用
  - 参考：[README.md: 297–305:297-305](file://README.md#L297-L305)
- 数据目录与迁移
  - 现象：首次启动找不到数据或历史数据未迁移
  - 处理：确认 ~/.forge 目录存在；首次访问会触发迁移逻辑
  - 参考：
    - [forge-data.ts: 20–26:20-26](file://src/lib/forge-data.ts#L20-L26)
    - [db.ts: 12–16:12-16](file://src/lib/db.ts#L12-L16)
- IM 桥接无法连接
  - 现象：通道状态异常或频繁重连
  - 处理：检查凭据有效性、网络可达性；查看桥接管理器状态与错误日志
  - 参考：[bridge-manager.ts: 104–144:104-144](file://src/lib/im/bridge-manager.ts#L104-L144)
- 计划任务未执行
  - 现象：任务未按预期触发
  - 处理：确认任务已启用且表达式正确；检查引擎是否运行
  - 参考：
    - [engine.ts: 21–62:21-62](file://src/lib/cron/engine.ts#L21-L62)
    - [executor.ts: 26–47:26-47](file://src/lib/cron/executor.ts#L26-L47)

**章节来源**
- [README.md: 297–333:297-333](file://README.md#L297-L333)
- [src/lib/forge-data.ts: 20–26:20-26](file://src/lib/forge-data.ts#L20-L26)
- [src/lib/db.ts: 12–16:12-16](file://src/lib/db.ts#L12-L16)
- [src/lib/im/bridge-manager.ts: 104–144:104-144](file://src/lib/im/bridge-manager.ts#L104-L144)
- [src/lib/cron/engine.ts: 21–62:21-62](file://src/lib/cron/engine.ts#L21-L62)
- [src/lib/cron/executor.ts: 26–47:26-47](file://src/lib/cron/executor.ts#L26-L47)

## 跨平台打包与发布
- macOS
  - 生成 DMG 与目录格式，目标架构为 arm64
  - 可通过脚本生成 Intel Mac 的安装包（源码打包）
- Windows
  - 生成 NSIS 安装包（x64），支持桌面快捷方式与开始菜单
- Linux
  - 生成 AppImage（x64），适合桌面发行版

```mermaid
flowchart TD
Start(["开始"]) --> Select["选择平台与目标"]
Select --> Mac{"macOS?"}
Mac --> |是| MacBuild["构建 DMG/目录<br/>目标: arm64"]
Mac --> |否| Win{"Windows?"}
Win --> |是| WinBuild["构建 NSIS<br/>目标: x64"]
Win --> |否| Linux{"Linux?"}
Linux --> |是| LinuxBuild["构建 AppImage<br/>目标: x64"]
MacBuild --> End(["结束"])
WinBuild --> End
LinuxBuild --> End
```

**图表来源**
- [electron-builder.json: 62–124:62-124](file://electron-builder.json#L62-L124)

**章节来源**
- [electron-builder.json: 1–126:1-126](file://electron-builder.json#L1-L126)
- [package.json: 21–24:21-24](file://package.json#L21-L24)

## 结语
通过上述步骤，你可以在最短时间内完成 Forge 的安装与运行，并基于内置 API 与桌面交互实现会话创建、IM 桥接与计划任务等核心功能。若需进一步定制或扩展，建议从数据库结构、IM 适配器与计划任务执行器入手，结合现有脚本与配置进行二次开发。