@ai-setting/roy-agent-cli 1.0.0

package/src/services/context-handler.service.ts

@@ -0,0 +1,372 @@
+/**
+ * @fileoverview Context Handler Service
+ * 
+ * 处理 env.handle_query 的上下文阈值检测和压缩逻辑
+ * 
+ * 功能：
+ * 1. 包装 handle_query，捕获 ContextError
+ * 2. 两阶段自动压缩：
+ *    - 阶段1: 调用 SessionComponent.generateCompactHint() 生成场景化提示
+ *    - 阶段2: 调用 SessionComponent.compact() 并传入 scenarioHint
+ * 3. 用 checkpoint 构造新 query 并重试
+ * 4. 生成 trace id 用于调用链追踪
+ */
+
+import type { Environment, AgentContext } from "@ai-setting/roy-agent-core";
+import type { SessionComponent, SessionCheckpoint } from "@ai-setting/roy-agent-core";
+import { 
+  ContextError, 
+  ErrorCodes, 
+  getTracerProvider, 
+  type OTelTracer,
+  TracedAs,
+} from "@ai-setting/roy-agent-core";
+import { createLogger } from "@ai-setting/roy-agent-core";
+
+// 创建 logger
+const logger = createLogger("context-handler");
+
+export interface CompactResult {
+  success: boolean;
+  checkpoint?: SessionCheckpoint;
+  newQuery?: string;
+  error?: string;
+}
+
+export interface HandleQueryOptions {
+  /** 最大重试次数（compact 后） */
+  maxRetries?: number;
+  /** 是否自动压缩 */
+  autoCompact?: boolean;
+}
+
+/**
+ * Context Handler Service
+ * 
+ * 处理 env.handle_query 的上下文阈值检测和压缩逻辑
+ * 
+ * 采用两阶段自动压缩流程：
+ * - 阶段1: 根据历史消息生成场景化的压缩提示 (generateCompactHint)
+ * - 阶段2: 使用生成的提示进行实际的压缩 (compact with scenarioHint)
+ */
+export class ContextHandlerService {
+  private readonly maxRetries: number;
+  private readonly autoCompact: boolean;
+  private tracer?: OTelTracer;
+
+  constructor(
+    private env: Environment,
+    private sessionComponent: SessionComponent,
+    options: HandleQueryOptions = {}
+  ) {
+    this.maxRetries = options.maxRetries ?? 1;
+    this.autoCompact = options.autoCompact ?? true;
+    
+    // 初始化 tracer
+    this.initializeTracer();
+  }
+
+  /**
+   * 初始化 tracer
+   */
+  private initializeTracer(): void {
+    try {
+      this.tracer = getTracerProvider().getTracer("roy-tracer");
+    } catch {
+      // Tracer 可能尚未初始化，延迟初始化
+      this.tracer = undefined;
+    }
+  }
+
+  /**
+   * 获取 tracer 实例
+   */
+  private getTracerInstance(): OTelTracer | undefined {
+    if (!this.tracer) {
+      try {
+        this.tracer = getTracerProvider().getTracer("roy-tracer");
+      } catch {
+        return undefined;
+      }
+    }
+    return this.tracer;
+  }
+
+  /**
+   * 包装 handle_query，添加上下文阈值处理和 trace 追踪
+   */
+  async handleQueryWithContext(
+    query: string,
+    context?: AgentContext
+  ): Promise<string> {
+    // 从 metadata 获取 trace id（如果上层已设置）
+    const traceId = (context?.metadata as Record<string, unknown>)?.traceId as string;
+    const sessionId = context?.sessionId;
+    
+    // 获取 tracer 实例并启动根 span
+    const tracer = this.getTracerInstance();
+    const span = tracer?.startSpan("handleQueryWithContext", {
+      attributes: {
+        query: query.substring(0, 200),
+        sessionId,
+        traceId,
+      },
+    });
+
+    let lastError: Error | undefined;
+
+    try {
+      for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+        try {
+          // 正常执行 handle_query
+          const result = await this.env.handle_query(query, context);
+          
+          // 结束根 span（成功）
+          if (span) {
+            span?.end(result);
+          }
+          
+          return result;
+
+        } catch (error) {
+          // 检查是否是上下文阈值异常
+          if (error instanceof ContextError && error.code === ErrorCodes.CONTEXT_THRESHOLD_EXCEEDED) {
+            lastError = error;
+
+            if (attempt >= this.maxRetries) {
+              logger.error("Context threshold exceeded after max retries", { 
+                attempt, 
+                maxRetries: this.maxRetries 
+              });
+              
+              // 结束根 span（失败）
+              if (span) {
+                span?.end(undefined, error as Error);
+              }
+              throw error;
+            }
+
+            if (!this.autoCompact) {
+              logger.warn("Auto compact disabled, propagating error");
+              
+              // 结束根 span（失败）
+              if (span) {
+                span?.end(undefined, error as Error);
+              }
+              throw error;
+            }
+
+            logger.info(`Context threshold exceeded, compacting (attempt ${attempt + 1}/${this.maxRetries + 1})`);
+
+            // 发布阈值即将压缩事件
+            this.env.pushEnvEvent({
+              type: "context.threshold_exceeded",
+              metadata: {
+                sessionId,
+                traceId,
+              },
+              payload: {
+                totalTokens: error.usage?.totalTokens,
+                contextWindow: error.contextWindow,
+                attempt: attempt + 1,
+              },
+            });
+
+            // 执行两阶段压缩
+            const compactResult = await this.compactSessionWithTwoPhases(
+              context?.sessionId,
+              query
+            );
+
+            if (!compactResult.success) {
+              logger.error("Compact failed", { error: compactResult.error });
+              
+              // 结束根 span（失败）
+              if (span) {
+                span?.end(undefined, error as Error);
+              }
+              throw error;
+            }
+
+            // 用新的 query 重试
+            if (compactResult.newQuery) {
+              query = compactResult.newQuery;
+            }
+
+            continue;
+          }
+
+          // 其他错误直接抛出
+          // 结束根 span（失败）
+          if (span) {
+            span?.end(undefined, error as Error);
+          }
+          throw error;
+        }
+      }
+
+      throw lastError ?? new Error("Unexpected exit from handleQueryWithContext");
+    } finally {
+      // 清理 span 上下文
+      if (span) {
+        tracer?.endSpan(span);
+      }
+    }
+  }
+
+  /**
+   * 执行两阶段 session compact
+   * 
+   * 阶段1: 生成场景化压缩提示 (generateCompactHint)
+   * 阶段2: 使用提示进行压缩 (compact with scenarioHint)
+   */
+  @TracedAs("context-handler.compactSessionWithTwoPhases", { recordParams: true, recordResult: true })
+  async compactSessionWithTwoPhases(
+    sessionId?: string,
+    originalQuery?: string
+  ): Promise<CompactResult> {
+    if (!sessionId) {
+      return { success: false, error: "No session ID provided" };
+    }
+
+    try {
+      // 发布压缩开始事件
+      this.env.pushEnvEvent({
+        type: "context.compacting",
+        metadata: { sessionId },
+        payload: { phase: "two-phase" },
+      });
+
+      // ========================================
+      // 阶段1: 生成场景化压缩提示
+      // ========================================
+      let scenarioHint = "";
+      try {
+        scenarioHint = await this.sessionComponent.generateCompactHint(sessionId);
+        logger.info("[Phase 1] Compact hint generated", {
+          sessionId,
+          hintLength: scenarioHint.length,
+          hintPreview: scenarioHint.substring(0, 100),
+        });
+      } catch (hintError) {
+        // 如果生成提示失败，继续使用空提示（不影响主流程）
+        logger.warn("[Phase 1] Hint generation failed, continuing with empty hint", {
+          error: hintError instanceof Error ? hintError.message : String(hintError),
+        });
+        scenarioHint = "";
+      }
+
+      // 发布提示生成完成事件
+      this.env.pushEnvEvent({
+        type: "context.hint_generated",
+        metadata: { sessionId },
+        payload: {
+          hintLength: scenarioHint.length,
+          hintPreview: scenarioHint.substring(0, 200),
+        },
+      });
+
+      // ========================================
+      // 阶段2: 执行实际压缩
+      // ========================================
+      const result = await this.sessionComponent.compact(sessionId, {
+        summary: originalQuery
+          ? `Auto-compacted. Original query: ${originalQuery.substring(0, 200)}${originalQuery.length > 200 ? "..." : ""}`
+          : "Auto-compacted due to context threshold",
+        scenarioHint,  // 传入场景化提示
+      });
+
+      // 发布压缩完成事件
+      this.env.pushEnvEvent({
+        type: "context.compacted",
+        metadata: { sessionId },
+        payload: {
+          checkpointId: result.checkpoint.id,
+          messagesCompacted: result.deletedMessageCount,
+          scenarioHintUsed: !!scenarioHint,
+        },
+      });
+
+      // 构造新 query
+      const newQuery = this.constructQueryWithCheckpoint(
+        result.checkpoint,
+        originalQuery
+      );
+
+      logger.info("[Phase 2] Compact completed", {
+        checkpointId: result.checkpoint.id,
+        deletedMessageCount: result.deletedMessageCount,
+        scenarioHintUsed: !!scenarioHint,
+      });
+
+      return {
+        success: true,
+        checkpoint: result.checkpoint,
+        newQuery,
+      };
+
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.error("Two-phase compact failed", { error: errorMessage });
+
+      return {
+        success: false,
+        error: errorMessage,
+      };
+    }
+  }
+
+  /**
+   * 执行 session compact（兼容旧接口，内部调用两阶段版本）
+   */
+  async compactSession(
+    sessionId?: string,
+    originalQuery?: string
+  ): Promise<CompactResult> {
+    return this.compactSessionWithTwoPhases(sessionId, originalQuery);
+  }
+
+  /**
+   * 用 checkpoint 构造新 query
+   */
+  @TracedAs("context-handler.constructQuery")
+  private constructQueryWithCheckpoint(
+    checkpoint: SessionCheckpoint,
+    originalQuery?: string
+  ): string {
+    const parts: string[] = [];
+
+    parts.push("【会话历史摘要】");
+    parts.push(checkpoint.summary);
+
+    if (checkpoint.processKeyPoints.length > 0) {
+      parts.push("");
+      parts.push("【已完成的工作】");
+      checkpoint.processKeyPoints.forEach((point, i) => {
+        parts.push(`${i + 1}. ${point}`);
+      });
+    }
+
+    if (checkpoint.currentState) {
+      parts.push("");
+      parts.push("【当前状态】");
+      parts.push(checkpoint.currentState);
+    }
+
+    if (checkpoint.nextSteps.length > 0) {
+      parts.push("");
+      parts.push("【待完成的任务】");
+      checkpoint.nextSteps.forEach((step, i) => {
+        parts.push(`${i + 1}. ${step}`);
+      });
+    }
+
+    if (originalQuery) {
+      parts.push("");
+      parts.push("【用户新输入】");
+      parts.push(originalQuery);
+    }
+
+    return parts.join("\n");
+  }
+}

package/src/services/environment.service.commands-prompt.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+import { EnvironmentService } from "./environment.service";
+import { OutputService } from "./output.service";
+
+// 测试命令目录常量（避免污染真实的 ~/.roy-agent/commands）
+const TEST_COMMANDS_DIR = path.join(os.homedir(), ".roy-agent", "commands");
+
+/**
+ * Commands Prompt Integration Test
+ * 
+ * 验证 EnvironmentService 在创建环境时，
+ * 是否正确注册 commands-prompt Hook，
+ * 使得 default prompt 能够动态注入用户命令信息。
+ * 
+ * 注意：这些测试会创建真实的命令在 TEST_COMMANDS_DIR，
+ * 会在 afterEach 中清理测试命令。
+ */
+describe("EnvironmentService Commands Prompt Integration", () => {
+  let tempDir: string;
+  let configPath: string;
+  let outputService: OutputService;
+  let testCmdName: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "roy-env-commands-test-"));
+    configPath = path.join(tempDir, "config.jsonc");
+    
+    // 创建空配置文件，使用测试命令目录
+    await fs.writeFile(configPath, JSON.stringify({
+      "command.userCommandsDir": TEST_COMMANDS_DIR,
+      "command.projectCommandsDir": path.join(tempDir, "project-commands"),
+    }));
+    
+    // 确保测试命令目录存在
+    await fs.mkdir(TEST_COMMANDS_DIR, { recursive: true });
+    
+    // 使用真实的 OutputService（支持 quiet 模式）
+    outputService = new OutputService({ quiet: true });
+    
+    // 使用唯一命令名避免冲突
+    testCmdName = `test-cmd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  });
+
+  afterEach(async () => {
+    // 清理测试创建的命令（只清理测试命令，不清理真实命令如 lark-cli）
+    try {
+      const entries = await fs.readdir(TEST_COMMANDS_DIR);
+      for (const entry of entries) {
+        // 只清理以 test-cmd 开头的测试命令
+        if (entry.startsWith("test-cmd")) {
+          await fs.rm(path.join(TEST_COMMANDS_DIR, entry), { recursive: true, force: true });
+        }
+      }
+    } catch {
+      // 忽略清理错误
+    }
+    
+    // 清理临时目录
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe("registerCommandsPromptHook", () => {
+    it("should inject commands into default prompt via hook", async () => {
+      // 1. 创建环境
+      const envService = new EnvironmentService(outputService);
+      
+      await envService.create({
+        configPath,
+        sessionStorage: { type: "memory" },  // 使用内存存储，避免污染正式数据库
+      });
+
+      try {
+        // 2. 获取 CommandsComponent 并添加命令
+        const commandsComponent = envService.getCommands();
+        expect(commandsComponent).toBeDefined();
+        
+        await commandsComponent!.add({
+          name: testCmdName,
+          target: "/usr/bin/echo",
+          description: "Test command",
+          tips: "Use with args",
+        });
+
+        // 3. 验证命令元信息存在
+        const metaList = await commandsComponent!.getCommandsMeta();
+        const testCmdMeta = metaList.find(m => m.name === testCmdName);
+        expect(testCmdMeta).toBeDefined();
+        expect(testCmdMeta?.description).toBe("Test command");
+        
+        // 4. 验证 renderCommandsSection 方法存在
+        const envServiceAny = envService as any;
+        expect(typeof envServiceAny.renderCommandsSection).toBe("function");
+        
+        // 5. 验证 commands section 渲染正确
+        const section = envServiceAny.renderCommandsSection(metaList);
+        expect(section).toContain("Your Commands Arsenal");
+        expect(section).toContain(`| \`${testCmdName}\` | Test command |`);
+        expect(section).toContain("Run `<command> --help`");
+        
+      } finally {
+        await envService.dispose();
+      }
+    });
+
+    it("should render commands section correctly", async () => {
+      // 验证 renderCommandsSection 逻辑
+      const metaList = [
+        { name: "git", description: "Git version control", tips: "Use --help" },
+        { name: "npm", description: "Node package manager", tips: "Use --help" },
+      ];
+
+      const envService = new EnvironmentService(outputService);
+      
+      // 通过反射获取私有方法（仅用于测试）
+      const renderCommandsSection = (envService as any).renderCommandsSection?.bind(envService);
+      
+      if (renderCommandsSection) {
+        const section = renderCommandsSection(metaList);
+        
+        expect(section).toContain("Your Commands Arsenal");
+        expect(section).toContain("| `git` | Git version control |");
+        expect(section).toContain("| `npm` | Node package manager |");
+        expect(section).toContain("Run `<command> --help`");
+        
+        // 验证按字母顺序排列
+        const gitIndex = section.indexOf("| `git`");
+        const npmIndex = section.indexOf("| `npm`");
+        expect(gitIndex).toBeLessThan(npmIndex);
+      }
+    });
+
+    it("should handle empty command list", async () => {
+      const envService = new EnvironmentService(outputService);
+      
+      // 通过反射获取私有方法
+      const renderCommandsSection = (envService as any).renderCommandsSection?.bind(envService);
+      
+      if (renderCommandsSection) {
+        const section = renderCommandsSection([]);
+        
+        // 空命令列表应该只返回标题（无表格行）
+        expect(section).toContain("Your Commands Arsenal");
+        expect(section).not.toContain("| `");
+      }
+    });
+
+    it("should register commands-prompt hook on environment creation", async () => {
+      const envService = new EnvironmentService(outputService);
+      
+      await envService.create({
+        configPath,
+        sessionStorage: { type: "memory" },  // 使用内存存储，避免污染正式数据库
+      });
+
+      try {
+        // 验证 Hook 已注册（通过日志输出确认）
+        const promptComponent = envService.getEnvironment()?.getComponent("prompt");
+        expect(promptComponent).toBeDefined();
+      } finally {
+        await envService.dispose();
+      }
+    });
+  });
+});