@ai-setting/roy-agent-core 1.0.0

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

@@ -0,0 +1,563 @@
+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({}),
+});