# 数据库管理

<cite>
**本文引用的文件**
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/forge-data.ts](file://src/lib/forge-data.ts)
- [src/app/api/sessions/route.ts](file://src/app/api/sessions/route.ts)
- [src/app/api/cron-tasks/route.ts](file://src/app/api/cron-tasks/route.ts)
- [src/app/api/chat/route.ts](file://src/app/api/chat/route.ts)
- [src/lib/im/concurrency.ts](file://src/lib/im/concurrency.ts)
- [src/lib/im/delivery.ts](file://src/lib/im/delivery.ts)
- [src/lib/im/bridge-manager.ts](file://src/lib/im/bridge-manager.ts)
- [src/lib/models.ts](file://src/lib/models.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [scripts/build-electron.mjs](file://scripts/build-electron.mjs)
</cite>

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

## 简介
本文件为数据库管理系统的综合文档，聚焦于基于 SQLite 的本地数据库实现与运维实践。内容涵盖数据库连接池与事务管理、并发控制、数据模型与关系映射、迁移与版本升级、数据完整性约束、查询与索引优化、备份与恢复、连接超时与错误重试、以及与业务层的集成方式（包括 ORM 映射、数据验证与业务规则）。文档以仓库中的实际实现为依据，避免臆测，确保可操作性与可追溯性。

## 项目结构
数据库相关能力主要由以下模块构成：
- 数据库初始化与迁移：负责数据库文件位置、WAL 模式、外键约束、表结构与索引初始化、历史版本迁移与增量字段补齐。
- 数据目录与迁移：负责从旧路径到新路径的数据迁移与上传目录同步。
- API 路由：通过统一的数据库句柄访问各业务表，执行 CRUD 与查询。
- 并发控制与错误重试：在消息桥接层实现会话级锁、指数退避重试与熔断保护。
- 类型与模型：定义数据库实体与字段映射，支撑前端与后端一致的数据契约。

```mermaid
graph TB
subgraph "应用层"
API_Sessions["API: /api/sessions"]
API_Cron["API: /api/cron-tasks"]
API_Chat["API: /api/chat"]
end
subgraph "服务层"
DB["数据库初始化与迁移<br/>表/索引/约束/迁移脚本"]
ForgeData["数据目录与迁移<br/>~/.forge/"]
end
subgraph "桥接与并发"
LockMgr["会话级并发锁"]
Delivery["消息投递与重试"]
BridgeMgr["桥接管理器<br/>重连/熔断/限流"]
end
API_Sessions --> DB
API_Cron --> DB
API_Chat --> DB
DB --> ForgeData
API_Chat --> LockMgr
API_Chat --> Delivery
API_Chat --> BridgeMgr
```

图表来源
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:20-103](file://src/lib/forge-data.ts#L20-L103)
- [src/app/api/sessions/route.ts:6-16](file://src/app/api/sessions/route.ts#L6-L16)
- [src/app/api/cron-tasks/route.ts:6-21](file://src/app/api/cron-tasks/route.ts#L6-L21)
- [src/app/api/chat/route.ts:187-215](file://src/app/api/chat/route.ts#L187-L215)
- [src/lib/im/concurrency.ts:8-60](file://src/lib/im/concurrency.ts#L8-L60)
- [src/lib/im/delivery.ts:223-240](file://src/lib/im/delivery.ts#L223-L240)
- [src/lib/im/bridge-manager.ts:569-592](file://src/lib/im/bridge-manager.ts#L569-L592)

章节来源
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:20-103](file://src/lib/forge-data.ts#L20-L103)
- [src/app/api/sessions/route.ts:6-16](file://src/app/api/sessions/route.ts#L6-L16)
- [src/app/api/cron-tasks/route.ts:6-21](file://src/app/api/cron-tasks/route.ts#L6-L21)
- [src/app/api/chat/route.ts:187-215](file://src/app/api/chat/route.ts#L187-L215)
- [src/lib/im/concurrency.ts:8-60](file://src/lib/im/concurrency.ts#L8-L60)
- [src/lib/im/delivery.ts:223-240](file://src/lib/im/delivery.ts#L223-L240)
- [src/lib/im/bridge-manager.ts:569-592](file://src/lib/im/bridge-manager.ts#L569-L592)

## 核心组件
- 数据库初始化与迁移
  - 单例数据库句柄：进程内全局缓存，避免重复打开。
  - WAL 模式与外键约束：提升并发读写性能与参照完整性。
  - 表结构与索引：按需创建核心表与二级索引，保证常用查询效率。
  - 历史迁移：检测旧表结构并进行重建或 ALTER 迁移，补齐新增列，修复约束。
  - Claude Code 自动同步：从用户主目录读取 MCP 服务器配置并写入数据库。
- 数据目录与迁移
  - 统一数据目录：优先环境变量，否则默认用户主目录下 ~/.forge。
  - 旧目录迁移：首次初始化时从工作目录下的 .forge-data 复制数据库与上传目录。
- API 路由
  - 会话列表与创建：使用预编译语句插入与查询，按更新时间倒序展示活跃会话。
  - 定时任务：支持按工作区过滤查询与创建任务，自动启动调度引擎。
  - 聊天接口：结合数据库加载历史消息，支持回退到全新会话重试。
- 并发控制与错误重试
  - 会话级锁：同一通道+聊天键串行化处理，避免竞态。
  - 投递重试：指数退避与抖动，最大重试次数限制。
  - 桥接重连：失败计数触发熔断，指数退避重连。
- 类型与模型
  - 数据模型：定义会话、消息、技能、代理、API 提供商、IM 渠道、定时任务等实体。
  - 内置模型：集中维护可用模型清单，便于 UI 与逻辑统一消费。

章节来源
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:20-103](file://src/lib/forge-data.ts#L20-L103)
- [src/app/api/sessions/route.ts:6-16](file://src/app/api/sessions/route.ts#L6-L16)
- [src/app/api/cron-tasks/route.ts:6-21](file://src/app/api/cron-tasks/route.ts#L6-L21)
- [src/app/api/chat/route.ts:187-215](file://src/app/api/chat/route.ts#L187-L215)
- [src/lib/im/concurrency.ts:8-60](file://src/lib/im/concurrency.ts#L8-L60)
- [src/lib/im/delivery.ts:223-240](file://src/lib/im/delivery.ts#L223-L240)
- [src/lib/im/bridge-manager.ts:569-592](file://src/lib/im/bridge-manager.ts#L569-L592)
- [src/lib/models.ts:20-50](file://src/lib/models.ts#L20-L50)
- [src/lib/types.ts:6-221](file://src/lib/types.ts#L6-L221)

## 架构总览
数据库层采用“单实例 + WAL + 外键”的轻量架构，配合 API 层的预编译语句与桥接层的并发控制，形成稳定可靠的本地存储与高并发处理能力。

```mermaid
graph TB
Client["客户端/浏览器"] --> NextAPI["Next.js API 路由"]
NextAPI --> GetDB["getDb()<br/>单例数据库句柄"]
GetDB --> SQLite["SQLite 文件<br/>WAL 模式"]
SQLite --> Migrations["初始化/迁移脚本"]
SQLite --> Tables["核心表与索引"]
NextAPI --> Business["业务逻辑<br/>预编译语句"]
Business --> SQLite
```

图表来源
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/app/api/sessions/route.ts:6-16](file://src/app/api/sessions/route.ts#L6-L16)
- [src/app/api/cron-tasks/route.ts:6-21](file://src/app/api/cron-tasks/route.ts#L6-L21)

## 详细组件分析

### 数据库初始化与迁移
- 初始化流程
  - 首次访问尝试从旧目录迁移数据；确定数据库文件路径；创建数据库实例。
  - 设置 PRAGMA：启用 WAL 日志模式与外键约束。
  - 执行 DDL：创建核心表、索引与种子数据。
  - 执行迁移：检测并执行多轮表结构与列的兼容性迁移。
  - 自动同步：从 Claude Code 配置导入 MCP 服务器。
- 迁移策略
  - 工作区表：从旧 schema 的多列重建为新 schema 的 path 唯一键。
  - 会话表：移除已废弃的 working_directory 列，重建并重建索引。
  - IM 渠道表：修正状态枚举值，放宽默认策略。
  - API 提供商表：新增状态与模型名列。
  - Hook 表：移除事件类型 CHECK 约束，支持扩展事件类型。
  - 定时任务表：新增工作区、动作类型、代理/技能名称列。
  - 任务执行表：新增会话标识列。
  - 渠道绑定表：新增会话标识列。
  - 会话表：新增权限模式列。
  - 新增 IM 桥接层表：出站引用、审计日志、去重表。
- 外部依赖
  - better-sqlite3：原生模块，构建与运行时需匹配 Electron Node 版本。
  - 通过脚本对 better-sqlite3 进行重新构建或预编译安装。

```mermaid
flowchart TD
Start(["初始化入口"]) --> CheckOld["检查旧目录迁移"]
CheckOld --> Path["计算数据库路径"]
Path --> OpenDB["打开数据库并设置PRAGMA"]
OpenDB --> CreateDDL["创建表/索引/种子数据"]
CreateDDL --> Migrate["执行迁移脚本"]
Migrate --> SyncMCP["同步MCP服务器配置"]
SyncMCP --> Done(["完成"])
```

图表来源
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:52-103](file://src/lib/forge-data.ts#L52-L103)
- [scripts/build-electron.mjs:313-335](file://scripts/build-electron.mjs#L313-L335)

章节来源
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:52-103](file://src/lib/forge-data.ts#L52-L103)
- [scripts/build-electron.mjs:313-335](file://scripts/build-electron.mjs#L313-L335)

### 并发控制与错误重试
- 会话级并发锁
  - 使用 Map 存储每个会话键的 Promise 链，确保同一键串行处理，避免竞态。
  - 释放函数仅在当前锁仍对应该 Promise 时删除，防止误删。
- 投递重试
  - 指数退避与抖动，最多重试固定次数，失败抛出最后一次错误。
- 桥接重连
  - 失败计数超过阈值触发熔断，进入暂停期；随后指数退避重连，带随机抖动。

```mermaid
sequenceDiagram
participant API as "API 路由"
participant Lock as "会话锁管理器"
participant DB as "数据库"
participant Delivery as "投递层"
API->>Lock : acquire(key)
Lock-->>API : 返回释放函数
API->>DB : 查询/插入/更新
DB-->>API : 结果
API->>Delivery : 发送消息
Delivery->>Delivery : 指数退避重试
API->>Lock : release()
```

图表来源
- [src/lib/im/concurrency.ts:21-49](file://src/lib/im/concurrency.ts#L21-L49)
- [src/lib/im/delivery.ts:223-240](file://src/lib/im/delivery.ts#L223-L240)
- [src/app/api/chat/route.ts:187-215](file://src/app/api/chat/route.ts#L187-L215)

章节来源
- [src/lib/im/concurrency.ts:8-60](file://src/lib/im/concurrency.ts#L8-L60)
- [src/lib/im/delivery.ts:223-240](file://src/lib/im/delivery.ts#L223-L240)
- [src/lib/im/bridge-manager.ts:569-592](file://src/lib/im/bridge-manager.ts#L569-L592)
- [src/app/api/chat/route.ts:187-215](file://src/app/api/chat/route.ts#L187-L215)

### 数据模型与关系映射
- 实体与字段
  - 会话：主键 id，标题、工作区、模型、状态、权限模式、时间戳。
  - 消息：主键 id，会话外键、角色、内容、时间戳。
  - 技能：主键 id，名称、描述、范围、启用、内容、时间戳。
  - 代理：主键 id，名称、描述、模型、权限模式、父子关系、启用、指令、身份、工具配置、时间戳。
  - 代理-技能关联：复合主键（代理, 技能），级联删除。
  - API 提供商：主键 id，名称、提供商、密钥、基础地址、模型名、激活状态、状态与错误信息、时间戳。
  - IM 渠道：主键 id，类型、启用、状态、凭据、DM/群组策略、触发模式、白名单、时间戳。
  - 定时任务：主键 id，名称、计划、动作、动作类型、代理/技能/工作区、启用、心跳标记、配置、最近执行时间与结果、时间戳。
  - 任务执行：主键 id，任务外键、任务名、结果、状态、会话标识、执行时间。
  - 设置：主键 key，值。
  - 工作区：主键 id，路径唯一、最后打开时间、创建时间。
  - 渠道绑定：主键 id，渠道外键、聊天标识、聊天名、工作区、会话标识、时间戳。
  - 渠道权限链接：主键 id，渠道外键、聊天标识、代理外键、权限模式、时间戳。
  - 市场模板：主键 id，名称、时间戳。
  - IM 桥接层：出站引用、审计日志、去重表。
- 关系映射
  - 一对多：会话-消息（会话删除级联删除消息）。
  - 多对多：代理-技能（通过中间表维护）。
  - 外键约束：严格参照完整性，保证引用一致性。
  - 索引策略：消息按会话+时间排序索引；任务执行按任务+时间倒序索引；渠道出站引用按三元组组合索引；审计日志按时间倒序索引。

```mermaid
erDiagram
SESSIONS ||--o{ MESSAGES : "包含"
AGENTS ||--o{ AGENT_SKILLS : "拥有"
SKILLS ||--o{ AGENT_SKILLS : "被拥有"
API_PROVIDERS ||--|| API_PROVIDERS : "自引用(无)"
IM_CHANNELS ||--o{ CHANNEL_BINDINGS : "绑定"
AGENTS ||--o{ CHANNEL_PERMISSION_LINKS : "授权"
CRON_TASKS ||--o{ TASK_EXECUTIONS : "执行"
IM_CHANNELS ||--o{ CHANNEL_AUDIT_LOGS : "审计"
```

图表来源
- [src/lib/db.ts:26-200](file://src/lib/db.ts#L26-L200)
- [src/lib/db.ts:401-430](file://src/lib/db.ts#L401-L430)

章节来源
- [src/lib/db.ts:26-200](file://src/lib/db.ts#L26-L200)
- [src/lib/db.ts:401-430](file://src/lib/db.ts#L401-L430)
- [src/lib/types.ts:6-221](file://src/lib/types.ts#L6-L221)

### 查询优化与索引策略
- 已有索引
  - 消息：(session_id, created_at) 用于按会话检索历史消息并按时间排序。
  - 任务执行：(task_id, executed_at DESC) 用于分页查询任务执行记录。
  - 出站引用：(channel_type, chat_id, internal_id) 用于快速查找平台消息映射。
  - 审计日志：(created_at DESC) 用于倒序查看审计事件。
- 查询建议
  - 会话列表：按 updated_at 倒序，配合索引高效返回活跃会话。
  - 定时任务：按工作区过滤时，利用索引减少扫描范围。
  - 聊天历史：按会话+时间查询，避免全表扫描。
- 性能注意事项
  - 使用预编译语句减少解析开销。
  - 合理使用 LIMIT/OFFSET 实现分页。
  - 避免 SELECT *，仅选择必要列。

章节来源
- [src/app/api/sessions/route.ts:12-15](file://src/app/api/sessions/route.ts#L12-L15)
- [src/app/api/cron-tasks/route.ts:14-18](file://src/app/api/cron-tasks/route.ts#L14-L18)
- [src/lib/db.ts:50-50](file://src/lib/db.ts#L50-L50)
- [src/lib/db.ts:146-146](file://src/lib/db.ts#L146-L146)
- [src/lib/db.ts:410-411](file://src/lib/db.ts#L410-L411)
- [src/lib/db.ts:421-422](file://src/lib/db.ts#L421-L422)

### 数据完整性约束
- 约束类型
  - 主键约束：所有表主键唯一且非空。
  - 外键约束：消息、任务执行、绑定、权限链接均设置外键并定义删除行为（如级联删除）。
  - 检查约束：状态枚举、角色枚举、动作枚举等限定合法值。
  - 唯一约束：工作区路径唯一、MCP 服务器名称唯一。
- 迁移中的约束修复
  - IM 渠道状态枚举补充“disconnected”。
  - Hook 事件类型 CHECK 移除以支持扩展事件。
  - API 提供商新增状态与模型名列，保持兼容性。

章节来源
- [src/lib/db.ts:31-31](file://src/lib/db.ts#L31-L31)
- [src/lib/db.ts:39-39](file://src/lib/db.ts#L39-L39)
- [src/lib/db.ts:104-106](file://src/lib/db.ts#L104-L106)
- [src/lib/db.ts:118-122](file://src/lib/db.ts#L118-L122)
- [src/lib/db.ts:149-156](file://src/lib/db.ts#L149-L156)
- [src/lib/db.ts:159-164](file://src/lib/db.ts#L159-L164)
- [src/lib/db.ts:166-178](file://src/lib/db.ts#L166-L178)
- [src/lib/db.ts:180-199](file://src/lib/db.ts#L180-L199)
- [src/lib/db.ts:208-224](file://src/lib/db.ts#L208-L224)

### 数据库备份与恢复
- 备份
  - 数据库文件：forge.db 及其 WAL 归档文件（-shm/-wal）。
  - 上传目录：位于数据目录下的 uploads 子目录。
- 恢复
  - 将备份的数据库文件复制回数据目录，覆盖现有文件。
  - 若存在旧目录，可先迁移再恢复。
- 迁移脚本
  - 提供从旧目录到新目录的数据迁移逻辑，包含数据库与上传目录同步。

章节来源
- [src/lib/forge-data.ts:74-103](file://src/lib/forge-data.ts#L74-L103)
- [src/lib/forge-data.ts:52-103](file://src/lib/forge-data.ts#L52-L103)

### 连接超时与错误重试机制
- better-sqlite3 构建与运行时匹配
  - Electron 打包场景下，需要确保原生模块与目标 Node 版本匹配。
  - 脚本提供 node-gyp 重建与 prebuild-install 降级方案。
- 连接超时
  - 在测试 MCP 连通性时使用子进程调用的超时参数，避免阻塞。
- 错误重试
  - 投递层：指数退避与抖动，限制最大重试次数。
  - 桥接层：失败计数触发熔断，指数退避重连。

章节来源
- [scripts/build-electron.mjs:313-335](file://scripts/build-electron.mjs#L313-L335)
- [src/lib/db.ts:483-498](file://src/lib/db.ts#L483-L498)
- [src/lib/im/delivery.ts:223-240](file://src/lib/im/delivery.ts#L223-L240)
- [src/lib/im/bridge-manager.ts:569-592](file://src/lib/im/bridge-manager.ts#L569-L592)

### ORM 映射、数据验证与业务规则
- ORM 映射
  - 使用 better-sqlite3 的预编译语句与命名参数，实现 SQL 与 JS 对象的映射。
  - 类型文件定义了数据库实体与字段的 TypeScript 接口，作为前后端契约。
- 数据验证
  - 枚举字段通过 CHECK 约束与前端/后端类型约束共同保障。
  - 创建/更新接口对必填字段进行默认值填充与序列化处理。
- 业务规则
  - 会话状态：仅展示 active，归档状态用于后续管理。
  - 权限模式：支持确认与全量两种模式，可在会话层覆盖。
  - 定时任务：支持多种动作类型与工作区维度，心跳任务默认禁用。

章节来源
- [src/app/api/sessions/route.ts:19-32](file://src/app/api/sessions/route.ts#L19-L32)
- [src/app/api/cron-tasks/route.ts:23-52](file://src/app/api/cron-tasks/route.ts#L23-L52)
- [src/lib/types.ts:4-221](file://src/lib/types.ts#L4-L221)
- [src/lib/models.ts:20-50](file://src/lib/models.ts#L20-L50)

## 依赖分析
- 组件耦合
  - API 路由依赖数据库初始化模块，确保单例句柄与表结构就绪。
  - 桥接层与并发控制模块独立于数据库，但与聊天 API 协同工作。
- 外部依赖
  - better-sqlite3：原生模块，需与 Electron Node 版本匹配。
  - OS 工具：用于检测命令是否存在，辅助 MCP 连通性测试。

```mermaid
graph LR
API["API 路由"] --> DB["数据库初始化"]
API --> Types["类型定义"]
ChatAPI["聊天 API"] --> Lock["会话锁"]
ChatAPI --> Delivery["投递层"]
DB --> FS["文件系统/迁移"]
DB --> MCP["MCP 同步"]
```

图表来源
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)
- [src/app/api/cron-tasks/route.ts:1-53](file://src/app/api/cron-tasks/route.ts#L1-L53)
- [src/app/api/chat/route.ts:187-215](file://src/app/api/chat/route.ts#L187-L215)
- [src/lib/db.ts:1-7](file://src/lib/db.ts#L1-L7)
- [src/lib/im/concurrency.ts:8-60](file://src/lib/im/concurrency.ts#L8-L60)
- [src/lib/im/delivery.ts:223-240](file://src/lib/im/delivery.ts#L223-L240)

章节来源
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)
- [src/app/api/cron-tasks/route.ts:1-53](file://src/app/api/cron-tasks/route.ts#L1-L53)
- [src/app/api/chat/route.ts:187-215](file://src/app/api/chat/route.ts#L187-L215)
- [src/lib/db.ts:1-7](file://src/lib/db.ts#L1-L7)
- [src/lib/im/concurrency.ts:8-60](file://src/lib/im/concurrency.ts#L8-L60)
- [src/lib/im/delivery.ts:223-240](file://src/lib/im/delivery.ts#L223-L240)

## 性能考虑
- WAL 模式：提升并发读写吞吐，降低写放大。
- 索引策略：针对高频查询建立合适索引，避免全表扫描。
- 预编译语句：减少 SQL 解析与计划生成开销。
- 分页与排序：LIMIT/OFFSET 与合适的排序列，避免一次性加载大量数据。
- 并发控制：会话级锁避免重复处理，投递层重试与熔断降低无效负载。
- 原生模块匹配：确保 better-sqlite3 与运行时 Node 版本一致，避免性能退化。

## 故障排查指南
- 数据库无法打开或迁移失败
  - 检查数据目录权限与路径是否正确。
  - 查看迁移日志输出，确认旧目录是否存在且非空。
- better-sqlite3 构建问题
  - 确认 Electron 打包时的 node-gyp 与 nodedir 配置。
  - 如 node-gyp 失败，使用 prebuild-install 降级方案。
- 连接超时与 MCP 不可达
  - 检查命令是否存在与可执行权限。
  - 对于 stdio 协议，确认命令二进制路径与参数。
- 投递失败与重试
  - 观察指数退避日志，确认最大重试次数是否合理。
  - 检查网络/外部服务状态，必要时调整重试策略。
- 桥接重连与熔断
  - 关注失败计数与熔断状态，避免频繁重试导致资源浪费。
  - 调整重连间隔与抖动参数，平衡恢复速度与系统压力。

章节来源
- [src/lib/forge-data.ts:52-103](file://src/lib/forge-data.ts#L52-L103)
- [scripts/build-electron.mjs:313-335](file://scripts/build-electron.mjs#L313-L335)
- [src/lib/db.ts:483-498](file://src/lib/db.ts#L483-L498)
- [src/lib/im/delivery.ts:223-240](file://src/lib/im/delivery.ts#L223-L240)
- [src/lib/im/bridge-manager.ts:569-592](file://src/lib/im/bridge-manager.ts#L569-L592)

## 结论
本系统以 SQLite 为核心，结合 WAL 模式、外键约束与完善的迁移脚本，实现了稳定可靠的数据持久化。通过预编译语句、索引优化与会话级并发控制，兼顾了性能与一致性。桥接层的重试与熔断机制进一步增强了对外部系统的鲁棒性。整体架构清晰、职责分离明确，适合在桌面与嵌入式场景中部署与维护。

## 附录
- 常用操作路径
  - 获取数据库句柄：[src/lib/db.ts:18-24](file://src/lib/db.ts#L18-L24)
  - 创建表与索引：[src/lib/db.ts:25-224](file://src/lib/db.ts#L25-L224)
  - 迁移脚本：[src/lib/db.ts:226-430](file://src/lib/db.ts#L226-L430)
  - 会话 API：[src/app/api/sessions/route.ts:6-16](file://src/app/api/sessions/route.ts#L6-L16)
  - 定时任务 API：[src/app/api/cron-tasks/route.ts:6-21](file://src/app/api/cron-tasks/route.ts#L6-L21)
  - 聊天 API（历史回退）：[src/app/api/chat/route.ts:187-215](file://src/app/api/chat/route.ts#L187-L215)
  - 会话锁：[src/lib/im/concurrency.ts:21-49](file://src/lib/im/concurrency.ts#L21-L49)
  - 投递重试：[src/lib/im/delivery.ts:223-240](file://src/lib/im/delivery.ts#L223-L240)
  - 桥接重连：[src/lib/im/bridge-manager.ts:569-592](file://src/lib/im/bridge-manager.ts#L569-L592)
  - 数据目录与迁移：[src/lib/forge-data.ts:20-103](file://src/lib/forge-data.ts#L20-L103)
  - 类型与模型：[src/lib/types.ts:6-221](file://src/lib/types.ts#L6-L221), [src/lib/models.ts:20-50](file://src/lib/models.ts#L20-L50)
  - better-sqlite3 构建：[scripts/build-electron.mjs:313-335](file://scripts/build-electron.mjs#L313-L335)