@ai-setting/roy-agent-core 1.0.0

package/src/env/tool/built-in/write-file.test.ts

@@ -0,0 +1,119 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { writeFileTool } from "./write-file";
+import { readFile, mkdir, rm } from "fs/promises";
+import { join } from "path";
+
+describe("writeFileTool", () => {
+  const testDir = join("/tmp", `write-test-${Date.now()}`);
+  const testFile = join(testDir, "output.txt");
+  const nestedFile = join(testDir, "nested", "dir", "output.txt");
+
+  beforeEach(async () => {
+    await mkdir(testDir, { recursive: true });
+  });
+
+  describe("parameters", () => {
+    test("should validate path and content", async () => {
+      const result = await writeFileTool.execute(
+        { path: testFile, content: "test content" },
+        {}
+      );
+      
+      expect(result.success).toBe(true);
+    });
+
+    test("should handle missing path gracefully", async () => {
+      const result = await writeFileTool.execute({ content: "test" } as any, {});
+      // 会因为文件系统错误而失败
+      expect(result.success).toBe(false);
+    });
+
+    test("should handle empty content gracefully", async () => {
+      const result = await writeFileTool.execute({ path: testFile, content: "" }, {});
+      // 空内容应该能成功写入
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("execution", () => {
+    test("should write file content", async () => {
+      const content = "Hello, World!";
+      const result = await writeFileTool.execute(
+        { path: testFile, content },
+        {}
+      );
+      
+      expect(result.success).toBe(true);
+      
+      // 验证文件内容
+      const written = await readFile(testFile, "utf-8");
+      expect(written).toBe(content);
+    });
+
+    test("should create parent directories with createDirs", async () => {
+      const result = await writeFileTool.execute(
+        { path: nestedFile, content: "nested content", createDirs: true },
+        {}
+      );
+      
+      expect(result.success).toBe(true);
+      
+      const written = await readFile(nestedFile, "utf-8");
+      expect(written).toBe("nested content");
+    });
+
+    test("should append with append flag", async () => {
+      await writeFileTool.execute(
+        { path: testFile, content: "Line 1" },
+        {}
+      );
+      
+      await writeFileTool.execute(
+        { path: testFile, content: "Line 2", append: true },
+        {}
+      );
+      
+      const content = await readFile(testFile, "utf-8");
+      expect(content).toBe("Line 1Line 2");
+    });
+
+    test("should overwrite without append flag", async () => {
+      await writeFileTool.execute(
+        { path: testFile, content: "Original" },
+        {}
+      );
+      
+      await writeFileTool.execute(
+        { path: testFile, content: "Overwritten" },
+        {}
+      );
+      
+      const content = await readFile(testFile, "utf-8");
+      expect(content).toBe("Overwritten");
+    });
+
+    test("should include metadata", async () => {
+      const result = await writeFileTool.execute(
+        { path: testFile, content: "test" },
+        {}
+      );
+      
+      expect(result.metadata?.execution_time_ms).toBeDefined();
+      expect(result.metadata?.output_size).toBe(4);
+      expect(result.metadata?.file_path).toBe(testFile);
+    });
+  });
+
+  describe("metadata", () => {
+    test("should have correct metadata", () => {
+      expect(writeFileTool.name).toBe("write_file");
+      expect(writeFileTool.metadata?.category).toBe("file");
+      expect(writeFileTool.metadata?.tags).toContain("write");
+    });
+
+    test("should require confirmation", () => {
+      expect(writeFileTool.permission?.requireConfirmation).toBe(true);
+      expect(writeFileTool.permission?.level).toBe("dangerous");
+    });
+  });
+});

package/src/env/tool/built-in/write-file.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { writeFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+import type { Tool, ToolContext, ToolResult } from "../types";
+
+/**
+ * 写入文件工具
+ */
+export const writeFileTool: Tool = {
+  name: "write_file",
+  description: "Write content to a file. Use this to create new files or overwrite existing ones.",
+  parameters: z.object({
+    path: z.string().describe("The file path to write to"),
+    content: z.string().describe("The content to write"),
+    createDirs: z.boolean().default(false).optional().describe("Create parent directories if they don't exist"),
+    append: z.boolean().default(false).optional().describe("Append to file instead of overwrite"),
+  }),
+  sandbox: {
+    enabled: true,
+    config: {
+      filesystem: {
+        denyWrite: ["/etc", "/usr", "/bin", "/sbin", "/boot", "/sys"],
+      },
+    },
+  },
+  permission: {
+    requireConfirmation: true,
+    level: "dangerous",
+  },
+  metadata: {
+    category: "file",
+    tags: ["write", "file", "io", "create"],
+    version: "1.0.0",
+  },
+  execute: async (args, ctx: ToolContext): Promise<ToolResult> => {
+    const startTime = Date.now();
+    const { path: filePath, content, createDirs = false, append = false } = args;
+
+    try {
+      // 如果需要创建目录
+      if (createDirs) {
+        await mkdir(dirname(filePath), { recursive: true });
+      }
+
+      const flags = append ? "a" : "w";
+      await writeFile(filePath, content, { flag: flags });
+
+      return {
+        success: true,
+        output: append ? `Content appended to: ${filePath}` : `File written: ${filePath}`,
+        metadata: {
+          execution_time_ms: Date.now() - startTime,
+          output_size: content.length,
+          file_path: filePath,
+        },
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: error instanceof Error ? error.message : String(error),
+        metadata: {
+          execution_time_ms: Date.now() - startTime,
+        },
+      };
+    }
+  },
+};

package/src/env/tool/index.ts

@@ -0,0 +1,24 @@
+// Tool 组件导出
+
+// 类型
+export * from "./types";
+
+// 组件
+export { ToolComponent } from "./tool-component";
+export type { ToolComponentConfig } from "./tool-component";
+
+// 注册中心
+export { ToolRegistry } from "./registry";
+
+// 验证器
+export { ToolValidator } from "./validator";
+
+// 内置工具
+export { getAllBuiltInTools, getBuiltInTool } from "./built-in";
+export { bashTool } from "./built-in/bash";
+export { echoTool } from "./built-in/echo";
+export { globTool } from "./built-in/glob";
+export { readFileTool } from "./built-in/read-file";
+export { writeFileTool } from "./built-in/write-file";
+export { editFileTool } from "./built-in/edit-file";
+export { grepTool } from "./built-in/grep";

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

@@ -0,0 +1,257 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { z } from "zod";
+import { ToolRegistry } from "./registry";
+import type { Tool, ToolRegistration, ToolListFilter } from "./types";
+
+describe("ToolRegistry", () => {
+  let registry: ToolRegistry;
+
+  // Helper to create a mock tool
+  const createMockTool = (name: string, category?: string): Tool => ({
+    name,
+    description: `Description for ${name}`,
+    parameters: z.object({
+      input: z.string().describe("Test input"),
+    }),
+    execute: async () => ({
+      success: true,
+      output: "ok",
+      metadata: { execution_time_ms: 0 },
+    }),
+    metadata: category ? { category } : undefined,
+  });
+
+  beforeEach(() => {
+    registry = new ToolRegistry();
+  });
+
+  describe("register", () => {
+    test("should register a tool", () => {
+      const tool = createMockTool("test-tool");
+      const registration: ToolRegistration = {
+        tool,
+        registeredAt: Date.now(),
+        source: "built-in",
+        enabled: true,
+      };
+
+      registry.register(tool, registration);
+
+      expect(registry.has("test-tool")).toBe(true);
+      expect(registry.getTool("test-tool")?.tool.name).toBe("test-tool");
+    });
+
+    test("should overwrite existing tool with same name", () => {
+      const tool1 = createMockTool("test-tool");
+      const tool2 = createMockTool("test-tool");
+
+      registry.register(tool1, { tool: tool1, registeredAt: 1, source: "built-in", enabled: true });
+      registry.register(tool2, { tool: tool2, registeredAt: 2, source: "dynamic", enabled: true });
+
+      expect(registry.getTool("test-tool")?.tool).toBe(tool2);
+      expect(registry.getTool("test-tool")?.source).toBe("dynamic");
+    });
+  });
+
+  describe("unregister", () => {
+    test("should unregister a tool", () => {
+      const tool = createMockTool("test-tool");
+      registry.register(tool, { tool, registeredAt: 1, source: "built-in", enabled: true });
+
+      expect(registry.unregister("test-tool")).toBe(true);
+      expect(registry.has("test-tool")).toBe(false);
+    });
+
+    test("should return false when unregistering non-existent tool", () => {
+      expect(registry.unregister("non-existent")).toBe(false);
+    });
+  });
+
+  describe("getTool", () => {
+    test("should return registered tool", () => {
+      const tool = createMockTool("test-tool");
+      registry.register(tool, { tool, registeredAt: 1, source: "built-in", enabled: true });
+
+      const result = registry.getTool("test-tool");
+      expect(result?.tool.name).toBe("test-tool");
+    });
+
+    test("should return undefined for non-existent tool", () => {
+      expect(registry.getTool("non-existent")).toBeUndefined();
+    });
+  });
+
+  describe("listTools", () => {
+    beforeEach(() => {
+      // Register multiple tools
+      registry.register(createMockTool("bash", "system"), {
+        tool: createMockTool("bash", "system"),
+        registeredAt: 1,
+        source: "built-in",
+        enabled: true,
+      });
+      registry.register(createMockTool("glob", "file"), {
+        tool: createMockTool("glob", "file"),
+        registeredAt: 2,
+        source: "built-in",
+        enabled: true,
+      });
+      registry.register(createMockTool("read_file", "file"), {
+        tool: createMockTool("read_file", "file"),
+        registeredAt: 3,
+        source: "built-in",
+        enabled: true,
+      });
+      registry.register(createMockTool("custom", "custom"), {
+        tool: createMockTool("custom", "custom"),
+        registeredAt: 4,
+        source: "dynamic",
+        enabled: true,
+      });
+      registry.register(createMockTool("disabled", "system"), {
+        tool: createMockTool("disabled", "system"),
+        registeredAt: 5,
+        source: "built-in",
+        enabled: false,
+      });
+    });
+
+    test("should list all tools without filter", () => {
+      const tools = registry.listTools();
+      expect(tools).toHaveLength(5);
+    });
+
+    test("should filter by category", () => {
+      const tools = registry.listTools({ category: "file" });
+      expect(tools).toHaveLength(2);
+      expect(tools.map((t) => t.name).sort()).toEqual(["glob", "read_file"]);
+    });
+
+    test("should filter by source", () => {
+      const tools = registry.listTools({ source: "dynamic" });
+      expect(tools).toHaveLength(1);
+      expect(tools[0].name).toBe("custom");
+    });
+
+    test("should filter by enabledOnly", () => {
+      const tools = registry.listTools({ enabledOnly: true });
+      expect(tools).toHaveLength(4);
+      expect(tools.find((t) => t.name === "disabled")).toBeUndefined();
+    });
+
+    test("should filter by exclude", () => {
+      const tools = registry.listTools({ exclude: ["bash", "glob"] });
+      expect(tools).toHaveLength(3);
+      expect(tools.map((t) => t.name).sort()).toEqual(["custom", "disabled", "read_file"]);
+    });
+
+    test("should filter by name glob pattern", () => {
+      const tools = registry.listTools({ name: "*_file" });
+      expect(tools).toHaveLength(1);
+      expect(tools[0].name).toBe("read_file");
+    });
+
+    test("should combine multiple filters", () => {
+      const tools = registry.listTools({
+        category: "system",
+        enabledOnly: true,
+      });
+      expect(tools).toHaveLength(1);
+      expect(tools[0].name).toBe("bash");
+    });
+  });
+
+  describe("enable/disable", () => {
+    test("should enable a tool", () => {
+      const tool = createMockTool("test-tool");
+      registry.register(tool, { tool, registeredAt: 1, source: "built-in", enabled: false });
+
+      expect(registry.enable("test-tool")).toBe(true);
+      expect(registry.getTool("test-tool")?.enabled).toBe(true);
+    });
+
+    test("should disable a tool", () => {
+      const tool = createMockTool("test-tool");
+      registry.register(tool, { tool, registeredAt: 1, source: "built-in", enabled: true });
+
+      expect(registry.disable("test-tool")).toBe(true);
+      expect(registry.getTool("test-tool")?.enabled).toBe(false);
+    });
+
+    test("should return false when enabling non-existent tool", () => {
+      expect(registry.enable("non-existent")).toBe(false);
+    });
+
+    test("should return false when disabling non-existent tool", () => {
+      expect(registry.disable("non-existent")).toBe(false);
+    });
+  });
+
+  describe("getCount", () => {
+    test("should return correct count", () => {
+      expect(registry.getCount()).toBe(0);
+
+      registry.register(createMockTool("tool1"), {
+        tool: createMockTool("tool1"),
+        registeredAt: 1,
+        source: "built-in",
+        enabled: true,
+      });
+      expect(registry.getCount()).toBe(1);
+
+      registry.register(createMockTool("tool2"), {
+        tool: createMockTool("tool2"),
+        registeredAt: 2,
+        source: "built-in",
+        enabled: true,
+      });
+      expect(registry.getCount()).toBe(2);
+    });
+  });
+
+  describe("clear", () => {
+    test("should remove all tools", () => {
+      registry.register(createMockTool("tool1"), {
+        tool: createMockTool("tool1"),
+        registeredAt: 1,
+        source: "built-in",
+        enabled: true,
+      });
+      registry.register(createMockTool("tool2"), {
+        tool: createMockTool("tool2"),
+        registeredAt: 2,
+        source: "built-in",
+        enabled: true,
+      });
+
+      registry.clear();
+      expect(registry.getCount()).toBe(0);
+    });
+  });
+
+  describe("snapshot/restore", () => {
+    test("should snapshot and restore tools", () => {
+      registry.register(createMockTool("tool1"), {
+        tool: createMockTool("tool1"),
+        registeredAt: 1,
+        source: "built-in",
+        enabled: true,
+      });
+      registry.register(createMockTool("tool2"), {
+        tool: createMockTool("tool2"),
+        registeredAt: 2,
+        source: "dynamic",
+        enabled: false,
+      });
+
+      const snapshot = registry.snapshot();
+      registry.clear();
+
+      expect(registry.getCount()).toBe(0);
+
+      registry.restore(snapshot);
+      expect(registry.getCount()).toBe(2);
+      expect(registry.getTool("tool2")?.enabled).toBe(false);
+    });
+  });
+});

package/src/env/tool/registry.ts

@@ -0,0 +1,167 @@
+import type {
+  Tool,
+  ToolRegistration,
+  ToolListFilter,
+} from "./types";
+
+/**
+ * 工具注册中心
+ * 管理所有已注册的工具
+ */
+export class ToolRegistry {
+  private tools = new Map<string, ToolRegistration>();
+
+  /**
+   * 注册工具
+   */
+  register(tool: Tool, registration: ToolRegistration): void {
+    this.tools.set(tool.name, registration);
+  }
+
+  /**
+   * 注销工具
+   */
+  unregister(name: string): boolean {
+    return this.tools.delete(name);
+  }
+
+  /**
+   * 获取工具
+   */
+  getTool(name: string): ToolRegistration | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * 获取所有工具注册信息
+   */
+  getAllTools(): ToolRegistration[] {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * 列出工具（带过滤）
+   */
+  listTools(filter?: ToolListFilter): Tool[] {
+    let tools = this.getAllTools();
+
+    if (!filter) {
+      return tools.map((r) => r.tool);
+    }
+
+    // 按名称过滤
+    if (filter.name) {
+      const names = Array.isArray(filter.name) ? filter.name : [filter.name];
+      tools = tools.filter((r) =>
+        names.some((pattern) => this.matchGlob(r.tool.name, pattern))
+      );
+    }
+
+    // 按分类过滤
+    if (filter.category) {
+      tools = tools.filter((r) => r.tool.metadata?.category === filter.category);
+    }
+
+    // 按标签过滤
+    if (filter.tags && filter.tags.length > 0) {
+      tools = tools.filter((r) =>
+        filter.tags!.some((tag) => r.tool.metadata?.tags?.includes(tag))
+      );
+    }
+
+    // 按来源过滤
+    if (filter.source) {
+      tools = tools.filter((r) => r.source === filter.source);
+    }
+
+    // 只返回启用的工具
+    if (filter.enabledOnly) {
+      tools = tools.filter((r) => r.enabled);
+    }
+
+    // 排除工具
+    if (filter.exclude && filter.exclude.length > 0) {
+      tools = tools.filter((r) => !filter.exclude!.includes(r.tool.name));
+    }
+
+    return tools.map((r) => r.tool);
+  }
+
+  /**
+   * 检查工具是否存在
+   */
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  /**
+   * 获取工具数量
+   */
+  getCount(): number {
+    return this.tools.size;
+  }
+
+  /**
+   * 启用工具
+   */
+  enable(name: string): boolean {
+    const reg = this.tools.get(name);
+    if (reg) {
+      reg.enabled = true;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * 禁用工具
+   */
+  disable(name: string): boolean {
+    const reg = this.tools.get(name);
+    if (reg) {
+      reg.enabled = false;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * 清除所有工具
+   */
+  clear(): void {
+    this.tools.clear();
+  }
+
+  /**
+   * 导出工具注册表快照
+   */
+  snapshot(): ToolRegistration[] {
+    return this.getAllTools();
+  }
+
+  /**
+   * 从快照恢复
+   */
+  restore(snapshot: ToolRegistration[]): void {
+    this.clear();
+    for (const reg of snapshot) {
+      this.tools.set(reg.tool.name, reg);
+    }
+  }
+
+  /**
+   * 简单的 glob 模式匹配
+   * 支持 * 匹配任意字符
+   */
+  private matchGlob(str: string, pattern: string): boolean {
+    if (pattern === "*") return true;
+    if (!pattern.includes("*")) return str === pattern;
+
+    // Convert glob pattern to regex
+    const regexPattern = pattern
+      .replace(/[.+?^${}()|[\]\\]/g, "\\$&") // Escape special regex chars
+      .replace(/\*/g, ".*"); // Convert * to .*
+
+    return new RegExp(`^${regexPattern}$`).test(str);
+  }
+}