@ai-setting/roy-agent-core 1.0.0

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

@@ -0,0 +1,249 @@
+/**
+ * @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

@@ -0,0 +1,46 @@
+/**
+ * @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

@@ -0,0 +1,267 @@
+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

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