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

package/dist/core/src/env/tool/tool-config-registration.test.js

@@ -0,0 +1,202 @@
+/**
+ * @fileoverview Tool Component 配置注册测试
+ *
+ * TDD: 先写测试，验证配置注册机制
+ */
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+import { ConfigComponent } from "../../config/config-component.js";
+import { ToolComponent } from "./tool-component.js";
+import { TOOL_CONFIG_REGISTRATION, TOOL_DEFAULTS } from "./tool-config-registration.js";
+// 模拟 registerComponent 调用
+const mockRegisterComponent = vi.fn();
+describe("Tool Config Registration", () => {
+    let configComponent;
+    let component;
+    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: {},
+            })).rejects.toThrow("ConfigComponent is required");
+        });
+        it("应该能够使用 ConfigComponent 初始化", async () => {
+            await component.init({
+                options: {
+                    configComponent,
+                },
+            });
+            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",
+                        },
+                    },
+                },
+            });
+            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,
+                    },
+                });
+                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,
+                },
+            });
+            // 验证 registerComponent 被调用
+            expect(spy).toHaveBeenCalledWith(TOOL_CONFIG_REGISTRATION);
+            spy.mockRestore();
+        });
+        it("应该使用 load('tool') 加载配置", async () => {
+            const loadSpy = vi.spyOn(configComponent, 'load');
+            await component.init({
+                options: {
+                    configComponent,
+                },
+            });
+            // 验证 load 被调用，且参数为 "tool"
+            expect(loadSpy).toHaveBeenCalledWith("tool");
+            loadSpy.mockRestore();
+        });
+        it("应该正确设置 TOOL_DEFAULTS 默认值", async () => {
+            await component.init({
+                options: {
+                    configComponent,
+                },
+            });
+            // 验证默认值被正确设置到 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,
+                },
+            });
+            // 验证环境变量覆盖了默认值
+            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",
+                        },
+                    },
+                },
+            });
+            // 验证 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,
+                },
+            });
+            // 验证 config 对象被正确处理
+            expect(configComponent.get("tool.toolsDir")).toBe("/custom/tools");
+        });
+    });
+});
+//# sourceMappingURL=tool-config-registration.test.js.map

package/dist/core/src/env/tool/types.d.ts

@@ -0,0 +1,226 @@
+import { z, ZodType, ZodError } from "zod";
+/**
+ * 沙箱配置
+ */
+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;
+}
+/**
+ * 工具结果元数据
+ */
+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;
+}
+/**
+ * 工具元数据
+ */
+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;
+/**
+ * 工具注册来源
+ */
+export type ToolSource = "built-in" | "plugin" | "dynamic";
+/**
+ * 工具注册信息
+ */
+export interface ToolRegistration {
+    /** 工具实例 */
+    tool: Tool;
+    /** 注册时间 */
+    registeredAt: number;
+    /** 注册来源 */
+    source: ToolSource;
+    /** 是否启用 */
+    enabled: boolean;
+}
+/**
+ * 工具执行请求
+ */
+export interface ToolExecuteRequest {
+    /** 工具名称 */
+    name: string;
+    /** 参数 */
+    args: Record<string, unknown>;
+    /** 上下文 */
+    context: ToolContext;
+    /** 是否跳过 Hook */
+    skipHooks?: boolean;
+}
+/**
+ * 工具列表过滤器
+ */
+export interface ToolListFilter {
+    /** 按名称过滤（支持 glob） */
+    name?: string | string[];
+    /** 按分类过滤 */
+    category?: string;
+    /** 按标签过滤 */
+    tags?: string[];
+    /** 按来源过滤 */
+    source?: ToolSource;
+    /** 只返回启用的工具 */
+    enabledOnly?: boolean;
+    /** 排除的工具 */
+    exclude?: string[];
+}
+/**
+ * 参数验证结果
+ */
+export interface ValidationResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 验证后的数据 */
+    data?: Record<string, unknown>;
+    /** 错误信息 */
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/src/env/tool/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/src/env/tool/validator.d.ts

@@ -0,0 +1,15 @@
+import type { Tool, ValidationResult } from "./types";
+/**
+ * 工具参数验证器
+ */
+export declare class ToolValidator {
+    /**
+     * 验证参数
+     */
+    validate(tool: Tool, args: Record<string, unknown>): Promise<ValidationResult>;
+    /**
+     * 格式化 Zod 错误
+     */
+    private formatError;
+}
+//# sourceMappingURL=validator.d.ts.map

package/dist/core/src/env/tool/validator.js

@@ -0,0 +1,43 @@
+import { ZodError } from "zod";
+/**
+ * 工具参数验证器
+ */
+export class ToolValidator {
+    /**
+     * 验证参数
+     */
+    async validate(tool, args) {
+        try {
+            // 使用 Zod 验证参数
+            const parsed = await tool.parameters.parseAsync(args);
+            return {
+                success: true,
+                data: parsed,
+            };
+        }
+        catch (error) {
+            if (error instanceof ZodError) {
+                const errorMessage = tool.formatValidationError
+                    ? tool.formatValidationError(error)
+                    : this.formatError(error);
+                return {
+                    success: false,
+                    error: `Invalid arguments for tool '${tool.name}': ${errorMessage}`,
+                };
+            }
+            return {
+                success: false,
+                error: `Validation error: ${error}`,
+            };
+        }
+    }
+    /**
+     * 格式化 Zod 错误
+     */
+    formatError(error) {
+        return error.errors
+            .map((e) => `${e.path.join(".")}: ${e.message}`)
+            .join("; ");
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/core/src/env/tool/validator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validator.test.d.ts.map

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

@@ -0,0 +1,102 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { z } from "zod";
+import { ToolValidator } from "./validator.js";
+describe("ToolValidator", () => {
+    let validator;
+    const createMockTool = (paramsSchema) => ({
+        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 = {
+                name: "test-tool",
+                description: "Test tool",
+                parameters: z.object({
+                    name: z.string(),
+                }),
+                execute: async () => ({ success: true, output: "ok" }),
+                formatValidationError: (error) => {
+                    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("-");
+        });
+    });
+});
+//# sourceMappingURL=validator.test.js.map