@xubill/xx-cli 2.0.0 → 2.0.1

package/plugin-development-old.md

@@ -0,0 +1,447 @@
+# 旧格式插件开发教程
+
+本教程将详细介绍如何在 xx-cli 中使用旧格式（类结构格式）创建、开发和部署插件。旧格式插件需要继承 `BasePlugin` 类，主要用于向后兼容。
+
+## 目录
+
+- [旧格式插件开发教程](#旧格式插件开发教程)
+  - [目录](#目录)
+  - [创建插件](#创建插件)
+    - [使用 plugin create 命令](#使用-plugin-create-命令)
+    - [手动创建插件](#手动创建插件)
+  - [插件结构](#插件结构)
+  - [命令注册](#命令注册)
+    - [基本命令注册](#基本命令注册)
+    - [带选项的命令注册](#带选项的命令注册)
+  - [命令选项](#命令选项)
+    - [常用选项类型](#常用选项类型)
+    - [选项示例](#选项示例)
+  - [插件配置](#插件配置)
+    - [配置文件结构](#配置文件结构)
+    - [读取配置](#读取配置)
+    - [写入配置](#写入配置)
+  - [插件工具](#插件工具)
+    - [基础插件类路径](#基础插件类路径)
+    - [核心功能](#核心功能)
+    - [使用示例](#使用示例)
+  - [插件生命周期](#插件生命周期)
+  - [测试插件](#测试插件)
+    - [本地测试](#本地测试)
+    - [命令测试](#命令测试)
+  - [部署插件](#部署插件)
+    - [发布到插件目录](#发布到插件目录)
+    - [分享插件](#分享插件)
+    - [从外部添加插件](#从外部添加插件)
+  - [最佳实践](#最佳实践)
+    - [命名规范](#命名规范)
+    - [代码组织](#代码组织)
+    - [错误处理](#错误处理)
+    - [用户体验](#用户体验)
+
+## 创建插件
+
+### 使用 plugin create 命令
+
+xx-cli 提供了 `plugin create` 命令，可以快速生成旧格式的插件模板：
+
+```bash
+# 创建旧格式插件
+xx plugin create <plugin-name> --format old
+```
+
+### 手动创建插件
+
+如果需要更灵活地控制插件结构，也可以手动创建插件文件：
+
+1. 在 `lib/plugins` 目录下创建一个新的 JavaScript 文件，例如 `my-plugin.js`
+2. 实现插件类，继承 `BasePlugin` 类并包含必要的方法
+
+## 插件结构
+
+旧格式使用类结构定义插件，需要继承 `BasePlugin` 类：
+
+```javascript
+/**
+ * hello-world 插件
+ * 用于实现 hello-world 相关功能
+ * 
+ * 命令说明：
+ * - helloWorld [options]：hello-world 相关功能
+ *   - 示例：helloWorld
+ * 
+ * 功能说明：
+ * - 实现 hello-world 相关功能
+ * 
+ * 用户体验：
+ * - 使用标准化的用户提示
+ * - 提供清晰的错误提示
+ * - 支持命令行参数
+ */
+
+const BasePlugin = require('../core/base-plugin');
+
+class HelloWorldPlugin extends BasePlugin {
+  constructor(options = {}) {
+    super(options);
+    this.pluginName = 'hello-world';
+  }
+
+  /**
+   * 注册命令
+   * @param {Object} program - Commander.js 实例
+   */
+  registerCommands(program) {
+    program.command('helloWorld')
+      .description('hello-world 相关功能')
+      .option('-v, --verbose', '显示详细信息')
+      .option('-h, --help', '显示帮助信息')
+      .action((options) => this.helloWorldCommand(options));
+  }
+
+  /**
+   * hello-world 命令
+   * @param {Object} options - 命令选项
+   */
+  helloWorldCommand(options) {
+    console.log('hello-world 命令执行成功！');
+    if (options && options.verbose) {
+      console.log('详细信息:');
+      console.log('- 命令名称:', 'helloWorld');
+      console.log('- 执行时间:', new Date().toLocaleString());
+    }
+  }
+}
+
+module.exports = HelloWorldPlugin;
+```
+
+## 命令注册
+
+对于旧格式的插件，命令注册通过实现 `registerCommands` 方法实现：
+
+### 基本命令注册
+
+```javascript
+registerCommands(program) {
+  program.command('helloWorld')
+    .description('hello-world 相关功能')
+    .action(() => this.helloWorldCommand());
+}
+```
+
+### 带选项的命令注册
+
+```javascript
+registerCommands(program) {
+  program.command('helloWorld [alias]')
+    .alias('hw')
+    .description('hello-world 相关功能')
+    .option('-v, --verbose', '显示详细信息')
+    .option('-n, --name <name>', '指定名称')
+    .action((alias, options) => this.helloWorldCommand(alias, options));
+}
+```
+
+## 命令选项
+
+命令选项可以增强命令的灵活性，允许用户自定义命令行为。
+
+### 常用选项类型
+
+#### 1. 布尔选项
+
+不需要参数的选项，用于开关功能。
+
+```javascript
+.option('-v, --verbose', '显示详细信息')
+```
+
+#### 2. 值选项
+
+需要参数的选项，用于传递具体值。
+
+```javascript
+.option('-n, --name <name>', '指定名称')
+```
+
+#### 3. 数组选项
+
+可以接收多个值的选项。
+
+```javascript
+.option('-a, --array <items...>', '指定数组参数')
+```
+
+#### 4. 带默认值的选项
+
+设置选项的默认值。
+
+```javascript
+.option('-p, --port <port>', '指定端口', '3000')
+```
+
+#### 5. 带验证器的选项
+
+使用验证器处理选项值。
+
+```javascript
+.option('-p, --port <port>', '指定端口', parseInt)
+```
+
+### 选项示例
+
+```javascript
+registerCommands(program) {
+  program.command('example')
+    .description('示例命令')
+    .option('-v, --verbose', '显示详细信息')
+    .option('-n, --name <name>', '指定名称')
+    .option('-a, --array <items...>', '指定数组参数')
+    .option('-p, --port <port>', '指定端口', '3000')
+    .option('-c, --count <count>', '指定数量', parseInt)
+    .action((options) => this.exampleCommand(options));
+}
+
+exampleCommand(options) {
+  console.log('示例命令执行成功！');
+  if (options.verbose) {
+    console.log('详细信息:');
+    console.log(`- 名称: ${options.name || '未指定'}`);
+    console.log(`- 数组: ${options.array ? options.array.join(', ') : '未指定'}`);
+    console.log(`- 端口: ${options.port}`);
+    console.log(`- 数量: ${options.count || '未指定'}`);
+  }
+}
+```
+
+## 插件配置
+
+插件可以使用配置文件来存储和管理配置信息，例如默认值、用户偏好设置等。
+
+### 配置文件结构
+
+配置文件通常存储在用户主目录的 `.xx-cli` 文件夹中，例如：
+
+```
+~/.xx-cli/
+  └── hello-world/
+      └── config.json
+```
+
+### 读取配置
+
+```javascript
+// 使用 BasePlugin 提供的方法
+const config = this.loadConfig('config');
+```
+
+### 写入配置
+
+```javascript
+// 使用 BasePlugin 提供的方法
+this.saveConfig(config, 'config');
+```
+
+## 插件工具
+
+对于旧格式的插件，使用 `BasePlugin` 基类：
+
+### 基础插件类路径
+
+`BasePlugin` 类位于 `/Users/userxx/xx-cli/lib/core/base-plugin.js`，插件可以通过以下方式导入：
+
+```javascript
+const BasePlugin = require('../core/base-plugin');
+```
+
+### 核心功能
+
+`BasePlugin` 类提供了以下核心功能：
+
+#### 1. 命令注册
+
+- **`registerCommands(program)`**：注册命令到 Commander.js 实例，子类必须实现此方法
+
+#### 2. 插件初始化
+
+- **`init()`**：插件初始化逻辑，子类可以覆盖
+- **`getInfo()`**：获取插件信息
+
+#### 3. 用户界面
+
+- **`startLoading(text)`**：显示加载状态
+- **`stopLoading(text)`**：停止加载状态
+- **`showError(text)`**：显示错误信息
+- **`startProgressBar(text, total)`**：启动进度条
+- **`updateProgressBar(current, text)`**：更新进度条
+- **`stopProgressBar(text)`**：停止进度条
+- **`showSuccess(text)`**：显示成功信息
+- **`showWarning(text)`**：显示警告信息
+- **`showInfo(text)`**：显示信息
+
+#### 4. 配置管理
+
+- **`loadConfig(configName, cliOptions)`**：加载配置
+- **`saveConfig(config, configName, isGlobal)`**：保存配置
+
+#### 5. 错误处理
+
+- **`handleError(error, message)`**：处理错误
+
+#### 6. 异步操作
+
+- **`executeAsync(fn, loadingText, successText, errorText)`**：执行异步操作并显示加载状态
+
+#### 7. 钩子系统
+
+- **`registerHook(event, callback)`**：注册钩子
+- **`triggerHook(event, data)`**：触发钩子
+- **`hasHook(event)`**：检查是否注册了指定钩子
+
+#### 8. 剪贴板操作
+
+- **`copyToClipboard(text, successMessage)`**：复制文本到剪贴板
+
+### 使用示例
+
+```javascript
+const BasePlugin = require('../core/base-plugin');
+
+class MyPlugin extends BasePlugin {
+  constructor(options = {}) {
+    super(options);
+    this.pluginName = 'my-plugin';
+  }
+
+  registerCommands(program) {
+    program.command('mycommand')
+      .description('My plugin command')
+      .action(() => this.myCommand());
+  }
+
+  async myCommand() {
+    try {
+      await this.executeAsync(
+        async () => {
+          // 执行异步操作
+          await new Promise(resolve => setTimeout(resolve, 1000));
+          return '操作结果';
+        },
+        '执行操作...',
+        '操作成功',
+        '操作失败'
+      );
+    } catch (error) {
+      this.handleError(error, '执行命令失败');
+    }
+  }
+}
+
+module.exports = MyPlugin;
+```
+
+## 插件生命周期
+
+插件的生命周期包括以下阶段：
+
+1. **初始化**：插件被加载时，系统会创建插件实例并准备执行环境
+2. **命令注册**：调用 `registerCommands` 方法注册命令
+3. **命令执行**：用户运行插件命令时，系统会调用相应的命令方法
+4. **清理**：命令执行完成后，系统会清理临时资源
+
+## 测试插件
+
+### 本地测试
+
+#### 1. 创建插件
+
+```bash
+xx plugin create <plugin-name> --format old
+```
+
+#### 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. **日志**：使用 `BasePlugin` 提供的方法输出日志信息
+
+### 错误处理
+
+1. **捕获错误**：使用 try-catch 捕获可能的错误
+2. **错误提示**：使用 `this.showError` 显示友好的错误信息
+3. **错误传递**：对于无法处理的错误，应该向上传递
+
+### 用户体验
+
+1. **加载状态**：对于耗时操作，使用 `this.startLoading` 显示加载状态
+2. **成功提示**：操作成功后，使用 `this.showSuccess` 显示成功信息
+3. **信息提示**：使用 `this.showInfo` 显示有用的信息
+4. **警告提示**：使用 `this.showWarning` 显示警告信息