@xubill/xx-cli 2.0.0 → 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/lib/core/index.js

@@ -362,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);
 
@@ -371,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);
       }
@@ -388,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);
         }
       });
     }
@@ -412,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个建议
   }

package/lib/plugins/ai.js

@@ -0,0 +1,295 @@
+/**
+ * AI 智能解释插件
+ * 用于解释 xx-cli 命令的含义，将自然语言转换为命令
+ *
+ * 命令说明：
+ * - ai <query>：解释用户输入的自然语言，转换为对应的 xx 命令
+ *   - 示例：
+ *     - xx ai 关闭微信
+ *     - xx ai 打开浏览器
+ *     - xx ai 端口占用
+ */
+
+const axios = require('axios');
+const BasePlugin = require('../core/base-plugin');
+
+class AIPlugin extends BasePlugin {
+  constructor() {
+    super();
+    this.pluginName = 'ai';
+  }
+
+  registerCommands(program) {
+    const aiCommand = program.command('ai')
+      .description('AI 智能解释命令，将自然语言转换为 xx 命令')
+      .option('-c, --config <path>', '指定配置文件路径')
+      .arguments('[query...]')
+      .action(async (query, options) => {
+        await this.handleAI(query || [], options);
+      });
+
+    // 添加生成配置文件的子命令
+    aiCommand.command('config')
+      .description('生成 AI 插件配置文件')
+      .option('-o, --output <path>', '输出配置文件路径', '.ai-config.json')
+      .action(async (options) => {
+        await this.generateConfig(options);
+      });
+
+    // 添加快捷添加 API key 的子命令
+    aiCommand.command('add')
+      .description('快捷添加 API key')
+      .arguments('<apiKey>')
+      .action(async (apiKey) => {
+        await this.addApiKey(apiKey);
+      });
+  }
+
+  /**
+   * 快捷添加 API key
+   * @param {string} apiKey - API key
+   */
+  async addApiKey(apiKey) {
+    try {
+      this.startLoading('正在保存 API key...');
+      
+      const defaultConfig = {
+        apiUrl: 'https://api.edgefn.net/v1/chat/completions',
+        apiKey: apiKey,
+        model: 'DeepSeek-R1-0528-Qwen3-8B'
+      };
+      
+      // 保存到全局配置
+      this.saveConfig(defaultConfig, 'config', true);
+      
+      this.stopLoading('API key 保存成功');
+      this.showSuccess('API key 已保存到全局配置');
+      this.showInfo('下次使用无需指定 --config 选项');
+      
+      console.log('\n使用示例:');
+      console.log('  xx ai 关闭3000端口');
+      console.log('  xx ai 生成readme');
+    } catch (error) {
+      this.stopLoading();
+      this.showError(`保存 API key 失败: ${error.message}`);
+    }
+  }
+
+  /**
+   * 生成配置文件
+   * @param {Object} options - 命令选项
+   */
+  async generateConfig(options) {
+    const defaultConfig = {
+      apiUrl: 'https://api.edgefn.net/v1/chat/completions',
+      apiKey: '',
+      model: 'DeepSeek-R1-0528-Qwen3-8B'
+    };
+
+    const outputPath = options.output;
+
+    try {
+      this.startLoading(`正在生成配置文件到 ${outputPath}...`);
+      
+      // 写入配置文件
+      const fs = require('fs');
+      fs.writeFileSync(outputPath, JSON.stringify(defaultConfig, null, 2));
+      
+      this.stopLoading(`配置文件已生成到 ${outputPath}`);
+      this.showSuccess(`配置文件已生成，请根据需要修改其中的参数`);
+      
+      console.log('\n配置文件格式说明：');
+      console.log('  apiUrl: AI API 接口地址');
+      console.log('  apiKey: API 密钥');
+      console.log('  model: 使用的模型名称');
+    } catch (error) {
+      this.stopLoading();
+      this.showError(`生成配置文件失败: ${error.message}`);
+    }
+  }
+
+  /**
+   * 获取所有可用命令列表
+   * @returns {Promise<Array>} 命令数组
+   */
+  async getAllCommands() {
+    const core = require('../core');
+    const { Command } = require('commander');
+    const tempProgram = new Command();
+    tempProgram.name('xx').version('2.0.0');
+
+    // 注册所有命令
+    core.registerCommands(tempProgram);
+
+    // 收集命令
+    const commands = [];
+    if (tempProgram.commands) {
+      tempProgram.commands.forEach((command) => {
+        const commandName = command._name;
+        if (commandName && commandName !== '*') {
+          // 获取命令描述
+          const description = command.description() || '';
+          commands.push({ name: commandName, description });
+        }
+      });
+    }
+
+    return commands;
+  }
+
+  /**
+   * 加载配置
+   * @param {Object} options - 命令行选项
+   * @returns {Object} 配置对象
+   */
+  loadAIConfig(options) {
+    const defaultConfig = {
+      apiUrl: 'https://api.edgefn.net/v1/chat/completions',
+      apiKey: '',
+      model: 'DeepSeek-R1-0528-Qwen3-8B'
+    };
+
+    // 检查是否通过 --config 指定了配置文件
+    if (options.config) {
+      try {
+        const fs = require('fs');
+        const customConfig = JSON.parse(fs.readFileSync(options.config, 'utf8'));
+        // 保存到全局配置
+        this.saveConfig(customConfig, 'config', true);
+        this.showInfo(`配置已保存到全局，下次使用无需指定 --config 选项`);
+      } catch (error) {
+        this.showError(`读取配置文件失败: ${error.message}`);
+      }
+    }
+
+    // 加载配置文件（此时会包含全局配置）
+    const config = this.loadConfig('config', options);
+
+    const aiConfig = {
+      apiUrl: config.apiUrl || defaultConfig.apiUrl,
+      apiKey: config.apiKey || defaultConfig.apiKey,
+      model: config.model || defaultConfig.model
+    };
+
+    // 检查是否有 API key
+    if (!aiConfig.apiKey) {
+      this.showWarning('未配置 API key');
+      console.log('请访问以下链接获取 API key:');
+      console.log('https://ai.baishan.com/auth/login?referralCode=9CbeQycJJP');
+      
+      // 生成配置文件
+      const fs = require('fs');
+      const configPath = '.ai-config.json';
+      try {
+        fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
+        this.showInfo(`已生成配置文件到 ${configPath}`);
+        console.log('请在配置文件中填写您的 API key:');
+        console.log(`  $ vim ${configPath}`);
+      } catch (error) {
+        this.showError(`生成配置文件失败: ${error.message}`);
+      }
+      
+      // 尝试打开浏览器
+      try {
+        const open = require('open');
+        open('https://ai.baishan.com/auth/login?referralCode=9CbeQycJJP');
+        this.showInfo('正在打开浏览器...');
+      } catch (error) {
+        // 忽略打开浏览器的错误
+      }
+      console.log('\n快捷使用:');
+      console.log('  直接添加 API key: xx ai add <apiKey>');
+      console.log('  示例: xx ai add sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
+
+      console.log('\n完全自定义使用方法:');
+      console.log('  1. 编辑配置文件');
+      console.log('  2. 使用命令: xx ai --config .ai-config.json <查询内容>');
+      console.log('  3. 配置会自动保存，下次使用无需指定 --config 选项');
+      
+      process.exit(1);
+    }
+
+    return aiConfig;
+  }
+
+  /**
+   * 调用 AI API 解释命令
+   * @param {string} query - 用户查询
+   * @param {Array} commands - 可用命令列表
+   * @param {Object} config - AI 配置
+   * @returns {Promise<string>} AI 返回的解释
+   */
+  async callAI(query, commands, config) {
+    const commandList = commands.map(c => `  - ${c.name}: ${c.description}`).join('\n');
+
+    const prompt = `你是一个命令行工具助手。用户使用 xx-cli 工具集，你需要解释用户的意图并给出对应的 xx 命令。\n\n可用命令列表：\n${commandList}\n\n规则：\n1. 如果用户的意图可以匹配到上述命令，返回对应的 xx 命令和简要说明，命令必须以 "xx" 开头\n2. 如果无法匹配，返回 "无法匹配" 并给出最相关的命令建议，建议的命令也必须以 "xx" 开头\n3. 直接返回结果，不需要额外解释\n\n用户输入: ${query}`;
+
+    const response = await axios.post(
+      config.apiUrl,
+      {
+        model: config.model,
+        messages: [{ role: 'user', content: prompt }]
+      },
+      {
+        headers: {
+          'Authorization': `Bearer ${config.apiKey}`,
+          'Content-Type': 'application/json'
+        }
+      }
+    );
+
+    return response.data.choices[0].message.content;
+  }
+
+  /**
+   * 主处理函数
+   * @param {Array} args - 命令参数
+   * @param {Object} options - 命令选项
+   */
+  async handleAI(args, options) {
+    // 处理参数，确保 args 是数组
+    let queryArgs = args;
+    if (!Array.isArray(args)) {
+      // 如果 args 不是数组，可能是因为 Commander.js 版本差异
+      // 检查 options 是否包含 args
+      if (options && options.args) {
+        queryArgs = options.args;
+      } else {
+        queryArgs = [];
+      }
+    }
+
+    if (!queryArgs || queryArgs.length === 0) {
+      this.showError('请输入要解释的内容，例如: xx ai 关闭微信');
+      console.log('\n用法: xx ai <查询内容>');
+      console.log('示例:');
+      console.log('  xx ai 关闭占用3000端口的进程');
+      console.log('  xx ai 生成readme');
+      console.log('  xx ai 查看ip地址');
+      return;
+    }
+
+    const query = queryArgs.join(' ');
+
+    try {
+      this.startLoading('正在获取命令列表...');
+      const commands = await this.getAllCommands();
+      this.stopLoading('命令列表获取成功');
+
+      this.startLoading('正在加载配置...');
+      const config = this.loadAIConfig(options);
+      this.stopLoading('配置加载成功');
+
+      this.startLoading('正在调用 AI 解释...');
+      const result = await this.callAI(query, commands, config);
+      this.stopLoading('解释完成');
+
+      console.log('\n' + result + '\n');
+    } catch (error) {
+      this.stopLoading();
+      this.showError(`调用失败: ${error.message}`);
+    }
+  }
+}
+
+module.exports = AIPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xubill/xx-cli",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "个人工具集",
   "main": "lib/core/index.js",
   "bin": {
@@ -55,8 +55,13 @@
     "zx": "^8.8.5"
   },
   "devDependencies": {
+    "medium-zoom": "^1.1.0",
+    "nprogress-v2": "^1.1.10",
     "standard-version": "^9.5.0",
     "vitepress": "^1.6.4",
+    "vitepress-plugin-announcement": "^0.1.7",
+    "vitepress-plugin-group-icons": "^1.7.1",
+    "vitepress-sidebar": "^1.33.1",
     "vue": "^3.5.26"
   }
 }