GameServerManager/server/data/plugins/插件开发文档.md

# GSM3 插件开发文档

## 概述

GSM3 插件系统允许开发者创建自定义的Web界面和功能扩展，通过标准化的API与GSM3核心系统进行交互。

## 插件结构

每个插件都应该包含以下文件：

```
plugin-name/
├── plugin.json          # 插件配置文件（必需）
├── index.html           # 主界面文件（可选）
├── gsm3-api.js         # API客户端库（推荐）
└── assets/             # 静态资源目录（可选）
    ├── css/
    ├── js/
    └── images/
```

## 配置文件 (plugin.json)

插件配置文件定义了插件的基本信息和行为：

```json
{
  "name": "plugin-name",              // 插件唯一标识符
  "displayName": "插件显示名称",        // 用户界面显示的名称
  "description": "插件功能描述",        // 插件功能说明
  "version": "1.0.0",                 // 插件版本号
  "author": "开发者名称",              // 插件作者
  "enabled": true,                    // 是否启用插件
  "hasWebInterface": true,            // 是否有Web界面
  "entryPoint": "index.html",         // 主入口文件
  "icon": "puzzle",                   // 图标名称
  "category": "工具"                   // 插件分类
}
```

### 配置字段说明

- **name**: 插件的唯一标识符，只能包含字母、数字、连字符
- **displayName**: 在用户界面中显示的插件名称
- **description**: 插件功能的详细描述
- **version**: 遵循语义化版本规范 (semver)
- **author**: 插件开发者信息
- **enabled**: 控制插件是否启用
- **hasWebInterface**: 是否提供Web界面
- **entryPoint**: Web界面的入口文件
- **icon**: 插件图标（支持FontAwesome图标名称）
- **category**: 插件分类，用于组织和筛选

## API 使用

### 引入API客户端

在HTML文件中引入GSM3 API客户端：

```html
<script src="gsm3-api.js"></script>
<script>
  // 初始化API客户端
  const api = new GSM3API();
  
  // 等待API准备就绪
  api.onReady(() => {
    console.log('GSM3 API 已准备就绪');
    // 在这里调用API方法
  });
</script>
```

### 可用API方法

#### 系统信息API

```javascript
// 获取系统状态
api.getSystemStatus().then(status => {
  console.log('系统状态:', status);
});

// 获取系统信息
api.getSystemInfo().then(info => {
  console.log('系统信息:', info);
});

// 健康检查
api.healthCheck().then(result => {
  console.log('健康检查:', result);
});
```

#### 实例管理API

```javascript
// 获取实例列表
api.getInstances().then(instances => {
  console.log('实例列表:', instances);
});

// 获取市场实例
api.getMarketInstances().then(marketInstances => {
  console.log('市场实例:', marketInstances);
});

// 创建实例
api.createInstance({
  name: '我的实例',
  game: 'minecraft',
  version: '1.20.1'
}).then(result => {
  console.log('创建结果:', result);
});

// 获取实例详情
api.getInstance('instance-id').then(instance => {
  console.log('实例详情:', instance);
});

// 启动实例
api.startInstance('instance-id').then(result => {
  console.log('启动结果:', result);
});

// 停止实例
api.stopInstance('instance-id').then(result => {
  console.log('停止结果:', result);
});

// 重启实例
api.restartInstance('instance-id').then(result => {
  console.log('重启结果:', result);
});

// 删除实例
api.deleteInstance('instance-id').then(result => {
  console.log('删除结果:', result);
});
```

#### 终端管理API

```javascript
// 获取终端列表
api.getTerminals().then(terminals => {
  console.log('终端列表:', terminals);
});

// 获取终端统计信息
api.getTerminalStats().then(stats => {
  console.log('终端统计:', stats);
});

// 获取终端会话
api.getTerminalSessions().then(sessions => {
  console.log('终端会话:', sessions);
});

// 获取活跃终端进程
api.getActiveTerminalProcesses().then(processes => {
  console.log('活跃进程:', processes);
});

// 更新终端会话名称
api.updateTerminalSessionName('session-id', '新名称').then(result => {
  console.log('更新结果:', result);
});
```

#### 文件操作API

```javascript
// 读取文件
api.readFile('/path/to/file.txt').then(content => {
  console.log('文件内容:', content);
});

// 写入文件
api.writeFile('/path/to/file.txt', '文件内容').then(result => {
  console.log('写入结果:', result);
});

// 列出目录
api.listDirectory('/path/to/directory').then(files => {
  console.log('目录内容:', files);
});

// 创建目录
api.createDirectory('/path/to/new/directory').then(result => {
  console.log('创建结果:', result);
});

// 删除文件
api.deleteFile('/path/to/file.txt').then(result => {
  console.log('删除结果:', result);
});

// 复制文件
api.copy('/source/path', '/destination/path').then(result => {
  console.log('复制结果:', result);
});

// 移动文件
api.move('/source/path', '/destination/path').then(result => {
  console.log('移动结果:', result);
});
```

#### 游戏管理API

```javascript
// 获取支持的游戏列表
api.getGames().then(games => {
  console.log('游戏列表:', games);
});
```

## 开发最佳实践

### 1. 错误处理

始终为API调用添加错误处理：

```javascript
api.getInstances()
  .then(instances => {
    // 处理成功响应
    console.log('获取实例成功:', instances);
  })
  .catch(error => {
    // 处理错误
    console.error('获取实例失败:', error);
    alert('操作失败: ' + error.message);
  });
```

### 2. 用户界面设计

- 使用响应式设计，确保在不同屏幕尺寸下都能正常显示
- 提供清晰的操作反馈和状态指示
- 遵循GSM3的设计风格和色彩方案

### 3. 性能优化

- 避免频繁的API调用
- 使用适当的缓存策略
- 对大量数据进行分页处理

### 4. 安全考虑

- 验证用户输入
- 避免执行不安全的操作
- 遵循最小权限原则

## 调试和测试

### 开发模式

在开发过程中，可以通过浏览器的开发者工具查看API调用和响应：

1. 打开浏览器开发者工具 (F12)
2. 切换到Network标签页
3. 执行插件操作，观察API请求和响应

### 日志记录

使用console.log记录关键信息：

```javascript
console.log('插件初始化完成');
console.log('API调用参数:', params);
console.log('API响应结果:', result);
```

## 示例插件

参考 `example-plugin` 目录中的示例代码，了解完整的插件实现。

## 常见问题

### Q: 如何处理API认证？
A: GSM3 API客户端会自动处理认证，无需手动管理token。

### Q: 插件如何与主系统通信？
A: 通过提供的API方法进行通信，所有操作都通过HTTP请求完成。

### Q: 可以访问文件系统吗？
A: 可以通过文件操作API访问指定目录下的文件，但有安全限制。

### Q: 如何更新插件？
A: 修改插件文件后，重新加载插件页面即可看到更新。

## 技术支持

如有问题，请联系GSM3开发团队或查看项目文档。