@xiaozhi-client/cli 1.10.8-beta.9 → 2.0.0-beta.4

package/README.md

@@ -42,15 +42,15 @@ packages/cli/
 
 - **入口点**：`src/index.ts` → `../../dist/cli/index.js`
 - **格式**：ESM (ES Modules)
-- **目标**：Node.js 18+
+- **目标**：Node.js 20+
 - **打包工具**：tsup (esbuild)
 
 ## 外部依赖
 
-CLI 包通过 external 配置引用 backend 模块：
+CLI 包通过 external 配置引用 backend 模块和 workspace 包：
 
 - `@/WebServer` → `dist/backend/WebServer.js` (通过 WebServerLauncher)
-- `@/lib/config/manager` → `dist/backend/lib/config/manager.js`
+- `@xiaozhi-client/config` → `dist/config/index.js` (配置管理)
 
 ## 导入方式
 
@@ -62,11 +62,14 @@ import { DIContainer } from "./Container";
 import { CommandRegistry } from "./commands/index";
 ```
 
-### 外部依赖（使用路径别名）
+### 外部依赖（使用 workspace 包）
 
 ```typescript
-// 引用 backend 模块
-import { configManager } from "@/lib/config/manager";
+// 引用配置管理（从 workspace 包导入）
+import { configManager } from "@xiaozhi-client/config";
+
+// 引用 WebServer（使用路径别名，运行时解析为 backend 模块）
+import { WebServer } from "@/WebServer";
 ```
 
 ## 开发命令

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiaozhi-client/cli",
-  "version": "1.10.8-beta.9",
+  "version": "2.0.0-beta.4",
   "private": false,
   "repository": {
     "type": "git",
@@ -22,10 +22,11 @@
     "commander": "^14.0.0",
     "consola": "^3.4.2",
     "ora": "^8.2.0",
-    "@xiaozhi-client/config": "1.10.8-beta.9"
+    "@xiaozhi-client/config": "2.0.0-beta.4"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.9.2"
   },
   "scripts": {

package/src/Container.ts

@@ -166,40 +166,6 @@ export class DIContainer implements IDIContainer {
       return new TemplateManagerModule.TemplateManagerImpl();
     });
 
-    // 注册命令层（稍后在命令层实现时添加）
-    // container.register('serviceCommand', () => {
-    //   const { ServiceCommand } = require('./commands/ServiceCommand.js');
-    //   const serviceManager = container.get('serviceManager');
-    //   const processManager = container.get('processManager');
-    //   return new ServiceCommand(serviceManager, processManager);
-    // });
-
-    // container.register('configCommand', () => {
-    //   const { ConfigCommand } = require('./commands/ConfigCommand.js');
-    //   const configManager = container.get('configManager');
-    //   const validation = container.get('validation');
-    //   return new ConfigCommand(configManager, validation);
-    // });
-
-    // container.register('projectCommand', () => {
-    //   const { ProjectCommand } = require('./commands/ProjectCommand.js');
-    //   const templateManager = container.get('templateManager');
-    //   const fileUtils = container.get('fileUtils');
-    //   return new ProjectCommand(templateManager, fileUtils);
-    // });
-
-    // container.register('mcpCommand', () => {
-    //   const { McpCommand } = require('./commands/McpCommand.js');
-    //   return new McpCommand();
-    // });
-
-    // container.register('infoCommand', () => {
-    //   const { InfoCommand } = require('./commands/InfoCommand.js');
-    //   const versionUtils = container.get('versionUtils');
-    //   const platformUtils = container.get('platformUtils');
-    //   return new InfoCommand(versionUtils, platformUtils);
-    // });
-
     return container;
   }
 }

package/src/commands/ConfigCommandHandler.ts

@@ -7,6 +7,10 @@ import chalk from "chalk";
 import ora from "ora";
 import type { SubCommand } from "../interfaces/Command";
 import { BaseCommandHandler } from "../interfaces/Command";
+import type {
+  CommandArguments,
+  CommandOptions,
+} from "../interfaces/CommandTypes";
 import type { IDIContainer } from "../interfaces/Config";
 
 /**
@@ -27,14 +31,14 @@ export class ConfigCommandHandler extends BaseCommandHandler {
           defaultValue: "json",
         },
       ],
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         await this.handleInit(options);
       },
     },
     {
       name: "get",
       description: "查看配置值",
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         this.validateArgs(args, 1);
         await this.handleGet(args[0]);
       },
@@ -42,7 +46,7 @@ export class ConfigCommandHandler extends BaseCommandHandler {
     {
       name: "set",
       description: "设置配置值",
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         this.validateArgs(args, 2);
         await this.handleSet(args[0], args[1]);
       },
@@ -56,14 +60,17 @@ export class ConfigCommandHandler extends BaseCommandHandler {
   /**
    * 主命令执行（显示帮助）
    */
-  async execute(args: any[], options: any): Promise<void> {
+  override async execute(
+    args: CommandArguments,
+    options: CommandOptions
+  ): Promise<void> {
     console.log("配置管理命令。使用 --help 查看可用的子命令。");
   }
 
   /**
    * 处理初始化命令
    */
-  private async handleInit(options: any): Promise<void> {
+  private async handleInit(options: CommandOptions): Promise<void> {
     const spinner = ora("初始化配置...").start();
 
     try {

package/src/commands/EndpointCommandHandler.ts

@@ -6,6 +6,10 @@ import chalk from "chalk";
 import ora from "ora";
 import type { SubCommand } from "../interfaces/Command";
 import { BaseCommandHandler } from "../interfaces/Command";
+import type {
+  CommandArguments,
+  CommandOptions,
+} from "../interfaces/CommandTypes";
 import type { IDIContainer } from "../interfaces/Config";
 
 /**
@@ -19,14 +23,14 @@ export class EndpointCommandHandler extends BaseCommandHandler {
     {
       name: "list",
       description: "列出所有 MCP 端点",
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         await this.handleList();
       },
     },
     {
       name: "add",
       description: "添加新的 MCP 端点",
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         this.validateArgs(args, 1);
         await this.handleAdd(args[0]);
       },
@@ -34,7 +38,7 @@ export class EndpointCommandHandler extends BaseCommandHandler {
     {
       name: "remove",
       description: "移除指定的 MCP 端点",
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         this.validateArgs(args, 1);
         await this.handleRemove(args[0]);
       },
@@ -42,7 +46,7 @@ export class EndpointCommandHandler extends BaseCommandHandler {
     {
       name: "set",
       description: "设置 MCP 端点（可以是单个或多个）",
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         this.validateArgs(args, 1);
         await this.handleSet(args);
       },
@@ -56,7 +60,10 @@ export class EndpointCommandHandler extends BaseCommandHandler {
   /**
    * 主命令执行（显示帮助）
    */
-  async execute(args: any[], options: any): Promise<void> {
+  override async execute(
+    args: CommandArguments,
+    options: CommandOptions
+  ): Promise<void> {
     console.log("MCP 端点管理命令。使用 --help 查看可用的子命令。");
   }
 

package/src/commands/ProjectCommandHandler.ts

@@ -7,6 +7,10 @@ import chalk from "chalk";
 import ora from "ora";
 import type { CommandOption } from "../interfaces/Command";
 import { BaseCommandHandler } from "../interfaces/Command";
+import type {
+  CommandArguments,
+  CommandOptions,
+} from "../interfaces/CommandTypes";
 import type { IDIContainer } from "../interfaces/Config";
 
 /**
@@ -30,7 +34,10 @@ export class ProjectCommandHandler extends BaseCommandHandler {
   /**
    * 执行创建项目命令
    */
-  async execute(args: any[], options: any): Promise<void> {
+  override async execute(
+    args: CommandArguments,
+    options: CommandOptions
+  ): Promise<void> {
     this.validateArgs(args, 1);
     const projectName = args[0];
 
@@ -42,7 +49,7 @@ export class ProjectCommandHandler extends BaseCommandHandler {
    */
   protected async handleCreate(
     projectName: string,
-    options: any
+    options: CommandOptions
   ): Promise<void> {
     const spinner = ora("初始化项目...").start();
 

package/src/commands/ServiceCommandHandler.ts

@@ -5,6 +5,10 @@
 import consola from "consola";
 import type { SubCommand } from "../interfaces/Command";
 import { BaseCommandHandler } from "../interfaces/Command";
+import type {
+  CommandArguments,
+  CommandOptions,
+} from "../interfaces/CommandTypes";
 import type { IDIContainer } from "../interfaces/Config";
 
 /**
@@ -26,21 +30,21 @@ export class ServiceCommandHandler extends BaseCommandHandler {
           description: "以 stdio 模式运行 MCP Server (用于 Cursor 等客户端)",
         },
       ],
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         await this.handleStart(options);
       },
     },
     {
       name: "stop",
       description: "停止服务",
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         await this.handleStop();
       },
     },
     {
       name: "status",
       description: "检查服务状态",
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         await this.handleStatus();
       },
     },
@@ -48,14 +52,14 @@ export class ServiceCommandHandler extends BaseCommandHandler {
       name: "restart",
       description: "重启服务",
       options: [{ flags: "-d, --daemon", description: "在后台运行服务" }],
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         await this.handleRestart(options);
       },
     },
     {
       name: "attach",
       description: "连接到后台服务查看日志",
-      execute: async (args: any[], options: any) => {
+      execute: async (args: CommandArguments, options: CommandOptions) => {
         await this.handleAttach();
       },
     },
@@ -68,14 +72,17 @@ export class ServiceCommandHandler extends BaseCommandHandler {
   /**
    * 主命令执行（显示帮助）
    */
-  async execute(args: any[], options: any): Promise<void> {
+  override async execute(
+    args: CommandArguments,
+    options: CommandOptions
+  ): Promise<void> {
     console.log("服务管理命令。使用 --help 查看可用的子命令。");
   }
 
   /**
    * 处理启动命令
    */
-  private async handleStart(options: any): Promise<void> {
+  private async handleStart(options: CommandOptions): Promise<void> {
     try {
       // 处理--debug参数
       if (options.debug) {
@@ -138,7 +145,7 @@ export class ServiceCommandHandler extends BaseCommandHandler {
   /**
    * 处理重启命令
    */
-  private async handleRestart(options: any): Promise<void> {
+  private async handleRestart(options: CommandOptions): Promise<void> {
     try {
       const serviceManager = this.getService<any>("serviceManager");
       await serviceManager.restart({

package/src/commands/index.ts

@@ -23,6 +23,28 @@ export class CommandRegistry implements ICommandRegistry {
     this.handlerFactory = new CommandHandlerFactory(container);
   }
 
+  /**
+   * 包装命令处理函数，统一处理错误
+   * @param handler 命令处理函数
+   * @returns 包装后的处理函数
+   */
+  private wrapCommandHandler(
+    handler: (args: string[], options: Record<string, unknown>) => Promise<void>
+  ) {
+    return async (...args: unknown[]) => {
+      try {
+        // Commander.js 传递的最后一个参数是 Command 对象，包含选项值
+        const command = args[args.length - 1] as {
+          opts: () => Record<string, unknown>;
+        };
+        const options = command.opts();
+        await handler(args.slice(0, -1) as string[], options);
+      } catch (error) {
+        ErrorHandler.handle(error as Error);
+      }
+    };
+  }
+
   /**
    * 注册所有命令到 Commander 程序
    */
@@ -87,28 +109,19 @@ export class CommandRegistry implements ICommandRegistry {
         }
 
         // 设置子命令处理函数
-        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);
-          }
-        });
+        cmd.action(
+          this.wrapCommandHandler(async (args, options) => {
+            await subcommand.execute(args, options);
+          })
+        );
       }
 
       // 设置主命令的默认行为
-      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);
-        }
-      });
+      commandGroup.action(
+        this.wrapCommandHandler(async (args, options) => {
+          await handler.execute(args, options);
+        })
+      );
     } else {
       // 没有子命令，注册为普通命令
       let commandName = handler.name;
@@ -130,15 +143,11 @@ export class CommandRegistry implements ICommandRegistry {
       }
 
       // 设置主命令处理函数
-      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);
-        }
-      });
+      command.action(
+        this.wrapCommandHandler(async (args, options) => {
+          await handler.execute(args, options);
+        })
+      );
     }
   }
 
@@ -208,16 +217,11 @@ export class CommandRegistry implements ICommandRegistry {
       }
 
       // 设置命令处理函数
-      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);
-        }
-      });
+      command.action(
+        this.wrapCommandHandler(async (args, options) => {
+          await subcommand.execute(args, options);
+        })
+      );
     }
   }
 

package/src/errors/ErrorHandlers.ts

@@ -66,6 +66,23 @@ export class ErrorHandler {
     }
   }
 
+  /**
+   * 错误处理包装器
+   */
+  private static wrapError(error: unknown, context: string): CLIError {
+    if (error instanceof CLIError) {
+      return error;
+    }
+    if (error instanceof Error) {
+      return new CLIError(
+        `${context}失败: ${error.message}`,
+        "OPERATION_FAILED",
+        1
+      );
+    }
+    return new CLIError(`${context}失败: 未知错误`, "OPERATION_FAILED", 1);
+  }
+
   /**
    * 异步操作错误处理包装器
    */
@@ -76,17 +93,7 @@ export class ErrorHandler {
     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);
+      throw ErrorHandler.wrapError(error, context);
     }
   }
 
@@ -97,17 +104,7 @@ export class ErrorHandler {
     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);
+      throw ErrorHandler.wrapError(error, context);
     }
   }
 

package/src/global.d.ts

@@ -1,3 +1,11 @@
+/**
+ * CLI 全局类型声明
+ *
+ * 扩展 Node.js 全局类型，包含以下内容：
+ * - Express 相关类型
+ * - WebSocket 相关类型
+ * - 环境变量类型扩展
+ */
 /// <reference types="node" />
 /// <reference types="express" />
 /// <reference types="ws" />

package/src/interfaces/Service.ts

@@ -80,20 +80,42 @@ export interface DaemonManager {
   stopDaemon(): Promise<void>;
 }
 
+/**
+ * 模板信息接口
+ */
+export interface TemplateInfo {
+  name: string;
+  path: string;
+  description?: string;
+  version?: string;
+  author?: string;
+  files: string[];
+}
+
+/**
+ * 模板创建选项
+ */
+export interface TemplateCreateOptions {
+  templateName?: string;
+  targetPath: string;
+  projectName: string;
+  variables?: Record<string, string>;
+}
+
 /**
  * 模板管理器接口
  */
 export interface TemplateManager {
   /** 获取可用模板列表 */
-  getAvailableTemplates(): Promise<any[]>;
+  getAvailableTemplates(): Promise<TemplateInfo[]>;
   /** 复制模板到目标目录 */
   copyTemplate(templateName: string, targetPath: string): Promise<void>;
   /** 验证模板是否存在 */
   validateTemplate(templateName: string): Promise<boolean>;
   /** 获取模板信息 */
-  getTemplateInfo(templateName: string): Promise<any | null>;
+  getTemplateInfo(templateName: string): Promise<TemplateInfo | null>;
   /** 创建项目 */
-  createProject(options: any): Promise<void>;
+  createProject(options: TemplateCreateOptions): Promise<void>;
   /** 清除模板缓存 */
   clearCache(): void;
 }

package/src/services/DaemonManager.ts

@@ -7,6 +7,7 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import type { WebServer } from "@/WebServer";
 import consola from "consola";
+import { RETRY_CONSTANTS } from "../Constants";
 import { ProcessError, ServiceError } from "../errors/index";
 import type {
   DaemonManager as IDaemonManager,
@@ -116,7 +117,9 @@ export class DaemonManagerImpl implements IDaemonManager {
       if (status.running) {
         await this.stopDaemon();
         // 等待一下确保完全停止
-        await new Promise((resolve) => setTimeout(resolve, 1000));
+        await new Promise((resolve) =>
+          setTimeout(resolve, RETRY_CONSTANTS.DEFAULT_INTERVAL)
+        );
       }
 
       // 重新启动守护进程
@@ -151,7 +154,7 @@ export class DaemonManagerImpl implements IDaemonManager {
       const tail = spawn(command, args, { stdio: "inherit" });
 
       // 处理中断信号
-      process.on("SIGINT", () => {
+      process.once("SIGINT", () => {
         console.log("\n断开连接，服务继续在后台运行");
         tail.kill();
         process.exit(0);

package/src/services/ProcessManager.ts

@@ -153,33 +153,7 @@ export class ProcessManagerImpl implements IProcessManager {
    */
   async gracefulKillProcess(pid: number): Promise<void> {
     try {
-      // 尝试优雅停止
-      process.kill(pid, "SIGTERM");
-
-      // 等待进程停止
-      let attempts = 0;
-      const maxAttempts = 30; // 3秒超时
-
-      while (attempts < maxAttempts) {
-        await new Promise((resolve) => setTimeout(resolve, 100));
-
-        try {
-          process.kill(pid, 0);
-          attempts++;
-        } catch {
-          // 进程已停止
-          return;
-        }
-      }
-
-      // 如果还在运行，强制停止
-      try {
-        process.kill(pid, 0);
-        process.kill(pid, "SIGKILL");
-        await new Promise((resolve) => setTimeout(resolve, 500));
-      } catch {
-        // 进程已停止
-      }
+      await PlatformUtils.killProcess(pid, "SIGTERM");
     } catch (error) {
       throw new ProcessError(
         `无法停止进程: ${error instanceof Error ? error.message : String(error)}`,

package/src/services/ServiceManager.ts

@@ -5,6 +5,7 @@
 import type { ConfigManager } from "@xiaozhi-client/config";
 import { ConfigInitializer } from "@xiaozhi-client/config";
 import consola from "consola";
+import { RETRY_CONSTANTS } from "../Constants";
 import { ConfigError, ServiceError } from "../errors/index";
 import type {
   ServiceManager as IServiceManager,
@@ -51,7 +52,9 @@ export class ServiceManagerImpl implements IServiceManager {
           this.processManager.cleanupPidFile();
 
           // 等待一下确保完全停止
-          await new Promise((resolve) => setTimeout(resolve, 1000));
+          await new Promise((resolve) =>
+            setTimeout(resolve, RETRY_CONSTANTS.DEFAULT_INTERVAL)
+          );
 
           consola.success("现有服务已停止，正在启动新服务...");
         } catch (stopError) {
@@ -127,7 +130,9 @@ export class ServiceManagerImpl implements IServiceManager {
       if (status.running) {
         await this.stop();
         // 等待一下确保完全停止
-        await new Promise((resolve) => setTimeout(resolve, 1000));
+        await new Promise((resolve) =>
+          setTimeout(resolve, RETRY_CONSTANTS.DEFAULT_INTERVAL)
+        );
       }
 
       // 重新启动服务
@@ -273,8 +278,8 @@ export class ServiceManagerImpl implements IServiceManager {
         process.exit(0);
       };
 
-      process.on("SIGINT", cleanup);
-      process.on("SIGTERM", cleanup);
+      process.once("SIGINT", cleanup);
+      process.once("SIGTERM", cleanup);
 
       await server.start();
     }
@@ -333,8 +338,8 @@ export class ServiceManagerImpl implements IServiceManager {
       process.exit(0);
     };
 
-    process.on("SIGINT", cleanup);
-    process.on("SIGTERM", cleanup);
+    process.once("SIGINT", cleanup);
+    process.once("SIGTERM", cleanup);
 
     // 保存 PID 信息
     this.processManager.savePidInfo(process.pid, "foreground");

package/src/services/TemplateManager.ts

@@ -5,32 +5,17 @@
 import fs from "node:fs";
 import path from "node:path";
 import { FileError, ValidationError } from "../errors/index";
-import type { TemplateManager as ITemplateManager } from "../interfaces/Service";
+import type {
+  TemplateManager as ITemplateManager,
+  TemplateCreateOptions,
+  TemplateInfo,
+} from "../interfaces/Service";
 import { FileUtils } from "../utils/FileUtils";
 import { PathUtils } from "../utils/PathUtils";
 import { Validation } from "../utils/Validation";
 
-/**
- * 模板信息接口
- */
-export interface TemplateInfo {
-  name: string;
-  path: string;
-  description?: string;
-  version?: string;
-  author?: string;
-  files: string[];
-}
-
-/**
- * 模板创建选项
- */
-export interface TemplateCreateOptions {
-  templateName?: string;
-  targetPath: string;
-  projectName: string;
-  variables?: Record<string, string>;
-}
+// 重新导出类型以保持向后兼容
+export type { TemplateInfo, TemplateCreateOptions };
 
 /**
  * 模板管理器实现

package/src/services/__tests__/ProcessManager.test.ts

@@ -139,43 +139,23 @@ describe("ProcessManagerImpl", () => {
   });
 
   describe("gracefulKillProcess", () => {
-    let originalKill: typeof process.kill;
-
-    beforeEach(() => {
-      originalKill = process.kill;
-      process.kill = vi.fn();
-    });
-
-    afterEach(() => {
-      process.kill = originalKill;
-    });
-
-    it("should gracefully kill process", async () => {
-      let killCallCount = 0;
-      (process.kill as any).mockImplementation((pid: number, signal: any) => {
-        killCallCount++;
-        if (killCallCount > 1) {
-          throw new Error("ESRCH"); // Process stopped
-        }
-      });
+    it("should delegate to PlatformUtils with SIGTERM signal", async () => {
+      mockPlatformUtils.killProcess.mockResolvedValue();
 
       await processManager.gracefulKillProcess(1234);
 
-      expect(process.kill).toHaveBeenCalledWith(1234, "SIGTERM");
+      expect(mockPlatformUtils.killProcess).toHaveBeenCalledWith(
+        1234,
+        "SIGTERM"
+      );
     });
 
-    it("should force kill if graceful kill fails", async () => {
-      (process.kill as any).mockImplementation((pid: number, signal: any) => {
-        if (signal === "SIGKILL") {
-          throw new Error("ESRCH"); // Process stopped
-        }
-        // Process still running for SIGTERM and signal 0
-      });
-
-      await processManager.gracefulKillProcess(1234);
+    it("should throw ProcessError when kill fails", async () => {
+      mockPlatformUtils.killProcess.mockRejectedValue(new Error("Kill failed"));
 
-      expect(process.kill).toHaveBeenCalledWith(1234, "SIGTERM");
-      expect(process.kill).toHaveBeenCalledWith(1234, "SIGKILL");
+      await expect(processManager.gracefulKillProcess(1234)).rejects.toThrow(
+        "无法停止进程"
+      );
     });
   });
 

package/src/services/__tests__/ServiceManager.test.ts

@@ -74,28 +74,6 @@ vi.mock("../../utils/PathUtils.js", () => ({
   },
 }));
 
-// Mock ConfigManager for WebServer
-vi.mock("@/lib/config/manager.js", () => {
-  const mockConfig = {
-    mcpEndpoint: "ws://localhost:3000",
-    mcpServers: {},
-    webServer: { port: 9999 },
-  };
-  const mockConfigManager = {
-    configExists: vi.fn().mockReturnValue(true),
-    getConfig: vi.fn().mockReturnValue(mockConfig),
-    loadConfig: vi.fn().mockResolvedValue(mockConfig),
-    getToolCallLogConfig: vi.fn().mockReturnValue({ enabled: false }),
-    getMcpServers: vi.fn().mockReturnValue({}),
-    getMcpEndpoint: vi.fn().mockReturnValue("ws://localhost:3000"),
-    getConfigDir: vi.fn().mockReturnValue("/mock/config"),
-  };
-  return {
-    configManager: mockConfigManager,
-    ConfigManager: vi.fn().mockImplementation(() => mockConfigManager),
-  };
-});
-
 // Mock fs
 vi.mock("node:fs", () => {
   const mockExistsSync = vi.fn().mockReturnValue(true);

package/src/types/backend.d.ts

@@ -1,48 +1,38 @@
 /**
  * Backend 模块类型声明
- * 使用 any 类型避免递归解析 backend 代码
+ *
+ * 这些声明用于 CLI 包中引用 Backend 模块的类型
+ * 避免递归解析 backend 代码，同时提供类型安全
  */
 
-declare module "@/lib/config/manager" {
-  export interface LocalMCPServerConfig {
-    command: string;
-    args: string[];
-    env?: Record<string, string>;
-  }
-
-  export interface MCPServerConfig {
-    type?: string;
-    url?: string;
-    command?: string;
-    args?: string[];
-    headers?: Record<string, string>;
-  }
-
-  export const configManager: any;
-}
-
-declare module "@/lib/config/manager.js" {
-  export interface LocalMCPServerConfig {
-    command: string;
-    args: string[];
-    env?: Record<string, string>;
-  }
-
-  export interface MCPServerConfig {
-    type?: string;
-    url?: string;
-    command?: string;
-    args?: string[];
-    headers?: Record<string, string>;
-  }
-
-  export const configManager: any;
-}
-
-declare module "@/WebServer" {
-  export class WebServer {}
-}
-
+/**
+ * WebServer 类型声明
+ * 对应 apps/backend/WebServer.ts
+ */
 declare module "@/WebServer.js" {
-  export class WebServer {}
+	/**
+	 * WebServer - Web 服务器主控制器
+	 */
+	export class WebServer {
+		/**
+		 * 创建 WebServer 实例
+		 * @param port - 可选的端口号，不指定则使用配置文件中的端口
+		 */
+		constructor(port?: number);
+
+		/**
+		 * 启动 Web 服务器
+		 */
+		start(): Promise<void>;
+
+		/**
+		 * 停止 Web 服务器
+		 */
+		stop(): Promise<void>;
+
+		/**
+		 * 销毁 WebServer 实例，清理所有资源
+		 */
+		destroy(): void;
+	}
 }

package/src/utils/Validation.ts

@@ -37,7 +37,10 @@ export class Validation {
   /**
    * 验证必填字段
    */
-  static validateRequired(value: any, fieldName: string): void {
+  static validateRequired(
+    value: string | number | boolean | object | null | undefined,
+    fieldName: string
+  ): void {
     if (value === undefined || value === null || value === "") {
       throw ValidationError.requiredField(fieldName);
     }
@@ -169,7 +172,7 @@ export class Validation {
   /**
    * 验证 JSON 格式
    */
-  static validateJson(jsonString: string, fieldName = "json"): any {
+  static validateJson(jsonString: string, fieldName = "json"): unknown {
     try {
       return JSON.parse(jsonString);
     } catch (error) {
@@ -206,8 +209,8 @@ export class Validation {
   /**
    * 验证数组长度
    */
-  static validateArrayLength(
-    array: any[],
+  static validateArrayLength<T>(
+    array: T[],
     fieldName: string,
     options: { min?: number; max?: number } = {}
   ): void {
@@ -230,7 +233,7 @@ export class Validation {
    * 验证对象属性
    */
   static validateObjectProperties(
-    obj: Record<string, any>,
+    obj: Record<string, unknown>,
     requiredProps: string[],
     fieldName = "object"
   ): void {

package/tsup.config.ts

@@ -11,7 +11,7 @@ export default defineConfig({
     index: "src/index.ts",
   },
   format: ["esm"],
-  target: "node18",
+  target: "node20",
   outDir: "../../dist/cli",
   clean: true,
   sourcemap: true,