# 后端服务

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [src/app/layout.tsx](file://src/app/layout.tsx)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/lib/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)
- [src/app/api/agents/route.ts](file://src/app/api/agents/route.ts)
- [src/app/api/workspaces/route.ts](file://src/app/api/workspaces/route.ts)
- [src/app/api/sessions/route.ts](file://src/app/api/sessions/route.ts)
- [src/app/api/im-channels/route.ts](file://src/app/api/im-channels/route.ts)
- [src/app/api/cron-tasks/route.ts](file://src/app/api/cron-tasks/route.ts)
</cite>

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

## 简介
本文件为 Forge 后端服务的综合技术文档，聚焦于：
- API 路由设计与控制流
- 中间件与全局初始化（主题、国际化）
- 业务逻辑层组织（会话、工作区、代理、IM 渠道、定时任务、市场模板）
- 数据库连接管理与迁移策略
- 计划任务引擎与 IM 桥接服务
- 文件系统操作与内存管理
- 服务间依赖关系、错误处理与日志策略
- API 版本管理、安全认证与性能监控建议
- 扩展指南、部署配置与运维最佳实践

## 项目结构
后端采用 Electron + Next.js 的桌面应用架构，API 层基于 Next.js App Router 的约定式路由（app/api/*），核心逻辑集中在 src/lib 下的模块化子系统中。

```mermaid
graph TB
subgraph "桌面壳层"
E["Electron 主进程<br/>electron/main.ts / preload.ts"]
end
subgraph "前端渲染层"
L["RootLayout<br/>src/app/layout.tsx"]
end
subgraph "后端 API 层"
A1["/api/agents"]
A2["/api/workspaces"]
A3["/api/sessions"]
A4["/api/im-channels"]
A5["/api/cron-tasks"]
end
subgraph "核心库"
D["数据库<br/>src/lib/db.ts"]
T["类型定义<br/>src/lib/types.ts"]
M["市场模板FS<br/>src/lib/marketplace-fs.ts"]
end
E --> L
L --> A1
L --> A2
L --> A3
L --> A4
L --> A5
A1 --> D
A2 --> D
A3 --> D
A4 --> D
A5 --> D
A1 --> T
A2 --> T
A3 --> T
A4 --> T
A5 --> T
A2 --> M
```

图示来源
- [src/app/layout.tsx:1-39](file://src/app/layout.tsx#L1-L39)
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-L42)
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)
- [src/app/api/im-channels/route.ts:1-13](file://src/app/api/im-channels/route.ts#L1-L13)
- [src/app/api/cron-tasks/route.ts:1-53](file://src/app/api/cron-tasks/route.ts#L1-L53)
- [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)
- [src/lib/marketplace-fs.ts:1-158](file://src/lib/marketplace-fs.ts#L1-L158)

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

## 核心组件
- 数据库与迁移：SQLite（better-sqlite3，WAL 模式）；自动迁移与表结构演进；MCP 服务器同步
- 类型系统：统一的数据模型与枚举，确保前后端一致
- 市场模板文件系统：模板目录树构建、复制到模板、从模板复制回项目
- API 路由：按资源分组（agents、workspaces、sessions、im-channels、cron-tasks），遵循 REST 风格
- 全局初始化：主题与国际化提供者包裹根布局

章节来源
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/types.ts:1-221](file://src/lib/types.ts#L1-L221)
- [src/lib/marketplace-fs.ts:1-158](file://src/lib/marketplace-fs.ts#L1-L158)
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-L42)
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)
- [src/app/api/im-channels/route.ts:1-13](file://src/app/api/im-channels/route.ts#L1-L13)
- [src/app/api/cron-tasks/route.ts:1-53](file://src/app/api/cron-tasks/route.ts#L1-L53)
- [src/app/layout.tsx:22-38](file://src/app/layout.tsx#L22-L38)

## 架构总览
后端以“API 路由 -> 业务逻辑 -> 数据库/文件系统”的分层组织，数据持久化通过 SQLite WAL 提升并发读取性能；IM 桥接与计划任务引擎作为独立子系统通过依赖注入或单例访问数据库与外部 SDK。

```mermaid
graph TB
C["客户端/桌面UI"] --> R["Next.js App Router API 路由"]
R --> S["业务逻辑模块<br/>agents / workspaces / sessions / im-channels / cron-tasks"]
S --> DB["SQLite 数据库<br/>better-sqlite3 (WAL)"]
S --> FS["文件系统<br/>市场模板/上传/项目目录"]
S --> IM["IM 桥接服务<br/>Feishu/Telegram/Discord"]
S --> CRON["计划任务引擎<br/>Cron Engine"]
S --> SDK["Claude Agent SDK 集成<br/>通过 CLI 或 Provider"]
```

图示来源
- [src/lib/db.ts:21-24](file://src/lib/db.ts#L21-L24)
- [src/app/api/agents/route.ts:5-16](file://src/app/api/agents/route.ts#L5-L16)
- [src/app/api/workspaces/route.ts:8-21](file://src/app/api/workspaces/route.ts#L8-L21)
- [src/app/api/sessions/route.ts:6-15](file://src/app/api/sessions/route.ts#L6-L15)
- [src/app/api/im-channels/route.ts:5-12](file://src/app/api/im-channels/route.ts#L5-L12)
- [src/app/api/cron-tasks/route.ts:6-20](file://src/app/api/cron-tasks/route.ts#L6-L20)

## 详细组件分析

### 数据库与迁移（db.ts）
- 初始化：首次访问时创建数据库文件，启用 WAL 与外键约束；创建核心表与索引；插入种子数据（API Providers、IM 渠道、Heartbeat 任务）
- 迁移：针对 workspaces、sessions、im_channels、hooks、cron_tasks、task_executions、channel_bindings 等表进行列增补与约束调整；兼容旧 schema 并重建表
- MCP 同步：读取用户主目录下的 Claude 配置，自动在数据库中创建/更新 MCP 服务器条目，并测试连接状态
- 单例：全局缓存数据库实例，避免重复打开

```mermaid
flowchart TD
Start(["首次访问 getDb()"]) --> Check["检查并迁移旧数据目录"]
Check --> NewDB["创建/打开 SQLite 数据库"]
NewDB --> WAL["设置 PRAGMA journal_mode=WAL"]
WAL --> FK["设置 PRAGMA foreign_keys=ON"]
FK --> CreateTables["创建/校验核心表与索引"]
CreateTables --> Seed["插入种子数据"]
Seed --> Migrate["执行多轮表结构迁移"]
Migrate --> SyncMCP["从 ~/.claude.json 同步 MCP 服务器"]
SyncMCP --> Cache["缓存数据库实例"]
Cache --> End(["返回数据库句柄"])
```

图示来源
- [src/lib/db.ts:12-16](file://src/lib/db.ts#L12-L16)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/db.ts:443-477](file://src/lib/db.ts#L443-L477)
- [src/lib/db.ts:483-498](file://src/lib/db.ts#L483-L498)

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

### 类型系统（types.ts）
- 统一定义会话、消息、代理、技能、API 提供商、IM 渠道、定时任务、市场模板等核心实体的字段与取值范围
- 明确权限模式、触发模式、任务执行状态、通道状态等枚举，保证跨模块一致性

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

### 市场模板文件系统（marketplace-fs.ts）
- 目录结构：模板存储于用户数据目录下的 marketplace 子目录，结构与项目 .claude/ 对应
- 功能：
  - 构建模板树：递归扫描模板目录，生成树形结构
  - 复制到模板：将项目 .claude/ 内容复制到模板（排除运行期数据）
  - 从模板复制：将模板内容复制到目标项目 .claude/（覆盖）

```mermaid
flowchart TD
A["选择模板ID"] --> B["定位模板目录 ~/.forge/marketplace/<id>"]
B --> C{"扫描目录"}
C --> |文件| D["加入结果列表"]
C --> |目录| E["递归扫描子目录"]
E --> C
D --> F["返回树形结构"]
```

图示来源
- [src/lib/marketplace-fs.ts:46-74](file://src/lib/marketplace-fs.ts#L46-L74)
- [src/lib/marketplace-fs.ts:80-92](file://src/lib/marketplace-fs.ts#L80-L92)
- [src/lib/marketplace-fs.ts:122-134](file://src/lib/marketplace-fs.ts#L122-L134)

章节来源
- [src/lib/marketplace-fs.ts:1-158](file://src/lib/marketplace-fs.ts#L1-L158)

### API 路由：代理（agents）
- GET /api/agents：查询所有代理，附加其技能关联
- POST /api/agents：创建新代理，写入基础信息与工具配置，返回新建代理

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Route as "agents/route.ts"
participant DB as "db.ts"
Client->>Route : GET /api/agents
Route->>DB : 查询 agents 表
DB-->>Route : 代理列表
Route-->>Client : JSON 列表
Client->>Route : POST /api/agents
Route->>DB : 插入 agents 行
DB-->>Route : 新建代理
Route-->>Client : 201 + 代理详情
```

图示来源
- [src/app/api/agents/route.ts:5-16](file://src/app/api/agents/route.ts#L5-L16)
- [src/app/api/agents/route.ts:19-41](file://src/app/api/agents/route.ts#L19-L41)
- [src/lib/db.ts:63-79](file://src/lib/db.ts#L63-L79)

章节来源
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-L42)

### API 路由：工作区（workspaces）
- GET /api/workspaces：列出已注册工作区，补充名称与存在性
- POST /api/workspaces：注册新工作区，校验路径合法性，若未注册则插入并初始化 .claude/ 目录

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Route as "workspaces/route.ts"
participant DB as "db.ts"
participant FS as "文件系统"
Client->>Route : POST /api/workspaces
Route->>Route : 校验请求体与路径
Route->>DB : 查询是否已存在
alt 已存在
Route->>DB : 更新 last_opened_at
DB-->>Route : 返回更新后的记录
else 不存在
Route->>DB : 插入新记录
Route->>FS : 初始化 .claude/ 目录
DB-->>Route : 返回新建记录
end
Route-->>Client : JSON + 201/200
```

图示来源
- [src/app/api/workspaces/route.ts:24-59](file://src/app/api/workspaces/route.ts#L24-L59)
- [src/lib/db.ts:159-164](file://src/lib/db.ts#L159-L164)

章节来源
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)

### API 路由：会话（sessions）
- GET /api/sessions：启动会话清理任务（每小时最多一次），查询活跃会话
- POST /api/sessions：创建新会话

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Route as "sessions/route.ts"
participant DB as "db.ts"
participant Clean as "session-cleanup"
Client->>Route : GET /api/sessions
Route->>Clean : 触发清理节流
Route->>DB : 查询 active 会话
DB-->>Route : 会话列表
Route-->>Client : JSON
Client->>Route : POST /api/sessions
Route->>DB : 插入新会话
DB-->>Route : 返回会话
Route-->>Client : 201 + 会话
```

图示来源
- [src/app/api/sessions/route.ts:6-16](file://src/app/api/sessions/route.ts#L6-L16)
- [src/app/api/sessions/route.ts:18-33](file://src/app/api/sessions/route.ts#L18-L33)

章节来源
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)

### API 路由：IM 渠道（im-channels）
- GET /api/im-channels：首次访问时初始化桥接管理器并返回渠道配置

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Route as "im-channels/route.ts"
participant DB as "db.ts"
participant BM as "BridgeManager"
Client->>Route : GET /api/im-channels
Route->>BM : 获取并初始化桥接管理器
Route->>DB : 查询 im_channels
DB-->>Route : 渠道列表
Route-->>Client : JSON
```

图示来源
- [src/app/api/im-channels/route.ts:5-12](file://src/app/api/im-channels/route.ts#L5-L12)

章节来源
- [src/app/api/im-channels/route.ts:1-13](file://src/app/api/im-channels/route.ts#L1-L13)

### API 路由：定时任务（cron-tasks）
- GET /api/cron-tasks?workspace_id=...：按工作区过滤，包含全局 Heartbeat 任务
- POST /api/cron-tasks：创建新任务，若引擎未运行则自动启动

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Route as "cron-tasks/route.ts"
participant DB as "db.ts"
participant Eng as "CronEngine"
Client->>Route : POST /api/cron-tasks
Route->>DB : 插入 cron_tasks
DB-->>Route : 返回新建任务
Route->>Eng : 若未运行则启动
Route-->>Client : 201 + 任务
```

图示来源
- [src/app/api/cron-tasks/route.ts:23-52](file://src/app/api/cron-tasks/route.ts#L23-L52)

章节来源
- [src/app/api/cron-tasks/route.ts:1-53](file://src/app/api/cron-tasks/route.ts#L1-L53)

### 全局初始化与中间件
- 根布局使用主题与国际化提供者包裹，确保全局样式与语言环境一致
- Next.js 开发模式下同时启动 Electron 与 Next.js 服务，生产构建打包为可分发包

章节来源
- [src/app/layout.tsx:22-38](file://src/app/layout.tsx#L22-L38)
- [package.json:13-26](file://package.json#L13-L26)

## 依赖分析
- 外部依赖
  - SQLite：better-sqlite3（WAL 模式）
  - Claude Agent SDK：@anthropic-ai/claude-agent-sdk
  - IM SDK：@larksuiteoapi/node-sdk（用于飞书）
  - 前端框架：Next.js 15、React 19
- 内部模块耦合
  - API 路由仅依赖 db.ts 与 types.ts，保持低耦合
  - marketplace-fs 与工作区 API 协作完成模板导入导出
  - IM 渠道与桥接管理器解耦，通过 db.ts 读取配置

```mermaid
graph LR
P["package.json 依赖"] --> S["SQLite better-sqlite3"]
P --> CSDK["@anthropic-ai/claude-agent-sdk"]
P --> LSKY["@larksuiteoapi/node-sdk"]
P --> N["Next.js / React"]
R1["agents/route.ts"] --> D["db.ts"]
R2["workspaces/route.ts"] --> D
R3["sessions/route.ts"] --> D
R4["im-channels/route.ts"] --> D
R5["cron-tasks/route.ts"] --> D
R2 --> M["marketplace-fs.ts"]
```

图示来源
- [package.json:27-41](file://package.json#L27-L41)
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-L42)
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)
- [src/app/api/im-channels/route.ts:1-13](file://src/app/api/im-channels/route.ts#L1-L13)
- [src/app/api/cron-tasks/route.ts:1-53](file://src/app/api/cron-tasks/route.ts#L1-L53)
- [src/lib/marketplace-fs.ts:1-158](file://src/lib/marketplace-fs.ts#L1-L158)

章节来源
- [package.json:27-41](file://package.json#L27-L41)

## 性能考虑
- 数据库
  - WAL 模式提升并发读取吞吐，适合桌面应用场景
  - 外键约束保障数据一致性，配合索引优化查询
- 路由与清理
  - 会话清理采用节流策略（每小时最多一次），降低开销
- 文件系统
  - 模板树构建与复制采用递归扫描，注意大目录的 IO 压力
- IM 与计划任务
  - 引擎按需启动，避免常驻进程占用资源

## 故障排查指南
- 数据库
  - 若迁移失败，检查表结构差异与约束变更；确认 WAL 文件可写
  - MCP 同步失败：检查 ~/.claude.json 权限与格式
- API
  - 工作区注册失败：确认路径存在且为目录；查看返回的错误信息
  - 会话创建失败：检查请求体 JSON 格式与必填字段
- IM 渠道
  - 首次访问无响应：等待桥接管理器初始化完成；检查凭证配置
- 定时任务
  - 任务未执行：确认任务已启用且引擎已启动；查看最近执行记录

章节来源
- [src/lib/db.ts:226-363](file://src/lib/db.ts#L226-L363)
- [src/app/api/workspaces/route.ts:24-59](file://src/app/api/workspaces/route.ts#L24-L59)
- [src/app/api/sessions/route.ts:18-33](file://src/app/api/sessions/route.ts#L18-L33)
- [src/app/api/im-channels/route.ts:5-12](file://src/app/api/im-channels/route.ts#L5-L12)
- [src/app/api/cron-tasks/route.ts:46-49](file://src/app/api/cron-tasks/route.ts#L46-L49)

## 结论
本后端以清晰的分层与模块化设计支撑了桌面 AI 工作站的核心能力：本地会话与记忆、IM 桥接、计划任务与市场模板。数据库采用 WAL 模式兼顾性能与可靠性；API 路由简洁稳定；文件系统与模板机制便于项目复用与迁移。后续可在安全认证、版本管理与监控方面进一步完善。

## 附录

### API 版本管理建议
- 使用路径前缀区分版本（如 /v1/agents），保留向后兼容接口
- 在响应头中声明版本号与兼容性策略
- 对破坏性变更采用 deprecation 通知并在未来版本移除

### 安全认证与授权
- 本地应用默认无网络暴露，建议在需要远程访问时引入轻量网关与鉴权
- 对敏感配置（IM 凭证、API Key）进行加密存储与最小权限访问

### 性能监控方案
- 数据库层面：监控慢查询、WAL 文件大小与锁竞争
- 任务层面：记录任务执行耗时、重试次数与告警状态
- 文件层面：统计模板复制耗时与磁盘占用

### 扩展指南
- 新增资源：在 app/api 下新增路由文件，复用 db.ts 与 types.ts
- 新增表：在 db.ts 中添加建表语句与迁移逻辑
- 新增功能：拆分为独立模块并通过依赖注入接入现有路由

### 部署配置与运维最佳实践
- 开发：使用 concurrently 同时启动 Electron 与 Next.js；确保 Claude CLI 可用
- 生产：构建 Next.js 与 Electron 并打包 DMG；关注 better-sqlite3 的原生依赖
- 日志：结合数据库审计表与应用日志追踪关键事件（IM 消息去重、任务执行）

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