# 扩展开发
**本文引用的文件**
- [README.md](file://README.md)
- [layout.tsx](file://src/app/layout.tsx)
- [types.ts](file://src/lib/types.ts)
- [db.ts](file://src/lib/db.ts)
- [use-mcp-servers.ts](file://src/hooks/use-mcp-servers.ts)
- [mcp-panel.tsx](file://src/components/manage/mcp-panel.tsx)
- [mcp-editor.tsx](file://src/components/manage/mcp-editor.tsx)
- [slash-commands.ts](file://src/lib/slash-commands.ts)
- [provider.ts](file://src/lib/provider.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)
- [route.ts](file://src/app/api/mcp/route.ts)
- [skills-route.ts](file://src/app/api/skills/route.ts)
- [workspaces-route.ts](file://src/app/api/workspaces/route.ts)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南面向希望在 Forge 平台上进行扩展开发的工程师与高级用户。Forge 是一个桌面本地 AI 工作台，基于 Claude Agent SDK 构建，提供会话与工作区管理、记忆系统、市场模板、IM 桥接、计划任务、以及 MCP（Model Context Protocol）服务器集成等能力。本文围绕以下扩展主题展开：
- 插件系统架构与扩展点：MCP 服务器集成、自定义命令、钩子机制
- React 组件开发、UI 定制与状态管理扩展
- API 扩展：新增 API 路由、数据库表扩展、业务逻辑扩展
- 安全、性能与兼容性最佳实践
- 可直接落地的扩展示例与参考路径
## 项目结构
Forge 的前端采用 Next.js App Router + Electron 主进程，核心目录与职责如下：
- electron/：Electron 主进程与预加载脚本
- src/app/：Next.js App Router，包含 API 路由与页面
- src/components/：React UI 组件
- src/hooks/：自定义 React Hooks
- src/lib/：核心逻辑（数据库、SDK 集成、IM 桥接、计划任务、市场模板等）
- src/types/：类型定义
- templates/：初始化配置模板
```mermaid
graph TB
subgraph "应用层"
UI["React 组件
src/components/*"]
Hooks["自定义 Hooks
src/hooks/*"]
Pages["Next.js 页面/布局
src/app/*"]
end
subgraph "服务层"
API["API 路由
src/app/api/*"]
Lib["核心库
src/lib/*"]
end
subgraph "数据层"
DB["SQLite 数据库
src/lib/db.ts"]
end
UI --> Hooks
Hooks --> API
Pages --> API
API --> Lib
Lib --> DB
```
图表来源
- [layout.tsx:22-38](file://src/app/layout.tsx#L22-L38)
- [db.ts:18-437](file://src/lib/db.ts#L18-L437)
章节来源
- [README.md:351-382](file://README.md#L351-L382)
- [layout.tsx:1-39](file://src/app/layout.tsx#L1-L39)
## 核心组件
- 类型系统：统一的数据模型与枚举，如会话、消息、技能、代理、MCP 服务器、IM 通道、计划任务、市场模板等，确保前后端一致的数据契约。
- 数据库层：SQLite（WAL 模式），内置迁移与自动同步（如 MCP 服务器从 Claude Code 配置同步）。
- API 层：App Router 下的 API 路由，负责 CRUD 与业务操作。
- UI 层：React 组件与 Hooks，提供 MCP 管理面板、编辑器、命令菜单等。
- 提供商解析：统一解析 API 提供商（含 CLI 认证与自定义端点）。
章节来源
- [types.ts:6-221](file://src/lib/types.ts#L6-L221)
- [db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [provider.ts:108-180](file://src/lib/provider.ts#L108-L180)
## 架构总览
Forge 的扩展架构以“类型 + 数据库 + API 路由 + UI 组件”为核心，形成可插拔的扩展点：
- MCP 服务器：通过数据库表存储配置，API 路由提供增删改查与连接测试；React 组件提供可视化管理界面。
- 技能与代理：通过数据库表与 API 路由实现持久化与管理。
- 命令系统：内置命令注册与过滤，支持技能、代理、MCP 工具的自动补全。
- 市场模板：以文件系统方式保存模板，支持导入导出到工作区。
```mermaid
graph TB
subgraph "扩展入口"
CMD["Slash 命令注册
src/lib/slash-commands.ts"]
MCP_UI["MCP 管理 UI
src/components/manage/mcp-panel.tsx
src/components/manage/mcp-editor.tsx"]
MCP_HOOK["MCP 状态 Hook
src/hooks/use-mcp-servers.ts"]
end
subgraph "后端"
API_MCP["/api/mcp
src/app/api/mcp/route.ts"]
API_SKILLS["/api/skills
src/app/api/skills/route.ts"]
API_WS["/api/workspaces
src/app/api/workspaces/route.ts"]
DB["数据库
src/lib/db.ts"]
end
CMD --> MCP_UI
MCP_UI --> MCP_HOOK
MCP_HOOK --> API_MCP
API_MCP --> DB
API_SKILLS --> DB
API_WS --> DB
```
图表来源
- [slash-commands.ts:20-69](file://src/lib/slash-commands.ts#L20-L69)
- [mcp-panel.tsx:25-146](file://src/components/manage/mcp-panel.tsx#L25-L146)
- [mcp-editor.tsx:93-334](file://src/components/manage/mcp-editor.tsx#L93-L334)
- [use-mcp-servers.ts:33-79](file://src/hooks/use-mcp-servers.ts#L33-L79)
- [route.ts:6-31](file://src/app/api/mcp/route.ts#L6-L31)
- [skills-route.ts:5-26](file://src/app/api/skills/route.ts#L5-L26)
- [workspaces-route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)
- [db.ts:18-437](file://src/lib/db.ts#L18-L437)
## 详细组件分析
### MCP 服务器扩展点
- 数据模型：MCP 服务器信息存储于 mcp_servers 表，字段包括协议、配置、启用状态与连接状态。
- API 路由：提供列表查询、创建、更新、删除与连接测试。
- UI 组件：左侧面板用于选择与上下文菜单操作，右侧编辑器支持表单与 JSON 编辑、连接测试、开关启用。
- 状态 Hook：封装 CRUD 与刷新逻辑，简化组件使用。
- 自动同步：启动时从 Claude Code 配置文件读取并自动创建未存在的服务器条目。
```mermaid
sequenceDiagram
participant U as "用户"
participant Panel as "MCP 面板
mcp-panel.tsx"
participant Hook as "MCP Hook
use-mcp-servers.ts"
participant API as "API 路由
/api/mcp/route.ts"
participant DB as "数据库
db.ts"
U->>Panel : 创建/编辑/删除 MCP 服务器
Panel->>Hook : 调用 create/update/delete
Hook->>API : 发起 HTTP 请求
API->>DB : 写入/更新/删除记录
DB-->>API : 返回最新记录
API-->>Hook : 返回结果
Hook-->>Panel : 更新状态与列表
```
图表来源
- [mcp-panel.tsx:25-146](file://src/components/manage/mcp-panel.tsx#L25-L146)
- [mcp-editor.tsx:93-334](file://src/components/manage/mcp-editor.tsx#L93-L334)
- [use-mcp-servers.ts:33-79](file://src/hooks/use-mcp-servers.ts#L33-L79)
- [route.ts:6-31](file://src/app/api/mcp/route.ts#L6-L31)
- [db.ts:89-115](file://src/lib/db.ts#L89-L115)
章节来源
- [types.ts:110-119](file://src/lib/types.ts#L110-L119)
- [db.ts:443-498](file://src/lib/db.ts#L443-L498)
- [route.ts:6-31](file://src/app/api/mcp/route.ts#L6-L31)
- [use-mcp-servers.ts:33-79](file://src/hooks/use-mcp-servers.ts#L33-L79)
- [mcp-panel.tsx:25-146](file://src/components/manage/mcp-panel.tsx#L25-L146)
- [mcp-editor.tsx:93-334](file://src/components/manage/mcp-editor.tsx#L93-L334)
### 自定义命令与钩子机制
- 命令系统：内置命令注册与分类排序，支持按前缀匹配与分组显示；技能、代理、MCP 工具均作为命令源参与自动补全。
- 钩子机制：数据库中存在 hooks 表，支持事件类型、工具模式匹配、动作（shell/block/log）与命令执行，可用于前置拦截或日志记录。
```mermaid
flowchart TD
Start(["输入 / 命令"]) --> Load["加载命令注册表
slash-commands.ts"]
Load --> Filter["按前缀过滤与分类排序"]
Filter --> Render["渲染命令菜单"]
Render --> Exec["执行命令技能/代理/MCP"]
Exec --> HookCheck{"是否命中钩子？"}
HookCheck --> |是| HookAction["执行钩子动作log/block/shell"]
HookCheck --> |否| Done["完成"]
HookAction --> Done
```
图表来源
- [slash-commands.ts:20-69](file://src/lib/slash-commands.ts#L20-L69)
- [db.ts:148-157](file://src/lib/db.ts#L148-L157)
章节来源
- [slash-commands.ts:20-69](file://src/lib/slash-commands.ts#L20-L69)
- [db.ts:148-157](file://src/lib/db.ts#L148-L157)
### React 组件开发与 UI 定制
- 组件组织：按功能模块拆分（聊天、布局、管理、市场、UI 控件等），便于扩展与复用。
- 状态管理：通过自定义 Hooks 封装 API 调用与本地状态，降低组件复杂度。
- 国际化与主题：根布局提供主题与国际化 Provider，确保扩展组件具备一致的外观与文案策略。
- 示例：MCP 管理面板与编辑器展示了表单/JSON 切换、连接测试、启用开关、上下文菜单等交互模式。
章节来源
- [layout.tsx:22-38](file://src/app/layout.tsx#L22-L38)
- [mcp-panel.tsx:25-146](file://src/components/manage/mcp-panel.tsx#L25-L146)
- [mcp-editor.tsx:93-334](file://src/components/manage/mcp-editor.tsx#L93-L334)
- [use-mcp-servers.ts:33-79](file://src/hooks/use-mcp-servers.ts#L33-L79)
### API 扩展方法
- 新增 API 路由：遵循 App Router 规范，在 src/app/api 下新增路由文件，使用 getDb 获取数据库实例，实现 CRUD 或业务逻辑。
- 数据库表扩展：在 db.ts 中添加建表语句与迁移逻辑，确保向后兼容与平滑升级。
- 业务逻辑扩展：在 lib 目录下新增模块（如 marketplace-fs、provider 等），并通过 API 路由暴露接口。
```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Route as "新 API 路由
src/app/api/xxx/route.ts"
participant DB as "数据库
src/lib/db.ts"
participant Model as "类型定义
src/lib/types.ts"
Dev->>Route : 实现 GET/POST/PATCH/DELETE
Dev->>Model : 定义/复用数据模型
Route->>DB : 查询/插入/更新/删除
DB-->>Route : 返回结果
Route-->>Dev : JSON 响应
```
图表来源
- [skills-route.ts:5-26](file://src/app/api/skills/route.ts#L5-L26)
- [workspaces-route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)
- [db.ts:25-224](file://src/lib/db.ts#L25-L224)
- [types.ts:66-74](file://src/lib/types.ts#L66-L74)
章节来源
- [skills-route.ts:5-26](file://src/app/api/skills/route.ts#L5-L26)
- [workspaces-route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)
- [db.ts:25-224](file://src/lib/db.ts#L25-L224)
- [types.ts:66-74](file://src/lib/types.ts#L66-L74)
### 市场模板与工作区扩展
- 市场模板：以文件系统保存模板，支持扫描树形结构、复制项目到模板、复制模板到项目等功能。
- 工作区：注册项目路径、维护最后打开时间、初始化 .claude/ 目录。
章节来源
- [marketplace-fs.ts:46-157](file://src/lib/marketplace-fs.ts#L46-L157)
- [workspaces-route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)
## 依赖分析
- 组件耦合：UI 组件通过自定义 Hooks 与 API 路由解耦，避免直接依赖数据库；API 路由集中处理业务与数据访问。
- 外部依赖：SQLite、better-sqlite3、Claude Agent SDK、IM 平台 SDK（通过外部化 webpack 保持原生行为）。
- 类型一致性：所有数据模型集中在 types.ts，确保前后端契约稳定。
```mermaid
graph LR
Types["类型定义
src/lib/types.ts"] --> DB["数据库
src/lib/db.ts"]
Types --> API["API 路由
src/app/api/*"]
DB --> API
API --> UI["React 组件
src/components/*"]
API --> Hooks["Hooks
src/hooks/*"]
Hooks --> UI
```
图表来源
- [types.ts:6-221](file://src/lib/types.ts#L6-L221)
- [db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [route.ts:6-31](file://src/app/api/mcp/route.ts#L6-L31)
章节来源
- [types.ts:6-221](file://src/lib/types.ts#L6-L221)
- [db.ts:18-437](file://src/lib/db.ts#L18-L437)
## 性能考量
- 数据库优化：WAL 模式提升并发读性能；为高频查询建立索引（如 messages.session_id、task_executions.task_id）。
- 连接测试：MCP 连接测试仅对 stdio 协议进行快速二进制检查，避免阻塞；其他协议延迟检测。
- UI 渲染：React 组件按需渲染与状态最小化，避免不必要的重绘；编辑器支持自动换行与大文本优化。
- 启动流程：数据库初始化与迁移只在首次访问执行，后续复用已连接实例。
章节来源
- [db.ts:22-24](file://src/lib/db.ts#L22-L24)
- [db.ts:50-50](file://src/lib/db.ts#L50-L50)
- [db.ts:146-146](file://src/lib/db.ts#L146-L146)
- [db.ts:483-498](file://src/lib/db.ts#L483-L498)
## 故障排查指南
- MCP 连接失败
- 检查协议与配置：确认 stdio 的命令是否存在、SSE/HTTP 的 URL 与头是否正确。
- 使用连接测试按钮触发测试，查看返回错误信息。
- 查看数据库中 status 字段与最近更新时间。
- 命令无法显示
- 确认命令注册表中类别与前缀匹配逻辑。
- 检查是否有钩子拦截导致命令不可见。
- 数据库异常
- 关注迁移日志：旧表结构变更（如 workspaces、im_channels、api_providers、hooks、cron_tasks、task_executions、channel_bindings、sessions）均已内置迁移。
- WAL 模式下并发读写问题：避免在同一事务中频繁切换表结构。
- IM 桥接
- 确认凭据配置与策略设置（DM/群组白名单、触发模式）。
- 检查审计日志与去重表，定位重复消息或失败原因。
章节来源
- [mcp-editor.tsx:123-142](file://src/components/manage/mcp-editor.tsx#L123-L142)
- [db.ts:432-477](file://src/lib/db.ts#L432-L477)
- [slash-commands.ts:42-60](file://src/lib/slash-commands.ts#L42-L60)
- [db.ts:226-394](file://src/lib/db.ts#L226-L394)
## 结论
Forge 的扩展体系以类型驱动、数据库持久化与 API 路由为中心，结合 React 组件与自定义 Hooks，提供了清晰的扩展边界与开发路径。通过 MCP 服务器、命令系统、钩子机制、市场模板与工作区等扩展点，开发者可以快速构建可复用的功能模块，并在保证安全与性能的前提下实现业务定制。
## 附录
- 扩展清单（建议）
- 新增 MCP 服务器：使用 /api/mcp 路由创建，配合 UI 面板与连接测试。
- 新增技能：使用 /api/skills 路由创建，结合命令系统与自动补全。
- 新增工作区：使用 /api/workspaces 路由注册，初始化 .claude/。
- 新增 API 路由：在 src/app/api 下新增路由文件，复用 getDb 与类型定义。
- 数据库迁移：在 db.ts 中添加建表与迁移逻辑，确保向后兼容。
- 市场模板：使用 marketplace-fs 工具复制/导入导出模板。
- 提供商解析：在 provider.ts 中扩展提供商映射与认证方式。
章节来源
- [route.ts:6-31](file://src/app/api/mcp/route.ts#L6-L31)
- [skills-route.ts:5-26](file://src/app/api/skills/route.ts#L5-L26)
- [workspaces-route.ts:8-59](file://src/app/api/workspaces/route.ts#L8-L59)
- [db.ts:25-224](file://src/lib/db.ts#L25-L224)
- [marketplace-fs.ts:46-157](file://src/lib/marketplace-fs.ts#L46-L157)
- [provider.ts:108-180](file://src/lib/provider.ts#L108-L180)