@xubill/xx-cli 2.0.0 → 2.0.1

package/plugin-development-new.md

@@ -0,0 +1,565 @@
+# 新格式插件开发教程
+
+本教程将详细介绍如何在 xx-cli 中使用新格式（配置对象格式）创建、开发和部署插件，这是推荐的插件开发方式。
+
+## 目录
+
+- [新格式插件开发教程](#新格式插件开发教程)
+  - [目录](#目录)
+  - [创建插件](#创建插件)
+    - [使用 plugin create 命令](#使用-plugin-create-命令)
+    - [手动创建插件](#手动创建插件)
+  - [插件结构](#插件结构)
+  - [命令注册](#命令注册)
+  - [命令选项](#命令选项)
+    - [常用选项类型](#常用选项类型)
+    - [选项示例](#选项示例)
+  - [插件配置](#插件配置)
+    - [配置文件结构](#配置文件结构)
+    - [读取配置](#读取配置)
+    - [写入配置](#写入配置)
+  - [插件工具](#插件工具)
+    - [导入 plugins-helper](#导入-plugins-helper)
+    - [核心功能](#核心功能)
+    - [使用示例](#使用示例)
+  - [插件生命周期](#插件生命周期)
+  - [测试插件](#测试插件)
+    - [本地测试](#本地测试)
+    - [命令测试](#命令测试)
+  - [部署插件](#部署插件)
+    - [发布到插件目录](#发布到插件目录)
+    - [分享插件](#分享插件)
+    - [从外部添加插件](#从外部添加插件)
+  - [最佳实践](#最佳实践)
+    - [命名规范](#命名规范)
+    - [代码组织](#代码组织)
+    - [错误处理](#错误处理)
+    - [用户体验](#用户体验)
+
+## 创建插件
+
+### 使用 plugin create 命令
+
+xx-cli 提供了 `plugin create` 命令，可以快速生成插件模板。这是推荐的创建插件的方式。
+
+#### 基本用法
+
+```bash
+# 创建插件到插件目录
+xx plugin create <plugin-name>
+
+# 或者使用别名
+xx p create <plugin-name>
+
+# 或者使用更短的别名
+xx p cr <plugin-name>
+```
+
+#### 示例
+
+```bash
+# 创建一个名为 `hello-world` 的插件
+xx plugin create hello-world
+
+# 输出：
+# 创建插件模板...
+# 插件模板已成功创建到：/Users/xub/.xx-cli/plugins/hello-world.js
+# 提示：请编辑插件文件，实现具体功能
+# 测试方法：运行 "node bin/cli.js <插件命令>"
+# 已自动打开 vscode 编辑插件文件
+```
+
+### 手动创建插件
+
+如果需要更灵活地控制插件结构，也可以手动创建插件文件。
+
+1. 在 `lib/plugins` 目录下创建一个新的 JavaScript 文件，例如 `my-plugin.js`
+2. 实现插件类，包含必要的方法
+
+## 插件结构
+
+新格式使用配置对象定义插件，结合了配置对象的简洁性和类结构的模块化优势，是推荐的插件开发方式。
+
+使用 `plugin create` 命令生成的默认插件模板包含以下结构：
+
+```javascript
+/**
+ * hello-world 插件
+ * 用于实现 hello-world 相关功能
+ * 
+ * 命令说明：
+ * - helloWorld [options]：hello-world 相关功能
+ *   - 示例：helloWorld
+ * 
+ * 功能说明：
+ * - 实现 hello-world 相关功能
+ * 
+ * 用户体验：
+ * - 使用标准化的用户提示
+ * - 提供清晰的错误提示
+ * - 支持命令行参数
+ */
+
+/**
+ * hello-world 插件类
+ * 实现 hello-world 相关核心功能
+ */
+class HelloWorldPlugin {
+  constructor() {
+    this.pluginName = 'hello-world';
+  }
+
+  /**
+   * 执行 hello-world 命令
+   * @param {Array} args - 命令参数
+   * @param {Object} options - 命令选项
+   * @param {Object} helper - 插件帮助器
+   */
+  async execute(args, options, helper) {
+    helper.showInfo('hello-world 命令执行成功！');
+    if (options && options.verbose) {
+      helper.showInfo('详细信息:');
+      helper.showInfo('- 命令名称: helloWorld');
+      helper.showInfo('- 执行时间: ' + new Date().toLocaleString());
+    }
+  }
+}
+
+// 创建插件实例
+const pluginInstance = new HelloWorldPlugin();
+
+module.exports = {
+  name: "helloWorld",
+  alias: "h",
+  description: "hello-world 相关功能",
+  options: [
+    {
+      name: "-v, --verbose",
+      description: "显示详细信息",
+    },
+    {
+      name: "-h, --help",
+      description: "显示帮助信息",
+    },
+  ],
+  action: async (args, options, helper) => {
+    await pluginInstance.execute(args, options, helper);
+  },
+};
+```
+
+## 命令注册
+
+对于新格式的插件，命令注册通过配置对象的 `options` 和 `action` 属性实现：
+
+```javascript
+module.exports = {
+  name: 'helloWorld',
+  alias: 'hw',
+  description: 'hello-world 相关功能',
+  options: [
+    {
+      name: '-v, --verbose',
+      description: '显示详细信息'
+    },
+    {
+      name: '-n, --name <name>',
+      description: '指定名称'
+    }
+  ],
+  action: async (args, options, helper) => {
+    await pluginInstance.execute(args, options, helper);
+  }
+};
+```
+
+## 命令选项
+
+命令选项可以增强命令的灵活性，允许用户自定义命令行为。
+
+### 常用选项类型
+
+#### 1. 布尔选项
+
+不需要参数的选项，用于开关功能。
+
+```javascript
+options: [
+  {
+    name: '-v, --verbose',
+    description: '显示详细信息'
+  }
+]
+```
+
+#### 2. 值选项
+
+需要参数的选项，用于传递具体值。
+
+```javascript
+options: [
+  {
+    name: '-n, --name <name>',
+    description: '指定名称'
+  }
+]
+```
+
+#### 3. 数组选项
+
+可以接收多个值的选项。
+
+```javascript
+options: [
+  {
+    name: '-a, --array <items...>',
+    description: '指定数组参数'
+  }
+]
+```
+
+#### 4. 带默认值的选项
+
+设置选项的默认值。
+
+```javascript
+options: [
+  {
+    name: '-p, --port <port>',
+    description: '指定端口',
+    default: '3000'
+  }
+]
+```
+
+#### 5. 带验证器的选项
+
+使用验证器处理选项值。
+
+```javascript
+options: [
+  {
+    name: '-p, --port <port>',
+    description: '指定端口',
+    validator: parseInt
+  }
+]
+```
+
+### 选项示例
+
+```javascript
+module.exports = {
+  name: 'example',
+  description: '示例命令',
+  options: [
+    {
+      name: '-v, --verbose',
+      description: '显示详细信息'
+    },
+    {
+      name: '-n, --name <name>',
+      description: '指定名称'
+    },
+    {
+      name: '-a, --array <items...>',
+      description: '指定数组参数'
+    },
+    {
+      name: '-p, --port <port>',
+      description: '指定端口',
+      default: '3000'
+    },
+    {
+      name: '-c, --count <count>',
+      description: '指定数量',
+      validator: parseInt
+    }
+  ],
+  action: async (args, options, helper) => {
+    helper.showInfo('示例命令执行成功！');
+    if (options.verbose) {
+      helper.showInfo('详细信息:');
+      helper.showInfo(`- 名称: ${options.name || '未指定'}`);
+      helper.showInfo(`- 数组: ${options.array ? options.array.join(', ') : '未指定'}`);
+      helper.showInfo(`- 端口: ${options.port}`);
+      helper.showInfo(`- 数量: ${options.count || '未指定'}`);
+    }
+  }
+};
+```
+
+## 插件配置
+
+插件可以使用配置文件来存储和管理配置信息，例如默认值、用户偏好设置等。
+
+### 配置文件结构
+
+配置文件通常存储在用户主目录的 `.xx-cli` 文件夹中，例如：
+
+```
+~/.xx-cli/
+  └── hello-world/
+      └── config.json
+```
+
+### 读取配置
+
+```javascript
+const fs = require('fs-extra');
+const path = require('path');
+
+// 获取用户主目录
+const homeDir = process.env.HOME || process.env.USERPROFILE;
+const xxDir = path.join(homeDir, '.xx-cli');
+const pluginConfigDir = path.join(xxDir, 'hello-world');
+const configFile = path.join(pluginConfigDir, 'config.json');
+
+// 读取配置
+let config = {};
+if (fs.existsSync(configFile)) {
+  config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+}
+```
+
+### 写入配置
+
+```javascript
+const fs = require('fs-extra');
+const path = require('path');
+
+// 获取用户主目录
+const homeDir = process.env.HOME || process.env.USERPROFILE;
+const xxDir = path.join(homeDir, '.xx-cli');
+const pluginConfigDir = path.join(xxDir, 'hello-world');
+const configFile = path.join(pluginConfigDir, 'config.json');
+
+// 确保配置目录存在
+fs.ensureDirSync(pluginConfigDir);
+
+// 写入配置
+fs.writeFileSync(configFile, JSON.stringify(config, null, 2));
+```
+
+## 插件工具
+
+对于新格式的插件，使用 `plugins-helper` 提供的功能来替代 `BasePlugin` 类的方法：
+
+### 导入 plugins-helper
+
+```javascript
+const { createPluginsHelper } = require('../utils/plugins-helper');
+```
+
+### 核心功能
+
+`plugins-helper` 提供了以下核心功能：
+
+#### 1. 用户界面
+
+- **`helper.showInfo(text)`**：显示信息
+- **`helper.showSuccess(text)`**：显示成功信息
+- **`helper.showWarning(text)`**：显示警告信息
+- **`helper.showError(text)`**：显示错误信息
+- **`helper.startLoading(text)`**：显示加载状态
+- **`helper.stopLoading(text)`**：停止加载状态
+
+#### 2. 配置管理
+
+可以使用 `fs-extra` 和 `path` 模块来实现配置管理：
+
+```javascript
+const fs = require('fs-extra');
+const path = require('path');
+
+// 确保配置目录存在
+function ensureConfigDir(pluginName) {
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  const xxDir = path.join(homeDir, '.xx-cli');
+  const pluginConfigDir = path.join(xxDir, pluginName);
+  fs.ensureDirSync(pluginConfigDir);
+  return pluginConfigDir;
+}
+
+// 加载配置
+function loadConfig(pluginName) {
+  const configDir = ensureConfigDir(pluginName);
+  const configFile = path.join(configDir, 'config.json');
+  if (fs.existsSync(configFile)) {
+    return JSON.parse(fs.readFileSync(configFile, 'utf8'));
+  }
+  return {};
+}
+
+// 保存配置
+function saveConfig(pluginName, config) {
+  const configDir = ensureConfigDir(pluginName);
+  const configFile = path.join(configDir, 'config.json');
+  fs.writeFileSync(configFile, JSON.stringify(config, null, 2));
+}
+```
+
+### 使用示例
+
+```javascript
+const { createPluginsHelper } = require('../utils/plugins-helper');
+
+class MyPlugin {
+  constructor() {
+    this.pluginName = 'my-plugin';
+  }
+
+  async execute(args, options, helper) {
+    try {
+      helper.showInfo('执行操作...');
+      
+      // 执行操作
+      setTimeout(() => {
+        helper.showSuccess('操作成功');
+        
+        if (options && options.verbose) {
+          helper.showInfo('详细信息:');
+          helper.showInfo('- 执行时间:', new Date().toLocaleString());
+        }
+      }, 1000);
+    } catch (error) {
+      helper.showError(`执行命令失败: ${error.message}`);
+    }
+  }
+}
+
+// 创建插件实例
+const pluginInstance = new MyPlugin();
+
+module.exports = {
+  name: 'myPlugin',
+  description: 'My plugin command',
+  options: [
+    {
+      name: '-v, --verbose',
+      description: '显示详细信息'
+    }
+  ],
+  action: (args, options, helper) => {
+    pluginInstance.execute(args, options, helper);
+  }
+};
+```
+
+## 插件生命周期
+
+插件的生命周期包括以下阶段：
+
+1. **初始化**：插件被加载时，系统会创建插件实例并准备执行环境
+2. **命令注册**：系统会自动解析配置对象并注册命令
+3. **命令执行**：用户运行插件命令时，系统会调用相应的 `action` 函数
+4. **清理**：命令执行完成后，系统会清理临时资源
+
+## 测试插件
+
+### 本地测试
+
+#### 1. 创建插件
+
+```bash
+xx plugin create <plugin-name>
+```
+
+#### 2. 编辑插件文件，实现具体功能
+
+#### 3. 运行插件命令
+
+```bash
+# 直接运行
+node bin/cli.js <plugin-command>
+
+# 或者使用 xx 命令（如果已全局安装）
+xx <plugin-command>
+```
+
+### 命令测试
+
+测试命令选项和参数：
+
+```bash
+# 测试布尔选项
+xx <plugin-command> --verbose
+
+# 测试值选项
+xx <plugin-command> --name John
+
+# 测试组合选项
+xx <plugin-command> --verbose --name John
+
+# 测试数组选项
+xx <plugin-command> --array item1 item2 item3
+```
+
+## 部署插件
+
+### 发布到插件目录
+
+1. 确保插件文件位于 `lib/plugins` 或 `lib/myplugins` 目录
+2. 运行 `xx plugin list` 命令，确认插件已被识别
+3. 插件会自动加载并注册到命令系统中
+
+### 分享插件
+
+如果要与他人分享插件，可以：
+
+1. 将插件文件发送给他人
+2. 他人将插件文件放入其 `lib/plugins` 或 `lib/myplugins` 目录
+3. 运行 `xx plugin list` 命令，确认插件已被识别
+
+### 从外部添加插件
+
+可以使用 `plugin add` 命令从 URL 或本地文件添加插件：
+
+```bash
+# 从 URL 添加插件
+xx plugin add https://example.com/my-plugin.js
+
+# 从本地文件添加插件
+xx plugin add /path/to/my-plugin.js
+```
+
+## 最佳实践
+
+### 命名规范
+
+1. **插件名称**：使用小写字母和连字符，例如 `hello-world`
+2. **命令名称**：使用驼峰命名法，例如 `helloWorld`
+3. **选项名称**：使用小写字母和连字符，例如 `--verbose`
+4. **变量名称**：使用驼峰命名法，例如 `pluginName`
+
+### 代码组织
+
+1. **模块化**：将不同功能的代码分离到不同的方法中
+2. **注释**：为关键代码添加注释，解释功能和实现细节
+3. **错误处理**：使用 try-catch 捕获和处理错误
+4. **日志**：使用 helper 提供的方法输出日志信息
+
+### 错误处理
+
+1. **捕获错误**：使用 try-catch 捕获可能的错误
+2. **错误提示**：使用 `helper.showError` 显示友好的错误信息
+3. **错误传递**：对于无法处理的错误，应该向上传递
+
+### 用户体验
+
+1. **加载状态**：对于耗时操作，使用 `helper.startLoading` 显示加载状态
+2. **成功提示**：操作成功后，使用 `helper.showSuccess` 显示成功信息
+3. **信息提示**：使用 `helper.showInfo` 显示有用的信息
+4. **警告提示**：使用 `helper.showWarning` 显示警告信息
+
+### 性能优化
+
+1. **异步操作**：对于耗时操作，使用异步方法
+2. **缓存**：对于重复计算的结果，使用缓存
+3. **惰性加载**：对于不常用的功能，使用惰性加载
+
+### 安全性
+
+1. **输入验证**：验证用户输入，防止恶意输入
+2. **文件操作**：安全处理文件操作，防止路径遍历攻击
+3. **网络请求**：安全处理网络请求，防止 XSS 攻击