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

package/dist/cli/src/commands/workflow/validators/workflow-validator.js

@@ -0,0 +1,284 @@
+/**
+ * @fileoverview Workflow-level validator
+ */
+import { ValidationErrorType } from "./types.js";
+import { getNodeValidator, getSupportedNodeTypes } from "./node-validator-factory.js";
+/**
+ * Workflow validator - validates both structure and nodes
+ */
+export class WorkflowValidator {
+    /**
+     * Validate a raw workflow definition
+     */
+    validate(workflow) {
+        const errors = [];
+        // 1. Structure validation
+        const structureErrors = this.validateStructure(workflow);
+        errors.push(...structureErrors);
+        // If structure is invalid, skip node validation
+        if (structureErrors.length > 0) {
+            return {
+                valid: false,
+                errors,
+                workflowName: typeof workflow.name === 'string' ? workflow.name : undefined,
+            };
+        }
+        // 2. Node validation
+        const nodes = workflow.nodes || [];
+        const nodeIds = new Set();
+        const nodeErrors = this.validateNodes(nodes, nodeIds);
+        errors.push(...nodeErrors);
+        // 3. Dependency validation
+        const depErrors = this.validateDependencies(nodes, nodeIds);
+        errors.push(...depErrors);
+        // 4. Template reference validation
+        const templateErrors = this.validateTemplateReferences(nodes, nodeIds);
+        errors.push(...templateErrors);
+        return {
+            valid: errors.length === 0,
+            errors,
+            workflowName: workflow.name,
+            nodeCount: nodes.length,
+        };
+    }
+    /**
+     * Validate workflow structure
+     */
+    validateStructure(workflow) {
+        const errors = [];
+        // Check name
+        if (!workflow.name || typeof workflow.name !== 'string' || !workflow.name.trim()) {
+            errors.push({
+                type: ValidationErrorType.MISSING_REQUIRED_FIELD,
+                description: 'Workflow name is missing or empty',
+                expected: 'name must be a non-empty string',
+                actual: String(workflow.name),
+                fix: 'Add a "name" field to the workflow, e.g., name: "my-workflow"',
+            });
+        }
+        // Check nodes
+        if (!workflow.nodes || !Array.isArray(workflow.nodes)) {
+            errors.push({
+                type: ValidationErrorType.EMPTY_NODES,
+                description: 'Workflow nodes is missing or not an array',
+                expected: 'nodes must be an array of node definitions',
+                actual: String(workflow.nodes),
+                fix: 'Add a "nodes" array to the workflow',
+            });
+            return errors;
+        }
+        if (workflow.nodes.length === 0) {
+            errors.push({
+                type: ValidationErrorType.EMPTY_NODES,
+                description: 'Workflow nodes array is empty',
+                expected: 'nodes must contain at least one node',
+                actual: '[]',
+                fix: 'Add at least one node to the workflow',
+            });
+        }
+        return errors;
+    }
+    /**
+     * Validate all nodes
+     */
+    validateNodes(nodes, nodeIds) {
+        const errors = [];
+        const seenIds = new Set();
+        for (const node of nodes) {
+            // Check for duplicate IDs
+            if (node.id) {
+                if (seenIds.has(node.id)) {
+                    errors.push({
+                        type: ValidationErrorType.DUPLICATE_NODE_ID,
+                        description: `Duplicate node ID found: "${node.id}"`,
+                        expected: 'Each node must have a unique ID',
+                        actual: `ID "${node.id}" appears multiple times`,
+                        fix: `Rename one of the nodes with ID "${node.id}" to a unique value`,
+                        nodeId: node.id,
+                    });
+                }
+                seenIds.add(node.id);
+                nodeIds.add(node.id);
+            }
+            // Validate node type
+            if (!node.type) {
+                errors.push({
+                    type: ValidationErrorType.MISSING_REQUIRED_FIELD,
+                    description: 'Node type is missing',
+                    expected: `type must be one of: ${getSupportedNodeTypes().join(', ')}`,
+                    actual: 'undefined',
+                    fix: `Add a "type" field to the node, e.g., type: "tool"`,
+                    nodeId: node.id,
+                });
+                continue;
+            }
+            // Get validator for node type
+            const validator = getNodeValidator(node.type);
+            if (!validator) {
+                errors.push({
+                    type: ValidationErrorType.INVALID_NODE_TYPE,
+                    description: `Unknown node type: "${node.type}"`,
+                    expected: `type must be one of: ${getSupportedNodeTypes().join(', ')}`,
+                    actual: String(node.type),
+                    fix: `Change type to one of: ${getSupportedNodeTypes().join(', ')}`,
+                    nodeId: node.id,
+                });
+                continue;
+            }
+            // Validate with type-specific validator
+            const nodeErrors = validator.validate(node);
+            errors.push(...nodeErrors);
+        }
+        return errors;
+    }
+    /**
+     * Validate node dependencies
+     */
+    validateDependencies(nodes, nodeIds) {
+        const errors = [];
+        for (const node of nodes) {
+            if (!node.depends_on || !Array.isArray(node.depends_on))
+                continue;
+            for (const depId of node.depends_on) {
+                if (!nodeIds.has(depId)) {
+                    errors.push({
+                        type: ValidationErrorType.INVALID_REFERENCE,
+                        description: `depends_on references non-existent node`,
+                        expected: 'All node IDs in depends_on must exist in workflow',
+                        actual: `depends_on: ["${depId}"], but "${depId}" not found`,
+                        fix: `Remove "${depId}" from depends_on or create a node with that ID`,
+                        nodeId: node.id,
+                    });
+                }
+            }
+        }
+        // Check for circular dependencies
+        const circularErrors = this.detectCircularDependencies(nodes);
+        errors.push(...circularErrors);
+        return errors;
+    }
+    /**
+     * Validate template references in node configs
+     *
+     * Extracts all template references like {{nodes.xxx.output}}, {{xxx.output}}, ${xxx.output}
+     * and validates that the referenced node IDs exist in the workflow.
+     */
+    validateTemplateReferences(nodes, nodeIds) {
+        const errors = [];
+        // Template reference patterns:
+        // 1. {{nodes.nodeId}} or {{nodes.nodeId.path}} or {{nodes.nodeId.path.more}}
+        // 2. {{nodeId}} or {{nodeId.path}} (bare node reference)
+        // 3. ${nodes.nodeId} or ${nodes.nodeId.path} (dollar-style)
+        // 4. ${nodeId} or ${nodeId.path} (dollar-style bare)
+        // 5. {{input.key}} - workflow input, not a node reference
+        const templatePatterns = [
+            /\{\{nodes\.([a-zA-Z_][a-zA-Z0-9_-]*)(?:\.[^}]+)?\}\}/g, // {{nodes.xxx}} or {{nodes.xxx.yyy}}
+            /\{\{([a-zA-Z_][a-zA-Z0-9_-]*)(?:\.[^}]+)?\}\}/g, // {{xxx}} or {{xxx.yyy}} (not input or nodes)
+            /\$\{nodes\.([a-zA-Z_][a-zA-Z0-9_-]*)(?:\.[^}]+)?\}/g, // ${nodes.xxx} or ${nodes.xxx.yyy}
+            /\$\{([a-zA-Z_][a-zA-Z0-9_-]*)(?:\.[^}]+)?\}/g, // ${xxx} or ${xxx.yyy}
+        ];
+        for (const node of nodes) {
+            if (!node.id || !node.config)
+                continue;
+            // Get all config values as strings to search for templates
+            const configStr = JSON.stringify(node.config);
+            // Find all template references
+            const foundRefs = new Set();
+            for (const pattern of templatePatterns) {
+                pattern.lastIndex = 0; // Reset regex state
+                let match;
+                while ((match = pattern.exec(configStr)) !== null) {
+                    // Skip 'input' and 'nodes' keywords
+                    const refId = match[1];
+                    if (refId !== 'input' && refId !== 'nodes') {
+                        foundRefs.add(refId);
+                    }
+                }
+            }
+            // Check each reference against node IDs
+            for (const refId of foundRefs) {
+                if (!nodeIds.has(refId)) {
+                    // Check if there's a similar node ID (hyphen/underscore mismatch)
+                    const normalizedRef = refId.includes('-')
+                        ? refId.replace(/-/g, '_')
+                        : refId.replace(/_/g, '-');
+                    let fix;
+                    if (nodeIds.has(normalizedRef)) {
+                        fix = `Change "${refId}" to "${normalizedRef}" to match the existing node ID`;
+                    }
+                    else {
+                        // Find all existing node IDs that are similar (for suggestions)
+                        const similarIds = Array.from(nodeIds).filter(id => {
+                            const n1 = id.replace(/-/g, '_').replace(/_/g, '-');
+                            const n2 = refId.replace(/-/g, '_').replace(/_/g, '-');
+                            return n1 === n2;
+                        });
+                        if (similarIds.length > 0) {
+                            fix = `Change "${refId}" to one of: ${similarIds.join(', ')}`;
+                        }
+                        else {
+                            fix = `Remove "${refId}" or create a node with that ID`;
+                        }
+                    }
+                    errors.push({
+                        type: ValidationErrorType.INVALID_TEMPLATE_REFERENCE,
+                        description: `Template references non-existent node: "${refId}"`,
+                        expected: `Referenced node ID must exist in the workflow`,
+                        actual: `Template references "${refId}" but this node does not exist`,
+                        fix,
+                        nodeId: node.id,
+                        template: `{{${refId}}}`,
+                        referencedNodeId: refId,
+                    });
+                }
+            }
+        }
+        return errors;
+    }
+    /**
+     * Detect circular dependencies using DFS
+     */
+    detectCircularDependencies(nodes) {
+        const errors = [];
+        const nodeMap = new Map();
+        for (const node of nodes) {
+            if (node.id)
+                nodeMap.set(node.id, node);
+        }
+        const visited = new Set();
+        const recursionStack = new Set();
+        const dfs = (nodeId, path) => {
+            visited.add(nodeId);
+            recursionStack.add(nodeId);
+            const node = nodeMap.get(nodeId);
+            if (!node)
+                return false;
+            for (const depId of node.depends_on || []) {
+                if (!visited.has(depId)) {
+                    if (dfs(depId, [...path, depId]))
+                        return true;
+                }
+                else if (recursionStack.has(depId)) {
+                    errors.push({
+                        type: ValidationErrorType.CIRCULAR_DEPENDENCY,
+                        description: 'Circular dependency detected',
+                        expected: 'Workflow should be a DAG (no cycles)',
+                        actual: `Cycle: ${[...path, depId].join(' → ')} → ${depId}`,
+                        fix: 'Remove the circular dependency by changing depends_on references',
+                        nodeId,
+                    });
+                    return true;
+                }
+            }
+            recursionStack.delete(nodeId);
+            return false;
+        };
+        for (const node of nodes) {
+            if (node.id && !visited.has(node.id)) {
+                dfs(node.id, [node.id]);
+            }
+        }
+        return errors;
+    }
+}
+//# sourceMappingURL=workflow-validator.js.map

package/dist/cli/src/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @roy-agent/cli - CLI for roy-agent
+ */
+export { runCli } from "./cli";
+export { OutputService } from "./services/output.service";
+export { EnvironmentService } from "./services/environment.service";
+export { ActCommand } from "./commands/act";
+export { InteractiveCommand } from "./commands/interactive";
+export { SessionsCommand } from "./commands/sessions";
+export { TasksCommand } from "./commands/tasks";
+export { CommandsCommand } from "./commands/commands";
+export { MemoryCommand } from "./commands/memory";
+export { SkillsCommand } from "./commands/skills";
+export { ToolsCommand } from "./commands/tools";
+export { McpCommand } from "./commands/mcp";
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * @roy-agent/cli - CLI for roy-agent
+ */
+// Re-export for convenience
+export { runCli } from "./cli.js";
+export { OutputService } from "./services/output.service.js";
+export { EnvironmentService } from "./services/environment.service.js";
+// Re-export all commands
+export { ActCommand } from "./commands/act.js";
+export { InteractiveCommand } from "./commands/interactive.js";
+export { SessionsCommand } from "./commands/sessions/index.js";
+export { TasksCommand } from "./commands/tasks/index.js";
+export { CommandsCommand } from "./commands/commands.js";
+export { MemoryCommand } from "./commands/memory/index.js";
+export { SkillsCommand } from "./commands/skills/index.js";
+export { ToolsCommand } from "./commands/tools/index.js";
+export { McpCommand } from "./commands/mcp/index.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/src/plugin/apply.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Apply Plugins to Yargs
+ *
+ * 将插件命令应用到 yargs 实例
+ */
+/**
+ * 将插件命令应用到 yargs 实例
+ *
+ * @param yargsInstance - yargs 实例
+ * @returns 应用了插件命令的 yargs 实例
+ *
+ * @example
+ * ```typescript
+ * import { applyPluginCommands } from "./plugin";
+ *
+ * let y = yargs();
+ * y = y.command(ActCommand);
+ * y = applyPluginCommands(y);
+ * y.parse();
+ * ```
+ */
+export declare function applyPluginCommands<T = any>(yargsInstance: any): any;
+/**
+ * 创建插件命令包装命令
+ *
+ * 用于在 yargs 中添加一个空的命令包装器，
+ * 使得插件命令可以在 strict 模式下正常工作
+ *
+ * @returns CommandModule
+ *
+ * @deprecated 此方法已废弃，仅用于兼容旧版本
+ */
+export declare function createPluginCommandsCommand(): any;
+/**
+ * 获取所有插件命令信息摘要
+ *
+ * @returns 命令摘要数组
+ */
+export declare function getPluginCommandsSummary(): Array<{
+    plugin: string;
+    command: string;
+    description?: string;
+}>;
+/**
+ * 检查是否存在指定名称的命令
+ *
+ * @param commandName - 命令名称
+ * @returns 是否存在
+ */
+export declare function hasPluginCommand(commandName: string): boolean;
+//# sourceMappingURL=apply.d.ts.map

package/dist/cli/src/plugin/apply.js

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Apply Plugins to Yargs
+ *
+ * 将插件命令应用到 yargs 实例
+ */
+import { globalPluginRegistry } from "./registry.js";
+/**
+ * 将插件命令应用到 yargs 实例
+ *
+ * @param yargsInstance - yargs 实例
+ * @returns 应用了插件命令的 yargs 实例
+ *
+ * @example
+ * ```typescript
+ * import { applyPluginCommands } from "./plugin.js";
+ *
+ * let y = yargs();
+ * y = y.command(ActCommand);
+ * y = applyPluginCommands(y);
+ * y.parse();
+ * ```
+ */
+export function applyPluginCommands(yargsInstance) {
+    const commands = globalPluginRegistry.getAllCommands();
+    for (const { command } of commands) {
+        yargsInstance = yargsInstance.command(command);
+    }
+    return yargsInstance;
+}
+/**
+ * 创建插件命令包装命令
+ *
+ * 用于在 yargs 中添加一个空的命令包装器，
+ * 使得插件命令可以在 strict 模式下正常工作
+ *
+ * @returns CommandModule
+ *
+ * @deprecated 此方法已废弃，仅用于兼容旧版本
+ */
+export function createPluginCommandsCommand() {
+    return {
+        command: "$0",
+        describe: false,
+        handler: () => {
+            // 不做任何事，由其他命令处理
+        },
+    };
+}
+/**
+ * 获取所有插件命令信息摘要
+ *
+ * @returns 命令摘要数组
+ */
+export function getPluginCommandsSummary() {
+    const summary = [];
+    for (const plugin of globalPluginRegistry.getAll()) {
+        const commands = plugin.getCommands?.() ?? [];
+        for (const { command } of commands) {
+            summary.push({
+                plugin: plugin.info.name,
+                command: command.command,
+                description: command.describe,
+            });
+        }
+    }
+    return summary;
+}
+/**
+ * 检查是否存在指定名称的命令
+ *
+ * @param commandName - 命令名称
+ * @returns 是否存在
+ */
+export function hasPluginCommand(commandName) {
+    for (const plugin of globalPluginRegistry.getAll()) {
+        const commands = plugin.getCommands?.() ?? [];
+        for (const { command } of commands) {
+            if (command.command.startsWith(commandName)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=apply.js.map

package/dist/cli/src/plugin/discover.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Plugin Discovery
+ *
+ * 扫描并发现已安装的插件
+ */
+/**
+ * 扫描指定路径并加载所有发现的插件
+ *
+ * @param scanPaths - 要扫描的路径数组，默认扫描标准 node_modules 位置
+ * @returns 已加载的插件数量
+ */
+export declare function discoverPlugins(scanPaths?: string[]): Promise<number>;
+/**
+ * 获取已加载的插件数量
+ */
+export declare function getLoadedPluginCount(): number;
+/**
+ * 清除插件加载缓存
+ *
+ * 主要用于测试
+ */
+export declare function clearPluginCache(): void;
+/**
+ * 重新扫描并加载插件
+ *
+ * 会先清空已注册的插件，然后重新发现
+ */
+export declare function reloadPlugins(): Promise<number>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/cli/src/plugin/discover.js

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview Plugin Discovery
+ *
+ * 扫描并发现已安装的插件
+ */
+import { globalPluginRegistry } from "./registry.js";
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+/**
+ * 插件包识别模式
+ *
+ * 扫描 node_modules 中匹配这些模式的包
+ */
+const PLUGIN_PATTERNS = [
+    "@ai-setting/agent-*",
+    "@roy-agent/plugin-*",
+];
+/**
+ * 插件入口文件名
+ *
+ * 插件包根目录下必须包含此文件
+ */
+const PLUGIN_ENTRY_FILE = "roy-plugin.js";
+/**
+ * 扫描路径
+ *
+ * 从这些路径扫描插件，默认包含项目 node_modules 和全局 node_modules
+ */
+const DEFAULT_SCAN_PATHS = [];
+/**
+ * 缓存已发现的插件路径，避免重复加载
+ */
+const loadedPaths = new Set();
+/**
+ * 初始化扫描路径
+ */
+function initScanPaths() {
+    if (DEFAULT_SCAN_PATHS.length > 0) {
+        return DEFAULT_SCAN_PATHS;
+    }
+    // 项目 node_modules
+    const projectNodeModules = resolve(process.cwd(), "node_modules");
+    if (existsSync(projectNodeModules)) {
+        DEFAULT_SCAN_PATHS.push(projectNodeModules);
+    }
+    // 全局 bun/node_modules
+    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    if (homeDir) {
+        const globalNodeModules = join(homeDir, ".bun", "install", "global", "node_modules");
+        if (existsSync(globalNodeModules)) {
+            DEFAULT_SCAN_PATHS.push(globalNodeModules);
+        }
+    }
+    // NODE_PATH 环境变量
+    if (process.env.NODE_PATH) {
+        const extraPaths = process.env.NODE_PATH.split(":").filter((p) => {
+            const fullPath = resolve(p);
+            if (!DEFAULT_SCAN_PATHS.includes(fullPath) && existsSync(fullPath)) {
+                return true;
+            }
+            return false;
+        });
+        DEFAULT_SCAN_PATHS.push(...extraPaths);
+    }
+    return DEFAULT_SCAN_PATHS;
+}
+/**
+ * 类型守卫：检查对象是否为有效的 RoyCliPlugin
+ */
+function isRoyCliPlugin(obj) {
+    return (typeof obj === "object" &&
+        obj !== null &&
+        "info" in obj &&
+        typeof obj.info.name === "string" &&
+        typeof obj.info.version === "string");
+}
+/**
+ * 加载单个插件
+ *
+ * @param pkgPath - 插件包路径
+ * @returns 是否成功加载
+ */
+async function loadPlugin(pkgPath) {
+    const pluginFile = join(pkgPath, PLUGIN_ENTRY_FILE);
+    if (!existsSync(pluginFile)) {
+        return false;
+    }
+    if (loadedPaths.has(pluginFile)) {
+        return true; // 已加载过
+    }
+    try {
+        // 使用动态导入加载插件
+        const plugin = await import(pluginFile);
+        // 尝试多种方式获取插件实例
+        const pluginInstance = plugin.default ||
+            plugin.bountyPlugin ||
+            plugin;
+        if (isRoyCliPlugin(pluginInstance)) {
+            // 跳过已注册的插件
+            if (globalPluginRegistry.has(pluginInstance.info.name)) {
+                console.log(`[roy] Plugin "${pluginInstance.info.name}" is already registered, skipping`);
+                return true;
+            }
+            globalPluginRegistry.register(pluginInstance);
+            console.log(`[roy] Loaded plugin: ${pluginInstance.info.name}@${pluginInstance.info.version}`);
+            loadedPaths.add(pluginFile);
+            return true;
+        }
+        else {
+            console.warn(`[roy] Invalid plugin at ${pkgPath}: missing required "info" property`);
+            // 调试信息
+            console.warn(`[roy] Available exports:`, Object.keys(plugin));
+        }
+    }
+    catch (err) {
+        console.warn(`[roy] Failed to load plugin from ${pkgPath}:`, err.message);
+    }
+    return false;
+}
+/**
+ * 扫描单个路径下的插件
+ *
+ * @param basePath - 基础路径
+ */
+async function scanPath(basePath) {
+    if (!existsSync(basePath)) {
+        return;
+    }
+    const { glob } = await import("glob");
+    for (const pattern of PLUGIN_PATTERNS) {
+        try {
+            const matches = await glob(pattern, {
+                cwd: basePath,
+                onlyDirectories: true,
+                absolute: true,
+            });
+            for (const match of matches) {
+                await loadPlugin(match);
+            }
+        }
+        catch {
+            // 忽略 glob 扫描错误
+        }
+    }
+}
+/**
+ * 扫描指定路径并加载所有发现的插件
+ *
+ * @param scanPaths - 要扫描的路径数组，默认扫描标准 node_modules 位置
+ * @returns 已加载的插件数量
+ */
+export async function discoverPlugins(scanPaths = initScanPaths()) {
+    const initialCount = globalPluginRegistry.size;
+    for (const path of scanPaths) {
+        await scanPath(path);
+    }
+    const loadedCount = globalPluginRegistry.size - initialCount;
+    if (loadedCount > 0) {
+        console.log(`[roy] Discovered and loaded ${loadedCount} plugin(s)`);
+    }
+    return loadedCount;
+}
+/**
+ * 获取已加载的插件数量
+ */
+export function getLoadedPluginCount() {
+    return globalPluginRegistry.size;
+}
+/**
+ * 清除插件加载缓存
+ *
+ * 主要用于测试
+ */
+export function clearPluginCache() {
+    loadedPaths.clear();
+}
+/**
+ * 重新扫描并加载插件
+ *
+ * 会先清空已注册的插件，然后重新发现
+ */
+export async function reloadPlugins() {
+    globalPluginRegistry.clear();
+    loadedPaths.clear();
+    return discoverPlugins();
+}
+//# sourceMappingURL=discover.js.map

package/dist/cli/src/plugin/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Plugin System
+ *
+ * Roy CLI 插件系统入口
+ *
+ * @example
+ * ```typescript
+ * import { globalPluginRegistry } from "@ai-setting/roy-agent-cli/plugin";
+ * import type { RoyCliPlugin } from "@ai-setting/roy-agent-cli/plugin";
+ * ```
+ */
+export type { PluginInfo, PluginComponentDefinition, PluginCommandDefinition, PluginEnvironmentContext, RoyCliPlugin, ComponentPluginDefinition, ComponentPluginInstance, } from "./types";
+export { PluginRegistry, globalPluginRegistry, loadBuiltinComponentPlugin, } from "./registry";
+export { discoverPlugins, getLoadedPluginCount, clearPluginCache, reloadPlugins, } from "./discover";
+export { applyPluginCommands, createPluginCommandsCommand, getPluginCommandsSummary, hasPluginCommand, } from "./apply";
+//# sourceMappingURL=index.d.ts.map