# API扩展

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/lib/provider.ts](file://src/lib/provider.ts)
- [src/app/api/agents/route.ts](file://src/app/api/agents/route.ts)
- [src/app/api/agents/[id]/route.ts](file://src/app/api/agents/[id]/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/settings/route.ts](file://src/app/api/settings/route.ts)
- [src/app/api/chat/route.ts](file://src/app/api/chat/route.ts)
- [src/app/api/models/route.ts](file://src/app/api/models/route.ts)
- [src/app/api/skills/route.ts](file://src/app/api/skills/route.ts)
</cite>

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

## 简介
本指南面向希望在Forge中进行API扩展开发的工程师，系统讲解如何新增API路由、扩展数据库表结构与增强业务逻辑。内容覆盖RESTful接口设计、参数校验与响应格式标准化、数据库表结构设计与迁移策略、钩子与中间件模式、事务处理、安全与性能优化、错误处理与版本兼容、测试与文档生成、监控告警等最佳实践，并提供从需求分析到部署上线的完整流程示例。

## 项目结构
Forge采用Next.js App Router组织API路由，核心后端逻辑集中在src/lib目录，数据库使用SQLite（better-sqlite3），通过WAL模式提升并发读性能；前端为React + TailwindCSS，桌面层由Electron承载。

```mermaid
graph TB
subgraph "应用层"
Next["Next.js 应用<br/>App Router 路由"]
end
subgraph "API 层"
Agents["/api/agents/*"]
Workspaces["/api/workspaces/*"]
Sessions["/api/sessions/*"]
Settings["/api/settings/*"]
Chat["/api/chat/*"]
Models["/api/models/*"]
Skills["/api/skills/*"]
end
subgraph "服务层"
DB["数据库服务<br/>SQLite(better-sqlite3)<br/>WAL 模式"]
Provider["模型与提供商解析<br/>provider.ts"]
Types["类型定义<br/>types.ts"]
end
Next --> Agents
Next --> Workspaces
Next --> Sessions
Next --> Settings
Next --> Chat
Next --> Models
Next --> Skills
Agents --> DB
Workspaces --> DB
Sessions --> DB
Settings --> DB
Chat --> DB
Models --> DB
Skills --> DB
Chat --> Provider
Models --> Provider
Settings --> Provider
```

图表来源
- [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/settings/route.ts:1-49](file://src/app/api/settings/route.ts#L1-L49)
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/app/api/models/route.ts:1-35](file://src/app/api/models/route.ts#L1-L35)
- [src/app/api/skills/route.ts:1-27](file://src/app/api/skills/route.ts#L1-L27)
- [src/lib/db.ts:1-499](file://src/lib/db.ts#L1-L499)
- [src/lib/provider.ts:1-201](file://src/lib/provider.ts#L1-L201)
- [src/lib/types.ts:1-221](file://src/lib/types.ts#L1-L221)

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

## 核心组件
- 数据库层：统一通过src/lib/db.ts初始化SQLite连接、创建基础表与索引、执行迁移脚本，确保WAL与外键约束开启。
- 类型系统：src/lib/types.ts集中定义会话、消息、代理、工作区、技能、任务等核心实体的TS类型，保证前后端一致的数据契约。
- 提供商解析：src/lib/provider.ts负责根据模型名解析提供商配置（含CLI认证与自定义端点），为SDK调用提供凭据。
- API路由：src/app/api下按领域划分路由，遵循REST风格，统一使用NextResponse返回JSON或SSE流式响应。

章节来源
- [src/lib/db.ts: 18-437:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/types.ts: 6-L221:6-221](file://src/lib/types.ts#L6-L221)
- [src/lib/provider.ts: 108-180:108-180](file://src/lib/provider.ts#L108-L180)

## 架构总览
Forge的API扩展遵循“路由层-服务层-数据层”分层架构。路由层负责请求解析与响应封装；服务层通过db.ts访问SQLite；provider.ts提供模型与提供商解析能力；types.ts确保类型一致性。

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "路由层<br/>App Router"
participant S as "服务层<br/>db.ts/provider.ts"
participant D as "数据层<br/>SQLite"
C->>R : "HTTP 请求"
R->>S : "参数校验/业务编排"
S->>D : "SQL 查询/更新"
D-->>S : "结果集/影响行数"
S-->>R : "领域对象/聚合数据"
R-->>C : "JSON/SSE 响应"
```

图表来源
- [src/app/api/chat/route.ts:74-342](file://src/app/api/chat/route.ts#L74-L342)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/provider.ts:108-180](file://src/lib/provider.ts#L108-L180)

## 详细组件分析

### 组件A：代理管理API（agents）
- 设计要点
  - 列表查询：支持按主代理优先与更新时间排序，同时加载代理关联的技能ID列表。
  - 创建：接收名称、描述、模型、权限模式、主代理标记、父代理ID、指令、身份、工具配置等字段，统一序列化存储。
  - 单条查询：返回代理详情及技能ID数组。
  - 更新：动态拼接字段，仅对传入字段更新，自动更新时间戳。
  - 删除：级联删除代理记录。
- 参数校验与响应
  - POST/GET/DELETE在路由层完成基本校验与返回标准JSON。
  - PATCH对空字段返回400错误，避免无效更新。
- 复杂度与性能
  - 列表查询包含一次多表联结（代理-技能映射）；建议在代理ID上建立索引以优化查询。
- 安全与版本
  - 工具配置字段支持字符串或对象，需在入库前做白名单与最小权限控制。
  - 版本变更时保持字段兼容，避免破坏既有客户端。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Agents as "agents 路由"
participant DB as "db.ts"
Client->>Agents : "POST /api/agents"
Agents->>DB : "插入代理记录"
DB-->>Agents : "成功"
Agents-->>Client : "201 + 新代理JSON"
Client->>Agents : "PATCH /api/agents/ : id"
Agents->>DB : "条件更新字段"
DB-->>Agents : "影响行数"
Agents-->>Client : "200 + 更新后代理JSON"
```

图表来源
- [src/app/api/agents/route.ts:19-41](file://src/app/api/agents/route.ts#L19-L41)
- [src/app/api/agents/[id]/route.ts](file://src/app/api/agents/[id]/route.ts#L14-L49)
- [src/lib/db.ts:34-44](file://src/lib/db.ts#L34-L44)

章节来源
- [src/app/api/agents/route.ts: 5-L42:5-42](file://src/app/api/agents/route.ts#L5-L42)
- [src/app/api/agents/[id]/route.ts: 4-L57](file://src/app/api/agents/[id]/route.ts#L4-L57)

### 组件B：工作区管理API（workspaces）
- 设计要点
  - 列表：返回最近打开的工作区，附加目录名与存在性检测。
  - 创建：校验路径存在且为目录，若未注册则写入数据库并初始化默认配置目录。
- 错误处理
  - 非法JSON、缺失路径、路径不存在或非目录均返回400。
- 性能与并发
  - 文件系统检查与数据库写入分离，避免阻塞；初始化操作在创建时触发。

```mermaid
flowchart TD
Start(["POST /api/workspaces"]) --> Parse["解析请求体"]
Parse --> Valid{"路径有效?"}
Valid --> |否| Err400["返回 400"]
Valid --> |是| Exists{"目录存在?"}
Exists --> |否| Err400
Exists --> |是| CheckDB["查询是否已注册"]
CheckDB --> Registered{"已注册?"}
Registered --> |是| Update["更新最后打开时间"] --> Return200["返回已存在工作区"]
Registered --> |否| Insert["插入新工作区"] --> Init["初始化 .claude/"] --> Return201["返回新建工作区"]
```

图表来源
- [src/app/api/workspaces/route.ts:24-60](file://src/app/api/workspaces/route.ts#L24-L60)

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

### 组件C：会话管理API（sessions）
- 设计要点
  - 列表：启动时自动清理过期会话，筛选活跃状态并按更新时间倒序。
  - 创建：生成随机ID，设置标题、工作区与模型。
- 事务与一致性
  - 创建会话为单条插入，无需事务；清理逻辑幂等。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Sessions as "sessions 路由"
participant DB as "db.ts"
Client->>Sessions : "GET /api/sessions"
Sessions->>DB : "清理过期会话"
DB-->>Sessions : "完成"
Sessions-->>Client : "活跃会话列表"
Client->>Sessions : "POST /api/sessions"
Sessions->>DB : "插入新会话"
DB-->>Sessions : "成功"
Sessions-->>Client : "201 + 会话JSON"
```

图表来源
- [src/app/api/sessions/route.ts:6-34](file://src/app/api/sessions/route.ts#L6-L34)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

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

### 组件D：设置管理API（settings）
- 设计要点
  - 首次读取时预热相关服务（如IM桥接与定时引擎），确保功能可用。
  - 批量写入使用事务，保证原子性。
- 并发与性能
  - 事务批量写入settings，减少多次提交开销。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Settings as "settings 路由"
participant DB as "db.ts"
Client->>Settings : "PUT /api/settings"
Settings->>DB : "事务批量 upsert"
DB-->>Settings : "完成"
Settings-->>Client : "200 { ok : true }"
```

图表来源
- [src/app/api/settings/route.ts:32-48](file://src/app/api/settings/route.ts#L32-L48)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

章节来源
- [src/app/api/settings/route.ts: 19-L49:19-49](file://src/app/api/settings/route.ts#L19-L49)

### 组件E：聊天流式API（chat）
- 设计要点
  - 流式输出：使用SSE与TransformStream，逐块发送事件，支持断线重连。
  - 权限与思考模式：支持“确认”和“全量”两种权限模式，思考模式可按提供商与全局设置推导。
  - 附件处理：支持图片与文件上传，自动复制到上传目录并注入附件块。
  - 回退机制：会话恢复失败时回退到历史上下文构建提示词重新发起。
- 错误处理
  - 异常捕获后保存部分响应或回滚用户消息，发送错误事件给前端。
- 性能与并发
  - 使用WAL与索引优化查询；后台内存归档与会话清理降低数据库压力。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Chat as "chat 路由"
participant SDK as "Claude Agent SDK"
participant DB as "db.ts"
Client->>Chat : "POST /api/chat (SSE)"
Chat->>DB : "读取会话/权限/模型"
Chat->>SDK : "创建查询(可恢复/可旁路权限)"
SDK-->>Chat : "流式消息块"
Chat->>DB : "持久化用户/助手消息"
Chat-->>Client : "SSE 事件流"
Chat-->>Client : "done/错误事件"
```

图表来源
- [src/app/api/chat/route.ts:74-342](file://src/app/api/chat/route.ts#L74-L342)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

章节来源
- [src/app/api/chat/route.ts: 74-L350:74-350](file://src/app/api/chat/route.ts#L74-L350)

### 组件F：模型查询API（models）
- 设计要点
  - 合并内置模型与自定义提供商模型，自定义模型来自状态为“已连接”的api_providers记录。
- 兼容性
  - 当数据库不可用时降级返回内置模型，保证前端可用。

章节来源
- [src/app/api/models/route.ts: 12-L35:12-35](file://src/app/api/models/route.ts#L12-L35)
- [src/lib/db.ts:166-178](file://src/lib/db.ts#L166-L178)

### 组件G：技能管理API（skills）
- 设计要点
  - 列表：按更新时间倒序。
  - 创建：默认Markdown模板，支持工作区/全局作用域。

章节来源
- [src/app/api/skills/route.ts: 5-L27:5-27](file://src/app/api/skills/route.ts#L5-L27)
- [src/lib/db.ts:52-61](file://src/lib/db.ts#L52-L61)

## 依赖分析
- 运行时与依赖
  - Next.js 15、Electron、better-sqlite3、Claude Agent SDK、Zod（类型校验）等。
- 内部耦合
  - 所有API路由依赖db.ts获取连接；聊天与模型API依赖provider.ts解析提供商；类型定义统一于types.ts。
- 外部集成
  - IM桥接、定时任务引擎在首次访问相关设置时被预热启动。

```mermaid
graph LR
Pkg["package.json 依赖"] --> Next["Next.js"]
Pkg --> Elec["Electron"]
Pkg --> DB["better-sqlite3"]
Pkg --> SDK["@anthropic-ai/claude-agent-sdk"]
Routes["API 路由"] --> DBLib["db.ts"]
Routes --> Prov["provider.ts"]
Routes --> Types["types.ts"]
```

图表来源
- [package.json: 27-67:27-67](file://package.json#L27-L67)
- [src/app/api/chat/route.ts:1-16](file://src/app/api/chat/route.ts#L1-L16)
- [src/lib/db.ts:1-10](file://src/lib/db.ts#L1-L10)
- [src/lib/provider.ts:1-17](file://src/lib/provider.ts#L1-L17)
- [src/lib/types.ts:1-10](file://src/lib/types.ts#L1-L10)

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

## 性能考量
- 数据库
  - WAL模式提升并发读性能；为messages与task_executions建立索引；外键约束启用保障一致性。
  - 迁移脚本对旧schema进行平滑升级，避免停机。
- 路由与流式
  - chat路由使用SSE与TransformStream，避免全量缓冲；对会话清理与权限清理进行节流。
- 缓存与预热
  - settings路由在首次读取时预热IM桥接与定时引擎，减少首调延迟。
- 并发与锁
  - chat在会话恢复失败时使用新的sessionId避免锁冲突。

章节来源
- [src/lib/db.ts: 22-L224:22-224](file://src/lib/db.ts#L22-L224)
- [src/app/api/chat/route.ts: 18-L342:18-342](file://src/app/api/chat/route.ts#L18-L342)
- [src/app/api/settings/route.ts: 9-L17:9-17](file://src/app/api/settings/route.ts#L9-L17)

## 故障排查指南
- 常见错误与定位
  - 400错误：请求体非法或缺少必要字段（如workspaces创建时的路径）。
  - 404错误：资源不存在（如agents/[id]查询）。
  - 400/500错误：chat路由异常时会保存部分响应或回滚用户消息，并向客户端发送错误事件。
- 诊断步骤
  - 查看路由层返回的错误信息与状态码。
  - 检查db.ts中的SQL执行日志与索引使用情况。
  - 对provider解析失败的情况，确认api_providers表中对应提供商的密钥与状态。
- 修复建议
  - 在路由层增加更细粒度的参数校验与Zod schema校验。
  - 对长耗时操作使用后台任务与队列，避免阻塞请求线程。

章节来源
- [src/app/api/workspaces/route.ts: 24-L60:24-60](file://src/app/api/workspaces/route.ts#L24-L60)
- [src/app/api/agents/[id]/route.ts: 4-L12](file://src/app/api/agents/[id]/route.ts#L4-L12)
- [src/app/api/chat/route.ts: 309-L325:309-325](file://src/app/api/chat/route.ts#L309-L325)
- [src/lib/db.ts: 226-L430:226-430](file://src/lib/db.ts#L226-L430)

## 结论
Forge的API扩展遵循清晰的分层与约定：路由层REST化、服务层通过db.ts访问SQLite、类型系统统一契约、provider解析统一提供商凭据。新增API时应严格遵循参数校验、响应标准化、事务与错误处理、性能与安全策略，并结合迁移脚本与版本兼容策略，确保平滑演进与稳定运行。

## 附录

### API扩展最佳实践清单
- 接口设计
  - 使用REST风格路径与动词；明确HTTP状态码与错误响应结构。
  - 对可选字段提供默认值，避免空指针。
- 参数校验
  - 在路由层进行基础校验；复杂场景引入Zod schema。
- 响应格式
  - 统一返回JSON；错误响应包含错误码与简要描述。
- 数据库扩展
  - 新增表时同步创建索引；编写迁移脚本，兼容旧schema。
  - 使用事务批量写入settings等场景。
- 业务逻辑
  - 将通用逻辑抽象为服务函数；对敏感操作引入权限与审计。
  - 对长耗时任务异步化，提供状态查询接口。
- 安全
  - 限制工具配置范围；对上传文件进行白名单与大小限制。
  - 对外部提供商凭据加密存储，最小权限原则。
- 性能
  - 使用WAL与索引；对热点查询加缓存；流式输出避免大对象阻塞。
- 错误处理与版本兼容
  - 返回结构化错误；对字段变更提供向后兼容。
- 测试与文档
  - 编写单元与集成测试；基于路由自动生成OpenAPI文档。
- 监控与告警
  - 记录关键指标（响应时间、错误率、数据库慢查询）；对异常行为告警。

### 完整扩展示例：新增“标签”功能
- 需求分析
  - 为会话添加标签字段，支持按标签过滤与统计。
- 数据库扩展
  - 在sessions表新增tags字段；迁移脚本兼容旧版本。
- 业务逻辑
  - 在创建/更新会话时校验标签合法性；提供按标签查询接口。
- API设计
  - POST/PUT /api/sessions 支持tags字段；GET /api/sessions?tag=xxx 实现过滤。
- 安全与性能
  - 标签白名单；对高频查询建立索引；事务批量更新。
- 测试与文档
  - 编写标签增删改查测试；更新API文档与变更日志。
- 上线与监控
  - 灰度发布；观察错误率与响应时间；异常告警。