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

package/src/env/tool/tool-component.ts

@@ -1,563 +0,0 @@
-import { z } from "zod";
-import {
-  BaseComponent,
-  type ComponentConfig,
-} from "../component";
-import type {
-  Tool,
-  ToolContext,
-  ToolResult,
-  ToolExecuteRequest,
-  ToolListFilter,
-  ToolRegistration,
-} from "./types";
-import { ToolRegistry } from "./registry";
-import { ToolValidator } from "./validator";
-import { createLogger } from "../log-trace/logger";
-import { globalHookManager, ToolHookPoints } from "../hook/global-hook-manager";
-import type { ConfigComponent } from "../../config/config-component";
-import { toEnvKey, envKeyToConfigKey } from "../../config/env-key";
-import { TOOL_CONFIG_REGISTRATION, TOOL_DEFAULTS } from "./tool-config-registration";
-import { AskUserError } from "../workflow/types/workflow-hil";
-
-// 创建日志器
-const logger = createLogger("tool");
-
-// ============================================================================
-// ToolComponentOptions (统一配置机制)
-// ============================================================================
-
-/**
- * ToolComponent 配置选项（通过 options 传递）
- * 
- * 配置加载顺序（优先级从低到高）：
- * 1. File - 配置文件（通过 configPath 指定）
- * 2. Env - 环境变量（通过 envPrefix 配置前缀）
- * 3. Object - 直接传入的 config 对象（最高优先级）
- */
-export interface ToolComponentOptions {
-  /** ConfigComponent 实例（必填） */
-  configComponent: ConfigComponent;
-  
-  /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
-  configPath?: string;
-  
-  /** 环境变量前缀（可选，默认 "TOOL"） */
-  envPrefix?: string;
-  
-  /** 直接传入的配置对象（可选，优先级最高） */
-  config?: Partial<ToolComponentConfig>;
-}
-
-/**
- * Tool Hook 上下文
- */
-export interface ToolHookContext {
-  tool?: Tool;
-  args?: Record<string, unknown>;
-  context?: ToolContext;
-  result?: ToolResult;
-}
-
-/**
- * ToolComponent 配置
- */
-export interface ToolComponentConfig {
-  /** 工具目录 */
-  toolsDir?: string;
-  /** 内置工具 */
-  builtInTools?: {
-    enabled: boolean;
-    loadAll?: boolean;
-    names?: string[];
-  };
-  /** 沙箱配置 */
-  sandbox?: {
-    enabled: boolean;
-    type: "native" | "docker";
-    defaultConfig?: Record<string, unknown>;
-  };
-  /** 执行配置 */
-  execution?: {
-    timeout?: number;
-    maxConcurrency?: number;
-  };
-}
-
-/**
- * ToolComponent
- * 工具管理核心组件
- */
-export class ToolComponent extends BaseComponent {
-  readonly name = "tool";
-  readonly version = "1.0.0";
-
-  private registry: ToolRegistry;
-  private validator: ToolValidator;
-  private config?: ToolComponentConfig;
-  
-  /** ConfigComponent 用于配置管理 */
-  private configComponent?: ConfigComponent;
-  
-  /** 配置变更 watcher 清理函数 */
-  private configWatcher?: () => void;
-
-  constructor() {
-    super();
-    this.registry = new ToolRegistry();
-    this.validator = new ToolValidator();
-  }
-
-  // ========================================================================
-  // Component Lifecycle
-  // ========================================================================
-
-  /**
-   * 初始化组件
-   * 
-   * 配置加载优先级（从高到低）：
-   * 1. Object - 直接传入的 config 对象
-   * 2. Env - 环境变量（通过 envPrefix 配置前缀）
-   * 3. File - 配置文件（通过 configPath 指定）
-   */
-  async init(config?: ComponentConfig): Promise<void> {
-    // 调用基类 init，注入 env
-    await super.init(config);
-
-    // 从 options 获取 ConfigComponent
-    const options = config?.options as unknown as ToolComponentOptions | undefined;
-    if (!options?.configComponent) {
-      throw new Error("ConfigComponent is required for ToolComponent initialization");
-    }
-
-    this.configComponent = options.configComponent;
-    await this.registerConfig(options);
-
-    // 加载内置工具
-    if (this.config?.builtInTools?.enabled !== false) {
-      await this.loadBuiltInTools();
-    }
-
-    logger.info(`ToolComponent initialized with ${this.getToolCount()} tools`);
-  }
-
-  /**
-   * 注册配置到 ConfigComponent
-   * 
-   * 配置加载顺序（优先级从低到高）：
-   * 1. FileSource - 从配置文件加载（最低）
-   * 2. EnvSource - 从环境变量加载（中等）
-   * 3. MemorySource - 直接配置对象（最高）
-   * 
-   * 实现步骤：
-   * 1. 使用 registerComponent(TOOL_CONFIG_REGISTRATION) 注册配置
-   * 2. 使用 load("tool") 加载已注册的配置
-   * 3. 设置 TOOL_DEFAULTS 默认值
-   * 4. 处理环境变量后备方案
-   * 5. 处理 config 对象（最高优先级）
-   */
-  private async registerConfig(options: ToolComponentOptions): Promise<void> {
-    const configComponent = options.configComponent;
-    if (!configComponent) return;
-
-    const { configPath, envPrefix, config } = options;
-    const prefix = envPrefix !== undefined ? envPrefix : "TOOL";
-
-    // 1. 使用 registerComponent 注册配置（不包含 file source 和 defaults）
-    configComponent.registerComponent(TOOL_CONFIG_REGISTRATION);
-
-    // 2. 注册 FileSource（如果提供了 configPath）
-    if (configPath) {
-      configComponent.registerSource({
-        type: "file",
-        relativePath: configPath,
-        optional: true,
-        watch: false
-      });
-    }
-
-    // 3. 使用 load("tool") 加载配置（从 file source 和 env source）
-    await configComponent.load("tool");
-
-    // 4. 处理环境变量后备方案（手动检查未捕获的环境变量）
-    const toolKeys = [
-      "tool.toolsDir",
-      "tool.builtInTools.enabled",
-      "tool.builtInTools.loadAll",
-      "tool.builtInTools.names",
-      "tool.sandbox.enabled",
-      "tool.sandbox.type",
-      "tool.sandbox.defaultConfig",
-      "tool.execution.timeout",
-      "tool.execution.maxConcurrency",
-    ];
-    
-    // 检查预定义的 toolKeys 对应的环境变量
-    for (const key of toolKeys) {
-      const envKey = toEnvKey(key, prefix);
-      const value = process.env[envKey];
-      if (value !== undefined) {
-        await configComponent.set(key, value);
-      }
-    }
-    
-    // 自动发现其他以 prefix 开头的环境变量
-    const envPrefixUpper = prefix.toUpperCase();
-    for (const envKey of Object.keys(process.env)) {
-      if (!envKey.startsWith(envPrefixUpper + "_")) continue;
-      const configKey = envKeyToConfigKey(envKey, prefix, "tool");
-      if (configKey && !toolKeys.includes(configKey)) {
-        const value = process.env[envKey];
-        if (value !== undefined) {
-          await configComponent.set(configKey, value);
-        }
-      }
-    }
-
-    // 5. 设置默认值（只有当配置不存在时）
-    for (const [key, value] of Object.entries(TOOL_DEFAULTS)) {
-      if (configComponent.get(key) === undefined) {
-        await configComponent.set(key, value);
-      }
-    }
-
-    // 6. 处理 config 对象（最高优先级）
-    if (config) {
-      const flatConfig = this.flattenConfig(config);
-      for (const [key, value] of Object.entries(flatConfig)) {
-        await configComponent.set(key, value);
-      }
-    }
-
-    // 7. 注册配置热更新监听
-    this.registerConfigWatcher(configComponent);
-    
-    // 8. 解析最终配置
-    const configData: Record<string, unknown> = {};
-    for (const key of toolKeys) {
-      const value = configComponent.get(key);
-      if (value !== undefined) {
-        configData[key.replace(/^tool\./, '')] = value;
-      }
-    }
-    // 合并直接传入的 config（优先级更高）
-    if (config) {
-      Object.assign(configData, config);
-    }
-    
-    const parsed = ToolComponentConfigSchema.safeParse(configData);
-    if (parsed.success) {
-      this.config = parsed.data as ToolComponentConfig;
-    } else {
-      // 回退到直接传入的 config
-      this.config = config || {};
-    }
-  }
-
-  /**
-   * 将配置对象展平为点号路径
-   */
-  private flattenConfig(
-    obj: Record<string, unknown>,
-    prefix = "tool"
-  ): Record<string, unknown> {
-    const result: Record<string, unknown> = {};
-    for (const [key, value] of Object.entries(obj)) {
-      const fullKey = `${prefix}.${key}`;
-      if (value && typeof value === "object" && !Array.isArray(value)) {
-        Object.assign(
-          result,
-          this.flattenConfig(value as Record<string, unknown>, fullKey)
-        );
-      } else {
-        result[fullKey] = value;
-      }
-    }
-    return result;
-  }
-
-  /**
-   * 注册配置热更新监听
-   */
-  private registerConfigWatcher(configComponent: ConfigComponent): void {
-    if (typeof configComponent.watch !== "function") {
-      return;
-    }
-    
-    this.configWatcher = configComponent.watch("tool.*", (event) => {
-      this.onConfigChange(event);
-    });
-  }
-
-  /**
-   * 处理配置变更
-   */
-  protected onConfigChange(event: { key: string; oldValue?: unknown; newValue?: unknown }): void {
-    logger.info(`Tool config changed: ${event.key}`, {
-      oldValue: event.oldValue,
-      newValue: event.newValue
-    });
-  }
-
-  /**
-   * 停止组件
-   */
-  async onStop(): Promise<void> {
-    // 清理配置 watcher
-    this.configWatcher?.();
-    this.configWatcher = undefined;
-    
-    this.setStatus("stopped");
-  }
-
-  // ========================================================================
-  // Tool Registration
-  // ========================================================================
-
-  /**
-   * 注册工具
-   */
-  register(tool: Tool, source: ToolRegistration["source"] = "dynamic"): void {
-    // 执行 before.register hooks
-    globalHookManager.execute(ToolHookPoints.BEFORE_REGISTER, { tool });
-
-    this.registry.register(tool, {
-      tool,
-      registeredAt: Date.now(),
-      source,
-      enabled: true,
-    });
-
-    logger.debug(`Registered tool: ${tool.name}`);
-
-    // 执行 after.register hooks
-    globalHookManager.execute(ToolHookPoints.AFTER_REGISTER, { tool });
-  }
-
-  /**
-   * 批量注册工具
-   */
-  registerMany(tools: Tool[], source: ToolRegistration["source"] = "dynamic"): void {
-    for (const tool of tools) {
-      this.register(tool, source);
-    }
-  }
-
-  /**
-   * 注销工具
-   */
-  unregister(name: string): boolean {
-    return this.registry.unregister(name);
-  }
-
-  /**
-   * 获取工具
-   */
-  getTool(name: string): Tool | undefined {
-    return this.registry.getTool(name)?.tool;
-  }
-
-  // ========================================================================
-  // Tool Discovery
-  // ========================================================================
-
-  /**
-   * 列出工具
-   */
-  listTools(filter?: ToolListFilter): Tool[] {
-    return this.registry.listTools(filter);
-  }
-
-  /**
-   * 获取工具数量
-   */
-  getToolCount(): number {
-    return this.registry.getCount();
-  }
-
-  /**
-   * 检查工具是否存在
-   */
-  hasTool(name: string): boolean {
-    return this.registry.has(name);
-  }
-
-  /**
-   * 按分类获取工具
-   */
-  getToolsByCategory(category: string): Tool[] {
-    return this.listTools({ category });
-  }
-
-  // ========================================================================
-  // Tool Execution
-  // ========================================================================
-
-  /**
-   * 执行工具
-   */
-  async execute(request: ToolExecuteRequest): Promise<ToolResult> {
-    const { name, args, context, skipHooks } = request;
-
-    // 获取工具
-    const registration = this.registry.getTool(name);
-    if (!registration) {
-      return {
-        success: false,
-        output: "",
-        error: `Tool not found: ${name}`,
-      };
-    }
-
-    if (!registration.enabled) {
-      return {
-        success: false,
-        output: "",
-        error: `Tool disabled: ${name}`,
-      };
-    }
-
-    const tool = registration.tool;
-
-    // 执行 before.execute hooks
-    if (!skipHooks) {
-      await globalHookManager.execute(
-        ToolHookPoints.BEFORE_EXECUTE,
-        { tool, args, context },
-        { toolName: tool.name }
-      );
-    }
-
-    const startTime = Date.now();
-
-    try {
-      // 参数验证
-      const validationResult = await this.validator.validate(tool, args);
-      if (!validationResult.success) {
-        return {
-          success: false,
-          output: "",
-          error: validationResult.error,
-          metadata: {
-            execution_time_ms: Date.now() - startTime,
-          },
-        };
-      }
-
-      // 执行工具
-      const result = await tool.execute(validationResult.data!, context);
-
-      // 添加执行时间
-      if (!result.metadata) {
-        result.metadata = { execution_time_ms: Date.now() - startTime };
-      } else {
-        result.metadata.execution_time_ms = Date.now() - startTime;
-      }
-
-      // 执行 after.execute hooks
-      if (!skipHooks) {
-        await globalHookManager.execute(
-          ToolHookPoints.AFTER_EXECUTE,
-          { tool, args, context, result },
-          { toolName: tool.name }
-        );
-      }
-
-      return result;
-    } catch (error) {
-      // 检查是否是 AskUserError - 这是用于工作流暂停的特殊错误，需要向上传播
-      // 以便 AgentComponent 和 WorkflowEngine 能够正确处理暂停逻辑
-      if (error instanceof AskUserError) {
-        throw error; // 重新抛出，让调用栈上层处理
-      }
-
-      const errorResult: ToolResult = {
-        success: false,
-        output: "",
-        error: error instanceof Error ? error.message : String(error),
-        metadata: {
-          execution_time_ms: Date.now() - startTime,
-        },
-      };
-
-      // 执行 after.execute hooks（即使出错）
-      if (!skipHooks) {
-        await globalHookManager.execute(
-          ToolHookPoints.AFTER_EXECUTE,
-          { tool, args, context, result: errorResult },
-          { toolName: tool.name }
-        );
-      }
-
-      // 执行 on.error hooks
-      if (!skipHooks) {
-        await globalHookManager.execute(
-          ToolHookPoints.ON_ERROR,
-          { tool, args, context, error },
-          { toolName: tool.name }
-        );
-      }
-
-      return errorResult;
-    }
-  }
-
-  // ========================================================================
-  // Built-in Tools
-  // ========================================================================
-
-  /**
-   * 加载内置工具
-   */
-  async loadBuiltInTools(): Promise<void> {
-    try {
-      const { getAllBuiltInTools } = await import("./built-in/index");
-      const tools = getAllBuiltInTools();
-      this.registerMany(tools, "built-in");
-      logger.info(`Loaded ${tools.length} built-in tools`);
-    } catch (err) {
-      logger.warn(`Failed to load built-in tools: ${(err as Error).message}`);
-    }
-  }
-
-  /**
-   * 获取 Tool Hook 点列表
-   */
-  getHookPoints(): string[] {
-    return [
-      ToolHookPoints.BEFORE_EXECUTE,
-      ToolHookPoints.AFTER_EXECUTE,
-      ToolHookPoints.BEFORE_REGISTER,
-      ToolHookPoints.AFTER_REGISTER,
-      ToolHookPoints.ON_ERROR,
-    ];
-  }
-}
-
-// ========================================================================
-// Config Schema
-// ========================================================================
-
-const ToolComponentConfigSchema = z.object({
-  toolsDir: z.string().optional(),
-  builtInTools: z
-    .object({
-      enabled: z.boolean().default(true),
-      loadAll: z.boolean().default(true),
-      names: z.array(z.string()).optional(),
-    })
-    .default({}),
-  sandbox: z
-    .object({
-      enabled: z.boolean().default(false),
-      type: z.enum(["native", "docker"]).default("native"),
-      defaultConfig: z.record(z.unknown()).optional(),
-    })
-    .default({}),
-  execution: z
-    .object({
-      timeout: z.number().int().positive().default(60000),
-      maxConcurrency: z.number().int().positive().default(4),
-    })
-    .default({}),
-});