@xubill/xx-cli 2.0.0 → 2.0.2

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/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/lib/core/index.js

@@ -229,6 +229,7 @@ class Core {
                 `警告: 插件 ${pluginName} 的命令别名与其他插件冲突，已跳过此插件的命令注册`,
               );
             } else {
+              console.log(error)
               console.error(
                 `错误: 插件 ${pluginName} 注册命令失败: ${error.message}`,
               );
@@ -362,7 +363,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 +372,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 +420,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 +442,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个建议
   }