@xubill/xx-cli 1.0.6 → 2.0.1

package/AGENTS.md

@@ -0,0 +1,177 @@
+# AGENTS.md
+
+本文档描述 xx-cli 项目中各个核心模块/代理的职责和交互关系。
+
+## 项目概述
+
+xx-cli 是一个基于 Node.js 的命令行工具集，提供丰富的开发辅助功能。采用插件化架构，支持自定义插件开发和动态命令加载。
+
+## 核心模块
+
+### 1. Core (核心管理器)
+
+**文件位置**: `lib/core/index.js`
+
+**职责**:
+- 初始化 CLI 系统环境
+- 加载和管理插件（内置插件 + 用户插件）
+- 注册命令到 Commander.js 框架
+- 实现命令自动建议功能（当用户输入错误命令时提供相似命令建议）
+- 管理全局钩子系统
+
+**关键方法**:
+- `init()`: 初始化核心功能
+- `loadPlugins()`: 扫描并加载插件目录
+- `loadPlugin(pluginFile)`: 加载单个插件，支持缓存
+- `registerCommands(program)`: 注册所有命令
+- `registerNewFormatPlugin()`: 注册新格式插件
+- `registerCommandSuggestions()`: 注册命令自动建议
+- `collectAllCommands()`: 收集所有可用命令
+- `getCommandSuggestions()`: 获取命令建议
+- `registerHook()` / `triggerHook()`: 钩子系统
+
+### 2. BasePlugin (插件基类)
+
+**文件位置**: `lib/core/base-plugin.js`
+
+**职责**:
+- 提供插件标准化接口
+- 实现通用功能（加载状态、进度条、错误处理等）
+- 提供配置管理和验证能力
+- 实现钩子系统
+
+**关键方法**:
+- `registerCommands(program)`: 注册命令（抽象方法，子类必须实现）
+- `init()`: 初始化插件
+- `startLoading()` / `stopLoading()`: 加载状态管理
+- `startProgressBar()` / `updateProgressBar()` / `stopProgressBar()`: 进度条管理
+- `showSuccess()` / `showWarning()` / `showError()` / `showInfo()`: 消息展示
+- `loadConfig()` / `saveConfig()` / `validateConfig()`: 配置管理
+- `handleError()`:  `executeAsync()`: 异步操作封装错误处理
+-
+- `registerHook()` / `triggerHook()`: 钩子系统
+- `copyToClipboard()`: 剪贴板操作
+
+### 3. PluginsHelper (插件辅助工具)
+
+**文件位置**: `lib/utils/plugins-helper.js`
+
+**职责**:
+- 为新格式插件（非类继承）提供与 BasePlugin 相同的通用功能
+- 无需继承即可使用插件能力
+
+**关键方法**: 与 BasePlugin 相同（详见上方）
+
+### 4. ConfigManager (配置管理器)
+
+**文件位置**: `lib/utils/config-manager.js`
+
+**职责**:
+- 管理插件配置文件（JSON 格式）
+- 实现配置优先级：命令行 > 配置文件 > 默认配置
+- 使用 Joi 进行配置验证
+- 支持全局配置和本地配置
+
+**关键方法**:
+- `loadConfig()`: 加载配置
+- `saveConfig()`: 保存配置
+- `validateConfig()`: 验证配置
+- `getConfigPath()`: 获取配置路径
+- `mergeConfig()`: 合并配置
+
+### 5. PluginConfig (插件配置)
+
+**文件位置**: `lib/utils/plugin-config.js`
+
+**职责**:
+- 管理插件的启用/禁用状态
+- 提供插件配置文件路径
+
+**关键方法**:
+- `isPluginDisabled()`: 检查插件是否禁用
+- `getPluginConfigPath()`: 获取插件配置路径
+
+## 插件类型
+
+### 核心插件 (Core Plugins)
+
+位于 `lib/plugins/`
+
+| 插件名称 | 功能描述 |
+|---------|---------|
+| config-manager | 配置管理 |
+| history | 命令历史记录 |
+| plugin-manager | 插件管理 |
+
+### 功能插件 (User Plugins)
+不要修改../plugins的引入，这个是核心代码。myplugins我会复制到安装目录的，不需要你操作，你只管生成就好。
+位于 `lib/myplugins/`
+
+
+## 插件开发格式
+
+### 新格式 (推荐)
+
+使用配置对象方式，无需继承类：
+
+```javascript
+module.exports = {
+  name: 'plugin-name',
+  description: '插件描述',
+  alias: '别名',
+  options: [
+    { name: '-o, --option', description: '选项描述' }
+  ],
+  action: async (args, options, helper) => {
+    // 插件逻辑
+  }
+};
+```
+
+### 旧格式 (向后兼容)
+
+使用类继承方式：
+
+```javascript
+const BasePlugin = require('../core/base-plugin');
+
+class MyPlugin extends BasePlugin {
+  registerCommands(program) {
+    program.command('my-plugin')
+      .description('我的插件')
+      .action(() => { /* 插件逻辑 */ });
+  }
+}
+
+module.exports = MyPlugin;
+```
+
+## 交互流程
+
+```
+用户输入命令
+    ↓
+bin/cli.js 入口
+    ↓
+Commander.js 解析
+    ↓
+Core.registerCommands() 注册命令
+    ↓
+插件 action 执行
+    ↓
+PluginsHelper/BasePlugin 提供工具方法
+    ↓
+命令完成，输出结果
+```
+
+## 错误处理
+
+- **命令不存在**: 通过 `registerCommandSuggestions` 提供相似命令建议
+- **插件加载失败**: 捕获错误并跳过该插件，继续加载其他插件
+- **配置错误**: 使用 Joi 验证并给出清晰错误信息
+
+## 配置优先级
+
+```
+命令行选项 > 本地配置文件 > 全局配置文件 > 默认配置
+```

package/bin/cli.js

@@ -60,12 +60,14 @@
   // 全局错误处理
   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);
   });

package/lib/core/index.js

@@ -8,6 +8,7 @@ const path = require("path");
 const logger = require("../utils/logger");
 const pkg = require("../../package.json");
 const pluginConfig = require("../utils/plugin-config");
+const { createPluginsHelper } = require('../utils/plugins-helper');
 
 class Core {
   constructor() {
@@ -42,7 +43,7 @@ class Core {
     const userPluginsDir = path.join(
       process.env.HOME || process.env.USERPROFILE,
       ".xx-cli",
-      "plugins"
+      "plugins",
     );
 
     // 确保用户插件目录存在
@@ -64,10 +65,10 @@ class Core {
       // 将用户插件添加到插件文件列表中
       pluginFiles = [...pluginFiles, ...userPluginFiles];
     }
-
     // 只收集插件文件信息，不立即加载
     this.pluginFiles = pluginFiles;
   }
+
   /**
    * 加载单个插件
    * @param {string} pluginFile - 插件文件名
@@ -85,7 +86,7 @@ class Core {
     const userPluginsDir = path.join(
       process.env.HOME || process.env.USERPROFILE,
       ".xx-cli",
-      "plugins"
+      "plugins",
     );
 
     // 优先从内置插件目录加载
@@ -111,14 +112,14 @@ class Core {
       const coreDir = path.join(__dirname, "../core");
       pluginContent = pluginContent.replace(
         /require\('\.\.\/core\//g,
-        `require('${coreDir}/`
+        `require('${coreDir}/`,
       );
 
       // 替换 ../utils 为绝对路径
       const utilsDir = path.join(__dirname, "../utils");
       pluginContent = pluginContent.replace(
         /require\('\.\.\/utils\//g,
-        `require('${utilsDir}/`
+        `require('${utilsDir}/`,
       );
 
       // 创建一个临时模块来加载修改后的插件内容
@@ -132,8 +133,17 @@ class Core {
 
       const Plugin = tempModule.exports;
 
-      // 检查是否为类
-      if (typeof Plugin === "function" && Plugin.prototype) {
+      // 检查是否为新格式的插件对象
+      if (
+        Plugin &&
+        typeof Plugin === "object" &&
+        Plugin.name &&
+        (Plugin.action || Plugin.subcommands)
+      ) {
+        // 新格式插件对象，不需要实例化
+        this.pluginCache.set(pluginFile, Plugin);
+        return Plugin;
+      } else if (typeof Plugin === "function" && Plugin.prototype) {
         // 实例化类插件
         const pluginInstance = new Plugin();
         pluginInstance.pluginName =
@@ -144,16 +154,28 @@ class Core {
         return pluginInstance;
       } else {
         // 保持非类插件的兼容性
-
-        // 缓存插件
-        this.pluginCache.set(pluginFile, Plugin);
-        return Plugin;
+        // 对于函数式插件，也可能是新格式
+        if (
+          Plugin &&
+          typeof Plugin === "object" &&
+          Plugin.name &&
+          (Plugin.action || Plugin.subcommands)
+        ) {
+          // 新格式插件对象
+          this.pluginCache.set(pluginFile, Plugin);
+          return Plugin;
+        } else {
+          // 旧格式函数式插件
+          this.pluginCache.set(pluginFile, Plugin);
+          return Plugin;
+        }
       }
     } catch (error) {
       logger.error(`加载插件 ${pluginFile} 失败: ${error.message}`);
       return null;
     }
   }
+
   /**
    * 获取所有插件信息
    * @returns {Array} 插件信息数组
@@ -187,15 +209,29 @@ class Core {
         }
 
         const plugin = this.loadPlugin(pluginFile);
-        if (plugin && plugin.registerCommands) {
+        if (plugin) {
           try {
-            plugin.registerCommands(program);
+            // 检查是否为新格式插件
+            if (
+              plugin.name &&
+              (typeof plugin.action === "function" ||
+                (plugin.subcommands && Array.isArray(plugin.subcommands)))
+            ) {
+              this.registerNewFormatPlugin(program, plugin, pluginName);
+            } else if (plugin.registerCommands) {
+              // 旧格式插件
+              plugin.registerCommands(program);
+            }
           } catch (error) {
             // 捕获命令别名冲突等错误，确保其他插件能够正常注册
-            if (error.message && error.message.includes('cannot add alias')) {
-              console.warn(`警告: 插件 ${pluginName} 的命令别名与其他插件冲突，已跳过此插件的命令注册`);
+            if (error.message && error.message.includes("cannot add alias")) {
+              console.warn(
+                `警告: 插件 ${pluginName} 的命令别名与其他插件冲突，已跳过此插件的命令注册`,
+              );
             } else {
-              console.error(`错误: 插件 ${pluginName} 注册命令失败: ${error.message}`);
+              console.error(
+                `错误: 插件 ${pluginName} 注册命令失败: ${error.message}`,
+              );
             }
           }
         }
@@ -206,6 +242,117 @@ class Core {
     this.registerCommandSuggestions(program);
   }
 
+  /**
+   * 注册新格式插件命令
+   * @param {Object} program - Commander 实例
+   * @param {Object} plugin - 插件对象
+   * @param {string} pluginName - 插件名称
+   */
+  registerNewFormatPlugin(program, plugin, pluginName) {
+    const cmd = program.command(plugin.name);
+
+    // 设置描述
+    if (plugin.description) {
+      cmd.description(plugin.description);
+    }
+
+    // 设置别名
+    if (plugin.alias) {
+      cmd.alias(plugin.alias);
+    }
+
+    // 添加选项
+    if (plugin.options && Array.isArray(plugin.options)) {
+      plugin.options.forEach((option) => {
+        if (option.name && option.description) {
+          cmd.option(option.name, option.description);
+        }
+      });
+    }
+
+    // 如果插件定义了子命令，则注册它们
+    if (plugin.subcommands && Array.isArray(plugin.subcommands)) {
+      plugin.subcommands.forEach((subcmd) => {
+        const subCommand = cmd.command(subcmd.name);
+
+        if (subcmd.description) {
+          subCommand.description(subcmd.description);
+        }
+
+        if (subcmd.options && Array.isArray(subcmd.options)) {
+          subcmd.options.forEach((option) => {
+            if (option.name && option.description) {
+              subCommand.option(option.name, option.description);
+            }
+          });
+        }
+
+        subCommand.action(async (...args) => {
+          let commandArgs = [];
+          let options = {};
+          
+          if (args.length > 0) {
+            const lastArg = args[args.length - 1];
+            if (lastArg && typeof lastArg === 'object' && typeof lastArg.opts === 'function') {
+              options = { ...lastArg.opts() };
+              commandArgs = lastArg.args || [];
+            } else {
+              commandArgs = [...args];
+            }
+          }
+          
+          // 创建插件帮助器实例
+          const helper = createPluginsHelper(plugin.name);
+          // 调用子命令的 action 方法
+          await subcmd.action(commandArgs, options, helper);
+        });
+      });
+    }
+
+    // 设置主命令的 action
+    if (plugin.action) {
+      cmd.action(async (...args) => {
+        // Commander.js 会将参数和选项作为单独的参数传递
+        // 最后一个参数通常是 Command 对象，其中包含选项
+        let commandArgs = [];
+        let options = {};
+        
+        // 如果有参数，需要正确识别哪个是 Command 对象
+        if (args.length > 0) {
+          // 从后往前检查，找到 Command 对象
+          let commandObjIndex = -1;
+          for (let i = args.length - 1; i >= 0; i--) {
+            const arg = args[i];
+            if (
+              arg &&
+              typeof arg === "object" &&
+              typeof arg.opts === "function"
+            ) {
+              commandObjIndex = i;
+              break;
+            }
+          }
+          
+          if (commandObjIndex !== -1) {
+            // 找到了 Command 对象
+            options = { ...args[commandObjIndex].opts() };
+            // 从 Command 对象的 args 属性获取命令参数
+            const commandObj = args[commandObjIndex];
+            commandArgs = commandObj.args || [];
+          } else {
+            // 没有 Command 对象，所有参数都是命令参数
+            commandArgs = [...args];
+          }
+        }
+        
+        // 创建插件帮助器实例
+      const helper = createPluginsHelper(plugin.name);
+      // 调用插件的 action 方法
+      await plugin.action(commandArgs, options, helper);
+      });
+    }
+  }
+
   /**
    * 注册命令自动建议功能
    * @param {Object} program - Commander 实例
@@ -215,7 +362,7 @@ class Core {
     const allCommands = this.collectAllCommands(program);
 
     // 添加命令自动建议
-    program.on("command:*", (args) => {
+    program.on("command:*", async (args) => {
       const inputCommand = args[0];
       const suggestions = this.getCommandSuggestions(inputCommand, allCommands);
 
@@ -224,6 +371,37 @@ class Core {
         suggestions.forEach((suggestion) => {
           console.log(`  - ${suggestion}`);
         });
+        console.log("");
+        process.exit(1);
+      } else {
+        // 如果没有建议，也显示错误信息
+        console.log(`\n未找到命令 "${inputCommand}"。`);
+        console.log('使用 "xx help" 查看所有可用命令。');
+        
+        // 自动调用 AI 解释命令作为兜底
+        console.log('\n正在调用 AI 解释您的输入...');
+        
+        try {
+          // 动态导入 ai 插件
+          const aiPath = path.join(__dirname, '../plugins/ai.js');
+          if (fs.existsSync(aiPath)) {
+            const AIPlugin = require(aiPath);
+            if (AIPlugin.prototype && typeof AIPlugin === 'function') {
+              // 类继承格式插件
+              const pluginInstance = new AIPlugin();
+              if (pluginInstance.handleAI) {
+                await pluginInstance.handleAI(args, {});
+              }
+            } else if (AIPlugin.action) {
+              // 配置对象格式插件
+              await AIPlugin.action(args, {});
+            }
+          }
+        } catch (error) {
+          // AI 调用失败时不影响主流程
+          console.log('AI 解释失败:', error.message);
+        }
+        
         console.log("");
         process.exit(1);
       }
@@ -241,14 +419,12 @@ class Core {
     // 收集核心命令
     if (program.commands) {
       program.commands.forEach((command) => {
+        // 直接使用 _name 获取命令名称
+        const commandName = command._name;
+        
         // 添加命令名称
-        if (command._name && command._name !== "*") {
-          commands.push(command._name);
-        }
-
-        // 添加命令别名
-        if (command._alias) {
-          commands.push(command._alias);
+        if (commandName && commandName !== "*") {
+          commands.push(commandName);
         }
       });
     }
@@ -265,7 +441,11 @@ class Core {
   getCommandSuggestions(input, commands) {
     return commands
       .filter((command) => {
-        return command.startsWith(input.toLowerCase());
+        // 确保 command 是字符串类型
+        if (typeof command !== 'string') {
+          return false;
+        }
+        return command.toLowerCase().startsWith(input.toLowerCase());
       })
       .slice(0, 5); // 最多返回5个建议
   }
@@ -322,7 +502,7 @@ class Core {
           } catch (error) {
             console.error(
               `执行插件 ${pluginName} 的钩子 ${event} 时出错:`,
-              error.message
+              error.message,
             );
           }
         }