@xiaozhi-client/cli 1.9.4-beta.5

package/src/commands/index.ts

@@ -0,0 +1,351 @@
+/**
+ * 命令注册器
+ */
+
+import type { Command } from "commander";
+import { ErrorHandler } from "../errors/ErrorHandlers";
+import type {
+  CommandHandler,
+  ICommandHandlerFactory,
+  ICommandRegistry,
+} from "../interfaces/Command";
+import type { IDIContainer } from "../interfaces/Config";
+import { CommandHandlerFactory } from "./CommandHandlerFactory";
+
+/**
+ * 命令注册器实现
+ */
+export class CommandRegistry implements ICommandRegistry {
+  private handlers: CommandHandler[] = [];
+  private handlerFactory: ICommandHandlerFactory;
+
+  constructor(private container: IDIContainer) {
+    this.handlerFactory = new CommandHandlerFactory(container);
+  }
+
+  /**
+   * 注册所有命令到 Commander 程序
+   */
+  async registerCommands(program: Command): Promise<void> {
+    try {
+      // 注册基本命令
+      this.registerVersionCommand(program);
+      this.registerHelpCommand(program);
+
+      // 创建并注册所有功能命令处理器
+      const handlers = this.handlerFactory.createHandlers();
+      for (const handler of handlers) {
+        this.registerHandler(handler);
+        this.registerCommand(program, handler);
+      }
+
+      // 注册向后兼容的顶级服务命令
+      this.registerLegacyServiceCommands(program, handlers);
+    } catch (error) {
+      ErrorHandler.handle(error as Error);
+    }
+  }
+
+  /**
+   * 注册命令处理器
+   */
+  registerHandler(handler: CommandHandler): void {
+    this.handlers.push(handler);
+  }
+
+  /**
+   * 注册单个命令
+   */
+  registerCommand(program: Command, handler: CommandHandler): void {
+    // 如果有子命令，创建命令组
+    if (handler.subcommands && handler.subcommands.length > 0) {
+      const commandGroup = program
+        .command(handler.name)
+        .description(handler.description);
+
+      for (const subcommand of handler.subcommands) {
+        let subcommandName = subcommand.name;
+
+        // 特殊处理需要参数的子命令
+        if (subcommand.name === "get") {
+          subcommandName = "get <key>";
+        } else if (subcommand.name === "set") {
+          subcommandName = "set <key> <value>";
+        } else if (subcommand.name === "call") {
+          subcommandName = "call <serviceName> <toolName>";
+        }
+
+        const cmd = commandGroup
+          .command(subcommandName)
+          .description(subcommand.description);
+
+        // 添加子命令选项
+        if (subcommand.options) {
+          for (const option of subcommand.options) {
+            cmd.option(option.flags, option.description, option.defaultValue);
+          }
+        }
+
+        // 设置子命令处理函数
+        cmd.action(async (...args) => {
+          try {
+            // Commander.js 传递的最后一个参数是 Command 对象，包含选项值
+            const command = args[args.length - 1];
+            const options = command.opts(); // 获取解析后的选项
+            await subcommand.execute(args.slice(0, -1), options);
+          } catch (error) {
+            ErrorHandler.handle(error as Error);
+          }
+        });
+      }
+
+      // 设置主命令的默认行为
+      commandGroup.action(async (...args) => {
+        try {
+          const command = args[args.length - 1];
+          const options = command.opts(); // 获取解析后的选项
+          await handler.execute(args.slice(0, -1), options);
+        } catch (error) {
+          ErrorHandler.handle(error as Error);
+        }
+      });
+    } else {
+      // 没有子命令，注册为普通命令
+      let commandName = handler.name;
+
+      // 特殊处理 create 命令，需要接受项目名称参数
+      if (handler.name === "create") {
+        commandName = "create <projectName>";
+      }
+
+      const command = program
+        .command(commandName)
+        .description(handler.description);
+
+      // 添加选项
+      if (handler.options) {
+        for (const option of handler.options) {
+          command.option(option.flags, option.description, option.defaultValue);
+        }
+      }
+
+      // 设置主命令处理函数
+      command.action(async (...args) => {
+        try {
+          const command = args[args.length - 1];
+          const options = command.opts(); // 获取解析后的选项
+          await handler.execute(args.slice(0, -1), options);
+        } catch (error) {
+          ErrorHandler.handle(error as Error);
+        }
+      });
+    }
+  }
+
+  /**
+   * 注册版本命令
+   */
+  private registerVersionCommand(program: Command): void {
+    const versionUtils = this.container.get("versionUtils") as any;
+
+    program.version(versionUtils.getVersion(), "-v, --version", "显示版本信息");
+
+    // 注册 --info 选项
+    program.option("--info", "显示详细信息");
+
+    // 注册 --version-info 选项
+    program.option("--version-info", "显示详细版本信息");
+  }
+
+  /**
+   * 注册帮助命令
+   */
+  private registerHelpCommand(program: Command): void {
+    program.helpOption("-h, --help", "显示帮助信息").addHelpText(
+      "after",
+      `
+示例:
+  xiaozhi init                     # 初始化配置文件
+  xiaozhi start                    # 启动服务（包含 Web UI）
+  xiaozhi start -d                 # 后台启动服务
+  xiaozhi start -s 3000            # 以 MCP Server 模式启动
+  xiaozhi stop                     # 停止服务
+  xiaozhi status                   # 检查服务状态
+  xiaozhi restart -d               # 重启服务（后台模式）
+  xiaozhi config mcpEndpoint <url> # 设置 MCP 端点
+  xiaozhi create my-project        # 创建项目
+  xiaozhi mcp list                 # 列出 MCP 服务
+
+更多信息请访问: https://github.com/your-org/xiaozhi-client
+`
+    );
+  }
+
+  /**
+   * 注册向后兼容的顶级服务命令
+   */
+  private registerLegacyServiceCommands(
+    program: Command,
+    handlers: CommandHandler[]
+  ): void {
+    // 找到服务命令处理器
+    const serviceHandler = handlers.find((h) => h.name === "service");
+    if (!serviceHandler || !serviceHandler.subcommands) {
+      return;
+    }
+
+    // 为每个服务子命令创建顶级命令
+    for (const subcommand of serviceHandler.subcommands) {
+      const command = program
+        .command(subcommand.name)
+        .description(subcommand.description);
+
+      // 添加选项
+      if (subcommand.options) {
+        for (const option of subcommand.options) {
+          command.option(option.flags, option.description, option.defaultValue);
+        }
+      }
+
+      // 设置命令处理函数
+      command.action(async (...args) => {
+        try {
+          // Commander.js 传递的最后一个参数是 Command 对象，包含选项值
+          const command = args[args.length - 1];
+          const options = command.opts(); // 获取解析后的选项
+          await subcommand.execute(args.slice(0, -1), options);
+        } catch (error) {
+          ErrorHandler.handle(error as Error);
+        }
+      });
+    }
+  }
+
+  /**
+   * 注册服务管理命令（稍后实现）
+   */
+  // private async registerServiceCommands(program: Command): Promise<void> {
+  //   const serviceCommand = this.container.get('serviceCommand');
+
+  //   // start 命令
+  //   program
+  //     .command('start')
+  //     .description('启动服务')
+  //     .option('-d, --daemon', '在后台运行服务')
+  //     .option('-u, --ui', '同时启动 Web UI 服务')
+  //     .option('-s, --server [port]', '以 MCP Server 模式启动 (可选指定端口，默认 3000)')
+  //     .option('--stdio', '以 stdio 模式运行 MCP Server (用于 Cursor 等客户端)')
+  //     .action(async (options) => {
+  //       await serviceCommand.start(options);
+  //     });
+
+  //   // stop 命令
+  //   program
+  //     .command('stop')
+  //     .description('停止服务')
+  //     .action(async () => {
+  //       await serviceCommand.stop();
+  //     });
+
+  //   // status 命令
+  //   program
+  //     .command('status')
+  //     .description('检查服务状态')
+  //     .action(async () => {
+  //       await serviceCommand.status();
+  //     });
+
+  //   // restart 命令
+  //   program
+  //     .command('restart')
+  //     .description('重启服务')
+  //     .option('-d, --daemon', '在后台运行服务')
+  //     .option('-u, --ui', '同时启动 Web UI 服务')
+  //     .action(async (options) => {
+  //       await serviceCommand.restart(options);
+  //     });
+
+  //   // attach 命令
+  //   program
+  //     .command('attach')
+  //     .description('连接到后台服务查看日志')
+  //     .action(async () => {
+  //       await serviceCommand.attach();
+  //     });
+  // }
+
+  /**
+   * 注册配置管理命令（稍后实现）
+   */
+  // private async registerConfigCommands(program: Command): Promise<void> {
+  //   const configCommand = this.container.get('configCommand');
+
+  //   // init 命令
+  //   program
+  //     .command('init')
+  //     .description('初始化配置文件')
+  //     .option('-f, --format <format>', '配置文件格式 (json, json5, jsonc)', 'json')
+  //     .action(async (options) => {
+  //       await configCommand.init(options);
+  //     });
+
+  //   // config 命令
+  //   program
+  //     .command('config <key> [value]')
+  //     .description('查看或设置配置')
+  //     .action(async (key, value) => {
+  //       await configCommand.manage(key, value);
+  //     });
+  // }
+
+  /**
+   * 注册项目管理命令（稍后实现）
+   */
+  // private async registerProjectCommands(program: Command): Promise<void> {
+  //   const projectCommand = this.container.get('projectCommand');
+
+  //   // create 命令
+  //   program
+  //     .command('create <projectName>')
+  //     .description('创建项目')
+  //     .option('-t, --template <templateName>', '使用指定模板创建项目')
+  //     .action(async (projectName, options) => {
+  //       await projectCommand.create(projectName, options);
+  //     });
+  // }
+
+  /**
+   * 注册 MCP 管理命令（稍后实现）
+   */
+  // private async registerMcpCommands(program: Command): Promise<void> {
+  //   const mcpCommand = this.container.get('mcpCommand');
+
+  //   // mcp 命令组
+  //   const mcpGroup = program.command('mcp').description('MCP 服务和工具管理');
+
+  //   // mcp list 命令
+  //   mcpGroup
+  //     .command('list')
+  //     .description('列出 MCP 服务')
+  //     .option('--tools', '显示所有服务的工具列表')
+  //     .action(async (options) => {
+  //       await mcpCommand.list(options);
+  //     });
+
+  //   // mcp server 命令
+  //   mcpGroup
+  //     .command('server <serverName>')
+  //     .description('管理指定的 MCP 服务')
+  //     .action(async (serverName) => {
+  //       await mcpCommand.server(serverName);
+  //     });
+
+  //   // mcp tool 命令
+  //   mcpGroup
+  //     .command('tool <serverName> <toolName> <action>')
+  //     .description('管理 MCP 工具 (enable/disable)')
+  //     .action(async (serverName, toolName, action) => {
+  //       await mcpCommand.tool(serverName, toolName, action);
+  //     });
+  // }
+}

package/src/errors/ErrorHandlers.ts

@@ -0,0 +1,141 @@
+/**
+ * 错误处理器
+ */
+
+import chalk from "chalk";
+import { ERROR_MESSAGES } from "./ErrorMessages";
+import { CLIError } from "./index";
+
+/**
+ * 错误处理器类
+ */
+export class ErrorHandler {
+  /**
+   * 处理错误并退出程序
+   */
+  static handle(error: Error): never {
+    if (error instanceof CLIError) {
+      ErrorHandler.handleCLIError(error);
+    } else {
+      ErrorHandler.handleUnknownError(error);
+    }
+
+    process.exit(1);
+  }
+
+  /**
+   * 处理 CLI 错误
+   */
+  private static handleCLIError(error: CLIError): void {
+    console.error(chalk.red(`❌ 错误: ${error.message}`));
+
+    // 显示错误码（调试模式）
+    if (process.env.DEBUG) {
+      console.error(chalk.gray(`错误码: ${error.code}`));
+    }
+
+    // 显示建议
+    if (error.suggestions && error.suggestions.length > 0) {
+      console.log(chalk.yellow("💡 建议:"));
+      for (const suggestion of error.suggestions) {
+        console.log(chalk.gray(`   ${suggestion}`));
+      }
+    }
+
+    // 显示相关帮助信息
+    const helpMessage = ERROR_MESSAGES.getHelpMessage(error.code);
+    if (helpMessage) {
+      console.log(chalk.blue(`ℹ️  ${helpMessage}`));
+    }
+  }
+
+  /**
+   * 处理未知错误
+   */
+  private static handleUnknownError(error: Error): void {
+    console.error(chalk.red(`❌ 未知错误: ${error.message}`));
+
+    // 在调试模式下显示完整堆栈
+    if (process.env.DEBUG || process.env.NODE_ENV === "development") {
+      console.error(chalk.gray("堆栈信息:"));
+      console.error(chalk.gray(error.stack));
+    } else {
+      console.log(
+        chalk.yellow("💡 提示: 设置 DEBUG=1 环境变量查看详细错误信息")
+      );
+    }
+  }
+
+  /**
+   * 异步操作错误处理包装器
+   */
+  static async handleAsync<T>(
+    operation: () => Promise<T>,
+    context: string
+  ): Promise<T> {
+    try {
+      return await operation();
+    } catch (error) {
+      if (error instanceof CLIError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        throw new CLIError(
+          `${context}失败: ${error.message}`,
+          "OPERATION_FAILED",
+          1
+        );
+      }
+      throw new CLIError(`${context}失败: 未知错误`, "OPERATION_FAILED", 1);
+    }
+  }
+
+  /**
+   * 同步操作错误处理包装器
+   */
+  static handleSync<T>(operation: () => T, context: string): T {
+    try {
+      return operation();
+    } catch (error) {
+      if (error instanceof CLIError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        throw new CLIError(
+          `${context}失败: ${error.message}`,
+          "OPERATION_FAILED",
+          1
+        );
+      }
+      throw new CLIError(`${context}失败: 未知错误`, "OPERATION_FAILED", 1);
+    }
+  }
+
+  /**
+   * 警告处理
+   */
+  static warn(message: string, suggestions?: string[]): void {
+    console.warn(chalk.yellow(`⚠️  警告: ${message}`));
+
+    if (suggestions && suggestions.length > 0) {
+      console.log(chalk.yellow("💡 建议:"));
+      for (const suggestion of suggestions) {
+        console.log(chalk.gray(`   ${suggestion}`));
+      }
+    }
+  }
+
+  /**
+   * 信息提示
+   */
+  static info(message: string): void {
+    console.log(chalk.blue(`ℹ️  ${message}`));
+  }
+
+  /**
+   * 成功提示
+   */
+  static success(message: string): void {
+    console.log(chalk.green(`✅ ${message}`));
+  }
+}

package/src/errors/ErrorMessages.ts

@@ -0,0 +1,121 @@
+/**
+ * 错误消息管理
+ */
+
+import { ERROR_CODES } from "../Constants";
+
+/**
+ * 错误消息映射
+ */
+const ERROR_HELP_MESSAGES: Record<string, string> = {
+  [ERROR_CODES.CONFIG_ERROR]: '运行 "xiaozhi --help" 查看配置相关命令',
+  [ERROR_CODES.SERVICE_ERROR]: '运行 "xiaozhi status" 检查服务状态',
+  [ERROR_CODES.VALIDATION_ERROR]: "检查输入参数是否正确",
+  [ERROR_CODES.FILE_ERROR]: "检查文件路径和权限",
+  [ERROR_CODES.PROCESS_ERROR]: "检查进程状态和权限",
+  [ERROR_CODES.NETWORK_ERROR]: "检查网络连接和防火墙设置",
+  [ERROR_CODES.PERMISSION_ERROR]: "尝试使用管理员权限运行",
+};
+
+/**
+ * 常见问题解决方案
+ */
+const COMMON_SOLUTIONS: Record<string, string[]> = {
+  config_not_found: [
+    '运行 "xiaozhi init" 初始化配置文件',
+    "检查当前目录是否为项目根目录",
+    "设置 XIAOZHI_CONFIG_DIR 环境变量指定配置目录",
+  ],
+  service_port_occupied: [
+    "检查端口是否被其他程序占用",
+    '使用 "lsof -i :端口号" 查看端口使用情况',
+    "更改配置文件中的端口设置",
+  ],
+  permission_denied: [
+    "检查文件和目录权限",
+    "使用 sudo 或管理员权限运行",
+    "确保当前用户有足够的权限",
+  ],
+  service_start_failed: [
+    "检查配置文件格式是否正确",
+    "查看日志文件获取详细错误信息",
+    "确保所有依赖服务正常运行",
+  ],
+};
+
+/**
+ * 错误消息管理类
+ */
+export class ERROR_MESSAGES {
+  /**
+   * 获取错误码对应的帮助信息
+   */
+  static getHelpMessage(errorCode: string): string | undefined {
+    return ERROR_HELP_MESSAGES[errorCode];
+  }
+
+  /**
+   * 获取常见问题的解决方案
+   */
+  static getSolutions(problemKey: string): string[] {
+    return COMMON_SOLUTIONS[problemKey] || [];
+  }
+
+  /**
+   * 格式化错误消息
+   */
+  static formatError(error: Error, context?: string): string {
+    const contextPrefix = context ? `[${context}] ` : "";
+    return `${contextPrefix}${error.message}`;
+  }
+
+  /**
+   * 获取友好的错误描述
+   */
+  static getFriendlyMessage(errorCode: string): string {
+    const friendlyMessages: Record<string, string> = {
+      [ERROR_CODES.CONFIG_ERROR]: "配置文件相关错误",
+      [ERROR_CODES.SERVICE_ERROR]: "服务运行相关错误",
+      [ERROR_CODES.VALIDATION_ERROR]: "输入验证错误",
+      [ERROR_CODES.FILE_ERROR]: "文件操作错误",
+      [ERROR_CODES.PROCESS_ERROR]: "进程管理错误",
+      [ERROR_CODES.NETWORK_ERROR]: "网络连接错误",
+      [ERROR_CODES.PERMISSION_ERROR]: "权限不足错误",
+    };
+
+    return friendlyMessages[errorCode] || "未知错误";
+  }
+
+  /**
+   * 检查是否为可恢复错误
+   */
+  static isRecoverable(errorCode: string): boolean {
+    const recoverableErrors: string[] = [
+      ERROR_CODES.NETWORK_ERROR,
+      ERROR_CODES.FILE_ERROR,
+      ERROR_CODES.SERVICE_ERROR,
+    ];
+
+    return recoverableErrors.includes(errorCode);
+  }
+
+  /**
+   * 获取错误的严重程度
+   */
+  static getSeverity(
+    errorCode: string
+  ): "low" | "medium" | "high" | "critical" {
+    const severityMap: Record<string, "low" | "medium" | "high" | "critical"> =
+      {
+        [ERROR_CODES.VALIDATION_ERROR]: "low",
+        [ERROR_CODES.FILE_ERROR]: "medium",
+        [ERROR_CODES.CONFIG_ERROR]: "medium",
+        [ERROR_CODES.NETWORK_ERROR]: "medium",
+        [ERROR_CODES.SERVICE_ERROR]: "high",
+        [ERROR_CODES.PROCESS_ERROR]: "high",
+        [ERROR_CODES.PERMISSION_ERROR]: "critical",
+      };
+
+    return severityMap[errorCode] || "medium";
+  }
+}