优化插件

This commit is contained in:
小朱
2025-07-12 11:09:14 +08:00
parent e7692e6b82
commit b602181f3d
6 changed files with 964 additions and 11 deletions

View File

@@ -0,0 +1,216 @@
# GSM3 插件目录
欢迎使用 GSM3 插件系统!这个目录包含了插件开发所需的所有资源和文档。
## 📁 目录结构
```
plugins/
├── README.md # 本文件 - 插件目录说明
├── 插件开发文档.md # 完整的插件开发指南
├── 插件模板.md # 快速开始模板
└── example-plugin/ # 示例插件目录
├── plugin.json # 插件配置文件
├── index.html # 主界面文件
└── gsm3-api.js # API客户端库
```
## 🚀 快速开始
### 1. 查看示例插件
首先访问 `example-plugin` 目录,这是一个功能完整的示例插件,展示了:
- 插件基本结构
- API调用方法
- 用户界面设计
- 错误处理
- 最佳实践
### 2. 阅读开发文档
查看 [插件开发文档.md](./插件开发文档.md) 了解:
- 插件系统架构
- 配置文件格式
- 可用API列表
- 开发最佳实践
- 调试和测试方法
### 3. 使用模板快速开发
参考 [插件模板.md](./插件模板.md) 快速创建您的第一个插件:
1. 复制模板代码
2. 修改配置信息
3. 自定义界面和功能
4. 测试和调试
## 📚 文档说明
### 插件开发文档.md
这是最完整的开发指南,包含:
- **插件结构**: 文件组织和命名规范
- **配置文件**: plugin.json 详细说明
- **API参考**: 所有可用API方法和参数
- **开发实践**: 代码规范和性能优化
- **调试指南**: 常见问题和解决方案
### 插件模板.md
提供了一个最小化的插件模板,适合:
- 初学者快速上手
- 创建简单功能插件
- 作为新项目的起点
### 示例插件 (example-plugin)
这是一个功能齐全的示例,展示了:
- **系统信息API**: 获取系统状态和信息
- **实例管理API**: 创建、启动、停止、删除实例
- **文件操作API**: 读写文件、目录操作
- **终端管理API**: 终端会话和进程管理
- **用户界面**: 现代化的响应式设计
- **错误处理**: 完善的异常处理机制
## 🛠️ 开发流程
### 第一步:环境准备
1. 确保 GSM3 服务器正在运行
2.`plugins` 目录下创建新的插件文件夹
3. 从示例插件复制 `gsm3-api.js` 文件
### 第二步:创建插件
1. 创建 `plugin.json` 配置文件
2. 创建 `index.html` 主界面文件
3. 根据需要添加其他资源文件
### 第三步:开发和测试
1. 编写插件逻辑和界面
2. 使用浏览器开发者工具调试
3. 测试各种API调用和错误情况
### 第四步:优化和发布
1. 优化性能和用户体验
2. 完善错误处理和用户提示
3. 编写插件说明文档
## 🎯 API 功能概览
GSM3 插件系统提供了丰富的API接口
### 系统管理
- `getSystemStatus()` - 获取系统状态
- `getSystemInfo()` - 获取系统信息
- `healthCheck()` - 健康检查
- `getVersion()` - 获取版本信息
### 实例管理
- `getInstances()` - 获取实例列表
- `getInstance(id)` - 获取实例详情
- `createInstance(config)` - 创建新实例
- `startInstance(id)` - 启动实例
- `stopInstance(id)` - 停止实例
- `restartInstance(id)` - 重启实例
- `deleteInstance(id)` - 删除实例
### 文件操作
- `readFile(path)` - 读取文件
- `writeFile(path, content)` - 写入文件
- `listDirectory(path)` - 列出目录
- `createDirectory(path)` - 创建目录
- `deleteFile(path)` - 删除文件
- `copy(src, dest)` - 复制文件
- `move(src, dest)` - 移动文件
### 终端管理
- `getTerminals()` - 获取终端列表
- `getTerminalSessions()` - 获取终端会话
- `getTerminalStats()` - 获取终端统计
- `updateTerminalSessionName()` - 更新会话名称
## 🔧 开发工具
### 浏览器开发者工具
使用 F12 打开开发者工具:
- **Console**: 查看日志和错误信息
- **Network**: 监控API请求和响应
- **Elements**: 调试HTML和CSS
- **Sources**: 调试JavaScript代码
### 调试技巧
```javascript
// 启用详细日志
console.log('API调用参数:', params);
console.log('API响应结果:', result);
// 错误处理
try {
const result = await api.someMethod();
console.log('成功:', result);
} catch (error) {
console.error('失败:', error);
}
```
## 📋 最佳实践
### 1. 代码组织
- 保持文件结构清晰
- 使用有意义的函数和变量名
- 添加适当的注释
### 2. 错误处理
- 为所有API调用添加错误处理
- 提供用户友好的错误信息
- 记录详细的调试信息
### 3. 用户体验
- 使用响应式设计
- 提供加载状态指示
- 确保操作反馈及时
### 4. 性能优化
- 避免频繁的API调用
- 使用适当的缓存策略
- 优化大数据的显示
## 🆘 常见问题
### Q: 插件不显示怎么办?
A: 检查 `plugin.json` 格式,确保 `enabled: true` 且文件路径正确。
### Q: API调用失败
A: 检查网络连接查看浏览器控制台错误信息确认API方法名和参数正确。
### Q: 如何调试插件?
A: 使用浏览器开发者工具,查看控制台日志和网络请求。
### Q: 插件如何与主系统通信?
A: 通过 `gsm3-api.js` 提供的API方法所有通信都通过HTTP请求完成。
## 📞 技术支持
如果您在开发过程中遇到问题:
1. 查看示例插件的实现
2. 阅读开发文档的相关章节
3. 检查浏览器控制台的错误信息
4. 联系GSM3开发团队获取支持
---
**祝您开发愉快!** 🎉
如果您创建了有趣的插件,欢迎分享给社区!

View File

@@ -242,6 +242,98 @@
<p>欢迎使用 GSM3 插件系统演示</p>
</div>
<!-- 开发文档说明 -->
<div class="demo-section">
<h3>📚 插件开发文档</h3>
<p>这是一个完整的插件开发示例,展示了如何使用 GSM3 插件系统创建功能丰富的 Web 界面。</p>
<div class="cards" style="margin-bottom: 20px;">
<div class="card">
<h3>📖 开发指南</h3>
<p>查看完整的插件开发文档了解插件结构、API使用方法和最佳实践。</p>
<div style="margin-top: 15px;">
<a href="../插件开发文档.md" target="_blank" class="btn btn-info">查看开发文档</a>
</div>
</div>
<div class="card">
<h3>🔧 快速开始</h3>
<p>复制这个示例插件作为模板,修改配置文件和界面即可创建您自己的插件。</p>
<div style="margin-top: 15px;">
<button class="btn btn-success" onclick="showQuickStart()">快速开始指南</button>
</div>
</div>
<div class="card">
<h3>🎯 核心功能</h3>
<p>本示例展示了系统信息、实例管理、文件操作、终端管理等核心API的使用方法。</p>
<div style="margin-top: 15px;">
<button class="btn btn-warning" onclick="showApiOverview()">API概览</button>
</div>
</div>
</div>
<!-- 快速开始指南 -->
<div id="quickStartGuide" style="display: none; margin-top: 20px; padding: 20px; background: rgba(255,255,255,0.1); border-radius: 15px;">
<h4>🚀 快速开始指南</h4>
<ol style="line-height: 1.8; padding-left: 20px;">
<li>复制 <code>example-plugin</code> 目录并重命名为您的插件名称</li>
<li>修改 <code>plugin.json</code> 文件中的插件信息</li>
<li>编辑 <code>index.html</code> 文件,创建您的界面</li>
<li>使用 <code>gsm3-api.js</code> 调用系统API</li>
<li>重新加载插件页面查看效果</li>
</ol>
<div style="margin-top: 15px;">
<button class="btn" onclick="hideQuickStart()">关闭</button>
</div>
</div>
<!-- API概览 -->
<div id="apiOverview" style="display: none; margin-top: 20px; padding: 20px; background: rgba(255,255,255,0.1); border-radius: 15px;">
<h4>🎯 主要API功能</h4>
<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 15px; margin-top: 15px;">
<div style="background: rgba(255,255,255,0.1); padding: 15px; border-radius: 10px;">
<h5 style="color: #ffd700; margin-bottom: 10px;">系统信息</h5>
<ul style="font-size: 0.9rem; line-height: 1.6;">
<li>getSystemStatus()</li>
<li>getSystemInfo()</li>
<li>healthCheck()</li>
</ul>
</div>
<div style="background: rgba(255,255,255,0.1); padding: 15px; border-radius: 10px;">
<h5 style="color: #ffd700; margin-bottom: 10px;">实例管理</h5>
<ul style="font-size: 0.9rem; line-height: 1.6;">
<li>getInstances()</li>
<li>createInstance()</li>
<li>startInstance()</li>
<li>stopInstance()</li>
</ul>
</div>
<div style="background: rgba(255,255,255,0.1); padding: 15px; border-radius: 10px;">
<h5 style="color: #ffd700; margin-bottom: 10px;">文件操作</h5>
<ul style="font-size: 0.9rem; line-height: 1.6;">
<li>readFile()</li>
<li>writeFile()</li>
<li>listDirectory()</li>
<li>createDirectory()</li>
</ul>
</div>
<div style="background: rgba(255,255,255,0.1); padding: 15px; border-radius: 10px;">
<h5 style="color: #ffd700; margin-bottom: 10px;">终端管理</h5>
<ul style="font-size: 0.9rem; line-height: 1.6;">
<li>getTerminals()</li>
<li>getTerminalStats()</li>
<li>getTerminalSessions()</li>
<li>updateTerminalSessionName()</li>
</ul>
</div>
</div>
<div style="margin-top: 15px;">
<button class="btn" onclick="hideApiOverview()">关闭</button>
</div>
</div>
</div>
<div class="cards">
<div class="card">
<h3>🚀 插件功能</h3>
@@ -1362,10 +1454,40 @@
}
}
// 显示快速开始指南
function showQuickStart() {
const guide = document.getElementById('quickStartGuide')
const overview = document.getElementById('apiOverview')
guide.style.display = 'block'
overview.style.display = 'none'
}
// 隐藏快速开始指南
function hideQuickStart() {
const guide = document.getElementById('quickStartGuide')
guide.style.display = 'none'
}
// 显示API概览
function showApiOverview() {
const guide = document.getElementById('quickStartGuide')
const overview = document.getElementById('apiOverview')
overview.style.display = 'block'
guide.style.display = 'none'
}
// 隐藏API概览
function hideApiOverview() {
const overview = document.getElementById('apiOverview')
overview.style.display = 'none'
}
// 控制台欢迎信息
console.log('%c🧩 GSM3 插件系统', 'color: #667eea; font-size: 20px; font-weight: bold;')
console.log('%c欢迎使用示例插件', 'color: #764ba2; font-size: 14px;')
console.log('插件开发文档: https://github.com/your-repo/gsm3-docs')
console.log('插件开发文档: 查看 ../插件开发文档.md')
console.log('API使用示例: 点击页面上的按钮体验各种功能')
console.log('快速开始: 复制此插件目录作为模板开始开发')
// 等待GSM3 API加载完成后进行健康检查
window.addEventListener('load', async () => {

View File

@@ -1,12 +1,15 @@
{
"name": "example-plugin",
"displayName": "示例插件",
"description": "这是一个演示插件功能的示例插件展示了如何创建自定义的Web界面。",
"description": "这是一个演示插件功能的示例插件展示了如何创建自定义的Web界面。包含完整的API使用示例和开发文档。",
"version": "1.0.0",
"author": "GSM3团队",
"enabled": true,
"hasWebInterface": true,
"entryPoint": "index.html",
"icon": "puzzle",
"category": "工具"
"category": "工具",
"documentation": "../插件开发文档.md",
"template": "../插件模板.md",
"keywords": ["示例", "开发", "API", "模板", "文档"]
}

View File

@@ -0,0 +1,297 @@
# 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开发团队或查看项目文档。

View File

@@ -0,0 +1,259 @@
# GSM3 插件模板
这是一个简化的插件模板,帮助您快速开始插件开发。
## 基础模板结构
```
my-plugin/
├── plugin.json # 插件配置文件
├── index.html # 主界面文件
└── gsm3-api.js # API客户端库从示例插件复制
```
## 1. 创建 plugin.json
```json
{
"name": "my-plugin",
"displayName": "我的插件",
"description": "这是我的第一个GSM3插件",
"version": "1.0.0",
"author": "您的名字",
"enabled": true,
"hasWebInterface": true,
"entryPoint": "index.html",
"icon": "cog",
"category": "工具"
}
```
## 2. 创建 index.html
```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>我的插件 - GSM3</title>
<script src="gsm3-api.js"></script>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
min-height: 100vh;
padding: 20px;
margin: 0;
}
.container {
max-width: 800px;
margin: 0 auto;
}
.header {
text-align: center;
margin-bottom: 40px;
}
.header h1 {
font-size: 2.5rem;
margin-bottom: 10px;
color: #ffd700;
}
.card {
background: rgba(255, 255, 255, 0.1);
backdrop-filter: blur(10px);
border-radius: 15px;
padding: 30px;
margin-bottom: 20px;
border: 1px solid rgba(255, 255, 255, 0.2);
}
.btn {
padding: 12px 24px;
border: none;
border-radius: 25px;
background: linear-gradient(45deg, #667eea, #764ba2);
color: white;
font-weight: 600;
cursor: pointer;
transition: all 0.3s ease;
margin: 5px;
}
.btn:hover {
transform: translateY(-2px);
box-shadow: 0 10px 20px rgba(0, 0, 0, 0.2);
}
.result {
background: rgba(0, 0, 0, 0.2);
padding: 15px;
border-radius: 10px;
margin-top: 15px;
font-family: 'Courier New', monospace;
white-space: pre-wrap;
max-height: 300px;
overflow-y: auto;
}
</style>
</head>
<body>
<div class="container">
<div class="header">
<h1>🔧 我的插件</h1>
<p>这是我的第一个GSM3插件</p>
</div>
<div class="card">
<h3>功能演示</h3>
<p>点击下面的按钮测试插件功能:</p>
<button class="btn" onclick="testSystemInfo()">获取系统信息</button>
<button class="btn" onclick="testInstances()">获取实例列表</button>
<button class="btn" onclick="testHealthCheck()">健康检查</button>
<div id="result" class="result">
点击按钮查看结果...
</div>
</div>
<div class="card">
<h3>开发说明</h3>
<p>这是一个基础的插件模板,您可以:</p>
<ul>
<li>修改界面样式和布局</li>
<li>添加更多功能按钮</li>
<li>调用更多GSM3 API</li>
<li>集成第三方服务</li>
</ul>
</div>
</div>
<script>
// 初始化API
const api = new GSM3API();
// 显示结果
function showResult(title, data) {
const resultDiv = document.getElementById('result');
resultDiv.textContent = `${title}:\n${JSON.stringify(data, null, 2)}`;
}
// 显示错误
function showError(title, error) {
const resultDiv = document.getElementById('result');
resultDiv.textContent = `${title} 失败:\n${error.message}`;
}
// 测试系统信息
async function testSystemInfo() {
try {
await api.initialize();
const info = await api.getSystemInfo();
showResult('系统信息', info);
} catch (error) {
showError('获取系统信息', error);
}
}
// 测试实例列表
async function testInstances() {
try {
await api.initialize();
const instances = await api.getInstances();
showResult('实例列表', instances);
} catch (error) {
showError('获取实例列表', error);
}
}
// 测试健康检查
async function testHealthCheck() {
try {
await api.initialize();
const health = await api.healthCheck();
showResult('健康检查', health);
} catch (error) {
showError('健康检查', error);
}
}
// 插件加载完成
console.log('我的插件已加载');
// 等待API准备就绪
api.onReady(() => {
console.log('GSM3 API已准备就绪');
showResult('插件状态', { status: 'ready', message: 'API已初始化' });
});
</script>
</body>
</html>
```
## 3. 复制API文件
从示例插件目录复制 `gsm3-api.js` 文件到您的插件目录。
## 4. 测试插件
1. 将插件目录放置在 `server/data/plugins/`
2. 重新加载GSM3面板
3. 在插件列表中找到您的插件
4. 点击进入插件页面
## 5. 自定义开发
### 修改样式
`<style>` 标签中修改CSS样式自定义插件外观。
### 添加功能
在JavaScript部分添加新的函数调用GSM3 API实现更多功能。
### 常用API示例
```javascript
// 文件操作
api.readFile('/path/to/file')
api.writeFile('/path/to/file', 'content')
api.listDirectory('/path/to/dir')
// 实例管理
api.createInstance({ name: '实例名', ... })
api.startInstance('instance-id')
api.stopInstance('instance-id')
// 终端操作
api.getTerminals()
api.getTerminalSessions()
```
## 6. 发布插件
完成开发后,您可以:
1. 打包插件目录
2. 分享给其他用户
3. 提交到插件市场(如果有)
## 常见问题
**Q: 插件不显示怎么办?**
A: 检查 `plugin.json` 格式是否正确,`enabled` 是否为 `true`
**Q: API调用失败怎么办**
A: 检查浏览器控制台错误信息,确保 `gsm3-api.js` 正确加载。
**Q: 如何调试插件?**
A: 使用浏览器开发者工具,查看控制台日志和网络请求。
---
更多详细信息请参考 [插件开发文档.md](./插件开发文档.md)