# 项目概述

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [electron/main.ts](file://electron/main.ts)
- [src/app/layout.tsx](file://src/app/layout.tsx)
- [next.config.ts](file://next.config.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/hooks/use-im-channels.ts](file://src/hooks/use-im-channels.ts)
- [src/hooks/use-cron-tasks.ts](file://src/hooks/use-cron-tasks.ts)
- [src/lib/workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [src/components/views/chat-view.tsx](file://src/components/views/chat-view.tsx)
</cite>

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

## 引言
Forge 是一款面向本地的 AI 智能体桌面应用，以“本地化 AI、远程控制”为核心定位，通过桌面端界面提供更自然、低门槛的 AI 协作体验。它基于 Electron + Next.js 技术栈构建，结合 Claude Agent SDK 实现强大的对话、工具调用与自动化能力；同时内置即时消息（IM）桥接、可视化计划任务调度、工作空间管理与持久化记忆系统，形成从“个人工作台”到“可复用解决方案”的完整闭环。

Forge 的核心价值在于：
- 将 Claude Code 的强大能力封装为原生桌面应用，支持流式响应、内联图片、工具调用可视化、文件树浏览与可视化任务调度。
- 以项目为单位的工作空间，每个项目拥有独立的规则、人格、记忆、技能与子智能体，实现“切换项目即切换团队”的长期协作体验。
- 内置 IM 桥接，打通飞书、电报、Discord 等平台，支持双向图片与文件传输，并提供心跳监控与告警能力。
- 可视化计划任务引擎，支持一次性与周期性任务，自动创建会话并可通知到 IM 平台。
- 基于 SQLite 的轻量数据库与 WAL 模式，确保多会话并发读写与高可用。

**章节来源**
- [README.md:16-31](file://README.md#L16-L31)
- [README.md:59-103](file://README.md#L59-L103)
- [README.md:343-382](file://README.md#L343-L382)

## 项目结构
项目采用“Electron 主进程 + Next.js 应用路由”的双层架构：
- electron/：Electron 主进程与预加载脚本，负责应用生命周期、系统集成（文件监听、剪贴板、打开路径）、以及在生产环境启动独立的 Next.js 服务器。
- src/app/：Next.js App Router，包含页面、API 路由与全局样式，提供聊天、IM、计划任务、市场等功能的后端接口与前端页面。
- src/components/ 与 src/hooks/：React 组件与自定义 Hook，承载 UI 交互与状态管理。
- src/lib/：核心业务逻辑，包括数据库访问、IM 桥接、计划任务引擎、工作空间文件系统、类型定义等。
- templates/：初始化配置模板，用于 /init 引导式设置。

```mermaid
graph TB
subgraph "桌面外壳Electron"
A["主进程<br/>electron/main.ts"]
B["预加载脚本<br/>electron/preload.ts"]
end
subgraph "Next.js 应用"
C["App Router<br/>src/app/*"]
D["组件与Hooks<br/>src/components/*, src/hooks/*"]
E["核心逻辑<br/>src/lib/*"]
end
subgraph "数据与资源"
F["SQLite 数据库<br/>src/lib/db.ts"]
G["工作空间文件系统<br/>src/lib/workspace-fs.ts"]
H["IM 桥接与计划任务<br/>src/lib/im/*, src/lib/cron/*"]
end
A --> C
A --> D
A --> E
C --> F
E --> F
E --> G
E --> H
```

**图表来源**
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [next.config.ts:3-12](file://next.config.ts#L3-L12)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/workspace-fs.ts:32-512](file://src/lib/workspace-fs.ts#L32-L512)

**章节来源**
- [README.md:351-382](file://README.md#L351-L382)

## 核心组件
- 会话与聊天（ChatView）
  - 支持流式响应、权限模式（询问/全权）、思考模式（关闭/自动/最大）、附件上传（图片/PDF/代码/文档）、斜杠命令（/init、/model、/clear、/compact、/export、/memory、/rename、/stop、/save-as-template、/workspace）等。
  - 通过 API 路由与数据库交互，实现消息持久化、会话管理与令牌用量统计。
- 即时消息桥接（IM Bridge）
  - 支持飞书、电报、Discord，提供通道配置、白名单策略、触发模式、绑定会话、审计日志与去重机制。
  - 提供 IM 事件处理、消息投递、权限审批与回执追踪。
- 计划任务调度（Cron Engine）
  - 支持一次性与周期性任务（分钟/小时/日/周/月），动作类型包括运行智能体、运行技能或自定义提示词。
  - 任务执行自动创建新会话，支持心跳任务与通知到 IM 平台。
- 工作空间管理（Workspace-FS）
  - 以项目为单位的 .claude/ 配置目录，包含 CLAUDE.md、SOUL.md、IDENTITY.md、USER.md、MEMORY.md、HEARTBEAT.md 等核心文件。
  - 支持全局 ~/.claude/ 与项目级 .claude/，并提供文件增删改查、迁移与归档。
- 数据与类型（DB + Types）
  - 使用 better-sqlite3 + WAL 模式，表结构覆盖 sessions、messages、agents、skills、mcp_servers、im_channels、cron_tasks、task_executions、hooks、workspaces、api_providers、channel_bindings、marketplace_templates 等。
  - 类型定义涵盖会话、消息、权限、智能体、MCP、API 提供商、IM 通道、计划任务、任务执行与市场模板等。

**章节来源**
- [src/components/views/chat-view.tsx:17-800](file://src/components/views/chat-view.tsx#L17-L800)
- [src/hooks/use-im-channels.ts:45-77](file://src/hooks/use-im-channels.ts#L45-L77)
- [src/hooks/use-cron-tasks.ts:47-116](file://src/hooks/use-cron-tasks.ts#L47-L116)
- [src/lib/workspace-fs.ts:32-512](file://src/lib/workspace-fs.ts#L32-L512)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/types.ts:6-221](file://src/lib/types.ts#L6-L221)

## 架构总览
下图展示了 Forge 的端到端架构：Electron 主进程启动 Next.js 独立服务器，前端通过 App Router 与 API 路由与后端交互；核心逻辑位于 src/lib，数据库与文件系统提供持久化支撑；IM 桥接与计划任务引擎分别处理外部通信与定时执行。

```mermaid
graph TB
subgraph "桌面层"
M["Electron 主进程<br/>electron/main.ts"]
N["Next.js 应用<br/>src/app/*"]
end
subgraph "业务层"
L1["聊天与会话<br/>ChatView + API 路由"]
L2["IM 桥接<br/>IM 通道 + 权限 + 投递"]
L3["计划任务<br/>解析器 + 执行器 + 通知"]
L4["工作空间<br/>.claude/ 文件系统"]
end
subgraph "数据层"
D1["SQLite 数据库<br/>src/lib/db.ts"]
D2["文件系统<br/>src/lib/workspace-fs.ts"]
end
M --> N
N --> L1
N --> L2
N --> L3
N --> L4
L1 --> D1
L2 --> D1
L3 --> D1
L4 --> D2
```

**图表来源**
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/workspace-fs.ts:32-512](file://src/lib/workspace-fs.ts#L32-L512)

**章节来源**
- [next.config.ts:3-12](file://next.config.ts#L3-L12)
- [src/app/layout.tsx:22-38](file://src/app/layout.tsx#L22-L38)

## 详细组件分析

### 会话与聊天（ChatView）
- 功能要点
  - 斜杠命令菜单与自动补全，支持 /init 引导、/model 切换模型、/clear 清空会话、/compact 压缩历史、/export 导出、/memory 打开记忆、/rename 重命名、/stop 停止、/save-as-template 保存为模板、/workspace 切换工作区。
  - 附件上传与预览，支持图片与多种文档格式，发送时转换为结构化数据以便多模态处理。
  - 流式渲染与滚动行为优化，仅在用户未向上滚动时自动跟随最新消息。
  - 权限模式与思考模式下拉菜单，支持 per-action 审批与不同推理强度。
- 数据与接口
  - 通过 fetch 调用 /api/sessions/{id}/compact、/api/workspaces/{id}/diff、/api/marketplace/save-from-workspace、/api/upload 等 API。
  - 与数据库交互以持久化消息与会话元数据。

```mermaid
sequenceDiagram
participant U as "用户"
participant V as "ChatView"
participant API as "API 路由"
participant DB as "数据库"
U->>V : 输入消息或斜杠命令
V->>API : 发送消息/执行命令如 /init、/model、/export
API->>DB : 读取/写入会话/消息/配置
DB-->>API : 返回结果
API-->>V : 响应消息、模板、状态
V-->>U : 渲染流式响应/系统消息/模型选择器
```

**图表来源**
- [src/components/views/chat-view.tsx:183-332](file://src/components/views/chat-view.tsx#L183-L332)
- [src/components/views/chat-view.tsx:449-483](file://src/components/views/chat-view.tsx#L449-L483)

**章节来源**
- [src/components/views/chat-view.tsx:17-800](file://src/components/views/chat-view.tsx#L17-L800)

### 即时消息桥接（IM 通道）
- 功能要点
  - 通道类型：飞书、电报、Discord；支持启用/禁用、连接状态、凭据存储、DM/群组策略、触发模式（提及/全部）与白名单。
  - 会话绑定：按通道与聊天 ID 绑定到具体会话，支持每会话绑定。
  - 审计与去重：记录操作日志与去重表，避免重复处理。
- 数据与接口
  - 通过 /api/im-channels 获取与更新通道配置；通过 /api/im-events 接收平台事件；通过 /api/im-channels/{id}/connect 触发连接测试。
  - 与数据库交互以持久化通道状态、绑定关系与审计日志。

```mermaid
flowchart TD
Start(["进入 IM 设置"]) --> List["列出所有通道"]
List --> Config["配置凭据/策略/触发模式"]
Config --> Connect["连接测试通道适配器"]
Connect --> Bind["绑定会话按聊天维度"]
Bind --> Audit["记录审计日志/去重"]
Audit --> End(["完成"])
```

**图表来源**
- [src/hooks/use-im-channels.ts:45-77](file://src/hooks/use-im-channels.ts#L45-L77)
- [src/lib/db.ts:102-200](file://src/lib/db.ts#L102-L200)

**章节来源**
- [src/hooks/use-im-channels.ts:1-77](file://src/hooks/use-im-channels.ts#L1-L77)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

### 计划任务调度（Cron 引擎）
- 功能要点
  - 任务类型：一次性、每 N 分钟、每小时、每日、每周、每月；动作类型：运行智能体、运行技能、自定义提示词。
  - 心跳任务：默认禁用，可通过 /api/cron-tasks 创建并启用，定期检查清单并通过 IM 通知。
  - 执行与追踪：每次执行创建新会话，记录执行时间、结果与状态。
- 数据与接口
  - 通过 /api/cron-tasks 获取/创建/更新/删除任务；通过 /api/cron-tasks/{id}/execute 触发立即执行。
  - 与数据库交互以持久化任务与执行记录。

```mermaid
flowchart TD
S(["创建/编辑任务"]) --> Save["保存到数据库"]
Save --> Enable{"启用？"}
Enable --> |否| Wait["等待启用"]
Enable --> |是| Schedule["按计划触发"]
Schedule --> Exec["执行动作新建会话"]
Exec --> Notify["通知IM/邮件"]
Notify --> Log["记录执行日志"]
Log --> End(["完成"])
```

**图表来源**
- [src/hooks/use-cron-tasks.ts:47-116](file://src/hooks/use-cron-tasks.ts#L47-L116)
- [src/lib/db.ts:117-147](file://src/lib/db.ts#L117-L147)

**章节来源**
- [src/hooks/use-cron-tasks.ts:1-116](file://src/hooks/use-cron-tasks.ts#L1-L116)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

### 工作空间与文件系统（.claude/）
- 功能要点
  - 核心文件：CLAUDE.md（项目规则）、SOUL.md（个性）、IDENTITY.md（身份）、USER.md（用户画像）、MEMORY.md（长期记忆索引）、HEARTBEAT.md（周期检查清单）。
  - 子目录：skills（项目技能）、agents（子智能体）、rules（条件规则）、memory（日常记忆与主题文件）。
  - 迁移与归档：支持从旧目录迁移、自动归档超过保留期的日常记忆。
- 数据与接口
  - 通过 API 路由与工作空间文件系统交互，实现文件读写、重命名、删除与目录结构维护。

```mermaid
flowchart TD
Init(["初始化工作区"]) --> Ensure["确保 .claude/ 目录存在"]
Ensure --> Files["创建核心文件与子目录"]
Files --> Context["加载上下文除 MEMORY.md 外"]
Context --> Memory["加载 MEMORY.md 前 200 行 + 最近 2 日日常记忆"]
Memory --> Archive["归档超期日常记忆至 archive.md"]
Archive --> Ready(["就绪"])
```

**图表来源**
- [src/lib/workspace-fs.ts:196-281](file://src/lib/workspace-fs.ts#L196-L281)
- [src/lib/workspace-fs.ts:355-397](file://src/lib/workspace-fs.ts#L355-L397)
- [src/lib/workspace-fs.ts:464-504](file://src/lib/workspace-fs.ts#L464-L504)

**章节来源**
- [src/lib/workspace-fs.ts:1-512](file://src/lib/workspace-fs.ts#L1-L512)

### 数据模型与类型
- 关键实体
  - 会话（Session）、消息（Message）、权限状态（PermissionStatus）、内容块（ContentBlock）、代理（Agent）、技能（Skill）、MCP 服务器（McpServer）、API 提供商（ApiProvider）、IM 通道（ImChannel）、计划任务（CronTask）、任务执行（TaskExecution）、市场模板（MarketplaceTemplate）。
- 设计要点
  - 类型驱动的数据结构，确保前后端一致性；外键约束与索引提升查询效率；JSON 字段用于灵活配置（如 MCP 配置、IM 凭据、任务配置）。

```mermaid
erDiagram
SESSIONS ||--o{ MESSAGES : "包含"
AGENTS ||--o{ AGENT_SKILLS : "关联"
SKILLS ||--o{ AGENT_SKILLS : "被关联"
IM_CHANNELS ||--o{ CHANNEL_BINDINGS : "绑定"
CHANNEL_BINDINGS ||--|| CHANNEL_PERMISSION_LINKS : "权限链接"
CRON_TASKS ||--o{ TASK_EXECUTIONS : "执行"
WORKSPACES ||--o{ AGENTS : "拥有"
WORKSPACES ||--o{ SKILLS : "拥有"
```

**图表来源**
- [src/lib/types.ts:6-221](file://src/lib/types.ts#L6-L221)
- [src/lib/db.ts:25-200](file://src/lib/db.ts#L25-L200)

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

## 依赖分析
- 技术栈选择
  - 桌面：Electron + Next.js 15（Turbopack），实现原生桌面体验与快速开发迭代。
  - 数据库：better-sqlite3 + WAL 模式，兼顾性能与可靠性。
  - AI：Claude Agent SDK，提供强大的智能体与工具调用能力。
  - 样式：Tailwind CSS，保证一致的视觉风格与响应式布局。
  - 包管理：pnpm，提升安装速度与磁盘占用。
- 外部依赖
  - @larksuiteoapi/node-sdk：飞书平台适配。
  - better-sqlite3：本地数据库。
  - react、react-dom、next：前端框架与服务端渲染。
  - lucide-react、react-markdown、shiki：UI 图标、Markdown 渲染与代码高亮。
- 构建与打包
  - 生产环境：Electron 启动独立的 Next.js 服务器，静态输出（standalone），禁用压缩以避免 SSE 缓冲问题。
  - 服务器外部包：better-sqlite3、@larksuiteoapi/node-sdk 外部化，保持原生 WebSocket 行为。

```mermaid
graph LR
P["package.json 依赖"] --> E["Electron"]
P --> N["Next.js"]
P --> S["better-sqlite3"]
P --> A["@anthropic-ai/claude-agent-sdk"]
P --> L["@larksuiteoapi/node-sdk"]
N --> C["Tailwind CSS"]
N --> R["React/ReactDOM"]
```

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

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

## 性能考虑
- 数据库
  - WAL 模式提升并发读取性能；为高频查询建立索引（如 messages.session_id、task_executions.task_id）。
  - 事务化写入与外键约束保障数据一致性。
- 前端
  - Next.js Turbopack 开发模式加速热更新；生产禁用 gzip，避免 SSE 缓冲导致的延迟。
  - ChatView 自动滚动与流式渲染优化用户体验，减少不必要的重绘。
- 服务器
  - Electron 在生产环境使用独立 Node.js 进程运行 Next.js 服务器，避免 ABI 兼容性问题与原生模块重新编译。
  - 通过扩展 PATH 使 SDK 能找到 claude CLI 与其它工具。

**章节来源**
- [src/lib/db.ts:21-24](file://src/lib/db.ts#L21-L24)
- [next.config.ts:5-5](file://next.config.ts#L5-L5)
- [electron/main.ts:85-118](file://electron/main.ts#L85-L118)

## 故障排查指南
- 启动失败
  - 症状：应用无法启动或弹出错误框。
  - 排查：确认 Node.js 已安装且可执行；查看主进程日志；检查独立服务器启动与端口占用。
  - 参考：[electron/main.ts:272-288](file://electron/main.ts#L272-L288)
- claude 命令不可用
  - 症状：提示 claude 命令未找到或认证失败。
  - 排查：安装并登录 Claude Code CLI；验证版本与认证状态；确保 PATH 中包含 CLI 安装路径。
  - 参考：[README.md:297-305](file://README.md#L297-L305)
- 数据位置与迁移
  - 症状：找不到数据或升级后异常。
  - 排查：数据位于 ~/.forge/；首次访问会尝试从旧目录迁移；检查数据库文件与上传目录是否存在。
  - 参考：[README.md:307-316](file://README.md#L307-L316)，[src/lib/db.ts:12-16](file://src/lib/db.ts#L12-L16)
- IM 桥接无公网需求
  - 症状：担心需要公网 IP 或端口转发。
  - 排查：三平台均使用出站连接（WebSocket/长轮询），无需公网暴露。
  - 参考：[README.md:324-333](file://README.md#L324-L333)
- 重置工作区人格
  - 症状：希望重置智能体个性与身份。
  - 排查：删除 .claude/ 对应文件后执行 /init 重新生成。
  - 参考：[README.md:335-339](file://README.md#L335-L339)

**章节来源**
- [electron/main.ts:272-288](file://electron/main.ts#L272-L288)
- [README.md:297-339](file://README.md#L297-L339)
- [src/lib/db.ts:12-16](file://src/lib/db.ts#L12-L16)

## 结论
Forge 通过 Electron + Next.js 的组合，将 Claude Agent SDK 的强大能力以原生桌面应用的形式呈现，配合 IM 桥接、计划任务与工作空间管理，构建了从“个人工作台”到“可复用解决方案”的完整生态。SQLite 与文件系统提供可靠持久化，类型驱动的设计与完善的 API 路由确保前后端一致性。对于初学者，斜杠命令与引导式初始化降低了上手门槛；对于专家，丰富的配置项、MCP 集成与任务引擎提供了高度可扩展的自动化能力。

## 附录
- 版本与许可
  - 当前版本：1.0.2
  - 许可证：Apache License 2.0
  - 作者：FEICAI
  - 仓库：https://github.com/feicaiclub/forge
- 开发与构建
  - 开发：pnpm dev（Next.js + Electron 并行）
  - 构建：pnpm build（Next.js + Electron）
  - 打包：pnpm package（electron-builder）

**章节来源**
- [package.json:2-11](file://package.json#L2-L11)
- [README.md:392-397](file://README.md#L392-L397)
- [README.md:369-382](file://README.md#L369-L382)