# 代码结构

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [next.config.ts](file://next.config.ts)
- [tsconfig.json](file://tsconfig.json)
- [electron/main.ts](file://electron/main.ts)
- [src/app/layout.tsx](file://src/app/layout.tsx)
- [src/app/page.tsx](file://src/app/page.tsx)
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/lib/utils.ts](file://src/lib/utils.ts)
- [src/hooks/use-workspaces.ts](file://src/hooks/use-workspaces.ts)
- [src/components/layout/app-layout.tsx](file://src/components/layout/app-layout.tsx)
- [src/app/api/workspaces/route.ts](file://src/app/api/workspaces/route.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)
</cite>

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

## 引言
本文件系统性梳理 Forge 项目的代码结构与组织原则，覆盖目录职责、TypeScript 文件组织、命名约定、分层架构设计以及模块化开发最佳实践。Forge 是一款基于桌面端的本地 AI 工作台，采用 Electron + Next.js 的混合架构，结合 SQLite 数据持久化与 Claude Agent SDK，提供聊天、IM 桥接、定时任务、市场模板等能力。

## 项目结构
- 根目录关键目录与职责概览
  - electron/: Electron 主进程与预加载脚本，负责应用生命周期、系统对话框、文件系统监听、剪贴板与资源路径等。
  - src/: 前端源码，包含 Next.js 应用路由、React 组件、自定义 Hooks、业务逻辑库与类型定义。
  - public/: 静态资源（本仓库未包含具体文件）。
  - scripts/: 构建与打包脚本，如打包 Electron 的构建脚本与签名脚本。
  - templates/: 初始化配置模板，用于 /init 引导工作区配置。
  - 其他：配置文件如 next.config.ts、tsconfig.json、package.json 等。

- 目录组织原则
  - 分层清晰：UI 层（components/）、业务层（hooks/、lib/）、数据层（lib/db.ts、lib/marketplace-fs.ts）。
  - 路由驱动：src/app/ 下使用 Next.js App Router，以文件系统即路由的方式组织 API 与页面。
  - 模块化：通过路径别名 @/* 统一导入，减少相对路径复杂度。
  - 平台集成：Electron 主进程负责系统级能力，Next.js 提供渲染与 API；两者通过本地 Standalone Server 协作。

```mermaid
graph TB
subgraph "桌面应用"
EMain["Electron 主进程<br/>electron/main.ts"]
EPreload["预加载脚本<br/>electron/preload.ts"]
end
subgraph "前端应用"
Next["Next.js 应用<br/>src/app/*"]
Cmp["React 组件<br/>src/components/*"]
Hooks["自定义 Hooks<br/>src/hooks/*"]
Lib["业务逻辑库<br/>src/lib/*"]
Types["类型定义<br/>src/lib/types.ts"]
end
EMain --> Next
EPreload --> Next
Next --> Cmp
Next --> Hooks
Next --> Lib
Next --> Types
```

**图表来源**
- [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/app/page.tsx:1-8](file://src/app/page.tsx#L1-L8)

**章节来源**
- [README.md:351-382](file://README.md#L351-L382)
- [package.json:13-26](file://package.json#L13-L26)
- [next.config.ts:1-13](file://next.config.ts#L1-L13)
- [tsconfig.json:17-20](file://tsconfig.json#L17-L20)

## 核心组件
- Electron 主进程
  - 启动 Next.js Standalone Server，注入环境变量（数据目录、资源路径等），处理窗口创建、系统对话框、文件系统监听、剪贴板与路径扩展。
  - 关键职责：服务发现与启动、IPC 对话框与系统能力、资源隔离与安全策略。
- Next.js 应用
  - 根布局与主题国际化提供者，页面入口组件包裹 AppLayout。
  - API 路由：如 /api/workspaces，负责数据库访问与工作区管理。
- React 组件与 Hooks
  - AppLayout 作为主容器，协调侧边栏、视图切换、会话管理、文件编辑器面板、IM 事件流等。
  - 自定义 Hooks：如 use-workspaces.ts 封装工作区 CRUD 与状态管理。
- 业务逻辑库
  - 类型定义：统一的数据模型与枚举（会话、消息、技能、代理、IM 渠道、定时任务、市场模板等）。
  - 数据库：SQLite 初始化、表结构、迁移与索引，以及 MCP 同步逻辑。
  - 市场模板文件系统：模板目录结构、树形扫描、复制到模板与从模板复制回项目。
  - 工具函数：样式合并工具 cn。
- 路由与页面
  - App Router：按文件系统组织 API 与页面，支持动态路由参数与嵌套路由。

**章节来源**
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [src/app/layout.tsx:22-38](file://src/app/layout.tsx#L22-L38)
- [src/app/page.tsx:3-7](file://src/app/page.tsx#L3-L7)
- [src/app/api/workspaces/route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)
- [src/hooks/use-workspaces.ts:26-76](file://src/hooks/use-workspaces.ts#L26-L76)
- [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)
- [src/lib/marketplace-fs.ts:27-157](file://src/lib/marketplace-fs.ts#L27-L157)
- [src/lib/utils.ts:1-7](file://src/lib/utils.ts#L1-L7)

## 架构总览
- 技术栈与运行时
  - 桌面：Electron + Next.js 15（TurboPack）
  - 数据库：SQLite（better-sqlite3，WAL 模式）
  - AI：Claude Agent SDK
  - 样式：Tailwind CSS
  - 包管理：pnpm
- 运行模式
  - 开发：Next.js 开发服务器与 Electron 并行启动，通过 IPC 与系统能力交互。
  - 生产：Next.js 以 Standalone 模式打包，Electron 内嵌 Node 运行时启动本地服务，避免原生模块 ABI 不匹配问题。
- 数据流
  - UI 通过 API 路由访问数据库与文件系统，IM 事件通过 Server-Sent Events 实时同步至桌面。
  - 市场模板在用户数据目录中以独立模板目录存储，实现方案复用与快速导入。

```mermaid
graph TB
UI["桌面 UI<br/>React 组件 + Next.js"]
API["API 路由<br/>src/app/api/*"]
DB["SQLite 数据库<br/>src/lib/db.ts"]
FS["文件系统<br/>src/lib/marketplace-fs.ts"]
IM["IM 事件流<br/>SSE /api/im-events"]
MCP["MCP 同步<br/>Claude Code 配置"]
Electron["Electron 主进程<br/>electron/main.ts"]
UI --> API
API --> DB
API --> FS
UI --> IM
UI --> MCP
Electron --> UI
Electron --> API
```

**图表来源**
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [src/app/api/workspaces/route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/marketplace-fs.ts:27-157](file://src/lib/marketplace-fs.ts#L27-L157)

**章节来源**
- [README.md:343-382](file://README.md#L343-L382)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [package.json:27-59](file://package.json#L27-L59)

## 详细组件分析

### 组件：AppLayout（主容器）
- 职责
  - 管理视图切换（聊天、管理、IM、调度、设置、市场）。
  - 维护侧边栏、编辑器面板宽度与折叠状态。
  - 会话生命周期管理（创建、删除、重命名、清空、压缩）。
  - IM 事件流监听与会话自动同步。
  - 语言与主题设置应用。
- 关键流程
  - 设置加载后根据语言与主题更新全局状态。
  - 选择工作区后筛选对应会话并自动选择首个会话。
  - 发送消息时合并会话级权限与思考模式覆盖，并刷新会话列表。
  - IM 事件触发后刷新会话并按需加载消息。
- 优化点
  - 使用 ref 缓存当前会话与工作区 ID，避免回调闭包陈旧值。
  - 侧边栏与编辑器宽度动态计算，保证主聊天区域最小宽度。

```mermaid
sequenceDiagram
participant UI as "聊天视图"
participant Layout as "AppLayout"
participant Hooks as "useChat/useSessions"
participant API as "API 路由"
participant DB as "SQLite"
UI->>Layout : "发送消息"
Layout->>Hooks : "sendMessage(content, permMode, thinkMode)"
Hooks->>API : "POST /api/sessions/[id]/messages"
API->>DB : "写入消息/会话"
DB-->>API : "成功"
API-->>Hooks : "返回结果"
Hooks-->>Layout : "刷新消息/会话"
Layout-->>UI : "更新界面"
```

**图表来源**
- [src/components/layout/app-layout.tsx:301-306](file://src/components/layout/app-layout.tsx#L301-L306)
- [src/app/api/workspaces/route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

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

### 组件：工作区 API（/api/workspaces）
- 职责
  - 列出已注册工作区，补充名称与存在性。
  - 新增工作区：校验路径、去重、初始化 .claude/ 目录。
- 处理逻辑
  - GET：查询数据库并补全派生字段。
  - POST：校验请求体与路径有效性，若未注册则插入并初始化工作区目录。
- 错误处理
  - 非法 JSON、缺少路径、路径不存在或非目录时返回 400。
  - 成功新增返回 201。

```mermaid
flowchart TD
Start(["请求进入 /api/workspaces"]) --> Method{"HTTP 方法"}
Method --> |GET| List["读取工作区列表<br/>补全名称与存在性"]
Method --> |POST| Validate["校验请求体与路径"]
Validate --> Exists{"路径有效且存在？"}
Exists --> |否| Err400["返回 400 错误"]
Exists --> |是| Dup{"是否已注册？"}
Dup --> |是| Touch["更新最近打开时间"]
Dup --> |否| Insert["插入新记录并初始化 .claude/"]
List --> Ok200["返回 200"]
Touch --> Ok200
Insert --> Ok201["返回 201"]
Err400 --> End(["结束"])
Ok200 --> End
Ok201 --> End
```

**图表来源**
- [src/app/api/workspaces/route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)

**章节来源**
- [src/app/api/workspaces/route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)

### 组件：数据库与迁移（src/lib/db.ts）
- 职责
  - 初始化 SQLite 数据库与 WAL 模式，创建核心表与索引。
  - 执行多版本迁移，兼容历史 schema 变更。
  - 自动同步 Claude Code 的 MCP 服务器配置。
- 表结构要点
  - sessions、messages、settings、skills、agents、agent_skills、mcp_servers、im_channels、cron_tasks、task_executions、hooks、workspaces、api_providers、channel_bindings、channel_outbound_refs、channel_audit_logs、channel_dedupe。
- 迁移策略
  - 通过 PRAGMA 查询列信息判断是否需要重建表或添加列。
  - 逐步修复约束与默认值，确保向后兼容。
- 性能特性
  - WAL 模式提升并发读取性能。
  - 为高频查询建立索引（如 messages.session_id）。

```mermaid
flowchart TD
Init["首次访问获取数据库路径"] --> Migrate["执行迁移检查"]
Migrate --> SchemaOK{"schema 是否最新？"}
SchemaOK --> |是| Seed["填充种子数据API Providers/IM Channels/Heartbeat"]
SchemaOK --> |否| Rebuild["重建/修改表结构"]
Rebuild --> Seed
Seed --> MCP["同步 Claude Code MCP 配置"]
MCP --> Ready["数据库就绪"]
```

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

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

### 组件：市场模板文件系统（src/lib/marketplace-fs.ts）
- 职责
  - 管理用户数据目录下的 marketplace 模板根目录。
  - 构建模板树形结构，支持最大深度限制。
  - 将项目 .claude/ 导出为模板（排除 MEMORY.md、memory/、HEARTBEAT.md），或将模板导入项目覆盖目标文件。
- 目录结构
  - 模板根目录：~/.forge/marketplace/<templateId>/
  - 结构镜像 .claude/，便于直接复制与导入。
- 复制策略
  - 导出时排除运行期数据，仅保留可复用配置。
  - 导入时覆盖现有文件，保持一致性。

```mermaid
flowchart TD
Scan["扫描模板目录"] --> Tree["生成树形结构"]
Tree --> Use["在市场视图展示"]
Export["导出 .claude/ 到模板"] --> Exclude["排除 MEMORY.md/memory/HEARTBEAT.md"]
Exclude --> CopyOut["递归复制到模板目录"]
Import["从模板导入到 .claude/"] --> CopyIn["递归复制覆盖目标"]
```

**图表来源**
- [src/lib/marketplace-fs.ts:27-157](file://src/lib/marketplace-fs.ts#L27-L157)

**章节来源**
- [src/lib/marketplace-fs.ts:27-157](file://src/lib/marketplace-fs.ts#L27-L157)

### 组件：类型系统（src/lib/types.ts）
- 设计理念
  - 统一数据模型与枚举，明确字段含义与取值范围。
  - 明确区分数据库行结构与前端使用结构（如 Workspace 与 DbWorkspace）。
- 关键类型
  - 会话、消息、设置、工作区、技能、代理、MCP 服务器、API Provider、IM 渠道、定时任务、任务执行、市场模板等。
- 作用
  - 为 Hooks、API 路由与组件提供强类型约束，降低运行时错误。

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

### 组件：工具函数（src/lib/utils.ts）
- 设计理念
  - 基于 clsx 与 tailwind-merge 的样式类合并工具，简化条件样式拼接。
- 作用
  - 在组件中统一处理 className，减少重复逻辑。

**章节来源**
- [src/lib/utils.ts:1-7](file://src/lib/utils.ts#L1-L7)

### 组件：自定义 Hook（示例：use-workspaces.ts）
- 设计理念
  - 将 API 访问与状态管理封装在 Hook 中，暴露简洁的接口。
  - 映射数据库行结构到前端模型，统一字段命名。
- 关键方法
  - fetchWorkspaces：拉取工作区列表。
  - openProjectFolder：新增工作区并初始化目录。
  - removeProject：删除工作区。
  - touchWorkspace：更新最近打开时间。
- 作用
  - 为 AppLayout 等组件提供工作区 CRUD 能力，保持 UI 与数据的一致性。

**章节来源**
- [src/hooks/use-workspaces.ts:26-76](file://src/hooks/use-workspaces.ts#L26-L76)

## 依赖分析
- 构建与运行时
  - Next.js 15（App Router、Standalone 输出、TurboPack）。
  - Electron 与 electron-builder，支持多平台打包。
  - better-sqlite3（WAL 模式），@larksuiteoapi/node-sdk（外部包外置）。
- 开发与工具
  - TypeScript（严格模式、路径别名 @/*），Tailwind CSS，tsup（Electron 编译）。
- 依赖关系
  - Electron 主进程依赖 Next.js Standalone Server，通过本地端口通信。
  - 前端组件依赖 Hooks 与 API 路由，API 路由依赖数据库与文件系统库。
  - 市场模板库依赖用户数据目录与文件系统。

```mermaid
graph LR
Pkg["package.json 脚本与依赖"]
TS["tsconfig.json 路径别名 @/*"]
NextCfg["next.config.ts"]
ElectronMain["electron/main.ts"]
AppRouter["src/app/*"]
HooksLib["src/hooks/*"]
LibDB["src/lib/db.ts"]
LibFS["src/lib/marketplace-fs.ts"]
Pkg --> ElectronMain
Pkg --> NextCfg
TS --> AppRouter
ElectronMain --> AppRouter
AppRouter --> HooksLib
AppRouter --> LibDB
AppRouter --> LibFS
```

**图表来源**
- [package.json:13-26](file://package.json#L13-L26)
- [tsconfig.json:17-20](file://tsconfig.json#L17-L20)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)

**章节来源**
- [package.json:13-26](file://package.json#L13-L26)
- [next.config.ts:3-10](file://next.config.ts#L3-L10)
- [tsconfig.json:17-20](file://tsconfig.json#L17-L20)

## 性能考虑
- 数据库
  - WAL 模式提升并发读取性能，适合桌面端高并发场景。
  - 为高频查询建立索引，减少扫描成本。
- 渲染与网络
  - Next.js Standalone 输出，生产环境禁用 gzip，避免缓冲影响 SSE 流。
  - Turbopack 加速开发体验。
- 文件系统
  - IM 事件使用 SSE，避免轮询开销；对快速变更进行防抖合并通知。
- 原生模块
  - Electron 内嵌 Node 运行时启动本地服务，避免 better-sqlite3 等原生模块 ABI 不匹配问题。

**章节来源**
- [src/lib/db.ts:21-23](file://src/lib/db.ts#L21-L23)
- [next.config.ts:5-9](file://next.config.ts#L5-L9)
- [electron/main.ts:80-139](file://electron/main.ts#L80-L139)

## 故障排查指南
- 启动失败（Electron）
  - 现象：应用无法启动，弹出错误框。
  - 排查：确认 Node.js 可用，检查控制台输出；查看主进程错误提示与超时日志。
  - 参考：[electron/main.ts:272-288](file://electron/main.ts#L272-L288)
- 服务未就绪
  - 现象：窗口空白或加载失败。
  - 排查：确认本地 Standalone Server 已在 127.0.0.1:PORT 启动，等待就绪后再加载页面。
  - 参考：[electron/main.ts:54-71](file://electron/main.ts#L54-L71)
- 工作区不可用
  - 现象：新增工作区无效或路径错误。
  - 排查：检查请求体 JSON、路径是否存在且为目录；查看数据库插入与初始化逻辑。
  - 参考：[src/app/api/workspaces/route.ts:24-59](file://src/app/api/workspaces/route.ts#L24-L59)
- 数据库迁移异常
  - 现象：表结构不一致或约束冲突。
  - 排查：查看迁移分支逻辑，确认列存在性与约束差异；必要时重建表。
  - 参考：[src/lib/db.ts:226-363](file://src/lib/db.ts#L226-L363)
- 市场模板导入失败
  - 现象：导入后文件缺失或未覆盖。
  - 排查：确认模板目录存在、目标 .claude/ 存在且可写；检查复制逻辑与排除规则。
  - 参考：[src/lib/marketplace-fs.ts:122-157](file://src/lib/marketplace-fs.ts#L122-L157)

**章节来源**
- [electron/main.ts:272-288](file://electron/main.ts#L272-L288)
- [src/app/api/workspaces/route.ts:24-59](file://src/app/api/workspaces/route.ts#L24-L59)
- [src/lib/db.ts:226-363](file://src/lib/db.ts#L226-L363)
- [src/lib/marketplace-fs.ts:122-157](file://src/lib/marketplace-fs.ts#L122-L157)

## 结论
Forge 的代码结构遵循“UI 层-业务层-数据层”的清晰分层，结合 Electron 与 Next.js 的混合架构，实现了桌面端的高性能与易维护性。通过 App Router 的文件系统即路由、严格的类型系统、完善的数据库迁移与文件系统抽象，项目具备良好的扩展性与可演进性。建议在后续开发中持续完善 API 路由的错误处理与日志记录，强化单元测试与端到端测试，进一步提升稳定性与可维护性。

## 附录
- 命名约定与文件命名规范
  - 目录命名：小写 + 复数（如 components/、hooks/、lib/）。
  - 文件命名：功能相关的小驼峰（如 use-workspaces.ts、marketplace-fs.ts）。
  - 组件文件：以大驼峰（如 AppLayout.tsx、ForgeFileEditor.tsx）。
  - API 路由：按资源与动作组织（如 /api/workspaces/route.ts）。
  - 类型文件：集中于 lib/types.ts，统一导出。
- 最佳实践
  - 使用 @/* 路径别名，避免深层相对路径。
  - 将 UI 与数据分离，Hooks 负责状态与副作用，组件只负责渲染。
  - API 路由中进行输入校验与错误包装，返回明确的状态码。
  - 数据库迁移采用增量策略，先检测再重建，保证向后兼容。
  - 文件系统操作谨慎处理异常与边界情况，提供用户可感知的反馈。