@ai-setting/roy-agent-cli 1.0.0

package/src/commands/shared/query-executor.ts

@@ -0,0 +1,324 @@
+/**
+ * @fileoverview Query Executor - 查询执行共享逻辑
+ * 
+ * 从 act.ts 抽取的查询执行逻辑，供 interactive 复用
+ * 
+ * 功能：
+ * - 初始化 SummaryAgent
+ * - 订阅 LLM/上下文事件
+ * - 流式输出
+ * - ContextHandler 执行
+ * - 支持 abort 流式输出
+ */
+
+import { OutputService } from "../../services/output.service";
+import { StreamOutputService, abortStream, resetStreamAbort } from "../../services/stream-output.service";
+import { ContextHandlerService } from "../../services/context-handler.service";
+import type { 
+  BaseEnvironment, 
+  SessionComponent, 
+  LLMComponent,
+  PromptComponent 
+} from "@ai-setting/roy-agent-core";
+import { ContextError, ErrorCodes, getTracerProvider } from "@ai-setting/roy-agent-core";
+
+export interface QueryExecutorOptions {
+  env: BaseEnvironment;
+  sessionComponent: SessionComponent;
+  output: OutputService;
+  quiet: boolean;
+}
+
+export interface StreamOptions {
+  showReasoning: boolean;
+  showToolCalls: boolean;
+  showToolResults: boolean;
+}
+
+/**
+ * QueryExecutor - 查询执行器
+ * 
+ * 封装查询执行的完整流程
+ */
+export class QueryExecutor {
+  private env: BaseEnvironment;
+  private sessionComponent: SessionComponent;
+  private output: OutputService;
+  private quiet: boolean;
+  private streamService: StreamOutputService | null = null;
+  private unsubscribe: (() => void) | null = null;
+  private streamOptions: StreamOptions = {
+    showReasoning: false,
+    showToolCalls: false,
+    showToolResults: false,
+  };
+  private _pendingContextConfig: { contextWindow: number; thresholdRatio: number } | null = null;
+
+  constructor(options: QueryExecutorOptions) {
+    this.env = options.env;
+    this.sessionComponent = options.sessionComponent;
+    this.output = options.output;
+    this.quiet = options.quiet;
+  }
+
+  /**
+   * 初始化 SummaryAgent（用于 compact）
+   */
+  initSummaryAgent(llmComponent: LLMComponent, promptComponent: PromptComponent): void {
+    this.sessionComponent.setSummaryComponents(promptComponent, llmComponent);
+  }
+
+  /**
+   * 初始化流式输出配置（设置 context window 信息）
+   */
+  initStreamOutput(llmComponent: LLMComponent | null, providerId: string = "minimax"): void {
+    if (llmComponent) {
+      const contextConfig = llmComponent.getContextThresholdConfig(providerId);
+      // 延迟设置：在 subscribeToEvents 时设置
+      this._pendingContextConfig = contextConfig;
+    }
+  }
+
+  /**
+   * 订阅事件（用于流式输出）
+   */
+  subscribeToEvents(options: StreamOptions): void {
+    // 只订阅一次
+    if (this.unsubscribe) {
+      return;
+    }
+
+    this.streamOptions = options;
+    this.streamService = new StreamOutputService(options);
+
+    // 设置 context window 信息
+    if (this._pendingContextConfig) {
+      this.streamService.setContextInfo(
+        this._pendingContextConfig.contextWindow,
+        this._pendingContextConfig.contextWindow * this._pendingContextConfig.thresholdRatio
+      );
+      this._pendingContextConfig = null;
+    }
+
+    this.unsubscribe = this.env.subscribeTo(
+      [
+        "llm.start",
+        "llm.text",
+        "llm.reasoning",
+        "llm.tool_call",
+        "llm.completed",
+        "llm.error",
+        "tool.result",
+        "tool.error",
+        "context.threshold_exceeded",
+        "context.compacting",
+        "context.compacted",
+      ],
+      (event) => this.handleEvent(event)
+    );
+  }
+
+  /**
+   * 处理事件
+   */
+  protected handleEvent(event: any): void {
+    // 工具调用
+    if (event.type === "llm.tool_call" && this.streamOptions.showToolCalls) {
+      const payload = event.payload as any;
+      this.output.log(`🔧 ${payload.toolCall.name}`);
+      return;
+    }
+    if (event.type === "tool.result" && this.streamOptions.showToolResults) {
+      const payload = event.payload as any;
+      const result = payload.result?.output ?? payload.result?.error ?? "无输出";
+      this.output.log(`📤 ${payload.name}: ${String(result).substring(0, 200)}`);
+      return;
+    }
+    if (event.type === "tool.error") {
+      this.output.error(`❌ ${event.payload.toolName}: ${event.payload.error}`);
+      return;
+    }
+
+    // 上下文事件
+    if (event.type === "context.threshold_exceeded" && !this.quiet) {
+      const payload = event.payload as any;
+      this.output.warn(`⚙ 上下文阈值 (${payload.totalTokens}/${payload.contextWindow})`);
+    }
+    if (event.type === "context.compacting" && !this.quiet) {
+      this.output.info("⚙ 压缩中...");
+    }
+    if (event.type === "context.compacted" && !this.quiet) {
+      this.output.success(`✓ 已压缩 (${event.payload.checkpointId})`);
+    }
+
+    // 其他事件交给 streamService
+    this.streamService?.handleEvent(event);
+  }
+
+  /**
+   * 执行查询
+   */
+  async execute(
+    message: string,
+    sessionId: string,
+    streamOptions?: Partial<StreamOptions>,
+    traceId?: string
+  ): Promise<string> {
+    // 合并流式选项
+    const options: StreamOptions = {
+      showReasoning: streamOptions?.showReasoning ?? this.streamOptions.showReasoning,
+      showToolCalls: streamOptions?.showToolCalls ?? this.streamOptions.showToolCalls,
+      showToolResults: streamOptions?.showToolResults ?? this.streamOptions.showToolResults,
+    };
+
+    // 订阅事件（如果尚未订阅）
+    if (!this.unsubscribe) {
+      this.subscribeToEvents(options);
+    }
+
+    if (!this.quiet) {
+      this.output.info(`执行: ${message}`);
+    }
+
+    // 创建 Context Handler
+    const contextHandler = new ContextHandlerService(
+      this.env,
+      this.sessionComponent,
+      { maxRetries: 1, autoCompact: true }
+    );
+
+    // 构建 context（携带 trace id）
+    const context = {
+      sessionId,
+      metadata: {
+        originalQuery: message,
+        traceId,
+      },
+    };
+
+    // ========================================================================
+    // 创建子 span
+    // 
+    // 使用与 interactive.ts 相同的 tracer 实例（roy-tracer）
+    // 这样可以继承 currentContext 中的 traceId
+    // ========================================================================
+    let span: any;
+    const tracer = getTracerProvider().getTracer("roy-tracer");
+    // 获取当前 tracer 的上下文（应该已经包含根 span 的上下文）
+    const currentContext = tracer.getCurrentContext();
+    span = tracer.startSpan("query-executor.execute", {
+      parent: currentContext,
+      attributes: {
+        query: message.substring(0, 200),
+        sessionId,
+      },
+    });
+
+    // 执行查询
+    let result: string;
+    try {
+      result = await contextHandler.handleQueryWithContext(message, context);
+      
+      // 结束 span（成功）
+      if (span) {
+        span.end(result);
+      }
+    } catch (error) {
+      // 结束 span（失败）
+      if (span) {
+        span.setAttribute("error", String(error));
+        span.end(undefined, error instanceof Error ? error : new Error(String(error)));
+      }
+      
+      if (error instanceof ContextError && error.code === ErrorCodes.CONTEXT_THRESHOLD_EXCEEDED) {
+        this.output.error(
+          `上下文阈值超出限制: ${error.usage?.totalTokens}/${error.contextWindow}`
+        );
+        this.output.info(
+          "请手动压缩会话: roy sessions compact " + sessionId
+        );
+      }
+      throw error;
+    } finally {
+      // span 结束由 tracer 自动处理
+    }
+
+    if (!this.quiet) {
+      this.output.success("执行完成");
+    }
+
+    return result;
+  }
+
+  /**
+   * 清理资源
+   */
+  dispose(): void {
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+  }
+
+  /**
+   * 获取流式输出服务的完整文本
+   */
+  getFullText(): string {
+    return this.streamService?.getFullText() ?? "";
+  }
+
+  /**
+   * 手动压缩会话上下文
+   * 
+   * 复用 ContextHandlerService.compactSession 逻辑
+   */
+  async compact(sessionId: string): Promise<{
+    success: boolean;
+    checkpoint?: any;
+    deletedMessageCount?: number;
+    error?: string;
+  }> {
+    try {
+      // 发布压缩开始事件
+      const envCore = this.env.getComponent("core") as any;
+      if (envCore?.pushEnvEvent) {
+        envCore.pushEnvEvent({
+          type: "context.compacting",
+          metadata: { sessionId },
+          payload: {},
+        });
+      }
+
+      // 执行 compact
+      const result = await this.sessionComponent.compact(sessionId, {
+        summary: "Manual compact from interactive mode",
+      });
+
+      // 发布压缩完成事件
+      if (envCore?.pushEnvEvent) {
+        envCore.pushEnvEvent({
+          type: "context.compacted",
+          metadata: { sessionId },
+          payload: {
+            checkpointId: result.checkpoint.id,
+            messagesCompacted: result.deletedMessageCount,
+          },
+        });
+      }
+
+      return {
+        success: true,
+        checkpoint: result.checkpoint,
+        deletedMessageCount: result.deletedMessageCount,
+      };
+
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.output.error(`压缩失败: ${errorMessage}`);
+      return {
+        success: false,
+        error: errorMessage,
+      };
+    }
+  }
+}

package/src/commands/shared/repl-engine.test.ts

@@ -0,0 +1,354 @@
+/**
+ * @fileoverview REPL Engine Test
+ * 
+ * TDD: 测试 REPL 引擎的核心功能
+ */
+
+import { describe, test, expect, vi, beforeEach, afterEach } from "bun:test";
+import * as readline from "readline";
+
+// We'll test the REPL class by testing its interface and logic
+// Since REPL relies on readline which is hard to mock in unit tests,
+// we'll focus on testing the command registry and event handling
+
+interface REPLCommand {
+  name: string;
+  aliases?: string[];
+  description: string;
+  execute: (args: string[]) => Promise<void>;
+}
+
+interface REPLOptions {
+  onExecute: (message: string) => Promise<string>;
+  onStatus: () => { sessionId: string; sessionTitle: string; messageCount: number; tokenCount: number };
+  onSwitchSession: (sessionId: string) => Promise<{ sessionId: string; sessionTitle: string }>;
+  onCompact: () => Promise<void>;
+}
+
+/**
+ * REPLCommandRegistry - 测试 REPL 命令注册逻辑
+ */
+class REPLCommandRegistry {
+  private commands: Map<string, REPLCommand> = new Map();
+  private registeredNames: Set<string> = new Set(); // Track original names for getAllCommands
+
+  registerCommand(command: REPLCommand): void {
+    // Store by lowercase name for case-insensitive lookup
+    const lowerName = command.name.toLowerCase();
+    this.commands.set(lowerName, command);
+    this.registeredNames.add(lowerName);
+    command.aliases?.forEach((alias) => {
+      this.commands.set(alias.toLowerCase(), command);
+    });
+  }
+
+  getCommand(name: string): REPLCommand | undefined {
+    return this.commands.get(name.toLowerCase());
+  }
+
+  getAllCommands(): REPLCommand[] {
+    // Return unique commands by registered names only (not aliases)
+    const uniqueCommands: REPLCommand[] = [];
+    const seen = new Set<REPLCommand>();
+    for (const name of this.registeredNames) {
+      const command = this.commands.get(name);
+      if (command && !seen.has(command)) {
+        uniqueCommands.push(command);
+        seen.add(command);
+      }
+    }
+    return uniqueCommands;
+  }
+
+  hasCommand(name: string): boolean {
+    return this.commands.has(name.toLowerCase());
+  }
+}
+
+describe("REPLCommandRegistry", () => {
+  let registry: REPLCommandRegistry;
+
+  beforeEach(() => {
+    registry = new REPLCommandRegistry();
+  });
+
+  describe("registerCommand()", () => {
+    test("should register command by name", async () => {
+      // Given
+      const executeFn = vi.fn();
+      const command: REPLCommand = {
+        name: "test",
+        description: "Test command",
+        execute: executeFn,
+      };
+
+      // When
+      registry.registerCommand(command);
+
+      // Then
+      expect(registry.hasCommand("test")).toBe(true);
+      expect(registry.getCommand("test")).toBe(command);
+    });
+
+    test("should register command aliases", async () => {
+      // Given
+      const executeFn = vi.fn();
+      const command: REPLCommand = {
+        name: "test",
+        aliases: ["t", "x"],
+        description: "Test command",
+        execute: executeFn,
+      };
+
+      // When
+      registry.registerCommand(command);
+
+      // Then
+      expect(registry.hasCommand("test")).toBe(true);
+      expect(registry.hasCommand("t")).toBe(true);
+      expect(registry.hasCommand("x")).toBe(true);
+      expect(registry.getCommand("t")).toBe(command);
+      expect(registry.getCommand("x")).toBe(command);
+    });
+
+    test("should overwrite existing command with same name", async () => {
+      // Given
+      const executeFn1 = vi.fn();
+      const executeFn2 = vi.fn();
+      registry.registerCommand({
+        name: "test",
+        description: "First",
+        execute: executeFn1,
+      });
+
+      // When
+      registry.registerCommand({
+        name: "test",
+        description: "Second",
+        execute: executeFn2,
+      });
+
+      // Then
+      expect(registry.getCommand("test")?.description).toBe("Second");
+    });
+  });
+
+  describe("getCommand()", () => {
+    test("should find command by exact name", async () => {
+      // Given
+      const command: REPLCommand = {
+        name: "help",
+        description: "Show help",
+        execute: vi.fn(),
+      };
+      registry.registerCommand(command);
+
+      // When & Then
+      expect(registry.getCommand("help")).toBe(command);
+    });
+
+    test("should find command by alias", async () => {
+      // Given
+      const command: REPLCommand = {
+        name: "help",
+        aliases: ["h", "?"],
+        description: "Show help",
+        execute: vi.fn(),
+      };
+      registry.registerCommand(command);
+
+      // When & Then
+      expect(registry.getCommand("h")).toBe(command);
+      expect(registry.getCommand("?")).toBe(command);
+    });
+
+    test("should return undefined for unknown command", async () => {
+      // When & Then
+      expect(registry.getCommand("unknown")).toBeUndefined();
+    });
+
+    test("should be case insensitive", async () => {
+      // Given
+      const command: REPLCommand = {
+        name: "Help",
+        description: "Show help",
+        execute: vi.fn(),
+      };
+      registry.registerCommand(command);
+
+      // When & Then
+      expect(registry.getCommand("help")).toBe(command);
+      expect(registry.getCommand("HELP")).toBe(command);
+    });
+  });
+
+  describe("getAllCommands()", () => {
+    test("should return all unique commands", async () => {
+      // Given
+      registry.registerCommand({
+        name: "cmd1",
+        aliases: ["c1"],
+        description: "Command 1",
+        execute: vi.fn(),
+      });
+      registry.registerCommand({
+        name: "cmd2",
+        aliases: ["c2"],
+        description: "Command 2",
+        execute: vi.fn(),
+      });
+
+      // When
+      const commands = registry.getAllCommands();
+
+      // Then
+      expect(commands.length).toBe(2);
+    });
+  });
+});
+
+/**
+ * REPLOptions Interface Test
+ */
+describe("REPLOptions", () => {
+  test("should require onExecute callback", () => {
+    // Given
+    const mockExecute = vi.fn().mockResolvedValue("response");
+
+    // When
+    const options: REPLOptions = {
+      onExecute: mockExecute,
+      onStatus: () => ({
+        sessionId: "sess_123",
+        sessionTitle: "Test Session",
+        messageCount: 5,
+        tokenCount: 1024,
+      }),
+      onSwitchSession: vi.fn().mockResolvedValue({
+        sessionId: "sess_456",
+        sessionTitle: "New Session",
+      }),
+      onCompact: vi.fn().mockResolvedValue(undefined),
+    };
+
+    // Then
+    expect(options.onExecute).toBeDefined();
+    expect(typeof options.onExecute("test")).toBe("object"); // Promise
+  });
+
+  test("should provide status information", () => {
+    // Given
+    const status = {
+      sessionId: "sess_123",
+      sessionTitle: "Test Session",
+      messageCount: 10,
+      tokenCount: 2048,
+    };
+
+    // When
+    const options: REPLOptions = {
+      onExecute: vi.fn().mockResolvedValue("response"),
+      onStatus: () => status,
+      onSwitchSession: vi.fn(),
+      onCompact: vi.fn(),
+    };
+
+    // Then
+    expect(options.onStatus()).toEqual(status);
+  });
+});
+
+/**
+ * Input Parsing Test
+ */
+describe("Input Parsing", () => {
+  test("should parse command with arguments", () => {
+    // Given
+    const input = "compact --force";
+
+    // When
+    const [command, ...args] = input.split(/\s+/);
+
+    // Then
+    expect(command).toBe("compact");
+    expect(args).toEqual(["--force"]);
+  });
+
+  test("should parse command without arguments", () => {
+    // Given
+    const input = "help";
+
+    // When
+    const [command, ...args] = input.split(/\s+/);
+
+    // Then
+    expect(command).toBe("help");
+    expect(args).toEqual([]);
+  });
+
+  test("should identify slash commands", () => {
+    // Given
+    const slashInput = "/help";
+    const normalInput = "show me something";
+
+    // When & Then
+    expect(slashInput.startsWith("/")).toBe(true);
+    expect(normalInput.startsWith("/")).toBe(false);
+  });
+
+  test("should strip slash prefix", () => {
+    // Given
+    const input = "/exit";
+
+    // When
+    const command = input.slice(1);
+
+    // Then
+    expect(command).toBe("exit");
+  });
+});
+
+/**
+ * Command Execution Flow Test
+ */
+describe("Command Execution Flow", () => {
+  test("should execute registered command", async () => {
+    // Given
+    const executeFn = vi.fn().mockResolvedValue(undefined);
+    const registry = new REPLCommandRegistry();
+    registry.registerCommand({
+      name: "test",
+      description: "Test command",
+      execute: executeFn,
+    });
+
+    // When
+    const command = registry.getCommand("test");
+    if (command) {
+      await command.execute([]);
+    }
+
+    // Then
+    expect(executeFn).toHaveBeenCalledWith([]);
+  });
+
+  test("should pass arguments to command", async () => {
+    // Given
+    const executeFn = vi.fn().mockResolvedValue(undefined);
+    const registry = new REPLCommandRegistry();
+    registry.registerCommand({
+      name: "test",
+      description: "Test command",
+      execute: executeFn,
+    });
+
+    // When
+    const command = registry.getCommand("test");
+    if (command) {
+      await command.execute(["arg1", "arg2"]);
+    }
+
+    // Then
+    expect(executeFn).toHaveBeenCalledWith(["arg1", "arg2"]);
+  });
+});