@ai-setting/roy-agent-cli 1.3.15 → 1.3.16

package/dist/core/src/env/tool/registry.test.js

@@ -0,0 +1,219 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { z } from "zod";
+import { ToolRegistry } from "./registry.js";
+describe("ToolRegistry", () => {
+    let registry;
+    // Helper to create a mock tool
+    const createMockTool = (name, category) => ({
+        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 = {
+                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);
+        });
+    });
+});
+//# sourceMappingURL=registry.test.js.map

package/dist/core/src/env/tool/tool-component.d.ts

@@ -0,0 +1,160 @@
+import { BaseComponent, type ComponentConfig } from "../component";
+import type { Tool, ToolContext, ToolResult, ToolExecuteRequest, ToolListFilter, ToolRegistration } from "./types";
+import type { ConfigComponent } from "../../config/config-component";
+/**
+ * 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 declare class ToolComponent extends BaseComponent {
+    readonly name = "tool";
+    readonly version = "1.0.0";
+    private registry;
+    private validator;
+    private config?;
+    /** ConfigComponent 用于配置管理 */
+    private configComponent?;
+    /** 配置变更 watcher 清理函数 */
+    private configWatcher?;
+    constructor();
+    /**
+     * 初始化组件
+     *
+     * 配置加载优先级（从高到低）：
+     * 1. Object - 直接传入的 config 对象
+     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+     * 3. File - 配置文件（通过 configPath 指定）
+     */
+    init(config?: ComponentConfig): Promise<void>;
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. FileSource - 从配置文件加载（最低）
+     * 2. EnvSource - 从环境变量加载（中等）
+     * 3. MemorySource - 直接配置对象（最高）
+     *
+     * 实现步骤：
+     * 1. 使用 registerComponent(TOOL_CONFIG_REGISTRATION) 注册配置
+     * 2. 使用 load("tool") 加载已注册的配置
+     * 3. 设置 TOOL_DEFAULTS 默认值
+     * 4. 处理环境变量后备方案
+     * 5. 处理 config 对象（最高优先级）
+     */
+    private registerConfig;
+    /**
+     * 将配置对象展平为点号路径
+     */
+    private flattenConfig;
+    /**
+     * 注册配置热更新监听
+     */
+    private registerConfigWatcher;
+    /**
+     * 处理配置变更
+     */
+    protected onConfigChange(event: {
+        key: string;
+        oldValue?: unknown;
+        newValue?: unknown;
+    }): void;
+    /**
+     * 停止组件
+     */
+    onStop(): Promise<void>;
+    /**
+     * 注册工具
+     */
+    register(tool: Tool, source?: ToolRegistration["source"]): void;
+    /**
+     * 批量注册工具
+     */
+    registerMany(tools: Tool[], source?: ToolRegistration["source"]): void;
+    /**
+     * 注销工具
+     */
+    unregister(name: string): boolean;
+    /**
+     * 获取工具
+     */
+    getTool(name: string): Tool | undefined;
+    /**
+     * 列出工具
+     */
+    listTools(filter?: ToolListFilter): Tool[];
+    /**
+     * 获取工具数量
+     */
+    getToolCount(): number;
+    /**
+     * 检查工具是否存在
+     */
+    hasTool(name: string): boolean;
+    /**
+     * 按分类获取工具
+     */
+    getToolsByCategory(category: string): Tool[];
+    /**
+     * 执行工具
+     */
+    execute(request: ToolExecuteRequest): Promise<ToolResult>;
+    /**
+     * 加载内置工具
+     */
+    loadBuiltInTools(): Promise<void>;
+    /**
+     * 获取 Tool Hook 点列表
+     */
+    getHookPoints(): string[];
+}
+//# sourceMappingURL=tool-component.d.ts.map