@ai-setting/roy-agent-core 1.3.9 → 1.3.11

package/src/env/environment.ts

@@ -1,708 +0,0 @@
-/**
- * @fileoverview BaseEnvironment Implementation
- * 
- * Environment 的基础实现类（非抽象），提供：
- * - 组件注册与管理
- * - 核心调度方法（handle_query, handle_action）
- * - EnvEvent 事件机制
- * 
- * 设计原则：
- * 1. Environment 只做两件事：
- *    - 组件管理：持有、注册、获取组件
- *    - 核心调度：handle_query / handle_action / EnvEvent
- * 2. 其他能力归属到对应 Component
- * 
- * 子类可覆盖：
- * - registerDefaultComponents(): 注册默认组件
- * - handle_query(): 查询处理逻辑
- * - handle_action(): 动作处理逻辑
- * - onInit/onStart/onStop: 生命周期钩子
- */
-
-import { BaseComponent, type Component } from "./component";
-import type { 
-  Environment, 
-  ServiceConfig, 
-  ComponentConfigEntry, 
-  GeneratedComponentOptions 
-} from "./interface";
-import type { 
-  EnvironmentConfig,
-  BaseEnvironmentConfig,
-  EnvEvent,
-  EnvEventInput,
-  EnvEventHandler,
-  Action,
-  ToolResult,
-  Context,
-} from "./types";
-import { createLogger } from "./log-trace/logger";
-import { generateId } from "../utils/id";
-import { ContextError, ErrorCodes } from "./errors";
-import * as fsSync from "fs";
-import * as path from "path";
-import { TracedAs } from "./log-trace/decorator";
-
-const logger = createLogger("environment");
-
-/**
- * BaseEnvironment 实现类（非抽象）
- * 
- * 实现 Environment 接口，提供简洁的环境基础功能。
- * 子类可继承此类并覆盖特定方法来自定义行为。
- */
-export class BaseEnvironment extends BaseComponent implements Environment {
-  // ============ 标识 ============
-  
-  readonly name: string;
-  readonly version: string;
-  
-  // ============ 组件管理 ============
-  
-  protected components = new Map<string, Component>();
-
-  /**
-   * 构造函数
-   */
-  constructor(config?: BaseEnvironmentConfig) {
-    super();
-    this.name = config?.name ?? "base-environment";
-    this.version = config?.version ?? "1.0.0";
-    
-    // 注册默认组件
-    this.registerDefaultComponents();
-  }
-
-  /**
-   * 注册默认组件（子类可覆盖）
-   */
-  protected registerDefaultComponents(): void {
-    // 子类可覆盖以注册默认组件
-  }
-
-  /**
-   * 获取环境配置
-   */
-  getConfig(): EnvironmentConfig & { env: Environment } {
-    return {
-      name: this.name,
-      version: this.version,
-      enabled: true,
-      env: this,
-    };
-  }
-
-  // ============ 组件管理 ============
-
-  /**
-   * 注册组件
-   */
-  registerComponent(component: Component): void {
-    this.components.set(component.name, component);
-    logger.debug(`Component registered: ${component.name}`);
-  }
-
-  /**
-   * 注销组件
-   */
-  unregisterComponent(name: string): void {
-    const component = this.components.get(name);
-    if (component) {
-      this.components.delete(name);
-      logger.debug(`Component unregistered: ${name}`);
-    }
-  }
-
-  /**
-   * 获取组件
-   */
-  getComponent<T extends Component>(name: string): T | undefined {
-    return this.components.get(name) as T | undefined;
-  }
-
-  /**
-   * 列出所有组件
-   */
-  listComponents(): Component[] {
-    return Array.from(this.components.values());
-  }
-
-  // ============ 核心能力（子类可覆盖） ============
-
-  /**
-   * 处理自然语言查询（核心入口）
-   * 
-   * 委托给 AgentComponent.run() 处理
-   */
-  @TracedAs("env.handle_query", { recordParams: true, recordResult: true, log: true })
-  async handle_query(
-    query: string,
-    context?: import("./agent/types").AgentContext
-  ): Promise<string> {
-    // 1. 获取 AgentComponent
-    const agentComponent = this.getComponent<import("./agent/agent-component").AgentComponent>("agent");
-    
-    if (!agentComponent) {
-      throw new Error("AgentComponent not found. Please register AgentComponent before calling handle_query.");
-    }
-    
-    // 2. 获取 system prompt（从 PromptComponent 获取）
-    let systemPrompt = "You are a helpful assistant.";
-    let promptSource = "fallback";
-    try {
-      const promptComponent = this.getComponent<import("./prompt/prompt-component").PromptComponent>("prompt");
-      if (promptComponent) {
-        const loadedPrompt = await promptComponent.getPrompt("default");
-        if (loadedPrompt) {
-          systemPrompt = loadedPrompt;
-          promptSource = "PromptComponent";
-        }
-      }
-    } catch (err) {
-      logger.warn(`[handle_query] Failed to get prompt from PromptComponent: ${err}`);
-    }
-    logger.info(`[handle_query] Using system prompt from ${promptSource}, length: ${systemPrompt.length}`);
-
-    // 3. 读取 memory 内容并注入到 prompt（如果 {{memory}} 变量存在）
-    let finalSystemPrompt = systemPrompt;
-    if (systemPrompt.includes("{{memory}}")) {
-      try {
-        const memoryComponent = this.getComponent<import("./memory/memory-component").MemoryComponent>("memory");
-        if (memoryComponent) {
-          const memoryContent = await memoryComponent.recallMemory();
-          finalSystemPrompt = systemPrompt.replace("{{memory}}", memoryContent || "(No memory)");
-          logger.info(`[handle_query] Injected memory content, length: ${memoryContent.length}`);
-        } else {
-          finalSystemPrompt = systemPrompt.replace("{{memory}}", "(Memory component not available)");
-        }
-      } catch (err) {
-        logger.warn(`[handle_query] Failed to load memory content: ${err}`);
-        finalSystemPrompt = systemPrompt.replace("{{memory}}", "(Failed to load memory)");
-      }
-    }
-
-    // 3.1 注入 workspace_dir（当前工作目录）
-    if (finalSystemPrompt.includes("{{workspace_dir}}")) {
-      const workspaceDir = process.cwd();
-      finalSystemPrompt = finalSystemPrompt.replace("{{workspace_dir}}", workspaceDir);
-      logger.debug(`[handle_query] Injected workspace_dir: ${workspaceDir}`);
-    }
-
-    // 4. 根据 agentType 获取或创建 agent
-    // - 如果 context.agentType 为空或 "default"，使用默认 agent
-    // - 否则使用 context.agentType 对应的 agent（delegate-tool 会预先注册）
-    const agentName = (context?.agentType && context.agentType !== "default") 
-      ? context.agentType 
-      : "default";
-    
-    let agent = agentComponent.getAgent(agentName);
-    if (!agent) {
-      // 如果指定了 agentType 但 agent 不存在，使用默认 agent
-      if (agentName !== "default") {
-        logger.warn(`[handle_query] Agent "${agentName}" not found, falling back to "default"`);
-      }
-      agent = agentComponent.getAgent("default");
-    }
-    
-    // 如果默认 agent 也不存在，则创建
-    if (!agent) {
-      agent = agentComponent.registerAgent("default", {
-        type: "primary",
-        systemPrompt: finalSystemPrompt,
-      });
-    }
-    
-    // 执行 agent
-    const result = await agentComponent.run(agent.name, query, context);
-    
-    // 4. 如果有错误，检查是否是 ContextError，需要让上层处理
-    if (result.error) {
-      // 如果错误信息包含上下文阈值相关，抛出 ContextError 让 ContextHandler 处理
-      const errorMsg = result.error.toLowerCase();
-      if (
-        errorMsg.includes("context") ||
-        errorMsg.includes("threshold") ||
-        errorMsg.includes("token") ||
-        result.error.includes("CTX_001")
-      ) {
-        // 尝试从错误消息中提取上下文使用信息
-        // 格式如: "Context threshold exceeded: 1230/10000 (12.3%)"
-        const usageMatch = result.error.match(/(\d+)\/(\d+)\s*\(([\d.]+)%\)/);
-        let usage: { promptTokens: number; completionTokens: number; totalTokens: number } | undefined;
-        let contextWindow: number | undefined;
-        
-        if (usageMatch) {
-          const totalTokens = parseInt(usageMatch[1], 10);
-          usage = { 
-            promptTokens: totalTokens, 
-            completionTokens: 0, 
-            totalTokens 
-          };
-          contextWindow = parseInt(usageMatch[2], 10);
-        }
-        
-        // 构造 ContextError 抛出
-        const ctxError = new ContextError(
-          result.error,
-          ErrorCodes.CONTEXT_THRESHOLD_EXCEEDED,
-          context?.sessionId,
-          usage,
-          contextWindow
-        );
-        throw ctxError;
-      }
-      // 其他错误继续抛出
-      throw new Error(result.error);
-    }
-    
-    // 6. 返回响应文本
-    return result.finalText || "";
-  }
-
-  /**
-   * 处理动作
-   * 
-   * 默认实现抛出错误，子类必须实现。
-   */
-  async handle_action(action: Action, context: Context): Promise<ToolResult> {
-    throw new Error("handle_action not implemented. Override in subclass.");
-  }
-
-  // ============ EnvEvent 机制 ============
-
-  /**
-   * 事件订阅者映射
-   */
-  protected eventHandlers = new Map<string, Set<EnvEventHandler>>();
-
-  /**
-   * 通配符订阅者（接收所有事件）
-   */
-  protected wildcardHandlers = new Set<EnvEventHandler>();
-
-  /**
-   * 订阅 EnvEvent（返回取消订阅函数）
-   */
-  subscribe(handler: EnvEventHandler): () => void {
-    this.wildcardHandlers.add(handler);
-    logger.debug(`EnvEvent handler subscribed (wildcard)`);
-    
-    // 返回取消订阅函数
-    return () => {
-      this.wildcardHandlers.delete(handler);
-      logger.debug(`EnvEvent handler unsubscribed (wildcard)`);
-    };
-  }
-
-  /**
-   * 订阅指定类型事件
-   */
-  subscribeTo(eventType: string | string[], handler: EnvEventHandler): () => void {
-    const types = Array.isArray(eventType) ? eventType : [eventType];
-    
-    for (const type of types) {
-      if (!this.eventHandlers.has(type)) {
-        this.eventHandlers.set(type, new Set());
-      }
-      this.eventHandlers.get(type)!.add(handler);
-    }
-    
-    logger.debug(`EnvEvent handler subscribed for types: ${types.join(", ")}`);
-    
-    // 返回取消订阅函数
-    return () => {
-      for (const type of types) {
-        this.eventHandlers.get(type)?.delete(handler);
-      }
-      logger.debug(`EnvEvent handler unsubscribed for types: ${types.join(", ")}`);
-    };
-  }
-
-  /**
-   * 订阅所有事件（通配符）
-   * 
-   * 与 subscribe 相同，为保持 API 一致性
-   */
-  subscribeAll(handler: EnvEventHandler): () => void {
-    return this.subscribe(handler);
-  }
-
-  /**
-   * 推送事件
-   */
-  pushEnvEvent(event: EnvEvent | EnvEventInput): void {
-    // 如果是完整 EnvEvent，直接使用；否则创建新的
-    const fullEvent: EnvEvent = "id" in event && event.id
-      ? event as EnvEvent
-      : {
-          id: (event as EnvEventInput).id ?? generateId(),
-          type: event.type,
-          timestamp: (event as EnvEventInput).timestamp ?? Date.now(),
-          metadata: {
-            ...(event as EnvEventInput).metadata,
-            env_name: (event as EnvEventInput).metadata?.env_name ?? this.name,
-          },
-          payload: (event as EnvEventInput).payload ?? {},
-        };
-
-    // 通知通配符订阅者
-    for (const handler of this.wildcardHandlers) {
-      try {
-        handler(fullEvent);
-      } catch (error) {
-        logger.error(`Error in EnvEvent handler: ${error}`);
-      }
-    }
-
-    // 通知特定类型订阅者
-    const handlers = this.eventHandlers.get(fullEvent.type);
-    if (handlers) {
-      for (const handler of handlers) {
-        try {
-          handler(fullEvent);
-        } catch (error) {
-          logger.error(`Error in EnvEvent handler for ${fullEvent.type}: ${error}`);
-        }
-      }
-    }
-  }
-
-  /**
-   * 创建并推送事件（便捷方法）
-   */
-  protected emit<T = unknown>(
-    type: string,
-    payload: T,
-    metadata?: Partial<EnvEvent["metadata"]>
-  ): void {
-    const event: EnvEvent<T> = {
-      id: generateId(),
-      type,
-      timestamp: Date.now(),
-      metadata: {
-        env_name: this.name,
-        ...metadata,
-      },
-      payload,
-    };
-    this.pushEnvEvent(event);
-  }
-
-  // ============ 生命周期 ============
-
-  /**
-   * 初始化所有组件（分阶段初始化）
-   * 
-   * 1. 第一阶段：初始化 ConfigComponent（如果存在）
-   * 2. 第二阶段：初始化其他组件
-   */
-  protected async initializeComponents(): Promise<void> {
-    logger.debug(`Starting component initialization, total: ${this.components.size}`);
-
-    // 1️⃣ 第一阶段：初始化 ConfigComponent（如果存在）
-    // 特殊处理：直接访问 this.components 因为此时 ConfigComponent 尚未 init
-    // 正常情况下组件应通过 this.env.getComponent() 获取其他已初始化的组件
-    const configComp = this.components.get("config");
-    if (configComp && configComp.getStatus() === "created") {
-      logger.debug(`Initializing ConfigComponent first...`);
-      await configComp.init({
-        name: "config",
-        version: configComp.version,
-        enabled: true,
-        env: this,
-      });
-      logger.debug(`ConfigComponent initialized`);
-    } else {
-      logger.debug(`No ConfigComponent found, skipping first stage`);
-    }
-
-    // 2️⃣ 第二阶段：初始化其他组件
-    const otherComponents = Array.from(this.components.values())
-      .filter(c => c.getStatus() === "created");
-    
-    if (otherComponents.length > 0) {
-      logger.debug(`Initializing ${otherComponents.length} other components...`);
-      for (const component of otherComponents) {
-        logger.debug(`Initializing component: ${component.name}`);
-        await component.init({
-          name: component.name,
-          version: component.version,
-          enabled: true,
-          env: this,
-        });
-        logger.debug(`Component initialized: ${component.name}`);
-      }
-    }
-    
-    logger.debug(`All components initialized`);
-  }
-
-  /**
-   * 启动所有组件
-   * 
-   * 注意：由于 Environment.init() 会将组件状态设为 "running"，我们需要确保
-   * 即使组件已经是 "running" 状态，它们的 start() 方法仍然被调用。
-   * 这是因为 start() 负责注册工具等运行时资源。
-   */
-  protected async startComponents(): Promise<void> {
-    // 启动所有已注册的组件（不检查状态）
-    const allComponents = Array.from(this.components.values());
-    
-    if (allComponents.length > 0) {
-      logger.debug(`Starting ${allComponents.length} components...`);
-      for (const component of allComponents) {
-        logger.debug(`Starting component: ${component.name} (current status: ${component.getStatus()})`);
-        await component.start();
-        logger.debug(`Component started: ${component.name}`);
-      }
-    }
-  }
-
-  /**
-   * 停止所有组件
-   */
-  protected async stopComponents(): Promise<void> {
-    const componentsToStop = Array.from(this.components.values())
-      .filter(c => c.getStatus() !== "stopped");
-    
-    if (componentsToStop.length > 0) {
-      logger.debug(`Stopping ${componentsToStop.length} components...`);
-      for (const component of componentsToStop) {
-        logger.debug(`Stopping component: ${component.name}`);
-        await component.stop();
-        logger.debug(`Component stopped: ${component.name}`);
-      }
-    }
-  }
-
-  /**
-   * 初始化（可覆盖）
-   */
-  protected async onInit(): Promise<void> {
-    await this.initializeComponents();
-    logger.info(`Environment "${this.name}" initialized`);
-  }
-
-  /**
-   * 启动（可覆盖）
-   */
-  protected async onStart(): Promise<void> {
-    await this.startComponents();
-    logger.info(`Environment "${this.name}" started`);
-  }
-
-  /**
-   * 停止（可覆盖）
-   */
-  protected async onStop(): Promise<void> {
-    await this.stopComponents();
-    // 清理事件处理器
-    this.eventHandlers.clear();
-    this.wildcardHandlers.clear();
-    logger.info(`Environment "${this.name}" stopped`);
-  }
-
-  /**
-   * BaseComponent 钩子
-   * 
-   * Environment 特殊处理：它本身就是 env，所以不需要外部传入。
-   * 此方法覆盖 BaseComponent.init()，直接设置自引用。
-   */
-  async init(): Promise<void> {
-    // Environment 特殊处理：设置自引用
-    // 注意：这里需要直接访问 protected env 属性，使用 TypeScript 的原型链访问
-    // 这是唯一需要绕过类型检查的地方，因为 Environment 是特殊情况
-    Object.defineProperty(this, "env", {
-      value: this,
-      writable: true,
-      enumerable: false,
-      configurable: true,
-    });
-    
-    this.setStatus("initializing");
-    await this.onInit();
-    this.setStatus("running");
-  }
-
-  async start(): Promise<void> {
-    // 注意：Environment.init() 会将状态设为 "running"，但组件的 start() 仍需被调用
-    // 所以这里使用一个内部标志来跟踪是否已经启动过
-    if ((this as any)._started) return;
-    (this as any)._started = true;
-    
-    await this.onStart();
-    this.setStatus("running");
-    logger.info(`Environment "${this.name}" started`);
-  }
-
-  async stop(): Promise<void> {
-    this.setStatus("stopping");
-    await this.onStop();
-    this.setStatus("stopped");
-  }
-
-  // ============ 服务配置能力 ============
-
-  /**
-   * 从配置文件加载服务配置
-   */
-  async loadServiceConfig(configPath: string): Promise<ServiceConfig> {
-    // 1. 获取 ConfigComponent
-    const configComponent = this.getComponent<import("../config/config-component").ConfigComponent>("config");
-    if (!configComponent) {
-      throw new Error("ConfigComponent not found. Please register ConfigComponent before loading service config.");
-    }
-
-    // 2. 获取配置目录
-    const xdgDataHome = configComponent.getXdgDataHome();
-    
-    // 3. 读取配置文件
-    const fullPath = path.resolve(xdgDataHome, configPath);
-    if (!fsSync.existsSync(fullPath)) {
-      throw new Error(`Service config file not found: ${fullPath}`);
-    }
-    
-    // 4. 解析配置文件（支持 JSON/JSONC）
-    const content = fsSync.readFileSync(fullPath, "utf-8");
-    let config: ServiceConfig;
-    
-    try {
-      config = JSON.parse(content);
-    } catch (e) {
-      throw new Error(`Failed to parse service config: ${e}`);
-    }
-    
-    logger.debug(`Service config loaded from: ${fullPath}`);
-    return config;
-  }
-
-  /**
-   * 生成组件初始化选项
-   */
-  generateComponentOptions(
-    componentName: string,
-    configEntry: ComponentConfigEntry
-  ): GeneratedComponentOptions {
-    // 1. 获取 ConfigComponent（必填）
-    const configComponent = this.getComponent<import("../config/config-component").ConfigComponent>("config");
-    if (!configComponent) {
-      throw new Error("ConfigComponent not found. Please register ConfigComponent before generating component options.");
-    }
-
-    // 2. 构建选项对象
-    const options: GeneratedComponentOptions = {
-      configComponent,
-      configPath: configEntry.configPath,
-      envPrefix: configEntry.envPrefix,
-      config: configEntry.config,
-    };
-    
-    logger.debug(`Generated options for component: ${componentName}`);
-    return options;
-  }
-
-  /**
-   * 注册组件并用配置初始化
-   */
-  async registerComponentWithConfig(
-    component: Component,
-    configEntry: ComponentConfigEntry
-  ): Promise<void> {
-    // 1. 如果组件未注册，先注册
-    if (!this.components.has(component.name)) {
-      this.registerComponent(component);
-    }
-    
-    // 2. 生成初始化选项
-    const options = this.generateComponentOptions(component.name, configEntry);
-    
-    // 3. 如果组件已初始化，跳过
-    if (component.getStatus() === "running") {
-      logger.debug(`Component ${component.name} already initialized, skipping`);
-      return;
-    }
-    
-    // 4. 初始化组件
-    await component.init({
-      name: component.name,
-      version: component.version,
-      enabled: configEntry.enabled ?? true,
-      env: this,
-      options,
-    });
-    
-    logger.debug(`Component ${component.name} registered and initialized with config`);
-  }
-
-  /**
-   * 从配置文件初始化整个环境
-   */
-  async initFromConfig(configPath: string): Promise<void> {
-    // 0. 设置 Environment 自引用（如果不尚未设置）
-    if (!(this as any).env) {
-      Object.defineProperty(this, "env", {
-        value: this,
-        writable: true,
-        enumerable: false,
-        configurable: true,
-      });
-    }
-    
-    // 1. 加载服务配置
-    const serviceConfig = await this.loadServiceConfig(configPath);
-    
-    // 2. 更新环境名称和版本（如果配置了）
-    if (serviceConfig.environment) {
-      if (serviceConfig.environment.name) {
-        (this as any).name = serviceConfig.environment.name;
-      }
-      if (serviceConfig.environment.version) {
-        (this as any).version = serviceConfig.environment.version;
-      }
-    }
-    
-    // 3. 确保 ConfigComponent 已注册
-    const configComponent = this.getComponent<import("../config/config-component").ConfigComponent>("config");
-    if (!configComponent) {
-      throw new Error("ConfigComponent not found. Please register ConfigComponent before initFromConfig.");
-    }
-    
-    // 4. 初始化 ConfigComponent
-    if (configComponent.getStatus() === "created") {
-      await configComponent.init({
-        name: "config",
-        version: configComponent.version,
-        enabled: true,
-        env: this,
-      });
-    }
-    
-    // 5. 初始化每个配置的组件
-    const components = serviceConfig.components || {};
-    for (const [componentName, configEntry] of Object.entries(components)) {
-      // 跳过禁用的组件
-      if (configEntry.enabled === false) {
-        logger.debug(`Component ${componentName} is disabled, skipping`);
-        continue;
-      }
-      
-      // 获取组件实例
-      const component = this.getComponent(componentName);
-      if (!component) {
-        logger.warn(`Component ${componentName} not registered, skipping`);
-        continue;
-      }
-      
-      // 跳过 ConfigComponent（已初始化）
-      if (component.name === "config") continue;
-      
-      // 注册并初始化
-      await this.registerComponentWithConfig(component, configEntry);
-    }
-    
-    // 6. 设置环境状态为 running
-    this.setStatus("running");
-    
-    logger.info(`Environment "${this.name}" initialized from config: ${configPath}`);
-  }
-}