@xubill/xx-cli 2.0.4

package/README.md

@@ -0,0 +1,181 @@
+# xx-cli
+
+个人开发工具集，支持插件系统，提供常用开发工具功能。
+
+## 安装与使用
+
+```bash
+# 全局安装 xx-cli
+npm i @xubill/xx-cli -g
+
+# 添加插件
+xx p add xxxx.js
+
+# 使用命令
+xx <command> [options]
+```
+
+## 版本记录
+
+### v2.0.0
+- 支持新格式命令注册，兼容旧格式插件
+- 更新插件创建模板，采用配置对象格式并包含类结构实现
+
+### v2.0.1
+- 新增ai插件，解析自然语言为xx命令
+
+## 框架自带命令
+
+xx-cli 框架自带以下核心命令（位于 core 模块中）：
+
+### 基础命令
+
+| 命令 | 别名 | 描述 |
+|------|------|------|
+| `help` | - | 显示帮助信息 |
+| `version` | `v` | 显示版本信息 |
+| `history` | `h` | 查看命令历史记录 |
+| `ai` | - | AI 智能解释命令，将自然语言转换为 xx 命令 |
+
+### AI 插件使用说明
+
+**获取 API key**：访问 [白山智算](https://ai.baishan.com/auth/login?referralCode=9CbeQycJJP) 获取 API key
+
+**使用方法**：
+
+```bash
+# 快捷添加 API key
+xx ai add <apiKey>
+
+# 使用 AI 解释命令
+xx ai <查询内容>
+
+# 生成配置文件
+xx ai config
+```
+
+**示例**：
+```bash
+# 添加 API key
+xx ai add sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# 解释命令
+xx ai 关闭占用3000端口的进程
+
+# 命令兜底（输入不存在的命令时自动调用 AI）
+xx npm
+```
+
+### 插件管理命令
+
+| 命令 | 别名 | 描述 |
+|------|------|------|
+| `plugin list` | `p ls` | 列出所有插件 |
+| `plugin enable <plugin>` | `p en <plugin>` | 启用插件 |
+| `plugin disable <plugin>` | `p dis <plugin>` | 禁用插件 |
+| `plugin add <url>` | `p add <url>` | 添加外部自定义插件 |
+| `plugin remove <plugin>` | `p rm <plugin>` | 删除指定插件 |
+| `plugin create <name>` | `p cr <name>` | 创建指定名称的插件模板 |
+| `plugin config <plugin> [key] [value]` | `p c <plugin> [key] [value]` | 查看和设置插件配置 |
+
+### 配置管理命令
+
+| 命令 | 别名 | 描述 |
+|------|------|------|
+| `config-manager export [target]` | `conf export [target]` | 导出所有插件配置到指定目录 |
+| `config-manager import [source]` | `conf import [source]` | 从指定目录导入配置并覆盖 |
+| `config-manager list` | `conf list` | 列出所有插件的配置文件位置和状态 |
+
+## 项目结构
+
+xx-cli 项目采用模块化设计，主要包含以下核心目录：
+
+### 核心模块目录 (`/Users/xub/xx-cli/lib/core`)
+
+核心模块目录包含 xx-cli 的核心功能实现，负责初始化系统、注册命令、管理插件等。
+
+#### 文件结构
+
+```
+lib/core/
+  ├── index.js         # 核心模块，负责初始化系统、注册命令、管理插件等
+  └── base-plugin.js   # 插件基础类，提供标准化的插件接口和通用功能
+```
+
+#### 核心文件说明
+
+- **index.js**：核心模块，负责初始化系统、注册命令、管理插件等。它包含了插件加载、命令注册、钩子管理等核心功能。
+- **base-plugin.js**：插件基础类，提供标准化的插件接口和通用功能。所有插件应该继承此类以确保一致性，它提供了命令注册、配置管理、用户界面等通用功能。
+
+### 插件目录 (`/Users/xub/xx-cli/lib/plugins`)
+
+插件目录包含 xx-cli 的内置插件，这些插件提供了各种功能，如配置管理、历史记录管理、插件管理等。
+
+#### 文件结构
+
+```
+lib/plugins/
+  ├── config-manager.js   # 配置管理插件，用于管理所有插件的配置文件
+  ├── history.js          # 历史记录插件，用于查看命令历史记录
+  └── plugin-manager.js   # 插件管理插件，用于管理所有插件
+```
+
+#### 内置插件说明
+
+- **config-manager.js**：配置管理插件，用于管理所有插件的配置文件。它提供了导出、导入、列出配置等功能。
+- **history.js**：历史记录插件，用于查看命令历史记录。它提供了查看、清除、搜索历史记录等功能。
+- **plugin-manager.js**：插件管理插件，用于管理所有插件。它提供了列出、启用、禁用、添加、删除、创建插件等功能。
+- **ai.js**：AI 智能解释插件，用于解释 xx-cli 命令的含义，将自然语言转换为命令。它提供了智能解释、命令兜底等功能。
+
+## 插件开发
+
+本部分将详细介绍如何在 xx-cli 中创建、开发和部署插件。
+
+### 插件格式
+
+xx-cli 支持两种插件格式：
+
+1. **新格式（配置对象格式）**：使用配置对象定义的插件实现（推荐）
+2. **旧格式（类结构格式）**：继承自 `BasePlugin` 类的插件实现（仅用于向后兼容）
+
+### 新格式插件开发（推荐）
+
+新格式插件使用配置对象定义插件信息和命令，结合类结构实现核心功能，是推荐的插件开发方式。
+
+#### 创建新格式插件
+
+```bash
+# 创建新格式插件（默认）
+xx plugin create <plugin-name>
+
+# 或者使用别名
+xx p create <plugin-name>
+# 或者使用更短的别名
+xx p cr <plugin-name>
+```
+
+#### 新格式插件特点
+
+- **配置对象格式**：使用配置对象定义插件的基本信息和命令
+- **包含类结构实现**：核心功能通过类结构实现，提高代码模块化和可维护性
+- **自动生成命令名称**：根据插件名称自动生成驼峰命名的命令名称
+- **标准的用户提示**：使用标准化的用户提示和错误处理
+
+#### 详细文档
+
+完整的新格式插件开发指南请参考：[新格式插件开发教程](./plugin-development-new.md)
+
+### 旧格式插件开发（仅用于向后兼容）
+
+旧格式插件需要继承 `BasePlugin` 类，主要用于向后兼容已有的插件。
+
+#### 创建旧格式插件
+
+```bash
+# 创建旧格式插件
+xx plugin create <plugin-name> --format old
+```
+
+#### 详细文档
+
+完整的旧格式插件开发指南请参考：[旧格式插件开发教程](./plugin-development-old.md)

package/bin/cli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/**
+ * xx CLI 工具入口文件
+ * 全局命令：xx
+ */
+
+(async () => {
+  const { program } = require("commander");
+  // 直接导入原始核心模块
+  const core = require("../lib/core");
+  const figlet = require("figlet");
+  const chalk = require("chalk").default;
+  const updateNotifier = require("update-notifier");
+  const pkg = require("../package.json");
+
+  // // 检查版本更新
+  // const notifier = updateNotifier({
+  //   pkg,
+  //   updateCheckInterval: 1000 * 60 * 60 * 24 // 1天检查一次
+  // });
+
+  // // 显示更新通知
+  // notifier.notify();
+
+  // 初始化核心功能
+  await core.init();
+
+  // 定义 CLI 命令
+  program
+    .name("xx")
+    .version(pkg.version)
+    .description("个人开发工具集，支持插件系统");
+
+  // 监听 --help 指令,加上额外的提示
+  program.on("--help", async function () {
+    // 美化logo
+    console.log(
+      chalk.green("\r\n" +
+        figlet.textSync("xx", {
+          font: "3D-ASCII",
+          horizontalLayout: "default",
+          verticalLayout: "default",
+          whitespaceBreak: true,
+        })
+      )
+    );
+    // 前后两个空行调整格式，更舒适
+    console.log();
+    console.log("示例:");
+    console.log("  $ xx help");
+    console.log("  $ xx version");
+    console.log();
+    console.log();
+  });
+
+  // 注册核心命令
+  core.registerCommands(program);
+
+  // 全局错误处理
+  process.on('uncaughtException', (error) => {
+    console.error(chalk.red('错误:'), error.message);
+    console.error(chalk.red('错误堆栈:'), error.stack);
+    console.error(chalk.yellow('提示:'), '请检查命令参数是否正确，或使用 --help 查看帮助信息');
+    process.exit(1);
+  });
+
+  process.on('unhandledRejection', (error) => {
+    console.error(chalk.red('错误:'), error.message);
+    console.error(chalk.red('错误堆栈:'), error.stack);
+    console.error(chalk.yellow('提示:'), '请检查命令参数是否正确，或使用 --help 查看帮助信息');
+    process.exit(1);
+  });
+
+  // 记录命令历史
+  const commandLine = process.argv.slice(2).join(' ');
+  if (commandLine) {
+    const historyManager = require('../lib/utils/history-manager');
+    historyManager.addHistory(commandLine);
+  }
+
+  // 解析命令行参数
+  program.parse(process.argv);
+
+  // 注册自动补全
+  if (program.autocomplete) {
+    program.autocomplete();
+  }
+})();

package/lib/core/base-plugin.js

@@ -0,0 +1,292 @@
+/**
+ * 插件基础类
+ * 提供标准化的插件接口和通用功能
+ * 所有插件应该继承此类以确保一致性
+ */
+
+const ConfigManager = require('../utils/config-manager');
+const chalk = require('chalk').default;
+const ora = require('ora').default;;
+const clipboardy = require('clipboardy').default;
+
+class BasePlugin {
+  /**
+   * 构造函数
+   * @param {Object} options - 插件选项
+   */
+  constructor(options = {}) {
+    this.pluginName = this.constructor.name.replace('Plugin', '').toLowerCase();
+    this.homeDir = process.env.HOME || process.env.USERPROFILE;
+    this.configManager = new ConfigManager(this.pluginName, options);
+    this.spinner = null;
+    this.progressTotal = 0;
+    this.progressCurrent = 0;
+    this.hooks = {};
+  }
+
+  /**
+   * 注册命令
+   * @param {Object} program - Commander.js 实例
+   * @abstract
+   */
+  registerCommands(program) {
+    throw new Error('子类必须实现 registerCommands 方法');
+  }
+
+  /**
+   * 初始化插件
+   * @returns {Promise<void>}
+   */
+  async init() {
+    // 插件初始化逻辑，子类可以覆盖
+  }
+
+  /**
+   * 获取插件信息
+   * @returns {Object} 插件信息对象
+   */
+  getInfo() {
+    return {
+      name: this.pluginName,
+      version: '1.0.0',
+      description: '插件描述'
+    };
+  }
+
+  /**
+   * 显示加载状态
+   * @param {string} text - 加载文本
+   */
+  startLoading(text) {
+    this.spinner = ora(text).start();
+  }
+
+  /**
+   * 停止加载状态
+   * @param {string} text - 成功文本
+   */
+  stopLoading(text) {
+    if (this.spinner) {
+      this.spinner.succeed(text);
+      this.spinner = null;
+    }
+  }
+
+  /**
+   * 显示错误状态
+   * @param {string} text - 错误文本
+   */
+  showError(text) {
+    if (this.spinner) {
+      this.spinner.fail(text);
+      this.spinner = null;
+    } else {
+      console.error(chalk.red(`❌ ${text}`));
+    }
+  }
+
+  /**
+   * 启动进度条
+   * @param {string} text - 进度条文本
+   * @param {number} total - 总进度值
+   */
+  startProgressBar(text, total = 100) {
+    this.spinner = ora({
+      text,
+      spinner: 'arc',
+      color: 'cyan'
+    }).start();
+    this.progressTotal = total;
+    this.progressCurrent = 0;
+  }
+
+  /**
+   * 更新进度条
+   * @param {number} current - 当前进度值
+   * @param {string} text - 进度条文本
+   */
+  updateProgressBar(current, text) {
+    if (this.spinner && this.progressTotal > 0) {
+      this.progressCurrent = current;
+      const percentage = Math.min(Math.round((current / this.progressTotal) * 100), 100);
+      this.spinner.text = `${text || ''} ${percentage}%`;
+    }
+  }
+
+  /**
+   * 停止进度条
+   * @param {string} text - 完成文本
+   */
+  stopProgressBar(text) {
+    if (this.spinner) {
+      this.spinner.succeed(text);
+      this.spinner = null;
+      this.progressTotal = 0;
+      this.progressCurrent = 0;
+    }
+  }
+
+  /**
+   * 显示成功信息
+   * @param {string} text - 成功文本
+   */
+  showSuccess(text) {
+    console.log(chalk.green(`✅ ${text}`));
+  }
+
+  /**
+   * 显示警告信息
+   * @param {string} text - 警告文本
+   */
+  showWarning(text) {
+    console.log(chalk.yellow(`⚠️  ${text}`));
+  }
+
+  /**
+   * 显示信息
+   * @param {string} text - 信息文本
+   */
+  showInfo(text) {
+    console.log(chalk.blue(`${text}`));
+  }
+
+  /**
+   * 加载配置
+   * @param {string} configName - 配置名称
+   * @param {Object} cliOptions - 命令行选项
+   * @returns {Object} 合并后的配置对象
+   */
+  loadConfig(configName = 'config', cliOptions = {}) {
+    return this.configManager.loadConfig(configName, cliOptions);
+  }
+
+  /**
+   * 保存配置
+   * @param {Object} config - 配置对象
+   * @param {string} configName - 配置名称
+   * @param {boolean} isGlobal - 是否保存到全局配置
+   */
+  saveConfig(config, configName = 'config', isGlobal = true) {
+    this.configManager.saveConfig(config, configName, isGlobal);
+  }
+
+  /**
+   * 验证配置
+   * @param {Object} config - 配置对象
+   * @param {Object} schema - 配置 schema
+   * @returns {Object} 验证结果
+   */
+  validateConfig(config, schema) {
+    return this.configManager.validateConfig(config, schema);
+  }
+
+  /**
+   * 错误处理
+   * @param {Error} error - 错误对象
+   * @param {string} message - 错误消息
+   */
+  handleError(error, message = '操作失败') {
+    this.showError(`${message}: ${error.message}`);
+    // 可以添加错误日志记录等逻辑
+  }
+
+  /**
+   * 执行异步操作
+   * @param {Function} fn - 异步函数
+   * @param {string} loadingText - 加载文本
+   * @param {string} successText - 成功文本
+   * @param {string} errorText - 错误文本
+   * @returns {Promise<any>}
+   */
+  async executeAsync(fn, loadingText, successText, errorText) {
+    try {
+      this.startLoading(loadingText);
+      const result = await fn();
+      this.stopLoading(successText);
+      return result;
+    } catch (error) {
+      this.handleError(error, errorText);
+      throw error;
+    }
+  }
+
+  /**
+   * 注册钩子
+   * @param {string} event - 事件名称
+   * @param {Function} callback - 回调函数
+   */
+  registerHook(event, callback) {
+    if (!this.hooks) {
+      this.hooks = {};
+    }
+    
+    if (!this.hooks[event]) {
+      this.hooks[event] = [];
+    }
+    
+    this.hooks[event].push(callback);
+  }
+
+  /**
+   * 触发钩子
+   * @param {string} event - 事件名称
+   * @param {*} data - 事件数据
+   * @returns {Promise<Array>} 钩子执行结果
+   */
+  async triggerHook(event, data) {
+    if (!this.hooks || !this.hooks[event]) {
+      return [];
+    }
+    
+    const results = [];
+    for (const callback of this.hooks[event]) {
+      try {
+        const result = await callback(data);
+        results.push(result);
+      } catch (error) {
+        this.handleError(error, `执行钩子 ${event} 时出错`);
+      }
+    }
+    
+    return results;
+  }
+
+  /**
+   * 检查是否注册了指定钩子
+   * @param {string} event - 事件名称
+   * @returns {boolean} 是否注册了钩子
+   */
+  hasHook(event) {
+    return this.hooks && this.hooks[event] && this.hooks[event].length > 0;
+  }
+
+  /**
+   * 复制文本到剪贴板
+   * @param {string} text - 要复制的文本
+   * @param {string} successMessage - 成功消息
+   * @returns {Promise<boolean>} 是否复制成功
+   */
+  async copyToClipboard(text, successMessage) {
+    try {
+      // 尝试不同的 clipboardy API 调用方式
+      if (clipboardy.default && typeof clipboardy.default.write === 'function') {
+        await clipboardy.default.write(text);
+      } else if (typeof clipboardy.write === 'function') {
+        await clipboardy.write(text);
+      } else if (typeof clipboardy.writeSync === 'function') {
+        clipboardy.writeSync(text);
+      } else {
+        throw new Error('clipboardy API 不可用');
+      }
+      if (successMessage) {
+        this.showSuccess(successMessage);
+      }
+      return true;
+    } catch (error) {
+      this.showWarning(`复制到剪贴板失败: ${error.message}`);
+      return false;
+    }
+  }
+}
+
+module.exports = BasePlugin;