feat(graceful-shutdown): 实现优雅退出机制

添加全局优雅退出管理器，处理未捕获异常和信号事件
在退出时自动清理后台进程、MCP连接和Hook资源

Author: huzijie.sea

CODE_OF_CONDUCT.md

@@ -0,0 +1,81 @@
+# Code of Conduct
+
+## Our Pledge
+
+As members, contributors, and maintainers, we pledge to make participation in this
+project and our community a harassment-free experience for everyone, regardless of
+age, body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, caste, color, religion, or
+sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+### Examples of positive behavior include:
+
+- Using welcoming and inclusive language
+- Respecting different viewpoints and experiences
+- Accepting constructive criticism gracefully
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+- Making constructive contributions to AI- and development-related discussions
+
+### Examples of unacceptable behavior include:
+
+- **Hate speech**: derogatory or threatening comments toward a group, especially
+  based on race, religion, gender, sexual orientation, or other protected traits
+- **Discriminatory language**: slurs, offensive comments, or demeaning jokes
+- **Personal attacks**: insults or hostile comments directed at individuals
+- **Harassment**: intimidation, stalking, following, or threatening others
+- **Doxxing**: publishing others’ private information without permission
+- **Spam**: excessive off-topic content, promotion, or repetitive posts
+- **Trolling**: deliberate provocation or disruptive behavior
+- **Sexual harassment**: unwelcome sexual attention or advances
+
+## Enforcement
+
+### Reporting
+
+If you experience or witness unacceptable behavior, you can report it by:
+
+- Creating an issue with the `moderation` label
+- Contacting the repository maintainers directly
+- Using GitHub’s built-in reporting tools
+
+### Consequences
+
+Project maintainers will follow these general guidelines when determining
+consequences:
+
+1. **Warning** – for a first or minor offense
+2. **Temporary restriction** – temporary loss of interaction privileges
+3. **Permanent ban** – for severe or repeated violations
+
+### Enforcement Actions
+
+- **Immediate removal** – hate speech, threats, or doxxing may result in
+  immediate content removal and bans
+- **Closing Issues/PRs** – inappropriate content may be closed and locked
+- **Account bans** – repeat offenders may be banned from the repository
+
+## Scope
+
+This Code of Conduct applies to all project spaces, including but not limited to:
+
+- Issues and Pull Requests
+- Discussions and comments
+- Wiki and documentation
+- Public representation of the project
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.
+
+## Contact
+
+For questions or concerns about this Code of Conduct, please contact the
+repository maintainers via GitHub Issues or Discussions.

src/blade.tsx

@@ -21,6 +21,7 @@ import { handlePrintMode } from './commands/print.js';
 import { updateCommands } from './commands/update.js';
 import { getConfigService } from './config/index.js';
 import { Logger } from './logging/Logger.js';
+import { initializeGracefulShutdown } from './services/GracefulShutdown.js';
 import { AppWrapper as BladeApp } from './ui/App.js';
 
 // ⚠️ 关键：在创建任何 logger 之前，先解析 --debug 参数并设置全局配置
@@ -35,6 +36,9 @@ if (debugIndex !== -1) {
 }
 
 export async function main() {
+  // 初始化优雅退出处理器（捕获 uncaughtException/unhandledRejection/SIGTERM）
+  initializeGracefulShutdown();
+
   // 首先检查是否是 print 模式
   if (await handlePrintMode()) {
     return;

src/mcp/McpRegistry.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'events';
-import type { Tool } from '../tools/types/index.js';
 import type { McpServerConfig } from '../config/types.js';
+import type { Tool } from '../tools/types/index.js';
 import { createMcpTool } from './createMcpTool.js';
 import { McpClient } from './McpClient.js';
 import { McpConnectionStatus, type McpToolDefinition } from './types.js';
@@ -139,7 +139,7 @@ export class McpRegistry extends EventEmitter {
     const nameConflicts = new Map<string, number>();
 
     // 第一遍：检测冲突
-    for (const [serverName, serverInfo] of this.servers) {
+    for (const [_serverName, serverInfo] of this.servers) {
       if (serverInfo.status === McpConnectionStatus.CONNECTED) {
         for (const mcpTool of serverInfo.tools) {
           const count = nameConflicts.get(mcpTool.name) || 0;
@@ -348,4 +348,25 @@ export class McpRegistry extends EventEmitter {
       isDiscovering: this.isDiscovering,
     };
   }
+
+  /**
+   * 断开所有 MCP 服务器连接
+   * 在应用退出时调用
+   */
+  async disconnectAll(): Promise<void> {
+    const disconnectPromises: Promise<void>[] = [];
+
+    for (const [name, serverInfo] of this.servers) {
+      if (serverInfo.status === McpConnectionStatus.CONNECTED) {
+        disconnectPromises.push(
+          serverInfo.client.disconnect().catch((error) => {
+            console.warn(`断开 MCP 服务器 "${name}" 时出错:`, error);
+          })
+        );
+      }
+    }
+
+    await Promise.allSettled(disconnectPromises);
+    this.servers.clear();
+  }
 }

src/services/GracefulShutdown.ts

@@ -0,0 +1,227 @@
+/**
+ * 优雅退出管理器
+ *
+ * 负责：
+ * 1. 全局崩溃捕获 (uncaughtException/unhandledRejection)
+ * 2. 信号处理 (SIGINT/SIGTERM)
+ * 3. 资源清理和会话保存
+ */
+
+import { createLogger, LogCategory } from '../logging/Logger.js';
+
+const logger = createLogger(LogCategory.SERVICE);
+
+/** 清理函数类型 */
+type CleanupHandler = () => void | Promise<void>;
+
+/** 退出原因 */
+type ExitReason =
+  | 'uncaughtException'
+  | 'unhandledRejection'
+  | 'SIGINT'
+  | 'SIGTERM'
+  | 'normal';
+
+/**
+ * 优雅退出管理器
+ * 单例模式，确保全局只有一个实例处理退出逻辑
+ */
+class GracefulShutdownManager {
+  private static instance: GracefulShutdownManager | null = null;
+
+  private cleanupHandlers: CleanupHandler[] = [];
+  private isShuttingDown = false;
+  private initialized = false;
+
+  private constructor() {}
+
+  static getInstance(): GracefulShutdownManager {
+    if (!GracefulShutdownManager.instance) {
+      GracefulShutdownManager.instance = new GracefulShutdownManager();
+    }
+    return GracefulShutdownManager.instance;
+  }
+
+  /**
+   * 初始化全局错误处理器
+   * 应该在应用启动时调用一次
+   */
+  initialize(): void {
+    if (this.initialized) {
+      logger.debug('[GracefulShutdown] 已初始化，跳过重复初始化');
+      return;
+    }
+
+    // 捕获未处理的异常
+    process.on('uncaughtException', (error: Error) => {
+      this.handleFatalError('uncaughtException', error);
+    });
+
+    // 捕获未处理的 Promise 拒绝
+    process.on('unhandledRejection', (reason: unknown) => {
+      const error = reason instanceof Error ? reason : new Error(String(reason));
+      this.handleFatalError('unhandledRejection', error);
+    });
+
+    // 处理 SIGTERM（通常由进程管理器发送，如 Docker、PM2）
+    process.on('SIGTERM', () => {
+      logger.info('[GracefulShutdown] 收到 SIGTERM 信号');
+      this.shutdown('SIGTERM', 0);
+    });
+
+    // 注意：SIGINT 由 useCtrlCHandler 处理，这里不重复处理
+    // 但如果是非 UI 模式（如 print 模式），需要处理 SIGINT
+    if (process.env.BLADE_NON_INTERACTIVE === 'true') {
+      process.on('SIGINT', () => {
+        logger.info('[GracefulShutdown] 收到 SIGINT 信号（非交互模式）');
+        this.shutdown('SIGINT', 0);
+      });
+    }
+
+    this.initialized = true;
+    logger.debug('[GracefulShutdown] 全局错误处理器已初始化');
+  }
+
+  /**
+   * 注册清理函数
+   * 在退出时按注册的逆序执行（后注册的先执行）
+   */
+  registerCleanup(handler: CleanupHandler): () => void {
+    this.cleanupHandlers.push(handler);
+    logger.debug(
+      `[GracefulShutdown] 注册清理函数，当前共 ${this.cleanupHandlers.length} 个`
+    );
+
+    // 返回取消注册的函数
+    return () => {
+      const index = this.cleanupHandlers.indexOf(handler);
+      if (index !== -1) {
+        this.cleanupHandlers.splice(index, 1);
+        logger.debug(
+          `[GracefulShutdown] 取消注册清理函数，剩余 ${this.cleanupHandlers.length} 个`
+        );
+      }
+    };
+  }
+
+  /**
+   * 处理致命错误
+   */
+  private handleFatalError(type: ExitReason, error: Error): void {
+    // 防止递归错误
+    if (this.isShuttingDown) {
+      console.error(`[GracefulShutdown] 退出过程中发生额外错误 (${type}):`, error);
+      return;
+    }
+
+    console.error('');
+    console.error('═'.repeat(60));
+    console.error(`💥 发生未捕获的错误 (${type})`);
+    console.error('═'.repeat(60));
+    console.error('');
+    console.error('错误信息:', error.message);
+    console.error('');
+    if (error.stack) {
+      console.error('堆栈跟踪:');
+      console.error(error.stack);
+    }
+    console.error('');
+    console.error('═'.repeat(60));
+    console.error('');
+
+    // 执行清理并退出
+    this.shutdown(type, 1);
+  }
+
+  /**
+   * 执行优雅退出
+   */
+  async shutdown(reason: ExitReason, exitCode: number = 0): Promise<void> {
+    if (this.isShuttingDown) {
+      logger.debug('[GracefulShutdown] 已在退出过程中，跳过重复退出');
+      return;
+    }
+
+    this.isShuttingDown = true;
+
+    logger.info(`[GracefulShutdown] 开始优雅退出 (原因: ${reason})`);
+
+    // 设置超时保护，防止清理函数卡住
+    const timeoutMs = 5000;
+    const timeoutPromise = new Promise<void>((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`清理超时 (${timeoutMs}ms)`));
+      }, timeoutMs);
+    });
+
+    try {
+      // 按逆序执行清理函数（后注册的先执行）
+      const cleanupPromise = this.runCleanupHandlers();
+
+      await Promise.race([cleanupPromise, timeoutPromise]);
+
+      logger.info('[GracefulShutdown] 所有清理函数执行完成');
+    } catch (error) {
+      console.error('[GracefulShutdown] 清理过程中发生错误:', error);
+    } finally {
+      // 给 Ink 一点时间完成终端清理
+      setTimeout(() => {
+        process.exit(exitCode);
+      }, 100);
+    }
+  }
+
+  /**
+   * 执行所有清理函数
+   */
+  private async runCleanupHandlers(): Promise<void> {
+    // 逆序执行
+    const handlers = [...this.cleanupHandlers].reverse();
+
+    for (const handler of handlers) {
+      try {
+        const result = handler();
+        if (result instanceof Promise) {
+          await result;
+        }
+      } catch (error) {
+        console.error('[GracefulShutdown] 清理函数执行失败:', error);
+        // 继续执行其他清理函数
+      }
+    }
+  }
+
+  /**
+   * 检查是否正在退出
+   */
+  isExiting(): boolean {
+    return this.isShuttingDown;
+  }
+
+  /**
+   * 重置状态（仅用于测试）
+   */
+  reset(): void {
+    this.isShuttingDown = false;
+    this.cleanupHandlers = [];
+    this.initialized = false;
+  }
+}
+
+// 导出单例获取函数
+export const getGracefulShutdown = (): GracefulShutdownManager => {
+  return GracefulShutdownManager.getInstance();
+};
+
+// 导出便捷函数
+export const registerCleanup = (handler: CleanupHandler): (() => void) => {
+  return getGracefulShutdown().registerCleanup(handler);
+};
+
+export const initializeGracefulShutdown = (): void => {
+  getGracefulShutdown().initialize();
+};
+
+export const isExiting = (): boolean => {
+  return getGracefulShutdown().isExiting();
+};

src/tools/builtin/shell/BackgroundShellManager.ts

@@ -199,4 +199,24 @@ export class BackgroundShellManager {
       signal: processInfo.signal,
     };
   }
+
+  /**
+   * 终止所有后台进程
+   * 在应用退出时调用
+   */
+  killAll(): void {
+    for (const [_shellId, processInfo] of this.processes) {
+      if (processInfo.status === 'running' && processInfo.process) {
+        try {
+          processInfo.process.kill('SIGTERM');
+          processInfo.status = 'killed';
+          processInfo.endTime = Date.now();
+          processInfo.process = undefined;
+        } catch {
+          // 忽略终止失败（进程可能已退出）
+        }
+      }
+    }
+    this.processes.clear();
+  }
 }