# 插件开发

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/mcp-test.ts](file://src/lib/mcp-test.ts)
- [src/lib/sdk/client.ts](file://src/lib/sdk/client.ts)
- [src/lib/sdk/mcp-loader.ts](file://src/lib/sdk/mcp-loader.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/hooks/use-mcp-servers.ts](file://src/hooks/use-mcp-servers.ts)
- [src/hooks/use-agents.ts](file://src/hooks/use-agents.ts)
- [src/app/api/mcp/route.ts](file://src/app/api/mcp/route.ts)
- [src/app/api/mcp/[id]/route.ts](file://src/app/api/mcp/[id]/route.ts)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts)
- [src/app/api/agents/route.ts](file://src/app/api/agents/route.ts)
- [src/components/manage/mcp-editor.tsx](file://src/components/manage/mcp-editor.tsx)
- [src/components/manage/mcp-panel.tsx](file://src/components/manage/mcp-panel.tsx)
- [src/components/manage/agent-editor.tsx](file://src/components/manage/agent-editor.tsx)
- [templates/init/CLAUDE.md](file://templates/init/CLAUDE.md)
</cite>

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

## 简介
本指南面向希望在Forge中开发与集成插件（MCP服务器与Agent）的开发者，系统讲解以下内容：
- MCP（Model Context Protocol）服务器的发现、连接与通信协议
- Agent加载器的工作原理：智能体注册、配置与生命周期管理
- 系统提示词的定制与管理：模板、变量替换与动态生成
- 完整插件开发示例：从MCP服务器创建到Agent集成的全流程
- 测试方法、调试技巧与性能优化建议
- 安全考虑、版本兼容性与错误处理策略

## 项目结构
Forge采用Electron + Next.js架构，核心逻辑集中在src/lib目录，前端界面通过React组件与API路由交互。与插件开发直接相关的关键模块如下：
- 数据层：SQLite数据库初始化、迁移与表结构定义
- MCP：自动同步Claude Code配置、本地编辑与连接测试
- SDK封装：统一构建查询实例，注入Agent、MCP与系统提示词
- 类型定义：前后端共享的类型约束（Agent、MCP服务器等）
- 前端Hooks与组件：MCP与Agent的增删改查与可视化编辑

```mermaid
graph TB
subgraph "桌面应用"
UI_MCP["MCP面板<br/>mcp-panel.tsx"]
UI_Agent["Agent编辑器<br/>agent-editor.tsx"]
end
subgraph "Next.js API 路由"
API_MCP_List["GET /api/mcp<br/>route.ts"]
API_MCP_CRUD["CRUD /api/mcp/:id<br/>route.ts"]
API_MCP_Test["POST /api/mcp/:id/test<br/>route.ts"]
API_Agents["GET/POST /api/agents<br/>route.ts"]
end
subgraph "后端逻辑"
Hook_MCP["useMcpServers<br/>use-mcp-servers.ts"]
Hook_Agents["useAgents<br/>use-agents.ts"]
DB["数据库初始化与迁移<br/>db.ts"]
SDK_Client["SDK客户端封装<br/>sdk/client.ts"]
SDK_MCP_Loader["MCP加载器<br/>sdk/mcp-loader.ts"]
MCP_Test["连接测试工具<br/>mcp-test.ts"]
end
UI_MCP --> Hook_MCP
UI_Agent --> Hook_Agents
Hook_MCP --> API_MCP_List
Hook_MCP --> API_MCP_CRUD
Hook_MCP --> API_MCP_Test
Hook_Agents --> API_Agents
API_MCP_List --> DB
API_MCP_CRUD --> DB
API_MCP_Test --> MCP_Test
API_Agents --> DB
SDK_Client --> SDK_MCP_Loader
SDK_Client --> DB
```

图表来源
- [src/components/manage/mcp-panel.tsx:1-181](file://src/components/manage/mcp-panel.tsx#L1-181)
- [src/components/manage/agent-editor.tsx:1-486](file://src/components/manage/agent-editor.tsx#L1-486)
- [src/hooks/use-mcp-servers.ts:1-80](file://src/hooks/use-mcp-servers.ts#L1-80)
- [src/hooks/use-agents.ts:1-103](file://src/hooks/use-agents.ts#L1-103)
- [src/app/api/mcp/route.ts:1-32](file://src/app/api/mcp/route.ts#L1-32)
- [src/app/api/mcp/[id]/route.ts](file://src/app/api/mcp/[id]/route.ts#L1-44)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L1-38)
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-42)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-437)
- [src/lib/sdk/client.ts:1-407](file://src/lib/sdk/client.ts#L1-407)
- [src/lib/sdk/mcp-loader.ts:1-41](file://src/lib/sdk/mcp-loader.ts#L1-41)
- [src/lib/mcp-test.ts:1-51](file://src/lib/mcp-test.ts#L1-51)

章节来源
- [README.md: 351-382:351-382](file://README.md#L351-L382)
- [src/lib/db.ts: 18-437:18-437](file://src/lib/db.ts#L18-L437)

## 核心组件
- 数据库与模型
  - 数据库初始化与迁移：创建会话、消息、技能、代理、MCP服务器、计划任务等表，并进行多轮迁移以兼容旧版本schema。
  - MCP服务器表：存储名称、协议（stdio/sse/http）、配置JSON、启用状态与更新时间。
  - 代理表：存储代理元数据、权限模式、父代理ID、工具配置与关联技能列表。
- MCP工具链
  - 自动同步：启动时读取用户主目录下的Claude Code配置文件，自动导入MCP服务器至本地数据库。
  - 连接测试：根据协议类型执行不同检查（本地命令存在性或HTTP/SSE可达性），并将状态写回数据库。
- SDK封装
  - 统一创建查询实例：注入系统提示词、Agent文件、MCP服务器（含浏览器MCP与额外扩展）、环境变量与API提供者信息。
  - 环境构建：确保SDK可访问CLI认证与工作区上下文，支持IM场景与桌面场景的差异化提示词。
- 类型系统
  - 明确定义Agent、MCP服务器、会话、消息、技能、计划任务等核心类型，保证前后端一致的数据契约。

章节来源
- [src/lib/db.ts: 25-224:25-224](file://src/lib/db.ts#L25-L224)
- [src/lib/db.ts: 443-498:443-498](file://src/lib/db.ts#L443-L498)
- [src/lib/sdk/client.ts: 378-407:378-407](file://src/lib/sdk/client.ts#L378-L407)
- [src/lib/types.ts: 89-119:89-119](file://src/lib/types.ts#L89-L119)

## 架构总览
Forge通过“前端组件 + Next.js API路由 + 数据库 + SDK封装”的分层设计，实现MCP与Agent的全生命周期管理。下图展示从用户操作到SDK执行的关键路径：

```mermaid
sequenceDiagram
participant U as "用户"
participant C as "MCP编辑器<br/>mcp-editor.tsx"
participant H as "useMcpServers<br/>use-mcp-servers.ts"
participant API as "Next.js API<br/>/api/mcp/*"
participant DB as "数据库<br/>db.ts"
participant SDK as "SDK客户端<br/>sdk/client.ts"
U->>C : 创建/编辑MCP服务器
C->>H : 触发保存/测试
H->>API : POST /api/mcp 或 PATCH /api/mcp/ : id
API->>DB : 写入/更新记录
H->>API : POST /api/mcp/ : id/test
API->>DB : 读取配置并调用测试
DB-->>API : 返回连接状态
API-->>H : 返回测试结果
H-->>C : 更新UI状态
Note over SDK,DB : SDK启动时加载MCP与Agent配置
SDK->>DB : 读取启用的MCP服务器
SDK->>SDK : 构建查询实例系统提示词+Agent+MCP
```

图表来源
- [src/components/manage/mcp-editor.tsx:112-142](file://src/components/manage/mcp-editor.tsx#L112-L142)
- [src/hooks/use-mcp-servers.ts:51-76](file://src/hooks/use-mcp-servers.ts#L51-L76)
- [src/app/api/mcp/route.ts:12-31](file://src/app/api/mcp/route.ts#L12-L31)
- [src/app/api/mcp/[id]/route.ts](file://src/app/api/mcp/[id]/route.ts#L12-L36)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L8-L37)
- [src/lib/db.ts:443-498](file://src/lib/db.ts#L443-L498)
- [src/lib/sdk/client.ts:378-407](file://src/lib/sdk/client.ts#L378-L407)

## 详细组件分析

### MCP服务器管理
- 发现与同步
  - 启动时扫描用户主目录中的Claude Code配置文件，将其中的MCP服务器条目自动导入本地数据库，避免重复（基于唯一索引）。
  - 对于stdio协议，快速检测命令是否存在；对于其他协议，仅记录状态为未连接（实际HTTP/SSE测试在API层完成）。
- 编辑与测试
  - 前端提供表单与JSON两种编辑模式，支持协议切换与字段校验。
  - 提供一键测试连接，调用API路由对指定服务器执行协议相关的可达性检查，并将结果写回数据库。
- API与数据库交互
  - 列表：返回所有MCP服务器，按最近更新排序。
  - 创建：生成随机ID，写入名称、协议、配置与初始状态，随后立即测试并更新状态。
  - 更新/删除：支持按字段增量更新与完整删除。
- 类型与状态
  - 协议枚举：stdio/sse/http。
  - 状态枚举：connected/disconnected/error。

```mermaid
flowchart TD
Start(["开始：用户点击测试"]) --> Load["读取服务器配置<br/>/api/mcp/:id"]
Load --> Parse{"解析配置成功？"}
Parse --> |否| Fail["返回错误"]
Parse --> |是| Switch{"协议类型？"}
Switch --> |stdio| CheckStdio["检查命令是否存在"]
Switch --> |sse/http| FetchUrl["发起HTTP请求超时限制"]
CheckStdio --> Result{"结果"}
FetchUrl --> Result
Result --> |2xx/405| MarkOK["标记为已连接"]
Result --> |其他| MarkErr["标记为错误"]
MarkOK --> Save["写回数据库状态"]
MarkErr --> Save
Save --> Done(["结束"])
Fail --> Done
```

图表来源
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L8-L37)
- [src/lib/mcp-test.ts:9-50](file://src/lib/mcp-test.ts#L9-L50)
- [src/lib/db.ts:483-498](file://src/lib/db.ts#L483-L498)

章节来源
- [src/lib/db.ts: 443-498:443-498](file://src/lib/db.ts#L443-L498)
- [src/app/api/mcp/route.ts: 6-31:6-31](file://src/app/api/mcp/route.ts#L6-L31)
- [src/app/api/mcp/[id]/route.ts: 4-43](file://src/app/api/mcp/[id]/route.ts#L4-L43)
- [src/app/api/mcp/[id]/test/route.ts: 8-37](file://src/app/api/mcp/[id]/test/route.ts#L8-L37)
- [src/hooks/use-mcp-servers.ts: 33-79:33-79](file://src/hooks/use-mcp-servers.ts#L33-L79)
- [src/components/manage/mcp-editor.tsx: 93-142:93-142](file://src/components/manage/mcp-editor.tsx#L93-L142)
- [src/components/manage/mcp-panel.tsx: 25-145:25-145](file://src/components/manage/mcp-panel.tsx#L25-L145)
- [src/lib/types.ts: 107-119:107-119](file://src/lib/types.ts#L107-L119)

### Agent加载器与生命周期
- 注册与持久化
  - 支持创建新代理，设置名称、描述、模型、权限模式、是否为主代理、父代理ID、工具配置与默认空技能列表。
  - 列表接口同时附带每个代理所关联的技能ID列表，便于前端展示与编辑。
- 配置与工具控制
  - 工具开关可通过预设或手动切换，实时更新代理的禁用工具集合。
  - 子代理（agents/*.md）支持独立指令与模型继承策略。
- 生命周期管理
  - 前端通过Hooks封装CRUD操作，支持刷新、更新技能列表与删除代理。
  - SDK侧在构建查询实例时加载工作区内的Agent文件，形成完整的上下文。

```mermaid
sequenceDiagram
participant U as "用户"
participant AE as "Agent编辑器<br/>agent-editor.tsx"
participant HA as "useAgents<br/>use-agents.ts"
participant API as "Next.js API<br/>/api/agents"
participant DB as "数据库<br/>db.ts"
U->>AE : 修改工具/模型/指令
AE->>HA : 触发保存/更新
HA->>API : POST /api/agents 或 PATCH /api/agents/ : id
API->>DB : 写入代理记录
DB-->>API : 返回最新代理
API-->>HA : 返回结果
HA-->>AE : 更新状态
```

图表来源
- [src/components/manage/agent-editor.tsx:209-293](file://src/components/manage/agent-editor.tsx#L209-L293)
- [src/hooks/use-agents.ts:47-101](file://src/hooks/use-agents.ts#L47-101)
- [src/app/api/agents/route.ts: 5-41:5-41](file://src/app/api/agents/route.ts#L5-L41)
- [src/lib/db.ts: 63-87:63-87](file://src/lib/db.ts#L63-L87)

章节来源
- [src/app/api/agents/route.ts: 5-41:5-41](file://src/app/api/agents/route.ts#L5-L41)
- [src/hooks/use-agents.ts: 24-45:24-45](file://src/hooks/use-agents.ts#L24-L45)
- [src/components/manage/agent-editor.tsx: 14-L30:14-30](file://src/components/manage/agent-editor.tsx#L14-L30)
- [src/components/manage/agent-editor.tsx: 209-L293:209-293](file://src/components/manage/agent-editor.tsx#L209-L293)
- [src/lib/types.ts: 89-105:89-105](file://src/lib/types.ts#L89-L105)

### 系统提示词定制与管理
- 模板与来源
  - 桌面与IM场景分别使用不同的基础提示词，但都会加载工作区上下文（规则、记忆、身份、用户等）。
  - 提供构建函数用于拼接环境变量与工作区信息，确保一致性。
- 动态生成
  - 根据当前工作区ID与IM标志位动态选择提示词变体，保证跨平台体验一致。
- 文件模板参考
  - 初始化模板包含项目规则、语言偏好、边界约束等，作为系统提示词的重要输入来源之一。

```mermaid
flowchart TD
Start(["开始：构建系统提示词"]) --> Mode{"IM场景？"}
Mode --> |是| BaseIM["使用IM基础提示词"]
Mode --> |否| BaseDesk["使用桌面基础提示词"]
BaseIM --> Ctx["加载工作区上下文<br/>规则/记忆/身份/用户"]
BaseDesk --> Ctx
Ctx --> Env["拼接环境变量与路径"]
Env --> Merge["合并为最终提示词"]
Merge --> End(["结束"])
```

图表来源
- [src/lib/sdk/client.ts: 382-L387:382-387](file://src/lib/sdk/client.ts#L382-L387)
- [src/lib/sdk/client.ts: 378-L407:378-407](file://src/lib/sdk/client.ts#L378-L407)
- [templates/init/CLAUDE.md:1-82](file://templates/init/CLAUDE.md#L1-L82)

章节来源
- [src/lib/sdk/client.ts: 378-L407:378-407](file://src/lib/sdk/client.ts#L378-L407)
- [templates/init/CLAUDE.md: 1-L82:1-82](file://templates/init/CLAUDE.md#L1-L82)

### MCP服务器到Agent集成的完整流程
- 步骤概览
  1) 在MCP面板中新增或编辑服务器，填写协议与配置。
  2) 使用“测试连接”验证可达性，状态回写数据库。
  3) SDK启动时加载启用的MCP服务器，合并浏览器MCP与额外扩展。
  4) 构建查询实例，将Agent指令、系统提示词与MCP工具注入到运行时。
  5) 执行对话或任务，SDK通过MCP与外部工具交互。
- 关键接口与职责
  - MCP加载器：将数据库中的启用服务器转换为SDK可识别的配置对象。
  - SDK客户端：统一创建查询实例，注入Agent、MCP与系统提示词。
  - 前端编辑器：提供直观的表单与JSON编辑模式，支持一键测试。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant UI as "MCP编辑器"
participant API as "Next.js API"
participant DB as "数据库"
participant Loader as "MCP加载器"
participant SDK as "SDK客户端"
Dev->>UI : 新增/编辑MCP服务器
UI->>API : 保存配置
API->>DB : 写入记录
UI->>API : 测试连接
API->>DB : 更新状态
SDK->>Loader : 读取启用的MCP服务器
Loader-->>SDK : 返回SDK配置对象
SDK-->>Dev : 可用的MCP工具与Agent上下文
```

图表来源
- [src/components/manage/mcp-editor.tsx:112-142](file://src/components/manage/mcp-editor.tsx#L112-L142)
- [src/app/api/mcp/route.ts:12-31](file://src/app/api/mcp/route.ts#L12-L31)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L8-L37)
- [src/lib/sdk/mcp-loader.ts:31-41](file://src/lib/sdk/mcp-loader.ts#L31-L41)
- [src/lib/sdk/client.ts:394-404](file://src/lib/sdk/client.ts#L394-L404)

章节来源
- [src/lib/sdk/mcp-loader.ts: 31-L41:31-41](file://src/lib/sdk/mcp-loader.ts#L31-L41)
- [src/lib/sdk/client.ts: 394-L404:394-404](file://src/lib/sdk/client.ts#L394-L404)
- [src/components/manage/mcp-editor.tsx: 112-L142:112-142](file://src/components/manage/mcp-editor.tsx#L112-L142)

## 依赖关系分析
- 组件耦合
  - 前端Hooks与API路由强耦合，负责数据获取与变更；数据库承担持久化职责。
  - SDK客户端依赖数据库（MCP与Agent配置）与类型系统（统一数据契约）。
- 外部依赖
  - Claude Agent SDK：提供查询实例、工具与上下文管理能力。
  - better-sqlite3：高性能SQLite驱动，WAL模式提升并发读取性能。
  - Node子进程与文件系统：用于命令查找、文件读写与CLI交互。
- 潜在循环依赖
  - 当前结构清晰，API路由仅做数据存取，不直接调用SDK，避免循环依赖风险。

```mermaid
graph LR
UI["前端组件"] --> Hooks["Hooks"]
Hooks --> API["Next.js API"]
API --> DB["SQLite数据库"]
SDK["SDK客户端"] --> DB
SDK --> Types["类型定义"]
DB --> Types
```

图表来源
- [src/hooks/use-mcp-servers.ts:1-80](file://src/hooks/use-mcp-servers.ts#L1-80)
- [src/hooks/use-agents.ts:1-103](file://src/hooks/use-agents.ts#L1-103)
- [src/app/api/mcp/route.ts:1-32](file://src/app/api/mcp/route.ts#L1-32)
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-42)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-437)
- [src/lib/sdk/client.ts:1-20](file://src/lib/sdk/client.ts#L1-L20)
- [src/lib/types.ts:1-221](file://src/lib/types.ts#L1-L221)

章节来源
- [src/lib/db.ts: 18-437:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/sdk/client.ts: 1-L20:1-20](file://src/lib/sdk/client.ts#L1-L20)
- [src/lib/types.ts: 1-L221:1-221](file://src/lib/types.ts#L1-L221)

## 性能考量
- 数据库优化
  - WAL模式：提升并发读取性能，适合频繁读取与少量写入的场景。
  - 索引：消息表按会话与时间建立索引，加速历史检索。
- MCP测试策略
  - 启动时仅进行快速检测（stdio命令存在性），HTTP/SSE测试在API层异步执行，避免阻塞启动。
- SDK查询实例
  - 按需加载：IM场景跳过Agent加载与MCP服务器加载，减少子进程启动开销。
  - 环境变量：统一构建，避免重复解析与拼接。
- 前端交互
  - Hooks缓存与懒加载：首次渲染失败静默忽略，待服务就绪后重试，提升用户体验。

## 故障排查指南
- MCP连接失败
  - 检查协议与配置：stdio命令是否存在、参数与环境变量格式是否正确；HTTP/SSE URL与Headers是否有效。
  - 使用“测试连接”按钮查看具体错误信息，必要时在终端手动验证命令或URL可达性。
  - 查看数据库状态字段，确认是否被标记为error。
- Agent无法加载
  - 确认代理文件位于工作区agents目录且命名规范，检查工具禁用列表与模型继承设置。
  - 通过API路由查看代理列表与关联技能ID，定位配置问题。
- 系统提示词异常
  - 检查工作区上下文文件（规则、记忆、身份、用户）是否完整，确认IM/桌面场景提示词选择逻辑。
- 数据库迁移问题
  - 若出现表结构不一致，确认已执行最新迁移脚本；必要时备份数据库后重新初始化。

章节来源
- [src/lib/mcp-test.ts: 9-L50:9-50](file://src/lib/mcp-test.ts#L9-L50)
- [src/app/api/mcp/[id]/test/route.ts: 8-L37](file://src/app/api/mcp/[id]/test/route.ts#L8-L37)
- [src/lib/db.ts: 226-437:226-437](file://src/lib/db.ts#L226-L437)

## 结论
Forge为插件开发提供了完善的基础设施：自动化的MCP服务器发现与测试、灵活的Agent配置与生命周期管理、可扩展的系统提示词体系，以及清晰的前后端协作模式。遵循本文档的流程与最佳实践，开发者可以高效地创建、测试与集成各类MCP工具与Agent，构建强大的本地AI工作站。

## 附录
- 快速开始
  - 安装并登录Claude Code CLI，启动Forge，打开项目工作区，即可通过“/init”引导生成系统提示词模板。
- 版本与兼容性
  - 数据库具备多轮迁移能力，兼容旧版本schema；若遇到异常，优先检查迁移日志与表结构。
- 安全建议
  - 严格控制MCP服务器的命令与环境变量，避免执行高危命令。
  - IM桥接场景下，注意白名单与触发模式配置，防止未授权访问。
- 错误处理策略
  - 前端Hooks对初次加载失败进行静默处理，API层对无效配置返回明确错误码，数据库层对异常进行降级与回滚。