@ai-setting/roy-agent-cli 1.0.0

package/src/commands/shared/event-handler.ts

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview Event Handler
+ * 
+ * 管理环境事件的订阅、队列和处理
+ */
+
+import type { BaseEnvironment, EnvEvent } from "@ai-setting/roy-agent-core";
+import { EventMessageFormatter } from "./event-message-formatter";
+
+/**
+ * EventHandler 配置选项
+ */
+export interface EventHandlerOptions {
+  /** 环境实例 */
+  env: BaseEnvironment;
+  /** 监听的事件类型（支持通配符，如 'task.*'） */
+  eventTypes: string[];
+  /** 事件消息触发回调 */
+  onEvent: (message: string) => Promise<void>;
+  /** 消息格式化器 */
+  formatter?: EventMessageFormatter;
+  /** 检查 agent 是否空闲 */
+  isIdle?: () => boolean;
+  /** 空闲检查间隔（毫秒） */
+  idleCheckInterval?: number;
+}
+
+/**
+ * 事件处理器
+ * 
+ * 订阅环境事件，格式化后通过队列管理，agent 空闲时触发处理
+ */
+export class EventHandler {
+  private env: BaseEnvironment;
+  private eventTypes: string[];
+  private onEvent: (message: string) => Promise<void>;
+  private formatter: EventMessageFormatter;
+  private isIdle: () => boolean;
+  private idleCheckInterval: number;
+  
+  private queue: string[] = [];
+  private isProcessing = false;
+  private isStopped = false;
+  private unsubscribe: (() => void) | null = null;
+
+  constructor(options: EventHandlerOptions) {
+    this.env = options.env;
+    this.eventTypes = options.eventTypes;
+    this.onEvent = options.onEvent;
+    this.formatter = options.formatter ?? new EventMessageFormatter();
+    this.isIdle = options.isIdle ?? (() => true);  // 默认认为总是空闲
+    this.idleCheckInterval = options.idleCheckInterval ?? 100;
+  }
+
+  /**
+   * 启动事件处理
+   * @returns 取消订阅函数
+   */
+  start(): () => void {
+    this.isStopped = false;
+    
+    // 使用 subscribeAll 接收所有事件，然后在 handler 中过滤类型
+    // 因为 subscribeTo 不支持通配符模式
+    this.unsubscribe = this.env.subscribeAll((event: EnvEvent) => {
+      // 检查事件类型是否匹配
+      if (this.matchesEventType(event.type)) {
+        this.handleEvent(event);
+      }
+    });
+
+    return () => this.stop();
+  }
+
+  /**
+   * 检查事件类型是否匹配
+   */
+  private matchesEventType(eventType: string): boolean {
+    for (const pattern of this.eventTypes) {
+      if (this.matchPattern(eventType, pattern)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * 通配符模式匹配
+   * 支持:
+   * - "task.*" 匹配 "task.started", "task.completed" 等
+   * - "task.started" 精确匹配
+   */
+  private matchPattern(eventType: string, pattern: string): boolean {
+    if (pattern === "*") return true;
+    
+    if (pattern.endsWith(".*")) {
+      const prefix = pattern.slice(0, -2);
+      return eventType === prefix || eventType.startsWith(prefix + ".");
+    }
+    
+    return eventType === pattern;
+  }
+
+  /**
+   * 停止事件处理
+   */
+  stop(): void {
+    this.isStopped = true;
+    
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+    
+    // 清空队列
+    this.queue = [];
+    this.isProcessing = false;
+  }
+
+  /**
+   * 处理收到的事件
+   */
+  private handleEvent(event: EnvEvent): void {
+    // 如果已停止，忽略事件
+    if (this.isStopped) {
+      return;
+    }
+    
+    // 格式化事件为用户消息
+    const message = this.formatter.format(event);
+    
+    // 加入队列
+    this.enqueue(message);
+  }
+
+  /**
+   * 将消息加入队列
+   */
+  enqueue(message: string): void {
+    // 如果已停止，忽略
+    if (this.isStopped) {
+      return;
+    }
+    
+    this.queue.push(message);
+    
+    // 如果没有在处理，触发处理
+    if (!this.isProcessing) {
+      this.processQueue();
+    }
+  }
+
+  /**
+   * 获取队列长度
+   */
+  getQueueLength(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * 检查队列是否为空
+   */
+  isQueueEmpty(): boolean {
+    return this.queue.length === 0;
+  }
+
+  /**
+   * 处理队列中的消息（使用 while 循环避免递归栈溢出）
+   */
+  private async processQueue(): Promise<void> {
+    this.isProcessing = true;
+    
+    while (!this.isStopped && this.queue.length > 0) {
+      // 等待 agent 空闲
+      await this.waitForIdle();
+      
+      // 如果已停止，退出循环
+      if (this.isStopped) {
+        break;
+      }
+      
+      // 取出队首消息
+      const message = this.queue.shift();
+      if (!message) {
+        break;
+      }
+
+      try {
+        // 触发事件处理
+        await this.onEvent(message);
+      } catch (error) {
+        console.error(`[EventHandler] 处理事件失败:`, error);
+      }
+    }
+    
+    this.isProcessing = false;
+  }
+
+  /**
+   * 等待 agent 空闲
+   */
+  private async waitForIdle(): Promise<void> {
+    while (!this.isStopped && !this.isIdle()) {
+      await this.sleep(this.idleCheckInterval);
+    }
+  }
+
+  /**
+   * 睡眠工具函数
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}

package/src/commands/shared/event-message-formatter.ts

@@ -0,0 +1,295 @@
+/**
+ * @fileoverview Event Message Formatter
+ * 
+ * 将 EnvEvent 格式化为用户可读的消息
+ */
+
+import type { EnvEvent } from "@ai-setting/roy-agent-core";
+
+// ============================================================================
+// Event Type Mapping
+// ============================================================================
+
+/**
+ * 任务事件类型
+ */
+export const TaskEventTypes = {
+  TASK_STARTED: "task.started",
+  TASK_PROGRESS: "task.progress",
+  TASK_COMPLETED: "task.completed",
+  TASK_FAILED: "task.failed",
+  TASK_TIMEOUT: "task.timeout",
+  TASK_STOPPED: "task.stopped",
+} as const;
+
+/**
+ * EventSource 事件类型
+ */
+export const EventSourceEventTypes = {
+  EVENT_SOURCE_STARTED: "event-source.started",
+  EVENT_SOURCE_STOPPED: "event-source.stopped",
+  EVENT_SOURCE_EVENT_PREFIX: "event-source.event.",
+} as const;
+
+/**
+ * 事件元信息接口
+ */
+export interface EventMetadata {
+  eventType?: string;
+  appId?: string;
+  chatId?: string;
+  chatType?: string;
+  messageId?: string;
+  messageType?: string;
+  senderId?: string;
+  tenantKey?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * 推荐动作接口
+ */
+export interface RecommendedAction {
+  action: string;
+  replyTo?: {
+    appId?: string;
+    chatId?: string;
+    messageId?: string;
+  };
+  rawCommand?: string;
+}
+
+/**
+ * EventSource 事件负载接口
+ */
+export interface EventSourceEventPayload {
+  sourceId: string;
+  sourceType: string;
+  rawEvent: unknown;
+  message: string;
+  metadata: EventMetadata;
+  recommendedAction?: RecommendedAction;
+  timestamp: number;
+}
+
+/**
+ * 任务事件负载接口
+ */
+export interface TaskEventPayload {
+  taskId: string;
+  subSessionId: string;
+  parentSessionId: string;
+  description: string;
+  subagentType: string;
+  status?: string;
+  progress?: number;
+  progressMessage?: string;
+  result?: string;
+  error?: string;
+  executionTimeMs?: number;
+  associatedTaskId?: number;
+}
+
+/**
+ * 格式化选项
+ */
+export interface EventMessageFormatterOptions {
+  /** 消息前缀 */
+  prefix?: string;
+  /** 是否显示详细时间 */
+  showTimestamp?: boolean;
+}
+
+// ============================================================================
+// EventMessageFormatter
+// ============================================================================
+
+/**
+ * 事件消息格式化器
+ * 
+ * 将 EnvEvent 转换为用户可读的文本消息
+ */
+export class EventMessageFormatter {
+  private prefix: string;
+  private showTimestamp: boolean;
+
+  constructor(options: EventMessageFormatterOptions = {}) {
+    this.prefix = options.prefix ?? "[通知]";
+    this.showTimestamp = options.showTimestamp ?? false;
+  }
+
+  /**
+   * 格式化事件为用户消息
+   */
+  format(event: EnvEvent): string {
+    const { type, payload } = event;
+    
+    // 根据事件类型格式化
+    switch (type) {
+      case TaskEventTypes.TASK_STARTED:
+        return this.formatTaskStarted(payload as TaskEventPayload);
+      case TaskEventTypes.TASK_PROGRESS:
+        return this.formatTaskProgress(payload as TaskEventPayload);
+      case TaskEventTypes.TASK_COMPLETED:
+        return this.formatTaskCompleted(payload as TaskEventPayload);
+      case TaskEventTypes.TASK_FAILED:
+        return this.formatTaskFailed(payload as TaskEventPayload);
+      case TaskEventTypes.TASK_TIMEOUT:
+        return this.formatTaskTimeout(payload as TaskEventPayload);
+      case TaskEventTypes.TASK_STOPPED:
+        return this.formatTaskStopped(payload as TaskEventPayload);
+      case EventSourceEventTypes.EVENT_SOURCE_STARTED:
+        return this.formatEventSourceStarted(payload as EventSourceEventPayload);
+      case EventSourceEventTypes.EVENT_SOURCE_STOPPED:
+        return this.formatEventSourceStopped(payload as EventSourceEventPayload);
+      default:
+        // 处理 event-source.event.* 类型的事件
+        if (type.startsWith(EventSourceEventTypes.EVENT_SOURCE_EVENT_PREFIX)) {
+          return this.formatEventSourceEvent(event);
+        }
+        return this.formatGeneric(event);
+    }
+  }
+
+  /**
+   * 格式化任务开始事件
+   */
+  private formatTaskStarted(payload: TaskEventPayload): string {
+    const desc = payload.description || "未命名任务";
+    return `${this.prefix} 📢 后台任务「${desc}」已启动`;
+  }
+
+  /**
+   * 格式化任务进度事件
+   */
+  private formatTaskProgress(payload: TaskEventPayload): string {
+    const desc = payload.description || "未命名任务";
+    const progress = payload.progress !== undefined ? `${payload.progress}%` : "";
+    const message = payload.progressMessage || "";
+    
+    let result = `${this.prefix} 🔄 后台任务「${desc}」进度更新`;
+    if (progress) result += `: ${progress}`;
+    if (message) result += ` - ${message}`;
+    
+    return result;
+  }
+
+  /**
+   * 格式化任务完成事件
+   */
+  private formatTaskCompleted(payload: TaskEventPayload): string {
+    const desc = payload.description || "未命名任务";
+    const result = payload.result;
+    const time = payload.executionTimeMs ? `(${this.formatDuration(payload.executionTimeMs)})` : "";
+    
+    let message = `${this.prefix} ✅ 后台任务「${desc}」已完成 ${time}`;
+    if (result) {
+      // 截断过长结果
+      const truncatedResult = result.length > 100 
+        ? result.substring(0, 100) + "..." 
+        : result;
+      message += `\n结果: ${truncatedResult}`;
+    }
+    
+    return message;
+  }
+
+  /**
+   * 格式化任务失败事件
+   */
+  private formatTaskFailed(payload: TaskEventPayload): string {
+    const desc = payload.description || "未命名任务";
+    const error = payload.error || "未知错误";
+    const time = payload.executionTimeMs ? `(${this.formatDuration(payload.executionTimeMs)})` : "";
+    
+    let message = `${this.prefix} ❌ 后台任务「${desc}」失败 ${time}`;
+    if (error) {
+      // 截断过长错误信息
+      const truncatedError = error.length > 100 
+        ? error.substring(0, 100) + "..." 
+        : error;
+      message += `\n错误: ${truncatedError}`;
+    }
+    
+    return message;
+  }
+
+  /**
+   * 格式化任务超时事件
+   */
+  private formatTaskTimeout(payload: TaskEventPayload): string {
+    const desc = payload.description || "未命名任务";
+    const time = payload.executionTimeMs ? `(${this.formatDuration(payload.executionTimeMs)})` : "";
+    
+    return `${this.prefix} ⏱️ 后台任务「${desc}」超时 ${time}`;
+  }
+
+  /**
+   * 格式化任务停止事件
+   */
+  private formatTaskStopped(payload: TaskEventPayload): string {
+    const desc = payload.description || "未命名任务";
+    const time = payload.executionTimeMs ? `(${this.formatDuration(payload.executionTimeMs)})` : "";
+    
+    return `${this.prefix} 🛑 后台任务「${desc}」已停止 ${time}`;
+  }
+
+  /**
+   * 格式化通用事件
+   */
+  private formatGeneric(event: EnvEvent): string {
+    return `${this.prefix} 收到事件: ${event.type}`;
+  }
+
+  // ============================================================================
+  // EventSource 事件格式化
+  // ============================================================================
+
+  /**
+   * 格式化事件源启动事件
+   */
+  private formatEventSourceStarted(payload: EventSourceEventPayload): string {
+    return `${this.prefix} 📡 事件源「${payload.sourceId}」(类型: ${payload.sourceType}) 已启动`;
+  }
+
+  /**
+   * 格式化事件源停止事件
+   */
+  private formatEventSourceStopped(payload: EventSourceEventPayload): string {
+    return `${this.prefix} 📡 事件源「${payload.sourceId}」(类型: ${payload.sourceType}) 已停止`;
+  }
+
+  /**
+   * 格式化事件源收到的事件（如飞书消息）
+   * 
+   * 泛化处理：直接序列化事件为可读文本，不依赖特定字段
+   */
+  private formatEventSourceEvent(event: EnvEvent): string {
+    const payload = event.payload as any;
+    const sourceType = payload?.sourceType || "unknown";
+    const message = payload?.message || "";
+    
+    // 直接使用 EventSourceComponent 格式化好的 message
+    if (message) {
+      return `[${sourceType}] ${message}`;
+    }
+    
+    // 如果没有预格式化的 message，整个事件序列化
+    return `[${sourceType}] ${JSON.stringify(payload, null, 2)}`;
+  }
+
+  // ============================================================================
+  // 辅助方法
+  // ============================================================================
+
+  /**
+   * 格式化时长
+   */
+  private formatDuration(ms: number): string {
+    if (ms < 1000) return `${ms}ms`;
+    if (ms < 60000) return `${(ms / 1000).toFixed(1)}秒`;
+    const minutes = Math.floor(ms / 60000);
+    const seconds = Math.floor((ms % 60000) / 1000);
+    return `${minutes}分${seconds}秒`;
+  }
+}

package/src/commands/shared/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Shared modules for CLI commands
+ * 
+ * 导出共享模块供 act、interactive 等命令复用
+ */
+
+export { SessionManager } from "./session-manager";
+export type { SessionInitResult, SessionManagerOptions } from "./session-manager";
+
+export { QueryExecutor } from "./query-executor";
+export type { QueryExecutorOptions, StreamOptions } from "./query-executor";