@ai-setting/roy-agent-core 1.3.10 → 1.3.14

package/src/env/tool/tool-config-registration.test.ts

@@ -1,249 +0,0 @@
-/**
- * @fileoverview Tool Component 配置注册测试
- * 
- * TDD: 先写测试，验证配置注册机制
- */
-
-import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
-import { ConfigComponent } from "../../config/config-component";
-import { ToolComponent } from "./tool-component";
-import { TOOL_CONFIG_REGISTRATION, TOOL_DEFAULTS } from "./tool-config-registration";
-
-// 模拟 registerComponent 调用
-const mockRegisterComponent = vi.fn();
-
-describe("Tool Config Registration", () => {
-  let configComponent: ConfigComponent;
-  let component: ToolComponent;
-
-  beforeEach(() => {
-    configComponent = new ConfigComponent();
-    component = new ToolComponent();
-  });
-
-  describe("TOOL_CONFIG_REGISTRATION", () => {
-    it("应该包含正确的 name", () => {
-      expect(TOOL_CONFIG_REGISTRATION.name).toBe("tool");
-    });
-
-    it("应该包含 env source 配置", () => {
-      const envSource = TOOL_CONFIG_REGISTRATION.sources.find(
-        (s) => s.type === "env"
-      );
-      expect(envSource).toBeDefined();
-      expect(envSource?.envPrefix).toBe("TOOL");
-      expect(envSource?.priority).toBe(20);
-    });
-
-    it("应该包含所有配置 keys", () => {
-      const keys = TOOL_CONFIG_REGISTRATION.keys;
-      expect(keys).toContainEqual(
-        expect.objectContaining({ key: "tool.toolsDir" })
-      );
-      expect(keys).toContainEqual(
-        expect.objectContaining({ key: "tool.builtInTools.enabled" })
-      );
-      expect(keys).toContainEqual(
-        expect.objectContaining({ key: "tool.sandbox.enabled" })
-      );
-      expect(keys).toContainEqual(
-        expect.objectContaining({ key: "tool.execution.timeout" })
-      );
-    });
-  });
-
-  describe("TOOL_DEFAULTS", () => {
-    it("应该包含 toolsDir 默认值（完整格式）", () => {
-      expect(TOOL_DEFAULTS["tool.toolsDir"]).toBe(".roy/tools");
-    });
-
-    it("应该包含 builtInTools.enabled 默认值（完整格式）", () => {
-      expect(TOOL_DEFAULTS["tool.builtInTools.enabled"]).toBe(true);
-    });
-
-    it("应该包含 sandbox.enabled 默认值（完整格式）", () => {
-      expect(TOOL_DEFAULTS["tool.sandbox.enabled"]).toBe(false);
-    });
-
-    it("应该包含 execution.timeout 默认值（完整格式）", () => {
-      expect(TOOL_DEFAULTS["tool.execution.timeout"]).toBe(30000);
-    });
-  });
-
-  describe("配置注册到 ConfigComponent", () => {
-    it("应该能够注册 TOOL_CONFIG_REGISTRATION", () => {
-      configComponent.registerComponent(TOOL_CONFIG_REGISTRATION);
-      expect(() => configComponent.registerComponent(TOOL_CONFIG_REGISTRATION)).not.toThrow();
-    });
-  });
-
-  describe("Component 配置加载", () => {
-    it("应该需要 ConfigComponent 初始化", async () => {
-      await expect(
-        component.init({
-          options: {},
-        } as any)
-      ).rejects.toThrow("ConfigComponent is required");
-    });
-
-    it("应该能够使用 ConfigComponent 初始化", async () => {
-      await component.init({
-        options: {
-          configComponent,
-        },
-      } as any);
-      
-      expect(component.name).toBe("tool");
-      expect(component.version).toBe("1.0.0");
-    });
-
-    it("应该能够通过 config 对象传入配置", async () => {
-      await component.init({
-        options: {
-          configComponent,
-          config: {
-            toolsDir: "/custom/tools",
-            sandbox: {
-              enabled: true,
-              type: "docker",
-            },
-          },
-        },
-      } as any);
-      
-      expect(component.name).toBe("tool");
-    });
-  });
-
-  describe("环境变量覆盖", () => {
-    it("应该能够通过环境变量覆盖配置", async () => {
-      // 设置环境变量
-      const originalValue = process.env.TOOL_TOOL_TOOLS_DIR;
-      process.env.TOOL_TOOL_TOOLS_DIR = "/env/tools";
-      
-      try {
-        await component.init({
-          options: {
-            configComponent,
-          },
-        } as any);
-        
-        expect(component.name).toBe("tool");
-      } finally {
-        // 恢复环境变量
-        if (originalValue !== undefined) {
-          process.env.TOOL_TOOL_TOOLS_DIR = originalValue;
-        } else {
-          delete process.env.TOOL_TOOL_TOOLS_DIR;
-        }
-      }
-    });
-  });
-
-  describe("核心验收标准 - registerConfig 实现", () => {
-    afterEach(() => {
-      // 清理环境变量
-      delete process.env.TOOL_TOOL_TOOLS_DIR;
-      delete process.env.TOOL_BUILT_IN_TOOLS_ENABLED;
-    });
-
-    it("应该使用 registerComponent 注册配置", async () => {
-      const spy = vi.spyOn(configComponent, 'registerComponent');
-      
-      await component.init({
-        options: {
-          configComponent,
-        },
-      } as any);
-      
-      // 验证 registerComponent 被调用
-      expect(spy).toHaveBeenCalledWith(TOOL_CONFIG_REGISTRATION);
-      spy.mockRestore();
-    });
-
-    it("应该使用 load('tool') 加载配置", async () => {
-      const loadSpy = vi.spyOn(configComponent, 'load');
-      
-      await component.init({
-        options: {
-          configComponent,
-        },
-      } as any);
-      
-      // 验证 load 被调用，且参数为 "tool"
-      expect(loadSpy).toHaveBeenCalledWith("tool");
-      loadSpy.mockRestore();
-    });
-
-    it("应该正确设置 TOOL_DEFAULTS 默认值", async () => {
-      await component.init({
-        options: {
-          configComponent,
-        },
-      } as any);
-      
-      // 验证默认值被正确设置到 configComponent（通过 registerComponent 的 defaults 机制）
-      expect(configComponent.get("tool.toolsDir")).toBe(".roy/tools");
-      expect(configComponent.get("tool.builtInTools.enabled")).toBe(true);
-      expect(configComponent.get("tool.execution.timeout")).toBe(30000);
-    });
-
-    it("环境变量应该能覆盖默认配置", async () => {
-      // 设置环境变量覆盖
-      process.env.TOOL_TOOL_TOOLS_DIR = "/override/tools";
-      
-      await component.init({
-        options: {
-          configComponent,
-        },
-      } as any);
-      
-      // 验证环境变量覆盖了默认值
-      expect(configComponent.get("tool.toolsDir")).toBe("/override/tools");
-    });
-
-    it("config 对象应该能覆盖环境变量和默认值", async () => {
-      // 设置环境变量
-      process.env.TOOL_TOOL_TOOLS_DIR = "/env/tools";
-      
-      await component.init({
-        options: {
-          configComponent,
-          config: {
-            toolsDir: "/config/tools",
-            sandbox: {
-              enabled: true,
-              type: "docker",
-            },
-          },
-        },
-      } as any);
-      
-      // 验证 config 对象覆盖了环境变量
-      expect(configComponent.get("tool.toolsDir")).toBe("/config/tools");
-    });
-
-    it("registerConfig 应该处理 config 对象", async () => {
-      const customConfig = {
-        toolsDir: "/custom/tools",
-        sandbox: {
-          enabled: true,
-          type: "docker",
-        },
-        execution: {
-          timeout: 60000,
-        },
-      };
-      
-      await component.init({
-        options: {
-          configComponent,
-          config: customConfig,
-        },
-      } as any);
-      
-      // 验证 config 对象被正确处理
-      expect(configComponent.get("tool.toolsDir")).toBe("/custom/tools");
-    });
-  });
-});

package/src/env/tool/tool-config-registration.ts

@@ -1,46 +0,0 @@
-/**
- * @fileoverview Tool Component 配置注册
- * 
- * 使用 ConfigComponent.registerComponent() 机制统一管理配置
- */
-
-import type { ComponentRegistration } from "../../config/config-component";
-
-/**
- * Tool Component 默认配置值
- * 
- * 注意：键使用完整格式（带 "tool." 前缀），在 registerConfig 中手动设置
- */
-export const TOOL_DEFAULTS: Record<string, unknown> = {
-  "tool.toolsDir": ".roy/tools",
-  "tool.builtInTools.enabled": true,
-  "tool.builtInTools.loadAll": true,
-  "tool.sandbox.enabled": false,
-  "tool.sandbox.type": "native",
-  "tool.execution.timeout": 30000,
-  "tool.execution.maxConcurrency": 5,
-};
-
-/**
- * Tool Component 配置注册常量
- * 
- * 定义了所有 Tool 相关的配置项和来源
- */
-export const TOOL_CONFIG_REGISTRATION: ComponentRegistration = {
-  name: "tool",
-  
-  sources: [
-    { type: "env", envPrefix: "TOOL", priority: 20, watch: false },
-  ],
-  
-  keys: [
-    { key: "tool.toolsDir", sources: ["env", "file"] },
-    { key: "tool.builtInTools.enabled", sources: ["env", "file"] },
-    { key: "tool.builtInTools.loadAll", sources: ["env", "file"] },
-    { key: "tool.sandbox.enabled", sources: ["env", "file"] },
-    { key: "tool.sandbox.type", sources: ["env", "file"] },
-    { key: "tool.execution.timeout", sources: ["env", "file"] },
-    { key: "tool.execution.maxConcurrency", sources: ["env", "file"] },
-  ],
-  // 注意：不使用 defaults 字段，默认值在 registerConfig 中手动 set
-};

package/src/env/tool/types.ts

@@ -1,267 +0,0 @@
-import { z, ZodType, ZodError } from "zod";
-
-// ============================================================================
-// Tool Context
-// ============================================================================
-
-/**
- * 沙箱配置
- */
-export interface SandboxConfig {
-  /** 是否启用沙箱 */
-  enabled: boolean;
-  /** 沙箱类型 */
-  type: "native" | "docker";
-  /** 动作过滤 */
-  actionFilter?: {
-    /** 包含的动作 */
-    include?: string[];
-    /** 排除的动作 */
-    exclude?: string[];
-  };
-  /** 文件系统限制 */
-  filesystem?: {
-    /** 允许读取 */
-    allowRead?: string[];
-    /** 禁止读取 */
-    denyRead?: string[];
-    /** 允许写入 */
-    allowWrite?: string[];
-    /** 禁止写入 */
-    denyWrite?: string[];
-  };
-  /** 网络限制 */
-  network?: {
-    /** 允许的域名 */
-    allowedDomains?: string[];
-    /** 禁止的域名 */
-    deniedDomains?: string[];
-  };
-  /** Docker 配置 */
-  docker?: {
-    /** 镜像 */
-    image?: string;
-    /** 网络模式 */
-    networkMode?: "bridge" | "host" | "none";
-    /** 卷挂载 */
-    volumes?: Record<string, string>;
-  };
-}
-
-/**
- * 工具执行上下文
- */
-export interface ToolContext {
-  /** 工作目录 */
-  workdir?: string;
-  /** 用户 ID */
-  user_id?: string;
-  /** 会话 ID */
-  session_id?: string;
-  /** 消息 ID */
-  message_id?: string;
-  /** 中断信号 */
-  abort?: AbortSignal;
-  /** 额外元数据 */
-  metadata?: Record<string, unknown>;
-  /** 沙箱配置 */
-  sandbox?: SandboxConfig;
-  /** 沙箱 Provider */
-  sandboxProvider?: unknown | null;
-}
-
-// ============================================================================
-// Tool Result
-// ============================================================================
-
-/**
- * 工具结果元数据
- */
-export interface ToolResultMetadata {
-  /** 执行时间（毫秒） */
-  execution_time_ms: number;
-  /** 输出大小（字节） */
-  output_size?: number;
-  /** 标准输出 */
-  stdout?: string;
-  /** 标准错误 */
-  stderr?: string;
-  /** 退出码 */
-  exit_code?: number;
-  /** Token 使用量 */
-  usage?: {
-    inputTokens: number;
-    outputTokens: number;
-    totalTokens?: number;
-  };
-  /** 额外元数据 */
-  [key: string]: unknown;
-}
-
-/**
- * 工具执行结果
- */
-export interface ToolResult {
-  /** 是否成功 */
-  success: boolean;
-  /** 输出内容 */
-  output: string | Record<string, unknown>;
-  /** 错误信息 */
-  error?: string;
-  /** 结果元数据 */
-  metadata?: ToolResultMetadata;
-}
-
-// ============================================================================
-// Tool Definition
-// ============================================================================
-
-/**
- * 工具元数据
- */
-export interface ToolMetadata {
-  /** 分类 */
-  category?: string;
-  /** 标签 */
-  tags?: string[];
-  /** 版本 */
-  version?: string;
-  /** 作者 */
-  author?: string;
-  /** 是否实验性 */
-  experimental?: boolean;
-  /** MCP 工具信息（MCP adapter 使用） */
-  mcpTool?: {
-    originalName: string;
-    originalDescription: string;
-    inputSchema?: unknown;
-  };
-}
-
-/**
- * 工具沙箱配置
- */
-export interface ToolSandboxConfig {
-  /** 是否启用沙箱 */
-  enabled: boolean;
-  /** 沙箱配置 */
-  config?: Partial<SandboxConfig>;
-}
-
-/**
- * 工具权限配置
- */
-export interface ToolPermissionConfig {
-  /** 是否需要用户确认 */
-  requireConfirmation?: boolean;
-  /** 权限级别 */
-  level?: "safe" | "dangerous" | "critical";
-}
-
-/**
- * 工具信息
- */
-export interface ToolInfo<Parameters extends ZodType = ZodType> {
-  /** 工具名称 */
-  name: string;
-  /** 工具描述 */
-  description: string;
-  /** 参数 Schema */
-  parameters: Parameters;
-  /** 初始化函数（可选） */
-  init?: (ctx?: ToolContext) => Promise<void>;
-  /** 执行函数 */
-  execute: (args: z.infer<Parameters>, ctx: ToolContext) => Promise<ToolResult>;
-  /** 参数验证错误格式化（可选） */
-  formatValidationError?: (error: ZodError) => string;
-  /** 沙箱配置 */
-  sandbox?: ToolSandboxConfig;
-  /** 权限配置 */
-  permission?: ToolPermissionConfig;
-  /** 工具元数据 */
-  metadata?: ToolMetadata;
-}
-
-/**
- * 工具类型别名
- */
-export type Tool = ToolInfo;
-
-// ============================================================================
-// Tool Registration
-// ============================================================================
-
-/**
- * 工具注册来源
- */
-export type ToolSource = "built-in" | "plugin" | "dynamic";
-
-/**
- * 工具注册信息
- */
-export interface ToolRegistration {
-  /** 工具实例 */
-  tool: Tool;
-  /** 注册时间 */
-  registeredAt: number;
-  /** 注册来源 */
-  source: ToolSource;
-  /** 是否启用 */
-  enabled: boolean;
-}
-
-// ============================================================================
-// Tool Execution
-// ============================================================================
-
-/**
- * 工具执行请求
- */
-export interface ToolExecuteRequest {
-  /** 工具名称 */
-  name: string;
-  /** 参数 */
-  args: Record<string, unknown>;
-  /** 上下文 */
-  context: ToolContext;
-  /** 是否跳过 Hook */
-  skipHooks?: boolean;
-}
-
-// ============================================================================
-// Tool List Filter
-// ============================================================================
-
-/**
- * 工具列表过滤器
- */
-export interface ToolListFilter {
-  /** 按名称过滤（支持 glob） */
-  name?: string | string[];
-  /** 按分类过滤 */
-  category?: string;
-  /** 按标签过滤 */
-  tags?: string[];
-  /** 按来源过滤 */
-  source?: ToolSource;
-  /** 只返回启用的工具 */
-  enabledOnly?: boolean;
-  /** 排除的工具 */
-  exclude?: string[];
-}
-
-// ============================================================================
-// Validation Result
-// ============================================================================
-
-/**
- * 参数验证结果
- */
-export interface ValidationResult {
-  /** 是否成功 */
-  success: boolean;
-  /** 验证后的数据 */
-  data?: Record<string, unknown>;
-  /** 错误信息 */
-  error?: string;
-}

package/src/env/tool/validator.test.ts

@@ -1,143 +0,0 @@
-import { describe, test, expect, beforeEach } from "bun:test";
-import { z, ZodError } from "zod";
-import { ToolValidator } from "./validator";
-import type { Tool, ValidationResult } from "./types";
-
-describe("ToolValidator", () => {
-  let validator: ToolValidator;
-
-  const createMockTool = (paramsSchema: z.ZodType): Tool => ({
-    name: "test-tool",
-    description: "Test tool",
-    parameters: paramsSchema,
-    execute: async () => ({ success: true, output: "ok" }),
-  });
-
-  beforeEach(() => {
-    validator = new ToolValidator();
-  });
-
-  describe("validate", () => {
-    test("should validate correct arguments", async () => {
-      const tool = createMockTool(
-        z.object({
-          name: z.string(),
-          age: z.number().optional(),
-        })
-      );
-
-      const result = await validator.validate(tool, { name: "test" });
-
-      expect(result.success).toBe(true);
-      expect(result.data).toEqual({ name: "test" });
-      expect(result.error).toBeUndefined();
-    });
-
-    test("should validate with optional fields", async () => {
-      const tool = createMockTool(
-        z.object({
-          name: z.string(),
-          age: z.number().optional(),
-        })
-      );
-
-      const result = await validator.validate(tool, { name: "test", age: 25 });
-
-      expect(result.success).toBe(true);
-      expect(result.data).toEqual({ name: "test", age: 25 });
-    });
-
-    test("should return error for missing required field", async () => {
-      const tool = createMockTool(
-        z.object({
-          name: z.string(),
-          age: z.number(),
-        })
-      );
-
-      const result = await validator.validate(tool, {});
-
-      expect(result.success).toBe(false);
-      expect(result.error).toContain("name");
-      expect(result.error).toContain("Required");
-    });
-
-    test("should return error for wrong type", async () => {
-      const tool = createMockTool(
-        z.object({
-          name: z.string(),
-        })
-      );
-
-      const result = await validator.validate(tool, { name: 123 });
-
-      expect(result.success).toBe(false);
-      expect(result.error).toContain("name");
-    });
-
-    test("should return error for invalid enum value", async () => {
-      const tool = createMockTool(
-        z.object({
-          status: z.enum(["active", "inactive"]),
-        })
-      );
-
-      const result = await validator.validate(tool, { status: "pending" });
-
-      expect(result.success).toBe(false);
-      expect(result.error).toContain("status");
-      expect(result.error).toMatch(/invalid|expected/i);
-    });
-
-    test("should validate nested objects", async () => {
-      const tool = createMockTool(
-        z.object({
-          user: z.object({
-            name: z.string(),
-            address: z.object({
-              city: z.string(),
-            }),
-          }),
-        })
-      );
-
-      const result = await validator.validate(tool, {
-        user: { name: "John", address: { city: "NYC" } },
-      });
-
-      expect(result.success).toBe(true);
-    });
-
-    test("should validate arrays", async () => {
-      const tool = createMockTool(
-        z.object({
-          tags: z.array(z.string()),
-        })
-      );
-
-      const result = await validator.validate(tool, { tags: ["a", "b", "c"] });
-
-      expect(result.success).toBe(true);
-    });
-
-    test("should validate with custom error formatter", async () => {
-      const tool: Tool = {
-        name: "test-tool",
-        description: "Test tool",
-        parameters: z.object({
-          name: z.string(),
-        }),
-        execute: async () => ({ success: true, output: "ok" }),
-        formatValidationError: (error: ZodError) => {
-          return error.errors.map((e) => `${e.path.join(".")} - ${e.message}`).join("; ");
-        },
-      };
-
-      const result = await validator.validate(tool, { name: 123 });
-
-      expect(result.success).toBe(false);
-      expect(result.error).toContain("name");
-      expect(result.error).toContain("-");
-    });
-  });
-});