@xiaozhi-client/cli 1.9.4-beta.10

package/src/errors/__tests__/index.test.ts

@@ -0,0 +1,186 @@
+/**
+ * 错误处理系统单元测试
+ */
+
+import { describe, expect, it } from "vitest";
+import { ERROR_CODES } from "../../Constants";
+import {
+  CLIError,
+  ConfigError,
+  FileError,
+  ProcessError,
+  ServiceError,
+  ValidationError,
+} from "../index";
+
+describe("CLIError", () => {
+  it("should create basic CLI error", () => {
+    const error = new CLIError("Test error", "TEST_ERROR");
+
+    expect(error.message).toBe("Test error");
+    expect(error.code).toBe("TEST_ERROR");
+    expect(error.exitCode).toBe(1);
+    expect(error.name).toBe("CLIError");
+  });
+
+  it("should create CLI error with suggestions", () => {
+    const suggestions = ["Try this", "Or that"];
+    const error = CLIError.withSuggestions(
+      "Test error",
+      "TEST_ERROR",
+      suggestions
+    );
+
+    expect(error.suggestions).toEqual(suggestions);
+  });
+
+  it("should create CLI error with custom exit code", () => {
+    const error = new CLIError("Test error", "TEST_ERROR", 2);
+
+    expect(error.exitCode).toBe(2);
+  });
+});
+
+describe("ConfigError", () => {
+  it("should create config error", () => {
+    const error = new ConfigError("Config not found");
+
+    expect(error.message).toBe("Config not found");
+    expect(error.code).toBe(ERROR_CODES.CONFIG_ERROR);
+    expect(error.name).toBe("ConfigError");
+  });
+
+  it("should create config not found error", () => {
+    const error = ConfigError.configNotFound();
+
+    expect(error.message).toBe("配置文件不存在");
+    expect(error.suggestions).toContain('请运行 "xiaozhi init" 初始化配置文件');
+  });
+
+  it("should create invalid format error", () => {
+    const error = ConfigError.invalidFormat("xml");
+
+    expect(error.message).toBe("无效的配置文件格式: xml");
+    expect(error.suggestions).toContain("支持的格式: json, json5, jsonc");
+  });
+});
+
+describe("ServiceError", () => {
+  it("should create service error", () => {
+    const error = new ServiceError("Service failed");
+
+    expect(error.message).toBe("Service failed");
+    expect(error.code).toBe(ERROR_CODES.SERVICE_ERROR);
+    expect(error.name).toBe("ServiceError");
+  });
+
+  it("should create already running error", () => {
+    const error = ServiceError.alreadyRunning(1234);
+
+    expect(error.message).toBe("服务已经在运行 (PID: 1234)");
+    expect(error.suggestions).toContain('请先运行 "xiaozhi stop" 停止现有服务');
+    expect(error.suggestions).toContain('或者使用 "xiaozhi restart" 重启服务');
+  });
+
+  it("should create auto restarting error", () => {
+    const error = ServiceError.autoRestarting(1234);
+
+    expect(error.message).toBe(
+      "检测到服务已在运行 (PID: 1234)，正在自动重启..."
+    );
+    expect(error.suggestions).toContain(
+      "如果不希望自动重启，请使用 xiaozhi stop 手动停止服务"
+    );
+  });
+
+  it("should create not running error", () => {
+    const error = ServiceError.notRunning();
+
+    expect(error.message).toBe("服务未运行");
+    expect(error.suggestions).toContain('请运行 "xiaozhi start" 启动服务');
+  });
+
+  it("should create start failed error", () => {
+    const error = ServiceError.startFailed("Port occupied");
+
+    expect(error.message).toBe("服务启动失败: Port occupied");
+    expect(error.suggestions).toContain("检查配置文件是否正确");
+  });
+});
+
+describe("ValidationError", () => {
+  it("should create validation error", () => {
+    const error = new ValidationError("Invalid value", "port");
+
+    expect(error.message).toBe("验证失败: port - Invalid value");
+    expect(error.code).toBe(ERROR_CODES.VALIDATION_ERROR);
+    expect(error.name).toBe("ValidationError");
+  });
+
+  it("should create invalid port error", () => {
+    const error = ValidationError.invalidPort(99999);
+
+    expect(error.message).toContain("端口号必须在 1-65535 范围内");
+    expect(error.message).toContain("99999");
+  });
+
+  it("should create required field error", () => {
+    const error = ValidationError.requiredField("name");
+
+    expect(error.message).toBe("验证失败: name - 必填字段不能为空");
+  });
+});
+
+describe("FileError", () => {
+  it("should create file error", () => {
+    const error = new FileError("File operation failed", "/path/to/file");
+
+    expect(error.message).toBe("File operation failed: /path/to/file");
+    expect(error.code).toBe(ERROR_CODES.FILE_ERROR);
+    expect(error.name).toBe("FileError");
+  });
+
+  it("should create file not found error", () => {
+    const error = FileError.notFound("/missing/file");
+
+    expect(error.message).toBe("文件不存在: /missing/file");
+    expect(error.suggestions).toContain("检查文件路径是否正确");
+  });
+
+  it("should create permission denied error", () => {
+    const error = FileError.permissionDenied("/protected/file");
+
+    expect(error.message).toBe("权限不足: /protected/file");
+    expect(error.suggestions).toContain("检查文件权限或使用管理员权限运行");
+  });
+
+  it("should create already exists error", () => {
+    const error = FileError.alreadyExists("/existing/file");
+
+    expect(error.message).toBe("文件已存在: /existing/file");
+    expect(error.suggestions).toContain("使用不同的文件名或删除现有文件");
+  });
+});
+
+describe("ProcessError", () => {
+  it("should create process error", () => {
+    const error = new ProcessError("Process failed", 1234);
+
+    expect(error.message).toBe("Process failed (PID: 1234)");
+    expect(error.code).toBe(ERROR_CODES.PROCESS_ERROR);
+    expect(error.name).toBe("ProcessError");
+  });
+
+  it("should create kill failed error", () => {
+    const error = ProcessError.killFailed(1234);
+
+    expect(error.message).toBe("无法终止进程 (PID: 1234)");
+    expect(error.suggestions).toContain("进程可能已经停止或权限不足");
+  });
+
+  it("should create not found error", () => {
+    const error = ProcessError.notFound(1234);
+
+    expect(error.message).toBe("进程不存在 (PID: 1234)");
+  });
+});

package/src/errors/index.ts

@@ -0,0 +1,163 @@
+/**
+ * 统一错误处理系统
+ */
+
+import { ERROR_CODES } from "../Constants";
+
+/**
+ * CLI 基础错误类
+ */
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public exitCode = 1,
+    public suggestions?: string[]
+  ) {
+    super(message);
+    this.name = "CLIError";
+
+    // 确保错误堆栈正确显示
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CLIError);
+    }
+  }
+
+  /**
+   * 创建带建议的错误
+   */
+  static withSuggestions(
+    message: string,
+    code: string,
+    suggestions: string[]
+  ): CLIError {
+    return new CLIError(message, code, 1, suggestions);
+  }
+}
+
+/**
+ * 配置错误
+ */
+export class ConfigError extends CLIError {
+  constructor(message: string, suggestions?: string[]) {
+    super(message, ERROR_CODES.CONFIG_ERROR, 1, suggestions);
+    this.name = "ConfigError";
+  }
+
+  static configNotFound(): ConfigError {
+    return new ConfigError("配置文件不存在", [
+      '请运行 "xiaozhi init" 初始化配置文件',
+    ]);
+  }
+
+  static invalidFormat(format: string): ConfigError {
+    return new ConfigError(`无效的配置文件格式: ${format}`, [
+      "支持的格式: json, json5, jsonc",
+    ]);
+  }
+}
+
+/**
+ * 服务错误
+ */
+export class ServiceError extends CLIError {
+  constructor(message: string, suggestions?: string[]) {
+    super(message, ERROR_CODES.SERVICE_ERROR, 1, suggestions);
+    this.name = "ServiceError";
+  }
+
+  static alreadyRunning(pid: number): ServiceError {
+    return new ServiceError(`服务已经在运行 (PID: ${pid})`, [
+      '请先运行 "xiaozhi stop" 停止现有服务',
+      '或者使用 "xiaozhi restart" 重启服务',
+    ]);
+  }
+
+  static autoRestarting(pid: number): ServiceError {
+    return new ServiceError(
+      `检测到服务已在运行 (PID: ${pid})，正在自动重启...`,
+      ["如果不希望自动重启，请使用 xiaozhi stop 手动停止服务"]
+    );
+  }
+
+  static notRunning(): ServiceError {
+    return new ServiceError("服务未运行", ['请运行 "xiaozhi start" 启动服务']);
+  }
+
+  static startFailed(reason: string): ServiceError {
+    return new ServiceError(`服务启动失败: ${reason}`, [
+      "检查配置文件是否正确",
+      "确保端口未被占用",
+      "查看日志文件获取详细信息",
+    ]);
+  }
+}
+
+/**
+ * 验证错误
+ */
+export class ValidationError extends CLIError {
+  constructor(message: string, field: string) {
+    super(`验证失败: ${field} - ${message}`, ERROR_CODES.VALIDATION_ERROR, 1);
+    this.name = "ValidationError";
+  }
+
+  static invalidPort(port: number): ValidationError {
+    return new ValidationError(
+      `端口号必须在 1-65535 范围内，当前值: ${port}`,
+      "port"
+    );
+  }
+
+  static requiredField(field: string): ValidationError {
+    return new ValidationError("必填字段不能为空", field);
+  }
+}
+
+/**
+ * 文件操作错误
+ */
+export class FileError extends CLIError {
+  constructor(message: string, filePath?: string, suggestions?: string[]) {
+    const fullMessage = filePath ? `${message}: ${filePath}` : message;
+    super(fullMessage, ERROR_CODES.FILE_ERROR, 1, suggestions);
+    this.name = "FileError";
+  }
+
+  static notFound(filePath: string): FileError {
+    return new FileError("文件不存在", filePath, ["检查文件路径是否正确"]);
+  }
+
+  static permissionDenied(filePath: string): FileError {
+    return new FileError("权限不足", filePath, [
+      "检查文件权限或使用管理员权限运行",
+    ]);
+  }
+
+  static alreadyExists(filePath: string): FileError {
+    return new FileError("文件已存在", filePath, [
+      "使用不同的文件名或删除现有文件",
+    ]);
+  }
+}
+
+/**
+ * 进程错误
+ */
+export class ProcessError extends CLIError {
+  constructor(message: string, pid?: number, suggestions?: string[]) {
+    const fullMessage = pid ? `${message} (PID: ${pid})` : message;
+    super(fullMessage, ERROR_CODES.PROCESS_ERROR, 1, suggestions);
+    this.name = "ProcessError";
+  }
+
+  static killFailed(pid: number): ProcessError {
+    return new ProcessError("无法终止进程", pid, [
+      "进程可能已经停止或权限不足",
+    ]);
+  }
+
+  static notFound(pid: number): ProcessError {
+    return new ProcessError("进程不存在", pid);
+  }
+}

package/src/global.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="node" />
+/// <reference types="express" />
+/// <reference types="ws" />
+/// <reference types="semver" />
+/// <reference types="node-fetch" />
+/// <reference types="supertest" />
+
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      readonly NODE_ENV: string;
+      readonly XIAOZHI_CONFIG_DIR?: string;
+      readonly TMPDIR?: string;
+      readonly TEMP?: string;
+    }
+  }
+}
+
+export {};

package/src/index.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * CLI 入口文件
+ * 负责初始化依赖注入容器和启动命令处理器
+ */
+
+import { Command } from "commander";
+import { DIContainer } from "./Container";
+import { CommandRegistry } from "./commands/index";
+import { ErrorHandler } from "./errors/ErrorHandlers";
+
+const program = new Command();
+
+/**
+ * 初始化 CLI 应用
+ */
+async function initializeCLI(): Promise<void> {
+  try {
+    // 创建依赖注入容器
+    const container = DIContainer.create();
+
+    // 创建命令注册器
+    const commandRegistry = new CommandRegistry(container);
+
+    // 注册所有命令
+    await commandRegistry.registerCommands(program);
+
+    // 配置程序基本信息
+    program
+      .name("xiaozhi")
+      .description("小智 MCP 客户端")
+      .helpOption("-h, --help", "显示帮助信息");
+
+    // 解析命令行参数
+    await program.parseAsync(process.argv);
+  } catch (error) {
+    ErrorHandler.handle(error as Error);
+  }
+}
+
+// 启动 CLI 应用
+// 使用更可靠的检测方法，兼容 Windows 路径
+// 将路径转换为 URL 格式进行比较
+const scriptPath = process.argv[1].replace(/\\/g, "/");
+const isMainModule =
+  import.meta.url === `file:///${scriptPath}` ||
+  import.meta.url === `file://${scriptPath}`;
+if (isMainModule) {
+  initializeCLI();
+}
+
+export { initializeCLI };

package/src/interfaces/Command.ts

@@ -0,0 +1,128 @@
+/**
+ * 命令接口定义
+ */
+
+import type { Command } from "commander";
+import type { CommandArguments, CommandOptions } from "./CommandTypes";
+import type { IDIContainer } from "./Config";
+
+/**
+ * 命令处理器接口
+ */
+export interface CommandHandler {
+  /** 命令名称 */
+  name: string;
+  /** 命令描述 */
+  description: string;
+  /** 命令选项 */
+  options?: CommandOption[];
+  /** 子命令 */
+  subcommands?: SubCommand[];
+  /** 执行命令 */
+  execute(args: CommandArguments, options: CommandOptions): Promise<void>;
+}
+
+/**
+ * 命令选项接口
+ */
+export interface CommandOption {
+  /** 选项标志 */
+  flags: string;
+  /** 选项描述 */
+  description: string;
+  /** 默认值（限制为 Commander.js 支持的类型） */
+  defaultValue?: string | boolean | string[];
+}
+
+/**
+ * 子命令接口
+ */
+export interface SubCommand {
+  /** 子命令名称 */
+  name: string;
+  /** 子命令描述 */
+  description: string;
+  /** 子命令选项 */
+  options?: CommandOption[];
+  /** 执行子命令 */
+  execute(args: CommandArguments, options: CommandOptions): Promise<void>;
+}
+
+/**
+ * 命令执行上下文
+ */
+export interface CommandContext {
+  /** DI 容器 */
+  container: IDIContainer;
+  /** 命令行参数 */
+  args: CommandArguments;
+  /** 命令选项 */
+  options: CommandOptions;
+}
+
+/**
+ * 基础命令处理器抽象类
+ */
+export abstract class BaseCommandHandler implements CommandHandler {
+  abstract name: string;
+  abstract description: string;
+  options?: CommandOption[];
+  subcommands?: SubCommand[];
+
+  constructor(protected container: IDIContainer) {}
+
+  abstract execute(
+    args: CommandArguments,
+    options: CommandOptions
+  ): Promise<void>;
+
+  /**
+   * 获取服务实例
+   */
+  protected getService<T>(serviceName: string): T {
+    return this.container.get(serviceName) as T;
+  }
+
+  /**
+   * 处理错误
+   */
+  protected handleError(error: Error): void {
+    const errorHandler = this.getService<unknown>("errorHandler");
+    // 类型断言：errorHandler 应该有 handle 方法
+    const handler = errorHandler as { handle: (error: Error) => void };
+    handler.handle(error);
+  }
+
+  /**
+   * 验证参数
+   */
+  protected validateArgs(args: CommandArguments, expectedCount: number): void {
+    if (args.length < expectedCount) {
+      throw new Error(
+        `命令需要至少 ${expectedCount} 个参数，但只提供了 ${args.length} 个`
+      );
+    }
+  }
+}
+
+/**
+ * 命令注册器接口
+ */
+export interface ICommandRegistry {
+  /** 注册所有命令到 Commander 程序 */
+  registerCommands(program: Command): Promise<void>;
+  /** 注册单个命令 */
+  registerCommand(program: Command, handler: CommandHandler): void;
+  /** 注册命令处理器 */
+  registerHandler(handler: CommandHandler): void;
+}
+
+/**
+ * 命令处理器工厂接口
+ */
+export interface ICommandHandlerFactory {
+  /** 创建所有命令处理器 */
+  createHandlers(): CommandHandler[];
+  /** 创建指定类型的命令处理器 */
+  createHandler(type: string): CommandHandler;
+}

package/src/interfaces/CommandTypes.ts

@@ -0,0 +1,95 @@
+/**
+ * CLI 命令相关类型定义
+ * 用于替代命令处理器中的 any 类型使用，提供类型安全保障
+ */
+
+import type {
+  LocalMCPServerConfig,
+  MCPServerConfig,
+} from "@xiaozhi-client/config";
+
+// =========================
+// 基础命令参数和选项类型
+// =========================
+
+/**
+ * 命令行参数类型
+ * 替代 any[] 类型
+ */
+export type CommandArguments = string[];
+
+/**
+ * 命令选项类型
+ * 替代 any 类型
+ */
+export type CommandOptions = Record<string, unknown>;
+
+// =========================
+// 子命令具体选项类型
+// =========================
+
+/**
+ * list 子命令选项
+ */
+export interface ListOptions {
+  /** 是否显示所有服务的工具列表 */
+  tools?: boolean;
+}
+
+/**
+ * call 子命令选项
+ */
+export interface CallOptions {
+  /** 工具参数 (JSON 格式) */
+  args?: string;
+}
+
+// =========================
+// 类型守卫函数
+// =========================
+
+/**
+ * 检查对象是否为本地 MCP 服务配置
+ * @param obj 待检查的对象
+ * @returns 是否为本地服务配置
+ */
+export function isLocalMCPServerConfig(
+  obj: unknown
+): obj is LocalMCPServerConfig {
+  const config = obj as MCPServerConfig;
+  return (
+    typeof config === "object" &&
+    config !== null &&
+    "command" in config &&
+    "args" in config &&
+    typeof config.command === "string" &&
+    Array.isArray(config.args) &&
+    config.args.every((arg: unknown) => typeof arg === "string")
+  );
+}
+
+// =========================
+// 类型化子命令接口
+// =========================
+
+/**
+ * 类型化子命令接口
+ * 提供类型安全的子命令定义
+ */
+export interface TypedSubCommand<TOptions = CommandOptions> {
+  /** 子命令名称 */
+  name: string;
+  /** 子命令描述 */
+  description: string;
+  /** 子命令选项 */
+  options?: Array<{
+    /** 选项标志 */
+    flags: string;
+    /** 选项描述 */
+    description: string;
+    /** 默认值 */
+    defaultValue?: unknown;
+  }>;
+  /** 执行子命令 */
+  execute: (args: CommandArguments, options: TOptions) => Promise<void>;
+}

package/src/interfaces/Config.ts

@@ -0,0 +1,25 @@
+/**
+ * 配置接口定义
+ */
+
+/**
+ * 依赖注入容器接口
+ */
+export interface IDIContainer {
+  /** 注册服务 */
+  register<T>(key: string, factory: () => T): void;
+  /** 获取服务实例 */
+  get<T>(key: string): T;
+  /** 检查服务是否已注册 */
+  has(key: string): boolean;
+}
+
+/**
+ * 配置验证结果
+ */
+export interface ValidationResult {
+  /** 是否有效 */
+  valid: boolean;
+  /** 错误信息 */
+  error?: string;
+}